- 28 Mar 2025
- 6 Minutes to read
- Print
- DarkLight
Get a building
- Updated on 28 Mar 2025
- 6 Minutes to read
- Print
- DarkLight
Get an existing building. Either reference or externalIdentifier must have a value. If both are given, both are used for retrieving the building.
Description
Retrieve the information currently known in the Bloxs database about a certain building. Either reference or externalIdentifier must have a value. Please note that if both identifiers are given, both must match; otherwise, an error message will be generated. It is recommended that the user utilizes only one identifier, with a preference for the reference.
A building is a standalone entity. It refers to a terraced house or an entire building that is not divided into multiple parts. A building is a rentable unit. If it contains multiple rental units, it is no longer considered a single building. A building can be included in a rental contract.
Use Case
Through this operation the user can display a specific building and the related information. For example the user wants to display all the information of the building to see which data points need to be adjusted. This endpoint can also be used to retrieve the reference, in case the value is not known to the user.
Request fields
The request contains the following fields:
Field | Description |
---|---|
reference | The relationship number within Bloxs. This is unique (per client specific environment) for all objects. The relationship number is generated by the Bloxs system. |
externalIdentifier | The unique identifier within the system of the requesting party. This identifier is not generated by the Bloxs system. |
Response fields
The response contains the fields in the table below. For the GET operation it gives a up-to-date insight in the data that is currently registered in Bloxs.
Field | Description |
---|---|
reference | The relationship number within Bloxs. This is unique (per client specific environment) for all objects. The relationship number is generated by the Bloxs system . |
externalIdentifier | The unique identifier within the system of the requesting party. This identifier is not generated by the Bloxs system. |
name | The custom name assigned to the object. This is used for reporting and to distinguish the object when the address alone is insufficient. In the case of room rentals, this would be the address + room number. This name can also be displayed on invoices and bills. |
displayName | A combination of the 'address' & the 'name' of the object. |
ownerReference | Property owner. This field is used to link the property to its owner. It is part of the contracts triangle of properties, owners, and tenants. The OwnerReference corresponds to the 'Reference' in the Relations. API. This unique ID is generated by the Bloxs portal and should not be confused with the external identifier. A property can have only one owner. |
categoryName | The name of the category. The category describes what type of object it concerns and gives an indication of what the purpose of the building is. Examples are: House, office or shop. The enumeration can be set by the user in the admin module. In the administration, there is already a default list created by Bloxs, which can be modified by the user. In order to retrieve the available list of categories, the following GET can be used: Get a list of categories. |
extraRelations | Via this field any existing relation (Person, organisation, supplier, Owner or Estate Agent) can be linked to this object. For example, if a certain person is responsible for the maintenance, this field can be used to link this person to the object. Note that only existing relations can be linked. New relations should be entered through the relations-api insert operations. If the user does not know the detailed information of the relation that should be linked, one of the GET operations from the relations API should be used. The owner of the property should be added through the field 'ownerReference'. The estate agent of the property should be added through the field 'EstateAgentReference'. All other relations that should be linked can be entered through extraRelations. |
extraRelations.extraRelationTypeName | The relation type of the existing relation that should be linked to this object. This is a separate field from the 'RelationTypeName' in the relations-api. The extraRelationTypeName refers to the relation type specifically assigned to the object. For example, a person has the relationTypeName 'maintenance' assigned. However, for this specific object the person performs the role of cleaner rather than maintenance. Through the field extraRelationTypeName the role of 'cleaner' can be assigned. The enumeration can be set by the user in the admin module. In the administration, there is already a default list created by Bloxs, which can be modified by the user. In order to retrieve the available list of relation types, the following GET operation can be used: GET extraRelationTypes. |
extraRelations.relationReference | The reference of the existing relation that should be linked to this object. The reference should be identical to the reference such as registered in the Bloxs application. |
remarks | Comments for free text. Anything that cannot be entered in the other fields can be entered here. It is important not to enter sensitive information here such as passwords, personal data, etc. |
underManagementSince | From this date, the user has become the manager of the object. The date is initially entered and remains unchanged until the sale/termination of management. |
salesDate | This is the date on which the object was sold or is no longer under management. Entering this date will result in the object being archived, and it will no longer be selectable in lists, etc. This date cannot be filled in if the object still has active contracts. |
lastModified | Timestamp of the last modification within Bloxs (determined by Bloxs). |
address | The address of the object. |
street | The street of the object. |
houseNumber | The house number of the object. |
postalCode | The postal code of the object. |
city | The place (city/town) in which the object is situated. |
countryISOCode | ISO country code. Use the 2-letter code from the ISO 639-1 Code list. |
regionName | Additional field for adding a region to a property This field allows you to add a region to a property. For managers with multiple properties, they may have grouped properties based on regions, such as neighborhoods, or areas like Gelderland-Noord, Amsterdam Zuid, etc. This is a standard list but can be configured by the user in the Bloxs application. In order to retrieve the full list of RegionNames, the following GET operation can be used: Get a list of regions. |
rawFloorArea | Gross Floor Area. The total measured floor area according to the NEN2580 standards. Decimals are separated with a period (.). |
rentableFloorArea | Rentable Floor Area. Rentable floor area according to the NEN2580 standards. Decimals are separated with a period (.) |
usableFloorArea | The surface of the floor that can actually be used. |
energyIndex | A representation of the energy performance of the property. More accurate than an energy label. Defined as a numerical value. The value can have decimals which should be entered with a dot (.). |
estateAgentReference | Real estate agent for the property. This field links the property to a real estate agent. It must be an existing agent who has been previously added either through the Bloxs application or via the relations-API. The estateAgentReference corresponds to the 'Reference' previously assigned to the real estate agent. This unique ID is generated by the Bloxs application and should not be confused with the external identifier. A property can have only one real estate agent. |
technicalManagement | Boolean. Indicates whether you are responsible for the technical management of the property. If no (False), then by default, the owner is always responsible. Default value is false. |
financialManagement | Boolean. Indicates whether you are responsible for the financial management of the property. If no (False), then by default, the owner is always responsible. Default value is false. |
mandateAmount | The mandate amount pertains to technical management and indicates the limit up to which the manager has the mandate to approve repairs, maintenance, etc., before the owner's approval is required. The value can have decimals which should be entered with a dot (.). |
constructionYear | The year of construction of the property indicates the year in which the building was built. |
Please enter a valid token
The internal identifier of the model (i.e. Reference, Code, Name, depends on model).
The external API identifier of the model.
OK
The requested building was not found.