Contents x
    Get units filtered and paged
    • 21 Feb 2025
    • 5 Minutes to read
    • Print
    • Dark
      Light
    Contents

    Get units filtered and paged

    • Updated on 21 Feb 2025
    • 5 Minutes to read
    • Print
    • Dark
      Light
    Article summary

    Get
    /api/v1/realestateobjects/units/filter

    [PREVIEW] Get a paged list of existing units, optionally filtered to the given parameters. A param-based alternative to the '/filter' POST endpoint.

    Description

    Retrieve a paged list of existing units, optionally filtered to the given parameters. The Bloxs real estate objects-api offers 2 options to get units filtered and paged. One is through the POST option, and as an alternative there is a GET operation available. The functional difference is that the POST option offers the ability to sort the results. Furthermore, the POST includes the parameters in the body whereas the GET includes them in the url.

    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 unit can be included in a rental contract. It is part of a larger entity, consisting of multiple units that can also be rented. Examples include a room in a student house or an apartment in a townhouse in Amsterdam. A unit always belongs to a complex, and optionally to a building section. A unit is either part of a complex or part of a building section; it cannot be part of both.

    Use Case

    The Bloxs user has an external App connected to Bloxs. Through this operation the user can display a paged list of units & the related information. This operation can be used if the user wants to display multiple units rather than just a specific one. If the user wants to display a single unit the preference is to use the GET (units) operation.   

    FieldDescription
    paging.pageSizeThe maximum number of pages to be returned per request. The default number is 100 and the maximum is 1.000. If more results are returned than specified in the PageSize, the remaining pages are dropped based on the reference (number).
    paging.pageNumberThis allows the requesting party to specify which of the pages they want to receive.
    nameThe 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.
    externalIdentifierThe unique identifier within the system of the requesting party. This identifier is not generated by the Bloxs system.
    complexReferenceThis allows the requesting party to specify which complexes the requested sections should belong to.

    A complex is a collection of rentable units. This is often under one roof but not necessarily. Example of not being under one roof: the employee housing site from a company, where all the different buildings are considered buildings within a complex. Typically, they are under one roof.
    sectionReference

    This allows the requesting party to specify which section name(s) they want to receive.

    A section refers to sections of a building. Example: A complex containing a building with a shop on the ground floor and three apartments above it. This is a combination of commercial real estate and residential living. Another example: In a large apartment complex (40 apartments), you could create a section per floor. This is especially important for the allocation of service costs. For instance, the ground floor shouldn't pay for the elevator, or the first floor shouldn't pay for the lighting on the fifth floor. Another example: Multiple Homeowners Associations (HOAs) within one complex, hence the need to create sections to divide HOA costs. It is crucial to set this up correctly as it forms the foundation of the object structure in Bloxs: proper cost allocation, reporting purposes, assignment of a 'concierge,' and creation of (service) notifications.

    ownerReferenceProperty owner. This field is used to link the property to its owner. Since a property must have an owner, this field is mandatory. It is part of the contracts triangle of properties, owners, and tenants. The OwnerReference corresponds to the 'Reference' in the Relations. 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.
    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 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.

    addressStreetAndHousenumberStreet and house number of the unit. 
    addressPostalCodePostal Code of the unit.
    addressCityCity in which the unit is located.
    addressCountryISOCodeISO country code. Use the 2-letter code from the ISO 639-1 Code list.

    Response fields

    In addition to the fields in the request, the response also contains the fields in the table below. 

    FieldDescription
    sorting.columnName

    The data field based on which sorting is applied. For example, if the results are sorted based on ascending name, columnName will contain the value 'name'.

    sorting.order

    Based on this value, the property defined in 'columnName' is either sorted ascending (a-z) or descending (z-a).

    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 (.)

    usableFloorAreaThe surface of the floor that can actually be used.
    underManagementSinceFrom 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.
    salesDateDate on which the building was sold.
    lastModifiedDate on which the data for this building was last modified.
    Security
    HTTP
    Type Bearer

    Please enter a valid token

    Query parameters
    pageSize
    integer (int32)

    The requested page size. Defaults to 100 when not given.

    Minimum1
    Maximum1000
    pageNumber
    integer (int32)

    The requested page number. Defaults to 1 when not given.

    Minimum1
    Maximum9999
    name
    string

    Optional filter on the name of the unit.

    reference
    string

    Optional filter on the reference of the unit.

    externalIdentifier
    string

    Optional filter on the external API identifier of the unit.

    complexReference
    string

    Optional filter on the reference of the complex the unit belongs to.

    sectionReference
    string

    Optional filter on the reference of the section the unit belongs to.

    ownerReference
    string

    Optional filter on the reference of the owner of the unit.

    estateAgentReference
    string

    Optional filter on the reference of the estate agent of the unit.

    addressStreetAndHouseNumber
    string

    Optional filter on the street and house number of the address of the unit.

    addressPostalCode
    string

    Optional filter on the postal code of the address of the unit.

    addressCity
    string

    Optional filter on the city of the address of the unit.

    addressCountryISOCode
    string

    Optional filter on the country ISO code of the address of the unit.

    Responses
    200

    OK

    Expand All
    object
    paging
    object (PagingInfo)
    pageSize
    integer (int32) | null
    Minimum1
    Maximum1000
    pageNumber
    integer (int32) | null
    Minimum1
    Maximum9999
    sorting
    object (SortingInfo)
    columnName
    string | null
    order
    integer (int32)

    0 = Ascending

    1 = Descending

    Valid values[ 0, 1 ]
    units
    Array of object (UnitSearchResultFilter) | null
    object
    name
    string | null
    reference
    string | null
    externalIdentifier
    string | null
    complexReference
    string | null
    sectionReference
    string | null
    estateAgentReference
    string | null
    addressStreetAndHouseNumber
    string | null
    addressPostalCode
    string | null
    addressCity
    string | null
    addressCountryISOCode
    string | null
    rawFloorArea
    number (double) | null
    rentableFloorArea
    number (double) | null
    usableFloorArea
    number (double) | null
    underManagementSince
    string (date-time) | null
    salesDate
    string (date-time) | null
    lastModified
    string (date-time)
    What's Next