Developer Portal

Identities

Mapped uses Identities to uniquely identify elements in its knowledge graph and link those entities to external systems through cloud connectors. Whether it’s a sensor in a room, a device on a BACnet network, or a building’s postal address, identities ensure uniqueness, interoperability, and traceability across platforms. An identity acts like a universal name tag for real-world assets, spaces, and people. Identities offer a single source of truth, aligning data from many systems (BMS, BAS, CMMS, connectors), empowering faster integrations, and driving better insights through accurate analytics and automation.

Use Cases

Alarm → Work Order (CMMS)

Goal: When a chiller alarm triggers, automatically open the right CMMS ticket.
Identity Recipe: External Identity on the Thing links the chiller to its CMMS asset record.
Outcome: Accurate, zero‑lookup routing of issues.

Occupancy‑aware setpoints

Goal: Adjust HVAC based on actual room usage.
Identity Recipe: Space Code to precisely map sensors to rooms. External Identity to link to occupancy or ticketing systems.
Outcome: Energy savings and better comfort.

Traffic monitoring with Access Readers

Goal: Understand how and when spaces are accessed.
Identity Recipe: Access Credential Identity tracks unique users through an Access Control connector such as ARD.
Outcome: Identify hotspots for access.

Identity Subclasses

Identity type	What it represents	Where you'll find it
Access Credential Identity	A badge/credential value used to identify an access holder	As a time series value of an Access_Activity_Status Point
BACnet Object ID	The standard unique ID for a BACnet device	On Things (e.g. controllers, BACnet devices)
Email Identity	A person’s email address	On People
External Identity	The ID or tag used by a third‑party system	On Buildings, Floors, Spaces, Things, Work Orders
Floor Level Identity	The level indicator for a floor (e.g., L01, 3)	On Floors
Name Identity	A unique name within a specific scope	On Things and Collections
Postal Address Identity	The address of a building	On Buildings
Space Code	A room/space identifier (often a room number)	On Spaces

Note on scopes: An identity is unique within a scope such as Organization, Connector, Site, Building, Floor or Thing. Scoping prevents naming collisions (e.g., “Room 101” on multiple floors) while still letting you find the right entity.

Example Queries

Most Identity values in the Mapped graph are of Union type, which means they must be queried using an inline fragment under the identities field. Example queries are outlined below for each subclass.

Access Credential Identity

Unlike the other subclasses, the Access Credential Identity is logged under the time series value for an Access_Activity_Status sensor.

Request ResponseCopy1
2
3
4
5
6
7
8
9
10
11
12
13
{
  points(filter: {exactType: {eq: "Access_Activity_Status"}}) {
    id
    name
    exactType
    series(latest: true) {
      timestamp
      value {
        json
      }
    }
  }
}

BACnet Object ID

Use this query to find the BACnet IDs from your organization's Controller and BACnet devices. BACnet object IDs are scoped to a Site within an organization, which means they're unique within that Site.

Request ResponseCopy1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
{
  things(filter: {exactType: {in: ["Controller", "BACnet_Device"]}}) {
    id
    name
    exactType
    identities {
      ... on BACnetObjectId {
        __typename
        dateCreated
        dateUpdated
        id
        scope
        scopeId
        value
      }
    }
  }
}

Email Identity

Each of the People you add as a user to your organization will have a unique email address identity, which you can review with this query.

Request ResponseCopy1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
{
  people {
    id
    name
    identities {
      ... on EmailIdentity {
        __typename
        dateCreated
        dateUpdated
        id
        scope
        scopeId
        value
      }
    }
  }
}

External Identity

External Identities can exist on Buildings, Spaces, Floors, Things and more to reflect identifiers from external data sources. They're often scoped to the organization or to the related connector.

Here's an example from a Building which has a unique identifier from an external data source.

Request ResponseCopy1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
{
  buildings(filter: {id: {eq: "BLDG5o26DguWKu5T9nRvSYn5Em"}}) {
    id
    name
    identities {
      ... on ExternalIdentity {
        __typename
        dateCreated
        dateUpdated
        id
        scope
        scopeId
        value
      }
    }
  }
}

External identities can represent digital twins imported from a third-party solution provider.

Request ResponseCopy1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
{
  spaces {
    id
    name
    identities {
      ... on ExternalIdentity {
        __typename
        dateCreated
        dateUpdated
        id
        scope
        scopeId
        value
      }
    }
  }
}

Floor Level Identity

Floor Level Identity is scoped within a Building, and you can verify it using this query.

Request ResponseCopy1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
{
  buildings {
    id
    name
    floors {
      id
      name
      identities {
        ... on FloorLevelIdentity {
          __typename
          dateCreated
          dateUpdated
          id
          scope
          scopeId
          value
        }
      }
    }
  }
}

Name Identity

Name Identities are more commonly used in Mapped's inference process to derive an entity from another entity, and they may be scoped to a Building or a Thing.

Request ResponseCopy1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
{
  things {
    id
    name
    exactType
    identities {
      ... on NameIdentity {
        __typename
        dateCreated
        dateUpdated
        id
        scope
        scopeId
        value
      }
    }
  }
}

Postal Address Identity

This is a unique address for a Building within an organization.

Request ResponseCopy1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
{
  buildings {
    id
    name
    identities {
      ... on PostalAddressIdentity {
        __typename
        dateCreated
        dateUpdated
        id
        scope
        scopeId
        value
      }
    }
  }
}

Space Code

Space Codes represent an identity within a floor like a room number, and they may be scoped to a Building or a Floor.

Request ResponseCopy1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
{
  buildings(filter: {id: {eq: "BLDG7kLm4nBvXc9zQw3eRt6yU8pA"}}) {
    spaces {
      id
      name
      exactType
      identities {
        ... on SpaceCode {
          __typename
          dateCreated
          dateUpdated
          id
          scope
          scopeId
          value
        }
      }
    }
  }
}