> ## Documentation Index > Fetch the complete documentation index at: https://www.bloxs.io/llms.txt > Use this file to discover all available pages before exploring further. # Insert a unit > Insert a new unit. ## OpenAPI ````json POST /api/v1/realestateobjects/units { "openapi": "3.0.4", "info": { "title": "RealEstateObjects V1", "description": "Welcome to BETA version of the new RealEstateObjects API - intended for client public testing before the launch of the final version. During this BETA phase, we'll be improving the API based on specific client's feedbacks.", "version": "v1" }, "security": [ {} ], "tags": [ { "name": "Admin" }, { "name": "Buildings" }, { "name": "Complexes" }, { "name": "Generic" }, { "name": "Metadata" }, { "name": "PublishObjects" }, { "name": "ScoringPointTotals" }, { "name": "Sections" }, { "name": "Units" } ], "paths": { "/api/v1/realestateobjects/units": { "post": { "tags": [ "Units" ], "summary": "Insert a unit", "description": "Insert a new unit.", "operationId": "InsertUnit", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Unit" } } } }, "responses": { "200": { "description": "The unit was created", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UnitAPIDetailModel" } } } }, "400": { "description": "The unit data has validation issues", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/APIErrorMessageModel" } } } } }, "x-d360-narrative-url": "

Insert a unit

This endpoint creates a new unit in Bloxs.

Integrators call it to add an individual rentable part of a larger property, such as a room in a student house or an apartment within a townhouse, from a third-party system.

The response returns the generated reference, which must be stored by the integrating system and used to identify this unit in all subsequent operations.

Request Fields

Field

Type

Required

Description

externalIdentifier

string

No

External identifier of the unit, as set by the integrating system. Maximum length 100 characters.

name

string

No

Name of the unit. Maximum length 256 characters.

categoryName

string

Yes

Category assigned to the unit. Category values are configurable in the Bloxs admin module. Maximum length 256 characters.

extraRelations

array of object

No

Additional relations to link to the unit. Only existing relations can be linked.

extraRelations.extraRelationTypeName

string

No

Relation type to assign to the linked party for this object, for example cleaner or maintenance. Configurable in the Bloxs admin module.

extraRelations.relationReference

string

No

Reference of the relation to link. Must correspond to an existing relation already registered in Bloxs.

remarks

string

No

Free text remarks to store on the unit.

underManagementSince

string (date)

No

Date the unit comes under management. ISO 8601 format, for example 2026-01-01.

complexReference

string

Yes

Reference of the complex the unit belongs to. Must be an existing complex. Maximum length 100 characters.

sectionReference

string

No

Reference of the section the unit belongs to, if applicable. Must be an existing section within the given complex. Maximum length 100 characters.

address.street

string

Yes

Street name of the unit's address. Maximum length 200 characters.

address.houseNumber

string

No

House number of the unit's address, including any suffix. Can also be used to enter a room number. Maximum length 40 characters.

address.postalCode

string

Yes

Postal code of the unit's address. Maximum length 20 characters.

address.city

string

Yes

City of the unit's address. Maximum length 200 characters.

address.countryISOCode

string

Yes

ISO 3166-1 alpha-2 country code of the unit's address, for example \"NL\". Maximum length 2 characters.

rawFloorArea

number (double)

No

Raw floor area of the unit, in square meters, measured according to the NEN2580 standard. Decimals are separated with a period. Minimum 0.01.

rentableFloorArea

number (double)

No

Rentable floor area of the unit, in square meters, measured according to the NEN2580 standard. Decimals are separated with a period. Minimum 0.01.

usableFloorArea

number (double)

No

Usable floor area of the unit, in square meters. Minimum 0.01.

energyIndex

number (double)

No

Energy index of the unit.

divisibleInfo.divisibleType

integer

Yes (within divisibleInfo)

Divisibility type of the unit. Valid values are 1 (SingleUnit), 2 (DivisibleByUnits), or 3 (DivisibleByFloorArea).

divisibleInfo.divisibleFloorAreaType

integer

No

Floor area type used when divisibleType is DivisibleByFloorArea. Valid values are 0 (NA), 1 (RawFloorArea), 2 (RentableFloorArea), or 3 (UsableFloorArea).

divisibleInfo.divisibleValue

number (double)

No

Threshold value used together with divisibleFloorAreaType to determine divisibility.

Response Fields

Field

Type

Required

Description

reference

string

No

Internal identifier generated by Bloxs for the newly created unit. This value must be stored by the integrating system and used to identify the unit in all subsequent operations.

externalIdentifier

string

No

External identifier of the unit, as set by the integrating system.

name

string

No

Name of the unit.

displayName

string

No

Display name of the unit, as shown in Bloxs.

ownerReference

string

No

Reference of the owner the unit belongs to.

categoryName

string

No

Category assigned to the unit.

extraRelations

array of object

No

Additional relations linked to the unit. Empty or omitted when no extra relations are set.

extraRelations.extraRelationTypeName

string

No

Relation type assigned to the linked party for this object.

extraRelations.relationReference

string

No

Reference of the linked relation.

remarks

string

No

Free text remarks stored on the unit.

underManagementSince

string (date-time)

No

Date the unit came under management. ISO 8601 format, for example 2026-01-01T00:00:00.

salesDate

string (date-time)

No

Date the unit was sold, if applicable. ISO 8601 format.

lastModified

string (date-time)

Yes

Date and time the unit was last modified. ISO 8601 format, UTC.

complexReference

string

No

Reference of the complex the unit belongs to.

sectionReference

string

No

Reference of the section the unit belongs to, if applicable.

address.street

string

Yes

Street name of the unit's address. Maximum length 200 characters.

address.houseNumber

string

No

House number of the unit's address, including any suffix. Maximum length 40 characters.

address.postalCode

string

Yes

Postal code of the unit's address. Maximum length 20 characters.

address.city

string

Yes

City of the unit's address. Maximum length 200 characters.

address.countryISOCode

string

Yes

ISO 3166-1 alpha-2 country code of the unit's address. Maximum length 2 characters.

rawFloorArea

number (double)

No

Raw floor area of the unit, in square meters, measured according to the NEN2580 standard. Decimals are separated with a period.

rentableFloorArea

number (double)

No

Rentable floor area of the unit, in square meters, measured according to the NEN2580 standard. Decimals are separated with a period.

usableFloorArea

number (double)

No

Usable floor area of the unit, in square meters.

energyIndex

number (double)

No

Energy index of the unit.

isDivisible

boolean

Yes

Indicates whether the unit can be divided further. Derived from the assigned category.

divisibleInfo.divisibleType

integer

Yes

Divisibility type of the unit. Valid values are 1 (SingleUnit), 2 (DivisibleByUnits), or 3 (DivisibleByFloorArea).

divisibleInfo.divisibleFloorAreaType

integer

No

Floor area type used when divisibleType is DivisibleByFloorArea. Valid values are 0 (NA), 1 (RawFloorArea), 2 (RentableFloorArea), or 3 (UsableFloorArea).

divisibleInfo.divisibleValue

number (double)

No

Threshold value used together with divisibleFloorAreaType to determine divisibility.

" } } }, "components": { "schemas": { "Unit": { "required": [ "address", "categoryName", "complexReference" ], "type": "object", "properties": { "externalIdentifier": { "maxLength": 100, "minLength": 0, "type": "string", "nullable": true }, "name": { "maxLength": 256, "minLength": 0, "type": "string", "nullable": true }, "categoryName": { "maxLength": 256, "minLength": 0, "type": "string" }, "extraRelations": { "type": "array", "items": { "$ref": "#/components/schemas/RealEstateExtraRelationAPIModel" }, "nullable": true }, "remarks": { "type": "string", "nullable": true }, "underManagementSince": { "type": "string", "format": "date", "nullable": true }, "complexReference": { "maxLength": 100, "minLength": 0, "type": "string" }, "sectionReference": { "maxLength": 100, "minLength": 0, "type": "string", "nullable": true }, "address": { "$ref": "#/components/schemas/Address" }, "rawFloorArea": { "maximum": 2147483647, "minimum": 0.01, "type": "number", "format": "double", "nullable": true }, "rentableFloorArea": { "maximum": 2147483647, "minimum": 0.01, "type": "number", "format": "double", "nullable": true }, "usableFloorArea": { "maximum": 2147483647, "minimum": 0.01, "type": "number", "format": "double", "nullable": true }, "energyIndex": { "maximum": 2147483647, "minimum": 0, "type": "number", "format": "double", "nullable": true }, "divisibleInfo": { "$ref": "#/components/schemas/DivisibleInfo" } }, "additionalProperties": false }, "UnitAPIDetailModel": { "type": "object", "properties": { "reference": { "type": "string", "nullable": true }, "externalIdentifier": { "type": "string", "nullable": true }, "name": { "type": "string", "nullable": true }, "displayName": { "type": "string", "nullable": true }, "ownerReference": { "type": "string", "nullable": true }, "categoryName": { "type": "string", "nullable": true }, "extraRelations": { "type": "array", "items": { "$ref": "#/components/schemas/RealEstateExtraRelationAPIModel" }, "nullable": true }, "remarks": { "type": "string", "nullable": true }, "underManagementSince": { "type": "string", "format": "date-time", "nullable": true }, "salesDate": { "type": "string", "format": "date-time", "nullable": true }, "lastModified": { "type": "string", "format": "date-time" }, "address": { "$ref": "#/components/schemas/Address" }, "complexReference": { "type": "string", "nullable": true }, "sectionReference": { "type": "string", "nullable": true }, "rawFloorArea": { "type": "number", "format": "double", "nullable": true }, "rentableFloorArea": { "type": "number", "format": "double", "nullable": true }, "usableFloorArea": { "type": "number", "format": "double", "nullable": true }, "energyIndex": { "type": "number", "format": "double", "nullable": true }, "isDivisible": { "type": "boolean" }, "divisibleInfo": { "$ref": "#/components/schemas/DivisibleInfo" } }, "additionalProperties": false }, "APIErrorMessageModel": { "type": "object", "properties": { "type": { "type": "string", "nullable": true }, "title": { "type": "string", "nullable": true }, "traceId": { "type": "string", "nullable": true }, "status": { "type": "integer", "format": "int32" }, "errors": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "string" }, "nullable": true }, "nullable": true } }, "additionalProperties": false }, "RealEstateExtraRelationAPIModel": { "type": "object", "properties": { "extraRelationTypeName": { "type": "string", "nullable": true }, "relationReference": { "type": "string", "nullable": true } }, "additionalProperties": false }, "Address": { "required": [ "city", "countryISOCode", "postalCode", "street" ], "type": "object", "properties": { "street": { "maxLength": 200, "minLength": 0, "type": "string" }, "houseNumber": { "maxLength": 40, "minLength": 0, "type": "string", "nullable": true }, "postalCode": { "maxLength": 20, "minLength": 0, "type": "string" }, "city": { "maxLength": 200, "minLength": 0, "type": "string" }, "countryISOCode": { "maxLength": 2, "minLength": 0, "type": "string" } }, "additionalProperties": false }, "DivisibleInfo": { "required": [ "divisibleType" ], "type": "object", "properties": { "divisibleType": { "type": "integer", "description": "SingleUnit = 1\nDivisibleByUnits = 2\nDivisibleByFloorArea = 3", "format": "int32", "x-enumNames": [ "SingleUnit", "DivisibleByUnits", "DivisibleByFloorArea" ] }, "divisibleFloorAreaType": { "type": "integer", "description": "NA = 0\nRawFloorArea = 1\nRentableFloorArea = 2\nUsableFloorArea = 3", "format": "int32", "nullable": true, "x-enumNames": [ "NA", "RawFloorArea", "RentableFloorArea", "UsableFloorArea" ] }, "divisibleValue": { "maximum": 2147483647, "minimum": 0, "type": "number", "format": "double", "nullable": true } }, "additionalProperties": false } } } } ````