Space external IDs

An external ID is your own identifier for a space, stored against that space in XY Sense. Where joining data to your own system covers keeping our id on your side, external IDs are the other direction: keeping your key on ours, so the mapping between your codes and our spaces lives with the space instead of in a table you maintain.

A space can hold any number of external IDs, each under a different name. The name is how you group them, so use one name consistently across your portfolio — acme.roomCode for every room code, rather than a different name per building.

You can set your own external IDs on spaces only. Floors, buildings and locations do not support them through this API.

Typical use

• Keep your room or asset code with the space in XY Sense, and read it back whenever you fetch spaces from the API.
• Recognise a space from an occupancy webhook. Payloads carry our FloorSpaceId, not your external IDs, so include externalIds in the space reference data you cache and match events on FloorSpaceId. See Resolve event data with GraphQL.
• Map the same space into two systems at once, under two names.

Reading external IDs

externalIds returns the external IDs you can manage on a space. Use externalId(name: "...") instead when you already know the name and want the value alone. Names XY Sense manages are left out of both, as described below.

Open in API Explorer

Example query

query SpaceExternalIds {
  floorSpaces(floorId: "a2961d46-971f-4ce1-a66e-7ee7bdb2a204") {
    id
    name
    externalIds {
      name
      value
    }
  }
}

Example response

{
  "data": {
    "floorSpaces": [
      {
        "id": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
        "name": "Meeting Room 4",
        "externalIds": [
          {
            "name": "acme.roomCode",
            "value": "\"L12-MR-04\""
          }
        ]
      }
    ]
  }
}

Values are stored and returned as JSON. A plain string therefore comes back quoted, as above, and needs parsing before you use it.

Availability

Space external IDs are on by default, and can be switched off per customer. If they have been switched off for yours, the mutations return:

{ "errors": [{ "message": "The external ID API is not enabled for this customer." }] }

The reads do not error. externalIds comes back as an empty list and externalId(name: "...") comes back null, so neither result on its own means a space has none set. Talk to your account contact if you need it back on.

Setting an external ID

setSpaceExternalId adds the external ID if that name is not yet set on the space, and replaces the value if it is. It returns true on success.

mutation SetSpaceExternalId {
  setSpaceExternalId(spaceId: "7c9e6679-7425-40de-944b-e07fc1f90ae7", name: "acme.roomCode", value: "L12-MR-04")
}

Both this and the delete below need an API key with write access. See Authentication.

Deleting an external ID

deleteSpaceExternalId takes the current value as well as the name. The delete only goes ahead if the stored value matches, which stops a stale request removing an ID that has since changed.

mutation DeleteSpaceExternalId {
  deleteSpaceExternalId(spaceId: "7c9e6679-7425-40de-944b-e07fc1f90ae7", name: "acme.roomCode", value: "L12-MR-04")
}

Names reserved by XY Sense

Some external ID names belong to XY Sense. They are not returned by the read queries above and cannot be written, so they are invisible through this API entirely:

• anything beginning with $, such as $bim and $bacnet
• serraview, Airthings and Kaiterra, which predate the $ convention and are already in use

Matching on the named ones is exact and case-insensitive, so a name of your own like serraview.ourRef is fine. Writing to a reserved name is rejected:

{
  "errors": [
    {
      "message": "External identifier '$bim' is XY Sense managed and cannot be edited manually."
    }
  ]
}

Pick a name with a prefix of your own, such as acme., and the reservation will never affect you.