# Attio

> Customer relationship management platform for managing contacts, companies, and deals with comprehensive CRUD operations.

Source: https://cotera.co/docs/reference/tools/individual-tools/attio

---

**Authentication Type:** API Key\
**Description:** Customer relationship management platform for managing contacts, companies, and deals with comprehensive CRUD operations.

***

## Authentication

To authenticate, you'll need an Attio API key. Learn how to create one in the [Attio Help Center](https://attio.com/help/apps/other-apps/generating-an-api-key).

**Required Scopes:**

* `lists:read-write` - Manage list entries
* `objects:read` - Access object definitions
* `records:read-write` - Create, read, update, and delete records
* `notes:read-write` - Create and manage notes

***

## Lists

Manage custom lists and entries in Attio for organizing related data.

### Add List Entry

Add a new entry to an existing Attio list, linking it to a parent record (company or person) with custom attribute values.

**Operation Type:** Mutation (Write)

**Parameters:**

* **listId** `string` (required): The ID of the list to add the entry to
* **parentRecord** `string` (required): The ID of the parent record
* **parentType** `enum` (required): The type of the parent record
  * Options: "companies", "people"
* **attributes** `array of objects` (required): Array of key-value pairs for attribute values
  * **key** `string` (required): Attribute name
  * **value** `string` (required): Attribute value

**Returns:**

* **id** `object`: List entry ID with workspace, list, and entry identifiers
  * **workspace\_id** `string`: Workspace identifier
  * **list\_id** `string`: List identifier
  * **entry\_id** `string`: Entry identifier
* **parent\_record\_id** `string`: ID of the parent record
* **parent\_object** `string`: Type of parent object
* **created\_at** `string`: Creation timestamp in ISO format
* **entry\_values** `object`: Record of entry values

**Example Usage:**

```json
{
  "listId": "list_123",
  "parentRecord": "record_456",
  "parentType": "companies",
  "attributes": [
    { "key": "status", "value": "active" },
    { "key": "priority", "value": "high" },
    { "key": "deal_value", "value": "50000" }
  ]
}
```

***

## Objects

Manage object definitions and schemas in Attio workspace.

### Get Object

Retrieve the definition and schema of a specific object type (like companies, people, or custom objects) including all its attributes and metadata.

**Operation Type:** Query (Read)

**Parameters:**

* **objectSlug** `string` (required): The unique slug identifier for the object type (e.g., "companies", "people")

**Returns:**

* **id** `object`: Object ID with workspace and object identifiers
  * **workspace\_id** `string`: Workspace identifier
  * **object\_id** `string`: Object identifier
* **api\_slug** `string`: API slug for the object
* **singular\_noun** `string`: Singular form of object name
* **plural\_noun** `string`: Plural form of object name
* **created\_at** `string`: Creation timestamp in ISO format

**Example Usage:**

```json
{
  "objectSlug": "companies"
}
```

### List Objects

Get all available object types in the Attio workspace, including both standard objects (companies, people) and custom objects with their schemas.

**Operation Type:** Query (Read)

**Parameters:**

* None

**Returns:**

* **objects** `array of objects`: Array of all available objects in the workspace
  * **id** `object`: Object ID with workspace and object identifiers
    * **workspace\_id** `string`: Workspace identifier
    * **object\_id** `string`: Object identifier
  * **api\_slug** `string`: API slug for the object
  * **singular\_noun** `string`: Singular form of object name
  * **plural\_noun** `string`: Plural form of object name
  * **created\_at** `string`: Creation timestamp in ISO format

**Example Usage:**

```json
{}
```

***

## Records

Create, read, update, and delete individual records within Attio objects.

### Create Record

Create a new record in an object (company, person, or custom object) with specified attribute values.

**Operation Type:** Mutation (Write)

**Parameters:**

* **objectSlug** `string` (required): The unique slug identifier for the object type (e.g., "companies", "people")
* **values** `array of objects` (required): Array of key-value pairs mapping attribute slugs to values
  * **key** `string` (required): Attribute slug
  * **value** `string` (required): Attribute value

**Returns:**

* **id** `object`: Record ID with workspace, object, and record identifiers
  * **record\_id** `string`: Record identifier
  * **workspace\_id** `string`: Workspace identifier
  * **object\_id** `string`: Object identifier
* **created\_at** `string`: Creation timestamp in ISO format
* **web\_url** `string`: URL to view the record in Attio web interface
* **values** `object`: Record of attribute values (key-value pairs)

**Example Usage:**

```json
{
  "objectSlug": "companies",
  "values": [
    { "key": "name", "value": "Acme Corp" },
    { "key": "domain", "value": "acme.com" },
    { "key": "industry", "value": "Technology" }
  ]
}
```

### Get Record

Retrieve a specific record by its ID, returning all current attribute values and metadata.

**Operation Type:** Query (Read)

**Parameters:**

* **objectSlug** `string` (required): The unique slug identifier for the object type
* **recordId** `string` (required): The unique identifier for the record

**Returns:**

* **id** `object`: Record ID with workspace, object, and record identifiers
  * **record\_id** `string`: Record identifier
  * **workspace\_id** `string`: Workspace identifier
  * **object\_id** `string`: Object identifier
* **created\_at** `string`: Creation timestamp in ISO format
* **web\_url** `string`: URL to view the record in Attio web interface
* **values** `object`: Record of current attribute values (key-value pairs)

**Example Usage:**

```json
{
  "objectSlug": "companies",
  "recordId": "rec_123456789"
}
```

### Update Record

Update specific attribute values of an existing record while preserving other unchanged attributes.

**Operation Type:** Mutation (Write)

**Parameters:**

* **objectSlug** `string` (required): The unique slug identifier for the object type
* **recordId** `string` (required): The unique identifier for the record to update
* **values** `array of objects` (required): Array of key-value pairs for attributes to update
  * **key** `string` (required): Attribute slug
  * **value** `string` (required): New attribute value

**Returns:**

* **id** `object`: Record ID with workspace, object, and record identifiers
  * **record\_id** `string`: Record identifier
  * **workspace\_id** `string`: Workspace identifier
  * **object\_id** `string`: Object identifier
* **created\_at** `string`: Creation timestamp in ISO format
* **web\_url** `string`: URL to view the record in Attio web interface
* **values** `object`: Record of updated attribute values (key-value pairs)

**Example Usage:**

```json
{
  "objectSlug": "people",
  "recordId": "rec_987654321",
  "values": [
    { "key": "job_title", "value": "Senior Software Engineer" },
    { "key": "phone_number", "value": "+1-555-123-4567" }
  ]
}
```

### Assert Record

Create a new record or update an existing one based on matching criteria - useful for upsert operations when you want to avoid duplicates.

**Operation Type:** Mutation (Write)

**Parameters:**

* **objectSlug** `string` (required): The unique slug identifier for the object type
* **values** `array of objects` (required): Array of key-value pairs for attribute values
  * **key** `string` (required): Attribute slug
  * **value** `string` (required): Attribute value
* **matching** `array of objects` (nullable): Optional matching criteria to find existing records
  * **key** `string` (required): Attribute slug to match on
  * **value** `string` (required): Value to match

**Returns:**

* **id** `object`: Record ID with workspace, object, and record identifiers
  * **record\_id** `string`: Record identifier
  * **workspace\_id** `string`: Workspace identifier
  * **object\_id** `string`: Object identifier
* **created\_at** `string`: Creation timestamp in ISO format
* **web\_url** `string`: URL to view the record in Attio web interface
* **values** `object`: Record of attribute values (key-value pairs)

**Example Usage:**

```json
{
  "objectSlug": "companies",
  "values": [
    { "key": "name", "value": "Acme Corp" },
    { "key": "domain", "value": "acme.com" },
    { "key": "employees", "value": "250" }
  ],
  "matching": [{ "key": "domain", "value": "acme.com" }]
}
```

### List Records

Query and retrieve multiple records from an object with support for filtering, pagination, and sorting.

**Operation Type:** Query (Read)

**Parameters:**

* **objectSlug** `string` (required): The unique slug identifier for the object type
* **limit** `number` (required): Maximum number of records to return (default: 25, max: 500)
* **offset** `number` (required): Number of records to skip for pagination
* **filter** `array of objects` (required): Filter criteria to apply to the query
  * **key** `string` (required): Attribute slug to filter on
  * **value** `string` (required): Value to filter by

**Returns:**

* **records** `array of objects`: Array of records matching the query criteria
  * **id** `object`: Record ID with workspace, object, and record identifiers
    * **record\_id** `string`: Record identifier
    * **workspace\_id** `string`: Workspace identifier
    * **object\_id** `string`: Object identifier
  * **created\_at** `string`: Creation timestamp in ISO format
  * **web\_url** `string`: URL to view the record in Attio web interface
  * **values** `object`: Record of attribute values (key-value pairs)
* **has\_more** `boolean`: Whether there are more records available for pagination

**Example Usage:**

```json
{
  "objectSlug": "companies",
  "limit": 50,
  "offset": 0,
  "filter": [
    { "key": "industry", "value": "Technology" },
    { "key": "status", "value": "active" }
  ]
}
```

### Delete Record

Permanently delete a specific record from an object - this action cannot be undone.

**Operation Type:** Mutation (Write)

**Parameters:**

* **objectSlug** `string` (required): The unique slug identifier for the object type
* **recordId** `string` (required): The unique identifier for the record to delete

**Returns:**

* Empty response indicating successful deletion

**Example Usage:**

```json
{
  "objectSlug": "companies",
  "recordId": "rec_123456789"
}
```

### Search Records

Search for records across one or more objects using fuzzy search that matches names, domains, emails, phone numbers, and social handles.

**Operation Type:** Query (Read)

**Parameters:**

* **query** `string` (required): Query string to search for. An empty string returns a default set of results
* **objects** `array of strings` (required): Specifies which objects to filter results by. At least one object must be specified. Accepts object slugs or IDs
* **limit** `number` (nullable): The maximum number of results to return (default: 25, max: 25)
* **requestAs** `enum` (nullable): Specifies the context in which to perform the search
  * Options: "workspace"

**Returns:**

* **data** `array of objects`: Array of search results with record information
  * **id** `object`: Record ID with workspace, object, and record identifiers
    * **record\_id** `string`: Record identifier
    * **workspace\_id** `string`: Workspace identifier
    * **object\_id** `string`: Object identifier
  * **record\_text** `string`: A human-readable label for the record
  * **record\_image** `string` (nullable): The image URL for the record
  * **object\_slug** `string`: The slug of the object this record belongs to
  * **email\_addresses** `array of strings` (nullable): Email addresses (for people objects)
  * **phone\_numbers** `array of strings` (nullable): Phone numbers (for people objects)
  * **domains** `array of strings` (nullable): Company domains (for company objects)

**Example Usage:**

```json
{
  "query": "acme software engineer",
  "objects": ["companies", "people"],
  "limit": 10,
  "requestAs": "workspace"
}
```

***

## Notes

Create and manage notes that can be linked to records for context and communication tracking.

### Create Note

Create a new note with markdown content that can be linked to one or more records (companies, people, etc.) for context.

**Operation Type:** Mutation (Write)

**Parameters:**

* **content** `string` (required): The content/body of the note in markdown format
* **title** `string` (nullable): Optional title for the note
* **linkedRecords** `array of objects` (nullable): Optional array of records to link this note to
  * **recordId** `string` (required): The ID of the record to link to this note
  * **objectSlug** `string` (required): The object type of the record being linked

**Returns:**

* **id** `object`: Note ID with workspace and note identifiers
  * **workspace\_id** `string`: Workspace identifier
  * **note\_id** `string`: Note identifier
* **parent\_object** `string`: Parent object type
* **parent\_record\_id** `string`: Parent record ID
* **title** `string`: Note title
* **content\_plaintext** `string`: Plain text version of content
* **content\_markdown** `string`: Markdown version of content
* **tags** `array of objects`: Note tags for categorization
  * **type** `enum`: Tag type ("record" or "workspace-member")
  * **object** `string` (nullable): Object type (for record tags)
  * **record\_id** `string` (nullable): Record ID (for record tags)
  * **workspace\_member\_id** `string` (nullable): Member ID (for member tags)
* **created\_by\_actor** `object`: Information about who created the note
  * **type** `string`: Actor type
  * **id** `string`: Actor ID
* **created\_at** `string`: Creation timestamp in ISO format

**Example Usage:**

```json
{
  "content": "# Quarterly Business Review\n\n## Key Discussion Points\n- Revenue growth exceeded expectations by 15%\n- Expanding team by 3 new hires\n- Planning product launch for Q2\n\n## Action Items\n- [ ] Send contract renewal proposal\n- [ ] Schedule follow-up meeting\n- [ ] Introduce to product team",
  "title": "Q1 2024 Business Review - Acme Corp",
  "linkedRecords": [
    {
      "recordId": "rec_123456789",
      "objectSlug": "companies"
    },
    {
      "recordId": "rec_987654321",
      "objectSlug": "people"
    }
  ]
}
```

### List Notes

Retrieve notes with optional filtering by linked records, supporting pagination for large result sets.

**Operation Type:** Query (Read)

**Parameters:**

* **recordId** `string` (required): Filter notes linked to a specific record ID
* **objectSlug** `string` (required): Filter notes linked to records of a specific object type
* **limit** `number` (nullable): Maximum number of notes to return (default: 25, max: 500)
* **offset** `number` (nullable): Number of notes to skip for pagination

**Returns:**

* **notes** `array of objects`: Array of notes matching the query criteria
  * **id** `object`: Note ID with workspace and note identifiers
    * **workspace\_id** `string`: Workspace identifier
    * **note\_id** `string`: Note identifier
  * **parent\_object** `string`: Parent object type
  * **parent\_record\_id** `string`: Parent record ID
  * **title** `string`: Note title
  * **content\_plaintext** `string`: Plain text version of content
  * **content\_markdown** `string`: Markdown version of content
  * **tags** `array of objects`: Note tags for categorization
    * **type** `enum`: Tag type ("record" or "workspace-member")
    * **object** `string` (nullable): Object type (for record tags)
    * **record\_id** `string` (nullable): Record ID (for record tags)
    * **workspace\_member\_id** `string` (nullable): Member ID (for member tags)
  * **created\_by\_actor** `object`: Information about who created the note
    * **type** `string`: Actor type
    * **id** `string`: Actor ID
  * **created\_at** `string`: Creation timestamp in ISO format
* **has\_more** `boolean`: Whether there are more notes available for pagination

**Example Usage:**

```json
{
  "recordId": "rec_123456789",
  "objectSlug": "companies",
  "limit": 25,
  "offset": 0
}
```

***

## Calls

Access call recordings and transcripts linked to Attio records.

### Get Transcript

Retrieve the transcript for a specific call recording, including speaker segments with timestamps.

**Operation Type:** Query (Read)

**Parameters:**

* **meetingId** `string` (required): The ID of the meeting/call recording to get the transcript for

**Returns:**

* **meetingId** `string`: The meeting identifier
* **callRecordingId** `string` (nullable): The call recording identifier
* **webUrl** `string` (nullable): URL to view the recording in the web interface
* **rawTranscript** `string` (nullable): Full transcript as plain text
* **segments** `array of objects` (nullable): Transcript segments with speaker attribution
  * **speaker** `string` (nullable): Name of the speaker
  * **speech** `string`: The spoken text
  * **startTime** `number` (nullable): Segment start time in seconds
  * **endTime** `number` (nullable): Segment end time in seconds

**Example Usage:**

```json
{
  "meetingId": "meeting_abc123"
}
```

### List Calls

List call recordings associated with your Attio workspace.

**Operation Type:** Query (Read)

**Parameters:**

* **limit** `number` (nullable): Maximum number of calls to return (default: 25)
* **offset** `number` (nullable): Number of calls to skip for pagination

**Returns:**

* **calls** `array of objects`: Array of call recordings
  * **meetingId** `string`: Meeting identifier
  * **callRecordingId** `string` (nullable): Recording identifier
  * **webUrl** `string` (nullable): URL to view the recording
  * **title** `string` (nullable): Call title
  * **startTime** `string` (nullable): Call start timestamp
  * **endTime** `string` (nullable): Call end timestamp
* **has\_more** `boolean`: Whether there are more calls available

**Example Usage:**

```json
{
  "limit": 25,
  "offset": 0
}
```

***

## Common Use Cases

**Contact Management:**

* Create and update company and person records with comprehensive attribute tracking
* Link related records through custom lists for project management
* Track interactions and communications with detailed markdown notes

**Data Organization:**

* Use custom objects for specialized business processes like deals, projects, or support tickets
* Organize records with custom lists and attributes for flexible data modeling
* Search and filter records by various criteria for efficient data retrieval

**Workflow Automation:**

* Assert records to prevent duplicates during imports and data synchronization
* Bulk operations through list and filter functionality for efficient data management
* Link activities, communications, and notes to relevant records for complete context

**Search and Discovery:**

* Fuzzy search across multiple object types to find related contacts and companies
* Search by names, domains, emails, phone numbers, and social handles
* Use advanced filtering to narrow down results for targeted outreach or analysis