Records

Assert a record

Use this endpoint to create or update people, companies and other records. A matching attribute is used to search for existing records. If a record is found with the same value for the matching attribute, that record will be updated. If no record with the same value for the matching attribute is found, a new record will be created instead. If you would like to avoid matching, please use the Create record endpoint.

If the matching attribute is a multiselect attribute, new values will be added and existing values will not be deleted. For any other multiselect attribute, all values will be either created or deleted as necessary to match the list of supplied values.

Required scopes: record_permission:read-write, object_configuration:read.

PUT

objects

{object}

records

curl --request PUT \
  --url https://api.attio.com/v2/objects/{object}/records \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '{
  "data": {
    "values": {
      "41252299-f8c7-4b5e-99c9-4ff8321d2f96": "Text value",
      "multiselect_attribute": [
        "Select option 1",
        "Select option 2"
      ]
    }
  }
}'

{
  "data": {
    "id": {
      "workspace_id": "14beef7a-99f7-4534-a87e-70b564330a4c",
      "object_id": "97052eb9-e65e-443f-a297-f2d9a4a7f795",
      "record_id": "bf071e1f-6035-429d-b874-d83ea64ea13b"
    },
    "created_at": "2022-11-21T13:22:49.061281000Z",
    "values": {}
  }
}

Authorizations

Authorization

string

header

required

This API uses OAuth 2.0 with the authorization code grant flow.

Path Parameters

object

string

required

A UUID or slug to identify the object the record should belong to.

Example:

"people"

Query Parameters

matching_attribute

string

required

The ID or slug of the attribute to use to check if a record already exists. The attribute must be unique.

Example:

"41252299-f8c7-4b5e-99c9-4ff8321d2f96"

Body

application/json

data

object

required

data.values

object

required

An object with an attribute api_slug or attribute_id as the key, and a single value (for single-select attributes), or an array of values (for single or multi-select attributes) as the values. For complete documentation on values for all attribute types, please see our attribute type docs.

Example:

{
  "41252299-f8c7-4b5e-99c9-4ff8321d2f96": "Text value",
  "multiselect_attribute": ["Select option 1", "Select option 2"]
}

Response

200

application/json

Success

data

object

required

data.id

object

required

data.created_at

string

required

When this record was created.

Example:

"2022-11-21T13:22:49.061281000Z"

data.values

object

required

A record type with an attribute api_slug as the key, and an array of value objects as the values.

data.values.{key}

object[]

data.values.{key}.active_from

string

required

The point in time at which this value was made "active". active_from can be considered roughly analogous to created_at.

Example:

"2023-01-01T15:00:00.000000000Z"

data.values.{key}.active_until

string | null

required

The point in time at which this value was deactivated. If null, the value is active.

Example:

"2023-01-01T15:00:00.000000000Z"

data.values.{key}.created_by_actor

object

required

The actor that created this value.

Example:

{
  "type": "workspace-member",
  "id": "50cf242c-7fa3-4cad-87d0-75b1af71c57b"
}

data.values.{key}.referenced_actor_type

enum<string>

required

The type of the referenced actor. Read more information on actor types here.

Available options:

api-token,

workspace-member,

system,

app

Example:

"workspace-member"

data.values.{key}.referenced_actor_id

string | null

required

The ID of the referenced actor.

Example:

"50cf242c-7fa3-4cad-87d0-75b1af71c57b"

data.values.{key}.attribute_type

enum<string>

required

The attribute type of the value.

Available options:

actor-reference

Example:

"actor-reference"

Was this page helpful?

List records Create a record

curl --request PUT \
  --url https://api.attio.com/v2/objects/{object}/records \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '{
  "data": {
    "values": {
      "41252299-f8c7-4b5e-99c9-4ff8321d2f96": "Text value",
      "multiselect_attribute": [
        "Select option 1",
        "Select option 2"
      ]
    }
  }
}'

{
  "data": {
    "id": {
      "workspace_id": "14beef7a-99f7-4534-a87e-70b564330a4c",
      "object_id": "97052eb9-e65e-443f-a297-f2d9a4a7f795",
      "record_id": "bf071e1f-6035-429d-b874-d83ea64ea13b"
    },
    "created_at": "2022-11-21T13:22:49.061281000Z",
    "values": {}
  }
}

Introduction

Tutorials

How-to guides

Endpoint reference

Assert a record

Authorizations

Path Parameters

Query Parameters

Body

Response