Slugs and IDs

IDs and Uniqueness

Entities returned from Attio’s API contain an id property which is composed of one or more sub-IDs. The sub-IDs are each a V4 UUID (universally unique identifier) that identifies either the entity or one of its parents.

// Example ID from a Record Response
{
  "data": {
    "id": {
      "workspace_id": "5821c091-cf04-4aab-a72a-f1646dbd6841",
      "object_id": "7c430b6d-fa5b-48c6-bfa7-9520c088c7bc",
      "record_id": "d2c2f990-3af0-4be5-808a-5605549e787f"
    },
    // ...
  }
}

Uniqueness of an ID is only guaranteed when the ID is taken as a whole, using all sub-IDs. For example, it is unsafe to assume in the example above that the Record is the only Record with record_id=”d2c2f990-3af0-4be5-808a-5605549e787f”. The safe assumption is that the Record is the only Record with record_id=”d2c2f990-3af0-4be5-808a-5605549e787f” AND object_id=”7c430b6d-fa5b-48c6-bfa7-9520c088c7bc" AND workspace_id="5821c091-cf04-4aab-a72a-f1646dbd6841".

In practice, such collisions will be rare, but they are important to bear in mind. This is especially true if you are building large integrations which operate on the data of many Workspaces.

If you are only operating on data from your own Workspace, you can essentially disregard the workspace_id key.

Slugs

For ergonomics and readability, Attio’s API utilises slugs across a variety of entities such as Lists, Objects and Attributes. Path parameters, query parameters, request bodies and responses will utilise a unique slug instead of an ID where appropriate.

For example, a request to the Create Record endpoint accepts values keyed by either the Attribute slug or Attribute ID and returns values keyed by slug.

Request

// Slug form
{
    "data": {
        "values": {
            "email_addresses": [
                {
                  "email_address": "[email protected]"
                }
            ]
        }
        // other values...
    }
}

// ID form
{
    "data": {
        "values": {
            "8a8ad54f-9314-4bdb-b867-e62d02a7d333": [
                {
                    "email_address": "[email protected]"
                }
            ]
        }
        // other values...
    }
}

Response

{
    "data": {
        "values": {
	    "email_addresses": [
                {
                    "active_from": "2023-06-01T15:49:08.524000000Z",
                    "active_until": null,
                    "created_by_actor": {
                        "type": "api-token",
                        "id": "d475d597-2900-4c93-841c-9f83154f21dc",
                    },
                    "original_email_address": "[email protected]",
                    "email_address": "[email protected]",
                    "email_domain": "bell-labs.com",
                    "email_root_domain": "bell-labs.com",
                    "email_local_specifier": "r.hamming",
                    "attribute_type": "email-address"
                }
            ],
            // other values...
        }
      // other properties on data...
    }
}

Slugs are set explicitly over the API or created automatically when entities are created through the UI. Slugs are not updated when entities are renamed through the UI.

Slugs must be unique across entities. For example, there cannot be two Attributes with the same slug on the same List.

Slugs of system Attributes and Objects are consistent across time and across Workspaces. Non-system slugs are mutable, so care should be taken when modifying them lest they break any integrations that rely upon them. If you would like to provide resilience against such changes, please use IDs instead.

Slugs are found on the following entities:

• Object (api_slug)
• Attribute (api_slug)
• List (api_slug)
• Status (title)
• Select Option (title)