The BuildingMinds API onboards a Digital Twin of your real-estate portfolio — a connected model of your assets, their tenancy and commercial structure, their energy and resource consumption, and the ESG attributes used for reporting. You push each entity from your own systems as JSON, and BuildingMinds links them into one model using the IDs you provide.

This page is the map: what the entities are, how they relate, and the vocabulary used across the API. New to the API? Start with the Getting Started guide. For field-level detail on any entity, see the API Reference.

How the entities fit together

graph TD
  Address --> Site
  Site --> Building
  Building --> Floor
  Floor --> Space
  Building --> RentalUnit["Rental Unit"]
  RentalUnit --> RentalContract["Rental Contract"]
  RentalContract --> RentalPayment["Rental Payment"]
  RentalContract --> RentalOption["Rental Option"]
  Building --> Meter
  RentalUnit --> Meter
  Meter --> ResourceConsumption["Resource Consumption (raw readings)"]
  Building --> OperationalMeasurement["Operational Measurement (aggregated)"]
  Building --> Certificate
  Building --> EnergyRating["Energy Rating"]
  Building --> Valuation
  Building --> AreaMeasurement["Area Measurement"]

Arrows show the typical belongs-to direction. You reference a parent by the ID you assigned it — and you can send entities in any order: a child that arrives before its parent is held and linked automatically.

The asset hierarchy

The physical structure of your portfolio is a hierarchy. Each level references the one above by ID:

Consumption & metering

How energy, water and waste data flows in:

📘

BuildingMinds performs the aggregation and contextualisation — keep your data raw on the way in. See the Metering Integration Prerequisites.

Tenancy & commercial

ESG & performance

How linking works

You assign every entity a stable external ID. References between entities use those IDs, so:

• Order doesn't matter. Send a child before its parent and it is held, then linked automatically once the parent arrives.
• A record waits for its parents. Until every referenced parent exists, the record stays in a New state; it only advances to Completed once its parents are successfully onboarded. (A Building that references a siteId or addressIds that haven't arrived yet stays New until they do.)
• Re-sending updates. Re-send an entity with the same ID and it updates rather than duplicates — keep your IDs stable.
• Track progress with the batch. Every submission returns a batchId; poll GET /batch/{batchId}/inbound until each record reaches Completed or Published.

Full mechanics are in the Getting Started guide.

Updating and deleting records

Every entity carries an optional eventType field following the pattern <Entity>Added / <Entity>Updated / <Entity>Deleted (e.g. BuildingAdded, OperationalMeasurementUpdated).

• Add / update: omit eventType (or send …Added / …Updated) and submit the record with the same external ID — the record is created or its fields are updated (upsert).
• Delete: submit the record with eventType: <Entity>Deleted. Only that record is removed — linked entities are not cascaded (deleting an Area Measurement, for example, leaves its building untouched).

A partial update only needs the external ID plus the fields you are changing — e.g. re-submit a Building with just its buildingId, its parent IDs, the changed field, and eventType: BuildingUpdated.

📘

Not every entity supports delete — Address, for instance, has only AddressAdded / AddressUpdated.

Dates & formats

Date fields use ISO-8601 in UTC — yyyy-mm-ddThh:mm:ssZ (e.g. 2021-12-01T12:00:00Z). Where only a year is known (e.g. constructionYear, yearOfLastRefurbishment), use the first of January: yyyy-01-01T00:00:00Z.

Glossary