Introduction
Guides
Endpoint reference
Webhook reference
curl --request PUT \
--url https://api.attio.com/v2/objects/users/records \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--data '
{
"data": {
"values": {
"user_id": "123",
"primary_email_address": "[email protected]",
"person": {
"target_object": "people",
"target_record_id": "891dcbfc-9141-415d-9b2a-2238a6cc012d"
},
"workspace": [
{
"target_object": "workspaces",
"target_record_id": "72ef5feaf-4919-4208-b332-1339ab8ba040"
}
]
}
}
}
'{
"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",
"web_url": "https://app.attio.com/salarya/person/bf071e1f-6035-429d-b874-d83ea64ea13b",
"values": {
"person": [
{
"active_from": "2023-01-01T15:00:00.000000000Z",
"active_until": null,
"created_by_actor": {
"type": "system",
"id": null
},
"target_object": "people",
"target_record_id": "891dcbfc-9141-415d-9b2a-2238a6cc012d",
"attribute_type": "record-reference"
}
],
"primary_email_address": [
{
"active_from": "2023-01-01T15:00:00.000000000Z",
"active_until": null,
"created_by_actor": {
"type": "system",
"id": null
},
"original_email_address": "[email protected]",
"email_address": "[email protected]",
"email_domain": "company.com",
"email_root_domain": "company.com",
"email_local_specifier": "person",
"attribute_type": "email-address"
}
],
"user_id": [
{
"active_from": "2023-01-01T15:00:00.000000000Z",
"active_until": null,
"created_by_actor": {
"type": "system",
"id": null
},
"value": "123",
"attribute_type": "text"
}
],
"workspace": [
{
"active_from": "2023-01-01T15:00:00.000000000Z",
"active_until": null,
"created_by_actor": {
"type": "system",
"id": null
},
"target_object": "workspaces",
"target_record_id": "72ef5feaf-4919-4208-b332-1339ab8ba040",
"attribute_type": "record-reference"
}
]
}
}
}Assert a user record
Use this endpoint to create or update user records, using a unique attribute to search for existing users (for example the primary_email_address attribute). If a user is found with the same value for the matching attribute, that user will be updated, otherwise a new user will be created instead. 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.
curl --request PUT \
--url https://api.attio.com/v2/objects/users/records \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--data '
{
"data": {
"values": {
"user_id": "123",
"primary_email_address": "[email protected]",
"person": {
"target_object": "people",
"target_record_id": "891dcbfc-9141-415d-9b2a-2238a6cc012d"
},
"workspace": [
{
"target_object": "workspaces",
"target_record_id": "72ef5feaf-4919-4208-b332-1339ab8ba040"
}
]
}
}
}
'{
"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",
"web_url": "https://app.attio.com/salarya/person/bf071e1f-6035-429d-b874-d83ea64ea13b",
"values": {
"person": [
{
"active_from": "2023-01-01T15:00:00.000000000Z",
"active_until": null,
"created_by_actor": {
"type": "system",
"id": null
},
"target_object": "people",
"target_record_id": "891dcbfc-9141-415d-9b2a-2238a6cc012d",
"attribute_type": "record-reference"
}
],
"primary_email_address": [
{
"active_from": "2023-01-01T15:00:00.000000000Z",
"active_until": null,
"created_by_actor": {
"type": "system",
"id": null
},
"original_email_address": "[email protected]",
"email_address": "[email protected]",
"email_domain": "company.com",
"email_root_domain": "company.com",
"email_local_specifier": "person",
"attribute_type": "email-address"
}
],
"user_id": [
{
"active_from": "2023-01-01T15:00:00.000000000Z",
"active_until": null,
"created_by_actor": {
"type": "system",
"id": null
},
"value": "123",
"attribute_type": "text"
}
],
"workspace": [
{
"active_from": "2023-01-01T15:00:00.000000000Z",
"active_until": null,
"created_by_actor": {
"type": "system",
"id": null
},
"target_object": "workspaces",
"target_record_id": "72ef5feaf-4919-4208-b332-1339ab8ba040",
"attribute_type": "record-reference"
}
]
}
}
}Authorizations
This API uses OAuth 2.0 with the authorization code grant flow.
Query Parameters
The ID or slug of the attribute to use to check if a user already exists. The attribute must be unique. For user records, you can use primary_email_address or user_id, or any additional custom attribute with a unique constraint.
"primary_email_address"
Body
Show child attributes
Show child attributes
This object's keys should be the slugs or IDs of the attributes you wish to update. Below, you'll find documentation for the value types of each standard user attribute. For information on potential custom attributes, refer to our attribute type docs.
Show child attributes
Show child attributes
- Option 1
- Option 2
Show child attributes
Show child attributes
{
"target_object": "people",
"target_record_id": "891dcbfc-9141-415d-9b2a-2238a6cc012d"
}Show child attributes
Show child attributes
An email address string
- Option 1
- Option 2
Show child attributes
Show child attributes
{
"target_object": "people",
"target_record_id": "891dcbfc-9141-415d-9b2a-2238a6cc012d"
}{
"user_id": "123",
"primary_email_address": "[email protected]",
"person": {
"target_object": "people",
"target_record_id": "891dcbfc-9141-415d-9b2a-2238a6cc012d"
},
"workspace": [
{
"target_object": "workspaces",
"target_record_id": "72ef5feaf-4919-4208-b332-1339ab8ba040"
}
]
}Response
Success
Success
Show child attributes
Show child attributes
Show child attributes
Show child attributes
A UUID identifying the workspace this record belongs to.
"14beef7a-99f7-4534-a87e-70b564330a4c"
A UUID identifying the object this record belongs to.
"97052eb9-e65e-443f-a297-f2d9a4a7f795"
A UUID identifying this record.
"bf071e1f-6035-429d-b874-d83ea64ea13b"
When this record was created.
"2022-11-21T13:22:49.061281000Z"
A URL that links directly to the record page in the Attio web application.
"https://app.attio.com/salarya/person/bf071e1f-6035-429d-b874-d83ea64ea13b"
An object with attribute_slug keys, and an array of value objects as the values. Attributes slugs (for example person or primary_email_address) can be used, including custom attribute slugs.
Show child attributes
Show child attributes
Show child attributes
Show child attributes
The point in time at which this value was made "active". active_from can be considered roughly analogous to created_at.
"2023-01-01T15:00:00.000000000Z"
The point in time at which this value was deactivated. If null, the value is active.
"2023-01-01T15:00:00.000000000Z"
The actor that created this value.
Show child attributes
Show child attributes
An ID to identify the actor.
The type of actor. Read more information on actor types here.
api-token, workspace-member, system, app {
"type": "workspace-member",
"id": "50cf242c-7fa3-4cad-87d0-75b1af71c57b"
}A slug identifying the object that the referenced record belongs to.
"people"
A UUID to identify the referenced record.
"891dcbfc-9141-415d-9b2a-2238a6cc012d"
The attribute type of the value.
record-reference "record-reference"
Show child attributes
Show child attributes
The point in time at which this value was made "active". active_from can be considered roughly analogous to created_at.
"2023-01-01T15:00:00.000000000Z"
The point in time at which this value was deactivated. If null, the value is active.
"2023-01-01T15:00:00.000000000Z"
The actor that created this value.
Show child attributes
Show child attributes
An ID to identify the actor.
The type of actor. Read more information on actor types here.
api-token, workspace-member, system, app {
"type": "workspace-member",
"id": "50cf242c-7fa3-4cad-87d0-75b1af71c57b"
}"app.attio.com"
"attio.com"
"alice"
The attribute type of the value.
email-address "email-address"
Show child attributes
Show child attributes
The point in time at which this value was made "active". active_from can be considered roughly analogous to created_at.
"2023-01-01T15:00:00.000000000Z"
The point in time at which this value was deactivated. If null, the value is active.
"2023-01-01T15:00:00.000000000Z"
The actor that created this value.
Show child attributes
Show child attributes
An ID to identify the actor.
The type of actor. Read more information on actor types here.
api-token, workspace-member, system, app {
"type": "workspace-member",
"id": "50cf242c-7fa3-4cad-87d0-75b1af71c57b"
}A raw text field. Values are limited to 10MB.
"Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua."
The attribute type of the value.
text "text"
Show child attributes
Show child attributes
The point in time at which this value was made "active". active_from can be considered roughly analogous to created_at.
"2023-01-01T15:00:00.000000000Z"
The point in time at which this value was deactivated. If null, the value is active.
"2023-01-01T15:00:00.000000000Z"
The actor that created this value.
Show child attributes
Show child attributes
An ID to identify the actor.
The type of actor. Read more information on actor types here.
api-token, workspace-member, system, app {
"type": "workspace-member",
"id": "50cf242c-7fa3-4cad-87d0-75b1af71c57b"
}A slug identifying the object that the referenced record belongs to.
"people"
A UUID to identify the referenced record.
"891dcbfc-9141-415d-9b2a-2238a6cc012d"
The attribute type of the value.
record-reference "record-reference"
{
"person": [
{
"active_from": "2023-01-01T15:00:00.000000000Z",
"active_until": null,
"created_by_actor": { "type": "system", "id": null },
"target_object": "people",
"target_record_id": "891dcbfc-9141-415d-9b2a-2238a6cc012d",
"attribute_type": "record-reference"
}
],
"primary_email_address": [
{
"active_from": "2023-01-01T15:00:00.000000000Z",
"active_until": null,
"created_by_actor": { "type": "system", "id": null },
"original_email_address": "[email protected]",
"email_address": "[email protected]",
"email_domain": "company.com",
"email_root_domain": "company.com",
"email_local_specifier": "person",
"attribute_type": "email-address"
}
],
"user_id": [
{
"active_from": "2023-01-01T15:00:00.000000000Z",
"active_until": null,
"created_by_actor": { "type": "system", "id": null },
"value": "123",
"attribute_type": "text"
}
],
"workspace": [
{
"active_from": "2023-01-01T15:00:00.000000000Z",
"active_until": null,
"created_by_actor": { "type": "system", "id": null },
"target_object": "workspaces",
"target_record_id": "72ef5feaf-4919-4208-b332-1339ab8ba040",
"attribute_type": "record-reference"
}
]
}Was this page helpful?