Docs Portal

Identities

Mapped uses Identities to solve the problem the same entity being contributed multiple times by different data sources.

Diagram of a BMS connector contributing a Thing called AHU 3 and a Building called University Gym, and another CMMS Connector contributing a Thing named AHU_3 and a Building called ABC Fitness Center.

Two different data sources -- for example, a Building Management System and a Computerized Maintenance Management System -- might contribute their own source data about the same entities.

Diagram of AHU 3 and AHU_3 brought together through an External Identity from the BMS, and the University Gym and ABC Fitness Center brought together through a shared Postal Address Identity.

Identities bring the same entities from different data sources together -- Things with an External Identity, and Buildings with a Postal Address Identity.

Diagram of a complex Source graph, with many contributions from different sources tied together, compared to the resolved knowledge Graph which has merged many contributions into single entities.

Identities shape the knowledge graph, bringing everything together. 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.

Identities offer a single source of truth, aligning data from many systems (BMS, BAS, CMMS, cloud 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.

Commonly Used Types of Identities

Most entities can have their own specific identity. Buildings have the Postal Address Identity, Floors have the Floor Level Identity, and Spaces and Zones have a Space Code Identity.

Here are the most common use cases for Identity Subclasses. You can find comprehensive Identity Subclass example query structures in our GraphQL API Reference.

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 any entity type
Floor Level Identity	The level indicator for a floor (e.g., L01, 3)	On Floors
Name Identity	A unique name within a specific scope	Things, Collections and more
Postal Address Identity	The address of a building	On Buildings
Space Code	A room/space identifier (often a room number)	On Spaces, Zones
SubBuilding Code	A designated division of a Building	On SubBuildings

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 the most commonly used subclasses.

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
        }
      }
    }
  }
}

SubBuilding Code

SubBuilding Codes represent a significant designated part of a Building, or a structure that's grouped with other SubBuildings into a Building entity, and they're scoped to a Building.

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