NAV
shell javascript

👋 Introduction

Thank you for deciding to read the Attio API Reference!

Our API is designed to make it easy to interact with the data inside of Attio using automated systems.

We have tried to make the Attio API as friendly as possible to developers by using standard REST conventions and JSON responses.

👩‍🏫 Developer Support

As Developers we understand that no API Reference can answer every question.

We have a Developer to Developer support system where if you are working with our API you can immediately speak directly to one of our Engineers.

If you have a question about our API just start a conversation with us using the chat widget on this page and your query will be sent to a member of our engineering team!

🔑 Authentication

API Keys

curl "https://api.attio.com"
    -u aa5c71134eb8e99f97e80785ef4d1dc22c6c5565c4d86a68ca7adf3867ab9447:  
import Attio from "attio"

const attioClient = new Attio("aa5c71134eb8e99f97e80785ef4d1dc22c6c5565c4d86a68ca7adf3867ab9447")

The Attio API uses API keys to identify and authorise calls to the developer API.

These tokens are managed through the Workspace Admin settings inside
the Attio product.

Your API keys are able to authenticate to Attio and perform actions on your account so it's important that you keep them safe in the same way that you would a password.

We accept both Bearer and Basic HTTP Authentication. We recommend using Bearer Authentication.

If you are using HTTP Basic Authentication you should provide your API key as the Basic Authentication username. You can safely leave the password blank.

If you are using HTTP Bearer Authentication you should provide your API key in the Authorization header as the Bearer value.

To keep your API key secure you should always connect to the Attio API using HTTPS.

Scopes

We group endpoints into families of similar endpoints that we refer to as Scopes.

When creating a token you will need to select which scopes you want the token to possess.

A token can only be used on the endpoints which it has been scoped for. Attempting to use an insufficiently scoped token will result in an Authorization error.

🚨 Errors

The Attio API builds on top of HTTP Status Codes to show errors to developers.

Where appropriate the API will include a detailed error message explaining the nature of the issue and how it can be resolved.

Client Errors

These errors are the result of an error on the side of the developer and will need to be addressed in your own code.

We will normally include further information to help resolve the error in the JSON body of the response.

Error Code Description
400 The input provided to the method was invalid. The response body will contain more details to help resolve the issue.
401 The token provided was not accepted. This could be because the token has been revoked or is incorrectly formatted.
402 The workspace this token is connected to does not have an active subscription.
403 The token provided is not authorized for the scope required. The response body will contain details including the scope that was missing.
404 The resource requested could not be found.
429 The IP address making the request has exceeded our rate limits. The request should be retried in a few minutes.

Server Errors

These errors indicate that something went wrong in our systems.

Errors of this category will automatically trigger notifications to our team and we'll start working behind the scenes to address the issue.

Error Code Description
500 An error occurred processing the request. This is normally an application error and will not be solved by retrying the request.
503 Our servers are too busy to handle the request. This issue is normally temporary and will be solved by retrying the request in a few minutes.

💯 Versioning

Our APIs are versioned so that we can continue to safely improve our APIs without affecting your existing code.

When we release updates to our API we will do so, where possible, in a backwards compatible way so that implementations relying on functionality of the API version do not need to be upgraded.

If we ship a change to our APIs that is not backwards compatible we will do so by releasing a new major version of the API such that the old version continues to work as originally described.

Rarely, we might need to remove an old version of the API entirely. Whilst we will try not to do that we will always notify the Administrators of any accounts that have used the deprecated APIs in the 30 days leading up to the deprecation.

Historic Documentation

We only provide documentation for the most recent version of our endpoints.

If you need to access information relating to a previous version of the endpoint please contact Developer Support.

🚦 Rate Limiting

As a multi-tenant service provider we place restrictions on the amount of requests that a single client can generate in order to provide a high quality of service to all of our customers.

By default, we apply a rate limit of 1000 requests per minute.

If your client exceeds this threshold it will be unable to make further requests until the rate limit resets.

When a rate limit is activated you will receive a 429 Too Many Requests response.

We also include a Retry-After Header in our response. The Header's value is the number of seconds remaining until the rate limit resets and can be used to perform load management in your client side code.

📡 Webhooks

Attio allows developers to subscribe to HTTP notification called Webhooks.

Once a webhook is created, Attio will begin to call the nominated Webhook whenever the observed action takes place.

Attio conforms to the Rest Hooks Pattern - an open standard that allows for the dynamic management of Webhooks.

Authenticating Webhooks

When receiving Webhooks it can be hard to know if the webhook you received was sent by us. To resolve this we attach a cryptographic signature to each webhook that we send so you can verify the origin of the request.

Attio includes two HTTP header called X-Attio-Signature and Attio-Signature.

The contents of both headers is always identical - the variations are provided to help traverse different HTTP server setups.

Calculating the Request Signature

echo '{"id": "1ec09c5b-8375-481a-b5cb-8118ce2f1523"}' | openssl dgst -sha256 -hmac aa5c71134eb8e99f97e80785ef4d1dc22c6c5565c4d86a68ca7adf3867ab9447
const isVerified = attioClient.webhooks.verify('{"id": "1ec09c5b-8375-481a-b5cb-8118ce2f1523"}')

The Attio-Signature is calculated using a SHA256 HMAC of the request body using the API Key as the secret key.

We encode the Attio-Signature as a hexadecimal string.

We only sign the request body - which we interpret as a UTF-8 string.

Examples of how to generate the signature are provided in the column to the right.

IP Addresses

Attio delivers Webhooks from a fixed set of IP Addresses.

In some environments with restrictive firewalls it might be necessary to whitelist these IPs.

34.76.181.69/32
34.77.63.171/32
34.77.170.251/32
35.189.212.204/32
35.190.200.137/32
35.205.134.181/32
35.205.218.25/32
35.240.20.227/32
104.155.38.31/32
104.199.25.43/32
34.76.181.69/32
34.77.63.171/32
34.77.170.251/32
35.189.212.204/32
35.190.200.137/32
35.205.134.181/32
35.205.218.25/32
35.240.20.227/32
104.155.38.31/32
104.199.25.43/32

Our current Webhook IP Addresses are:

An IPV4 (CIDR Notation) text list is also provided in the code browser.

🔐 Token Metadata

Show Current Token

Example Request

curl https://api.attio.com/v1/token \
    -u aa5c71134eb8e99f97e80785ef4d1dc22c6c5565c4d86a68ca7adf3867ab9447:

Example Response (Status Code 200)

{
    "id": "1206f6bc-a803-499a-ad75-819ba7884024",
    "workspace": {
        "id": "d8baa3e5-c2ef-42e1-898c-c878e78575d3",
        "name": "Uber",
        "slug": "uber",
        "logo_url": "https://res-5.cloudinary.com/crunchbase-production/image/upload/c_lpad,h_120,w_120,f_auto,b_white,q_auto:eco/r3brbjf6y7thcnqhchq2"
    },
    "scopes": {
        "user_management": "read",
        "record_permission": "read-write",
        "public_collection": "disabled",
        "private_collection": "disabled",
        "task": "read",
        "note": "read-write",
        "webhook": "disabled"
    }
}

Retrieve information about the token being used and the Workspace to which it belongs.

Required Scopes

This endpoint does not require any scopes.

HTTP Request

Request Path

GET https://api.attio.com/v1/token

HTTP Response

Status Code - 200

id
Required string
The Resource ID of the Current Token
workspace
Required object
An object containing information about the Workspace that the Token belongs to
Show child properties
id
Required string
The Resource ID of the Workspace
name
Required string
The Name of the Workspace
slug
Required string
The Unique Slug of the Workspace
logo_url
Optional string
A URL to the Logo Image of the Workspace
scopes
Required object
An object containing the scopes that have been granted to the token
Show child properties
user_management
Optional string
record_permission
Optional string
public_collection
Optional string
private_collection
Optional string
task
Optional string
note
Optional string
webhook
Optional string

🏢 Company Records

Assert Company Record

Example Request

curl https://api.attio.com/v1/companies \
    -X PUT \
    -u aa5c71134eb8e99f97e80785ef4d1dc22c6c5565c4d86a68ca7adf3867ab9447:\
    -H application/json \
    -d '{"name":"Tesla Motors","domains":["tesla.com"],"primary_location":{"city":"Palo Alto","state":"California","country_code":"US"},"social_media":{"twitter":"tesla","linkedin":"tesla-motors","facebook":"tesla","angellist":"tesla","instagram":"teslamotors"}}'

Example Response (Status Code 200)

{
    "id": "7cd94aa9-1dba-4814-88b6-c9c514dd259f",
    "name": "Tesla",
    "logo_url": "https://tesla.com/tesla-logo.png",
    "description": "Tesla is an American electric vehicle company.",
    "domains": [
        "tesla.com"
    ],
    "primary_location": {
        "city": "Palo Alto",
        "state": "California",
        "country_name": "United States of America",
        "country_code": "US"
    },
    "social_media": {
        "twitter": {
            "handle": "tesla",
            "url": "https://twitter.com/tesla"
        },
        "linkedin": {
            "handle": "tesla-motors",
            "url": "https://www.linkedin.com/company/tesla-motors"
        },
        "facebook": {
            "handle": "tesla",
            "url": "https://www.facebook.com/instagram"
        },
        "angellist": {
            "handle": "tesla",
            "url": "https://angel.co/company/uber"
        },
        "instagram": {
            "handle": "teslamotors",
            "url": "https://www.instagram.com/teslamotors/"
        }
    },
    "communication_intelligence": {
        "last_contacted_at": "2020-07-10T17:43:47.421Z",
        "last_contacted_by": {
            "id": "f839e0f6-700e-41c6-908f-f12aefac119c",
            "first_name": "Elon",
            "last_name": "Musk",
            "avatar_url": "https://www.gravatar.com/avatar/63e3e6f3dbc0146f94e7df8369e6bc76?s=256",
            "email_address": "[email protected]",
            "is_admin": true,
            "is_suspended": false
        },
        "strongest_connection_strength": "GOOD",
        "strongest_connection_user": {
            "id": "f839e0f6-700e-41c6-908f-f12aefac119c",
            "first_name": "Elon",
            "last_name": "Musk",
            "avatar_url": "https://www.gravatar.com/avatar/63e3e6f3dbc0146f94e7df8369e6bc76?s=256",
            "email_address": "[email protected]",
            "is_admin": true,
            "is_suspended": false
        }
    },
    "created_at": "2020-07-10T17:43:47.421Z"
}

Create a company, if the company doesn't already exist. Existing companies are matched by their domains, as two companies cannot share the same domain. If no domain is provided, the company will always be created, as companies can share the same company name.

Required Scopes

Scope Required Level
Records Read and Write

HTTP Request

Request Path

PUT https://api.attio.com/v1/companies

Body Parameters

name
Optional string
Name of the company.
domains
Optional array
Domains used by the company. This is an ordered list, as the domains are used for data enrichment.
Optional string
primary_location
Optional object
Primary location of the company.
Show child properties
city
Optional string
Name of the City.
state
Optional string
Name of the State.
country_code
Optional string
Alpha-2 ISO 3166 Country Code.
social_media
Optional object
Show child properties
twitter
Optional string
Twitter handle of the company.
linkedin
Optional string
Linked-In handle of the company.
facebook
Optional string
Facebook handle of the company.
angellist
Optional string
Angellist handle of the company.
instagram
Optional string
Instagram handle of the company.

HTTP Response

Status Code - 200

id
Required string
Resource ID of this Company.
name
Required string
Name of the Company.
logo_url
Optional string
URL of the company logo.
description
Required string
Description of the Company.
domains
Required array
Domains used by the company. This is an ordered list, as the domains are used for data enrichment.
Optional string
primary_location
Required object
Address of the primary location of the company.
Show child properties
city
Required string
City.
state
Required string
State.
country_name
Required string
Country.
country_code
Required string
ISO 3166-1 alpha-2 country code.
social_media
Optional object
Show child properties
twitter
Required object
Twitter user information about the company.
Show child properties
handle
Required string
Twitter handle of the company.
url
Required string
URL of the Twitter account of the company.
linkedin
Required object
Linked-In user information about the company.
Show child properties
handle
Required string
Linked-In handle of the company.
url
Required string
URL of the Linked-In account of the company.
facebook
Required object
Facebook user information about the company.
Show child properties
handle
Required string
Facebook handle of the company.
url
Required string
URL of the Facebook account of the company.
angellist
Required object
Angellist user information about the company.
Show child properties
handle
Required string
Angellist handle of the company.
url
Required string
URL of the Angellist account of the company.
instagram
Required object
Instagram user information about the company.
Show child properties
handle
Required string
Instagram handle of the company.
url
Required string
URL of the Instagram account of the company.
communication_intelligence
Required object
Communication information between your organization and the company.
Show child properties
last_contacted_at
Required date
Last time there was an email between your organisation and the company.
last_contacted_by
Required object
Show child properties
id
Required string
Resource ID of this user.
first_name
Required string
First name of this user.
last_name
Required string
Last name of this user.
avatar_url
Required string
URL to the avatar image of this user.
email_address
Required string
Email address of this user.
is_admin
Required boolean
Whether this user is an administrator.
is_suspended
Required boolean
Whether the user is suspended.
strongest_connection_strength
Required string
Connection Strength between the company and your organization.
strongest_connection_user
Required object
Best connected user to the company.
Show child properties
id
Required string
Resource ID of this user.
first_name
Required string
First name of this user.
last_name
Required string
Last name of this user.
avatar_url
Required string
URL to the avatar image of this user.
email_address
Required string
Email address of this user.
is_admin
Required boolean
Whether this user is an administrator.
is_suspended
Required boolean
Whether the user is suspended.
created_at
Required date
Date this record was created.

👩‍ Person Records

Assert Person Record

Example Request

curl https://api.attio.com/v1/people \
    -X PUT \
    -u aa5c71134eb8e99f97e80785ef4d1dc22c6c5565c4d86a68ca7adf3867ab9447:\
    -H application/json \
    -d '{"first_name":"Elon","last_name":"Musk","email_addresses":["[email protected]"],"primary_location":{"city":"Palo Alto","state":"California","country_code":"US"},"social_media":{"twitter":"elonmusk","linkedin":"elonmusk","facebook":"elonmusk","angellist":"elonmusk","instagram":"elonmusk"}}'

Example Response (Status Code 200)

{
    "id": "7cd94aa9-1dba-4814-88b6-c9c514dd259f",
    "first_name": "Elon",
    "last_name": "Musk",
    "avatar_url": "https://img.fullcontact.com/static/3dd17f95b6506dcec386c9afa298d442_8f82d7fc7af526a1ae066e4badb0d2efd404509aae3d3caf74176e346616fe4b",
    "description": "Elon Musk is an entrepreneur and founder of Tesla and SpaceX.",
    "email_addresses": [
        "[email protected]"
    ],
    "primary_location": {
        "city": "Palo Alto",
        "state": "California",
        "country_name": "United States of America",
        "country_code": "US"
    },
    "social_media": {
        "twitter": {
            "handle": "elonmusk",
            "url": "https://twitter.com/elonmusk"
        },
        "linkedin": {
            "handle": "elonmusk",
            "url": "https://www.linkedin.com/in/elonmusk"
        },
        "facebook": {
            "handle": "elonmusk",
            "url": "https://www.facebook.com/elonmusk"
        },
        "angellist": {
            "handle": "elonmusk",
            "url": "https://angel.co/elonmusk"
        },
        "instagram": {
            "handle": "elonmusk",
            "url": "https://www.instagram.com/p/elonmusk/"
        }
    },
    "communication_intelligence": {
        "last_contacted_at": "2020-07-10T17:43:47.424Z",
        "last_contacted_by": {
            "id": "f839e0f6-700e-41c6-908f-f12aefac119c",
            "first_name": "Elon",
            "last_name": "Musk",
            "avatar_url": "https://www.gravatar.com/avatar/63e3e6f3dbc0146f94e7df8369e6bc76?s=256",
            "email_address": "[email protected]",
            "is_admin": true,
            "is_suspended": false
        },
        "strongest_connection_strength": "GOOD",
        "strongest_connection_user": {
            "id": "f839e0f6-700e-41c6-908f-f12aefac119c",
            "first_name": "Elon",
            "last_name": "Musk",
            "avatar_url": "https://www.gravatar.com/avatar/63e3e6f3dbc0146f94e7df8369e6bc76?s=256",
            "email_address": "[email protected]",
            "is_admin": true,
            "is_suspended": false
        }
    },
    "created_at": "2020-07-10T17:43:47.424Z"
}

Create a person, if the person doesn't already exist. Existing people are matched by their email addresses, as two people cannot share the same email address. If no email address is provided, the person will always be created, as people can share the same name.

Required Scopes

Scope Required Level
Records Read and Write

HTTP Request

Request Path

PUT https://api.attio.com/v1/people

Body Parameters

first_name
Optional string
First name of the person.
last_name
Optional string
Last Name of the person.
email_addresses
Optional array
Email addresses used by the person. This is an ordered list, as the email addresses are used for data enrichment.
Optional string
primary_location
Optional object
Primary location of the person.
Show child properties
city
Optional string
Name of the City.
state
Optional string
Name of the State.
country_code
Optional string
Alpha-2 ISO 3166 Country Code.
social_media
Optional object
Show child properties
twitter
Optional string
Twitter handle of the person.
linkedin
Optional string
Linked-In handle of the person.
facebook
Optional string
Facebook handle of the person.
angellist
Optional string
Angellist handle of the person.
instagram
Optional string
Instagram handle of the person.

HTTP Response

Status Code - 200

id
Required string
Resource ID of the person.
first_name
Required string
First name of the person.
last_name
Required string
Last Name of the person.
avatar_url
Optional string
URL of the person avatar.
description
Required string
Description of the person.
email_addresses
Required array
Email addresses used by the person. This is an ordered list, as the email addresses are used for data enrichment.
Optional string
primary_location
Required object
Address of the primary location of the person.
Show child properties
city
Required string
City.
state
Required string
State.
country_name
Required string
Country.
country_code
Required string
ISO 3166-1 alpha-2 country code.
social_media
Optional object
Show child properties
twitter
Required object
Twitter user information about the person.
Show child properties
handle
Required string
Twitter handle of the person.
url
Required string
URL of the Twitter account of the person.
linkedin
Required object
Linked-In user information about the person.
Show child properties
handle
Required string
Linked-In handle of the person.
url
Required string
URL of the Twitter account of the person.
facebook
Required object
Facebook user information about the person.
Show child properties
handle
Required string
Facebook handle of the person.
url
Required string
URL of the Twitter account of the person.
angellist
Required object
Angellist user information about the person.
Show child properties
handle
Required string
Angellist handle of the person.
url
Required string
URL of the Twitter account of the person.
instagram
Required object
Instagram user information about the person.
Show child properties
handle
Required string
Instagram handle of the person.
url
Required string
URL of the Twitter account of the person.
communication_intelligence
Required object
Twitter user information about the person.
Show child properties
last_contacted_at
Required date
Last time there was an email between your organisation and the person.
last_contacted_by
Required object
Show child properties
id
Required string
Resource ID of this user.
first_name
Required string
First name of this user.
last_name
Required string
Last name of this user.
avatar_url
Required string
URL to the avatar image of this user.
email_address
Required string
Email address of this user.
is_admin
Required boolean
Whether this user is an administrator.
is_suspended
Required boolean
Whether the user is suspended.
strongest_connection_strength
Required string
Connection Strength between the person and your organization.
strongest_connection_user
Required object
Best connected user to the person.
Show child properties
id
Required string
Resource ID of this user.
first_name
Required string
First name of this user.
last_name
Required string
Last name of this user.
avatar_url
Required string
URL to the avatar image of this user.
email_address
Required string
Email address of this user.
is_admin
Required boolean
Whether this user is an administrator.
is_suspended
Required boolean
Whether the user is suspended.
created_at
Required date
Date this record was created.

🙋 Users

List Users

Example Request

curl https://api.attio.com/v1/users \
    -u aa5c71134eb8e99f97e80785ef4d1dc22c6c5565c4d86a68ca7adf3867ab9447:

Example Response (Status Code 200)

[
    {
        "id": "f839e0f6-700e-41c6-908f-f12aefac119c",
        "first_name": "Elon",
        "last_name": "Musk",
        "avatar_url": "https://www.gravatar.com/avatar/63e3e6f3dbc0146f94e7df8369e6bc76?s=256",
        "email_address": "[email protected]",
        "is_admin": true,
        "is_suspended": false
    }
]

List all users.

Required Scopes

Scope Required Level
User Management Read

HTTP Request

Request Path

GET https://api.attio.com/v1/users

HTTP Response

Status Code - 200

Required array
Optional object
Show child properties
id
Required string
Resource ID of this user.
first_name
Required string
First name of this user.
last_name
Required string
Last name of this user.
avatar_url
Required string
URL to the avatar image of this user.
email_address
Required string
Email address of this user.
is_admin
Required boolean
Whether this user is an administrator.
is_suspended
Required boolean
Whether the user is suspended.

🗄 Collections

List Collections

Example Request

curl https://api.attio.com/v1/collections \
    -u aa5c71134eb8e99f97e80785ef4d1dc22c6c5565c4d86a68ca7adf3867ab9447:

Example Response (Status Code 200)

[
    {
        "id": "7cd94aa9-1dba-4814-88b6-c9c514dd259f",
        "name": "7cd94aa9-1dba-4814-88b6-c9c514dd259f"
    }
]

List all collections.

Required Scopes

Scope Required Level
Public Collections Read
Private Collections Read

HTTP Request

Request Path

GET https://api.attio.com/v1/collections

HTTP Response

Status Code - 200

Required array
Optional object
Show child properties
id
Required string
Resource ID of the Collection.
name
Required string
Resource ID of the Collection.
is_public
Required boolean
created_at
Required date