th {
    text-align: left;
}

:not(pre)>code {
  padding: 0.125rem;
}

.mermaid-inline button {
  width: 100%;
  display: flex;
  justify-content: center;
  align-items: center;
}

.mermaid-inline button > a {
  width: 100%;
}

img[alt~="logo"] {
  width: 90px;
}

.rounded-xl {
  border-radius: 10px;
}

.rounded-2xl {
  border-radius: 10px;
}

#navbar div > a[href="/sdk/introduction"] {
  position: relative;
}

#navbar div > a[href="/sdk/introduction"]::after {
  content: "Alpha";
  display: inline-block;
  font-size: 0.7rem;
  font-weight: 600;
  color: #0066ff;
  background-color: rgba(0, 102, 255, 0.1);
  padding: 0.1rem 0.4rem;
  border-radius: 4px;
  margin-left: 0.5rem;

}

#navigation-items > ul > li > a[href="/sdk/introduction"] {
  position: relative;
}

#navigation-items > ul > li > a[href="/sdk/introduction"]::after {
  content: "Alpha";
  display: inline-block;
  font-size: 0.7rem;
  font-weight: 600;
  color: #0066ff;
  background-color: rgba(0, 102, 255, 0.1);
  padding: 0.1rem 0.4rem;
  border-radius: 4px;
  margin-left: 0.5rem;
}

Users and workspaces

Attio Docs

Overview

Objects and lists

Actors

Slugs and IDs

Default values

Archiving vs deleting

An overview of the functionality provided by the App SDK

Introduction to the App SDK

Learn how to build your first app with the App SDK

Creating an app

Sharing your app

Shipping updates

Design guidelines

RecordAction

Registers a bulk action for records in Attio

BulkRecordAction

Methods to imperatively give feedback to the user

Notifying the user

alert()

confirm()

showToast()

showDialog()

<Button />

<Checkbox />

A component for laying out children vertically.

<Column />

<Combobox />

A component that wraps your form inputs and provides an `onSubmit` handler.

<Form />

<NumberInput />

A component for laying out children horizontally.

<Row />

A section of UI with a title. It can be thought of like a `<div/>` in DOM.

<Section />

<SubmitButton />

A block of text whose content can be aligned.

<TextBlock />

<TextInput />

<Toggle />

<Typography />

A non-visual component to get form state when rendering JSX

<WithState />

Form schema

Querying Attio data on the client via GraphQL

Using GraphQL

Imperatively run an asynchronous GraphQL query

runQuery()

A suspenseful hook that returns, and caches, the results of calling one or more async functions, typically to load data from a third-party via server functions.

useAsyncCache()

A hook for creating forms inside your Attio app.

useForm()

useQuery()

Server functions

attioFetch()

Tells you which Attio platform your client code is running inside.

platform

Learn how to create an OAuth 2.0 app to access Attio's REST API

Connect an app to Attio through OAuth

How to ensure your app handles rate limits gracefully

How to handle rate limits

How to apply filters and sorts

How to paginate API results

How to configure webhooks

An overview of the general concept of apps.

What are apps?

Companies and people are available in all workspaces

An object to represent businesses: customers, partners, peers...

Companies

People

An object to represent deals involving people & companies

Deals

An object to represent users of your product

Users

Workspaces

References to workspace members and others

Actor reference

Checkbox

Currency

Date

Domain

Email address

Interaction

Location

(Personal) name

Number

Phone number

Rating

Relationships and one-way links between records

Record reference

Select

Similar to select attributes, originally designed for use in Lists

Status

Human-readable, unconstrained text inputs

Text

A calendar date including time information, stored in UTC

Timestamp

Form Schema

Server Functions

Connections

getUserConnection()

getWorkspaceConnection()

Events

Fires when a connection is added to an app

connection-added

Fires when a connection is removed from an app

connection-removed

Server code that can be executed when called via HTTP from a third party

Webhook Handlers

createWebhookHandler()

deleteWebhookHandler()

updateWebhookHandler()

Learn how to build your first app with the REST API

Configuring webhooks

Rate limiting

Filtering and sorting

Pagination

Configuring OAuth

Use open source libraries to perform OAuth 2.0. You can find a list of libraries here: https://oauth.net/code/

Authorize Endpoint

Token Endpoint

Check whether an access token is valid, and if so, what scopes and identity it grants

Introspect Endpoint

Lists all system-defined and user-defined objects in your workspace.

Required scopes: `object_configuration:read`.

List objects

Creates a new custom object in your workspace.

Required scopes: `object_configuration:read-write`.

Create an object

Gets a single object by its `object_id` or slug.

Required scopes: `object_configuration:read`.

Get an object

Updates a single object. The object to be updated is identified by its `object_id`.

Required scopes: `object_configuration:read-write`.

Update an object

Lists all attributes defined on a specific object or list. Attributes are returned in the order that they are sorted by in the UI.

Required scopes: `object_configuration:read`.

List attributes

Creates a new attribute on either an object or a list.

To create an attribute on an object, you must also have the `object_configuration:read-write` scope.

To create an attribute on a list, you must also have the `list_configuration:read-write` scope.

Create an attribute

Gets information about a single attribute on either an object or a list.

Required scopes: `object_configuration:read`.

Get an attribute

Updates a single attribute on a given object or list.

Required scopes: `object_configuration:read-write`.

Update an attribute

Lists all select options for a particular attribute on either an object or a list.

Required scopes: `object_configuration:read`.

List select options

Adds a select option to a select attribute on an object or a list.

Required scopes: `object_configuration:read-write`.

Create a select option

Updates a select option on an attribute on either an object or a list.

Required scopes: `object_configuration:read-write`.

Update a select option

Lists all statuses for a particular status attribute on either an object or a list.

Required scopes: `object_configuration:read`.

List statuses

Add a new status to a status attribute on either an object or a list.

Required scopes: `object_configuration:read-write`.

Create a status

Update a status on an status attribute on either an object or a list.

Required scopes: `object_configuration:read-write`.

Update a status

Lists people, company or other records, with the option to filter and sort results.

Required scopes: `record_permission:read`, `object_configuration:read`.

List records

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](/reference/post_v2-objects-object-records).

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`.

Assert a record

Creates a new person, company or other record. This endpoint will throw on conflicts of unique attributes. If you would prefer to update records on conflicts, please use the [Assert record endpoint](/reference/put_v2-objects-object-records) instead.

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

Create a record

Gets a single person, company or other record by its `record_id`.

Required scopes: `record_permission:read`, `object_configuration:read`.

Get a record

Use this endpoint to update people, companies, and other records by `record_id`. If the update payload includes multiselect attributes, the values supplied will overwrite/remove the list of values that already exist (if any). Use the `PATCH` endpoint to append multiselect values without removing those that already exist.

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

Update a record (overwrite multiselect values)

Deletes a single record (e.g. a company or person) by ID.

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

Delete a record

Use this endpoint to update people, companies, and other records by `record_id`. If the update payload includes multiselect attributes, the values supplied will be created and prepended to the list of values that already exist (if any). Use the `PUT` endpoint to overwrite or remove multiselect attribute values.

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

Update a record (append multiselect values)

Gets all values for a given attribute on a record. If the attribute is historic, this endpoint has the ability to return all historic values using the `show_historic` query param.

Required scopes: `record_permission:read`, `object_configuration:read`.

List record attribute values

List all entries, across all lists, for which this record is the parent.

Required scopes: `record_permission:read`, `object_configuration:read`, `list_entry:read`.

List record entries

List all lists that your access token has access to. lists are returned in the order that they are sorted in the sidebar.

Required scopes: `list_configuration:read`.

List all lists

Creates a new list.

Once you have your list, add attributes to it using the [Create attribute](/reference/post_v2-target-identifier-attributes) API, and add records to it using the [Add records to list](/reference/post_v2-lists-list-entries) API. 

New lists must specify which records can be added with the `parent_object` parameter which accepts either an object slug or an object ID. Permissions for the list are controlled with the `workspace_access` and `workspace_member_access` parameters.

Please note that new lists must have either `workspace_access` set to `"full-access"` or one or more element of `workspace_member_access` with a `"full-access"` level. It is also possible to receive a `403` billing error if your workspace is not on a plan that supports either advanced workspace or workspace member-level access for lists.

Required scopes: `list_configuration:read-write`.

Create a list

Gets a single list in your workspace that your access token has access to.

Required scopes: `list_configuration:read`.

Get a list

Updates an existing list. Permissions for the list are controlled with the `workspace_access` and `workspace_member_access` parameters. Please note that lists must have either `workspace_access` set to `"full-access"` or one or more element of `workspace_member_access` with a `"full-access"` level. It is also possible to receive a `403` billing error if your workspace is not on a plan that supports either advanced workspace or workspace member level access for lists. Changing the parent object of a list is not possible through the API as it can have unintended side-effects that should be considered carefully. If you wish to carry out a parent object change you should do so through the UI.

Required scopes: `list_configuration:read-write`.

Update a list

Lists entries in a given list, with the option to filter and sort results.

Required scopes: `list_entry:read`, `list_configuration:read`.

List entries

Use this endpoint to create or update a list entry for a given parent record. If an entry with the specified parent record is found, that entry will be updated. If no such entry is found, a new entry will be created instead. If there are multiple entries with the same parent record, this endpoint with return the "MULTIPLE_MATCH_RESULTS" error. When writing to multi-select attributes, all values will be either created or deleted as necessary to match the list of values supplied in the request body.

Required scopes: `list_entry:read-write`, `list_configuration:read`.

Assert a list entry by parent

Adds a record to a list as a new list entry. This endpoint will throw on conflicts of unique attributes. Multiple list entries are allowed for the same parent record

Required scopes: `list_entry:read-write`, `list_configuration:read`.

Create an entry (add record to list)

Gets a single list entry by its `entry_id`.

Required scopes: `list_entry:read`, `list_configuration:read`.

Get a list entry

Use this endpoint to update list entries by `entry_id`. If the update payload includes multiselect attributes, the values supplied will overwrite/remove the list of values that already exist (if any). Use the `PATCH` endpoint to add multiselect attribute values without removing those value that already exist.

Required scopes: `list_entry:read-write`, `list_configuration:read`.

Update a list entry (overwrite multiselect values)

Deletes a single list entry by its `entry_id`.

Required scopes: `list_entry:read-write`, `list_configuration:read`.

Delete a list entry

Use this endpoint to update list entries by `entry_id`. If the update payload includes multiselect attributes, the values supplied will be created and prepended to the list of values that already exist (if any). Use the `PUT` endpoint to overwrite or remove multiselect attribute values.

Required scopes: `list_entry:read-write`, `list_configuration:read`.

Update a list entry (append multiselect values)

Gets all values for a given attribute on a list entry. If the attribute is historic, this endpoint has the ability to return all historic values using the `show_historic` query param.

Required scopes: `list_entry:read`, `list_configuration:read`.

List attribute values for a list entry

Lists all workspace members in the workspace.

Required scopes: `user_management:read`.

List workspace members

Gets a single workspace member by ID.

Required scopes: `user_management:read`.

Get a workspace member

List notes for all records or for a specific record.

Required scopes: `note:read`, `object_configuration:read`, `record_permission:read`.

Get started

Core concepts

Further reading

Users and workspaces