Integration Guide¶

This guide describes the Building X data model and walks you through the sequence of API calls needed to onboard building data. Use the accompanying Postman collection to follow along step by step.

Data Model¶

The Building X APIs are organized around a hierarchy of core resources. Understanding how they relate to each other is essential before making integration calls.

flowchart LR
    Customer -- "has" --> Partition
    Partition -- "contains" --> Location
    Device -. "has-location" .-> Location
    Equipment -. "has-location" .-> Location
    Equipment -. "is-controlled-by" .-> Device
    Equipment -. "has-equipment-type" .-> EquipmentType
    Device -- "hosts\n(point-group)" --> Point
    Equipment -- "has-points\n(point-group)" --> Point
    Point -- "has" --> PointValue

Data Onboarding Sequence¶

The diagram below shows the sequence of API calls to onboard building data, reflecting the steps in the Postman collection.

sequenceDiagram
    autonumber
    participant Client
    participant Auth as Auth Server
    participant Structure as Building Structure API
    participant Ops as Building Operations API
    participant Ingest as Point Value Ingest API

    rect rgb(240, 248, 255)
    Note over Client, Ingest: Phase 1 — Authentication
    Client->>Auth: POST /oauth/token (client_credentials)
    Auth-->>Client: access_token
    end

    rect rgb(240, 255, 240)
    Note over Client, Ingest: Phase 2 — Building Structure
    Client->>Structure: POST /locations (type: Campus + Address)
    Structure-->>Client: campusId
    Client->>Structure: POST /locations (type: Building, isBuildingOf: campusId + Address)
    Structure-->>Client: buildingId
    Client->>Structure: POST /locations (type: Floor, isFloorOf: buildingId)
    Structure-->>Client: floorId
    Client->>Structure: POST /locations (type: Room, isRoomOf: floorId)
    Structure-->>Client: roomId
    Note right of Client: Repeat for additional floors and rooms
    end

    rect rgb(255, 248, 240)
    Note over Client, Ingest: Phase 3 — Device Registration
    Client->>Ops: POST /devices (name, modelName, serialNumber)
    Ops-->>Client: deviceId
    Client->>Structure: PATCH /assets/{deviceId}/relationships/has-location
    Note right of Client: Assign device to a location (e.g. Building)
    end

    rect rgb(248, 240, 255)
    Note over Client, Ingest: Phase 4 — Equipment Setup
    Client->>Structure: GET /equipment-types
    Structure-->>Client: equipmentTypeId (e.g. "meter")
    Client->>Structure: POST /equipment (hasEquipmentType, isControlledBy: deviceId)
    Structure-->>Client: equipmentId
    Client->>Structure: PATCH /assets/{equipmentId}/relationships/has-location
    Note right of Client: Assign equipment to a location
    Note right of Client: Repeat for sub-meters (isPartOf: parent equipmentId)
    end

    rect rgb(255, 255, 240)
    Note over Client, Ingest: Phase 5 — Point Creation & Assignment
    Client->>Structure: POST /point-groups/Device-{deviceId}/points
    Structure-->>Client: pointId
    Client->>Structure: POST /point-groups/Equipment-{equipmentId}/relationships/has-points
    Note right of Client: Assign point to equipment
    Note right of Client: Repeat for each data point
    end

    rect rgb(240, 255, 255)
    Note over Client, Ingest: Phase 6 — Data Ingestion
    Client->>Ingest: POST /points/{pointId}/values (batch of timestamped values)
    Ingest-->>Client: 201 Created
    Note right of Client: Repeat for each point
    end

Phase 1 — Authentication¶

Obtain an access token using the client_credentials grant. See Getting Started for details.

Phase 2 — Building Structure¶

Create the location hierarchy using the Building Structure API. Each location type references its parent through a relationship:

1. Campus — top-level grouping with a postal address and geo-location.
2. Building — linked to the campus via isBuildingOf. Must also have a postal address.
3. Floor — linked to the building via isFloorOf.
4. Room — linked to a floor via isRoomOf.

The Postman collection creates a sample structure with one campus, one building, two floors, and two rooms per floor.

Phase 3 — Device Registration¶

Create a device via the Building Operations API and then assign it to a location using the Building Structure API.

For API-based integrations the device represents a virtual device — a logical data source that connects a third-party cloud system to Building X. This is different from a physical gateway device installed on-site.

Phase 4 — Equipment Setup¶

Equipment represents the logical assets you want to monitor (meters, sensors, etc.).

1. Get equipment types — retrieve the available types (e.g. meter, sensor) from GET /equipment-types.
2. Create equipment — link it to an equipment type (hasEquipmentType) and to the device (isControlledBy).
3. Assign to a location — place the equipment at the appropriate level in the building hierarchy.
4. Build equipment hierarchies — sub-meters or sub-sensors use the isPartOf relationship to reference a parent equipment (e.g. a floor meter is part of the building-level meter).

Phase 5 — Point Creation & Assignment¶

Points are the data interfaces that carry time-series values.

1. Create points on the device — use POST /point-groups/Device-{deviceId}/points to register each data point with its name, data type, unit, and function (sensor, command, or setpoint).
2. Assign points to equipment — use POST /point-groups/Equipment-{equipmentId}/relationships/has-points to link each point to its corresponding equipment.

Phase 6 — Data Ingestion¶

Push time-series values for each point using the Point Value Ingest API:

• Single-point ingestion — POST /points/{pointId}/values with a batch of up to 100 timestamped values.
• Multi-point batch ingestion — POST /points/covs to push 1 value for up to 50 points in a single request.

The Postman collection includes example requests for pushing electricity consumption, occupancy, and indoor air quality data.

Using the Postman Collection¶

The Postman collection contains ready-to-run requests organized into folders matching the phases above. It includes three scenario examples:

Setup¶

1. Import the collection into your tool of choice like Postman, Insomnia or Bruno.

2. Set the following collection variables:

   Variable	Description
   API_URL	The Building X API base URL
   partition	The partition ID to onboard data into

3. Run the Authorize request first — it uses client_credentials to obtain a token and stores it automatically for subsequent requests.

4. Execute the folders in order: 1. Building Structure → 2. Device → 3.x Scenario. Each request auto-saves the created resource IDs into collection variables for use in later steps.

Next Steps¶

• General Information — learn about filtering, pagination, error handling, and other API conventions.
• Try Out APIs — explore all available APIs interactively from the Developer Portal.
• Refer to individual API overviews for detailed resource documentation.