Expands

API objects reference other objects by ID. For example, a gadget has a site_id field referencing the site it belongs to. Normally, getting the site’s details would require a second request. Instead, you can ask the API to expand the reference: the response then embeds the full referenced object, saving you the extra round-trip.

To expand a reference, pass the expand query parameter with the name of the reference to expand. The expanded object is added to the response under a new key named after the expand, alongside the original *_id field.

For example, GET /v2/gadgets/{gadget_id} normally returns:

{
  "id": "gad_3merw5pijgst6g8mrhgc",
  "name": "Main door",
  "site_id": "site_3merw5p9deg9z3xrfd2c",
  "device_id": "dev_3merw5pawtprdb33ym9c",
  "actions": [{"id": "open", "name": "Open"}]
}

With GET /v2/gadgets/{gadget_id}?expand=site,device you get the site and device objects embedded:

{
  "id": "gad_3merw5pijgst6g8mrhgc",
  "name": "Main door",
  "site_id": "site_3merw5p9deg9z3xrfd2c",
  "site": {
    "id": "site_3merw5p9deg9z3xrfd2c",
    "name": "Headquarters",
    "...": "..."
  },
  "device_id": "dev_3merw5pawtprdb33ym9c",
  "device": {
    "id": "dev_3merw5pawtprdb33ym9c",
    "name": "Main door controller",
    "...": "..."
  },
  "actions": [{"id": "open", "name": "Open"}]
}

To expand multiple references, separate them with commas: expand=site,device,tags.

Each object supports a specific set of expands, listed in the API reference in each object’s section. Requesting an expand the object doesn’t support fails with 400 Bad Request and a message like Invalid expand 'foo' for object 'gadget'.

To-many expands

Some expands reference a list of objects instead of a single one. For example, members support expand=pins,cards,emails, which embeds arrays of the member’s PINs, cards and emails. These expand to a JSON array.

Nested expands

Expanded objects can themselves be expanded, by chaining names with a dot. Each level expands a reference of the object from the previous level.

For example, on GET /v2/members/{member_id}?expand=group_associations.member_group:

• group_associations embeds the member’s group association objects.
• .member_group additionally embeds the full member group inside each association.

{
  "id": "mem_3merw5pijgst6g8mrhgc",
  "name": "Jane Doe",
  "group_associations": [
    {
      "id": "mga_3merw5q2vyqe614qajqr",
      "member_group_id": "mg_3merw5phpgrk2dj97hpr",
      "member_group": {
        "id": "mg_3merw5phpgrk2dj97hpr",
        "name": "Employees",
        "...": "..."
      }
    }
  ]
}

There is no depth limit, and you can combine nested and plain expands: expand=organization,group_associations.member_group.

Where expands are available

The expand parameter is available on every endpoint that returns objects:

• Get: the returned object is expanded.
• List: every item in data is expanded.
• Create, edit (PATCH) and delete: the returned (created, edited, deleted) object is expanded.
• Reveal endpoints (PINs, member tokens, magic links): the returned object is expanded.

Webhooks can also expand the events they deliver: set the webhook’s expand field to a list of event expands, and the delivered payloads embed the expanded objects.

The expansion is done efficiently server-side (one extra query per expanded relation, not per object), but it does make responses larger. Only expand what you need, especially on list endpoints.

Permissions

Expanded objects follow the same permission rules as fetching them directly: if your token doesn’t have permission to see a referenced object, the expanded key is simply omitted from the response (the *_id field is unaffected). Field-level permissions also apply to the expanded object’s fields.