Identities

What are Identities?

The same entity may be contributed multiple times by different data sources, potentially creating duplicates. Additionally, an entity contributed from one cloud source may need to be recognized and ingested by a different cloud destination. Mapped solves both of these problems with Identities.

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.

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

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

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.

{
  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.

{
  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.

{
    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.

{
    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.

{
    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.

{
    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.

{
    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.

{
    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.

{
    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.

{
    subBuildings {
      id
      name
      exactType
      identities {
        ... on SubBuildingCode {
          __typename
          dateCreated
          dateUpdated
          id
          value
          scope
          scopeId
        }
      }
    }
}