Actor reference

Actor references are used to link to actors in Attio. You're most likely to encounter this attribute via the created_by attribute which is available on every object, the owner attribute on a deal object, or the strongest_connection_user on a company or person.

Actor reference attributes can be single-select or multi-select.

Please note, in the mobile and web clients, attributes of this type are marked as "User" attributes.

Reading values

Actor reference values have two properties, referenced_actor_type and referenced_actor_id. The referenced_actor_type can be one of "api-token", "workspace-member" or "system". The referenced_actor_id is a UUID, or the value null, that uniquely identifies the actor.

{
  "active_from": "2023-04-03T15:21:06.447000000Z",
  "active_until": null,
  "created_by_actor": {...},
  "attribute_type": "actor-reference",
  "referenced_actor_type": "workspace-member",
  "referenced_actor_id": "fbe75eb0-d704-4d12-9e41-aa187e60ed73"
}

Writing values

Currently, the only type of actor that can be explicitly set in our API is "workspace-member". We may expand this list in future.

When writing references to workspace members, we allow you to identify actors by email addresses. You may do this either by passing an email address string directly, or by using an object with the key workspace_member_email_address.

Actor reference attributes may be multi-select or single-select. When writing to multi-select attributes, you must always wrap values in an array. Single-select attributes accept unwrapped data.

{
  "owner": ["[email protected]"]
}

{
  "owner": "[email protected]"
}

{
  "owner": [
    {
      "workspace_member_email_address": "[email protected]"
    }
  ]
}

You may also specify the actor type and ID explicitly using an object with the keys referenced_actor_type and referenced_actor_id.

{
  "owner": [
    {
      "referenced_actor_type": "workspace-member",
      "referenced_actor_id": "50cf242c-7fa3-4cad-87d0-75b1af71c57b"
    }
  ]
}

Filtering

Actor reference values can only be filtered using both the referenced_actor_type and referenced_actor_id properties. If using explicit operators, only the $eq operator is supported. For example:

{
  "filter": {
    "created_by": {
      "referenced_actor_type": "workspace-member",
      "referenced_actor_id": "ec44a06c-b690-4e4f-95b6-757fb4e2f55f"
    }
  }
}

{
  "filter": {
    "created_by": {
      "referenced_actor_type": "api-token",
    }
  }
}

{
  "filter": {
    "created_by": {
      "referenced_actor_type": {
        "$eq": "api-token"
      }
    }
  }
}