attio

# Attio Access the Attio REST API with managed OAuth authentication. Manage CRM objects, records, tasks, comments, and workspace data. ## Quick Start ```bash # List all objects in workspace python <<'EOF' import urllib.request, os, json req = urllib.request.Request('https://gateway.maton.ai/attio/v2/objects') req.add_header('Authorization', f'Bearer {os.environ["MATON_API_KEY"]}') print(json.dumps(json.load(urllib.request.urlopen(req)), indent=2)) EOF ``` ## Base URL ``` https://gateway.maton.ai/attio/{native-api-path} ``` Replace `{native-api-path}` with the actual Attio API endpoint path. The gateway proxies requests to `api.attio.com` and automatically injects your OAuth token. ## Authentication All requests require the Maton API key in the Authorization header: ``` Authorization: Bearer $MATON_API_KEY ``` **Environment Variable:** Set your API key as `MATON_API_KEY`: ```bash export MATON_API_KEY="YOUR_API_KEY" ``` ### Getting Your API Key 1. Sign in or create an account at [maton.ai](https://maton.ai) 2. Go to [maton.ai/settings](https://maton.ai/settings) 3. Copy your API key ## Connection Management Manage your Attio OAuth connections at `https://ctrl.maton.ai`. ### List Connections ```bash python <<'EOF' import urllib.request, os, json req = urllib.request.Request('https://ctrl.maton.ai/connections?app=attio&status=ACTIVE') req.add_header('Authorization', f'Bearer {os.environ["MATON_API_KEY"]}') print(json.dumps(json.load(urllib.request.urlopen(req)), indent=2)) EOF ``` ### Create Connection ```bash python <<'EOF' import urllib.request, os, json data = json.dumps({'app': 'attio'}).encode() req = urllib.request.Request('https://ctrl.maton.ai/connections', data=data, method='POST') req.add_header('Authorization', f'Bearer {os.environ["MATON_API_KEY"]}') req.add_header('Content-Type', 'application/json') print(json.dumps(json.load(urllib.request.urlopen(req)), indent=2)) EOF ``` ### Get Connection ```bash python <<'EOF' import urllib.request, os, json req = urllib.request.Request('https://ctrl.maton.ai/connections/{connection_id}') req.add_header('Authorization', f'Bearer {os.environ["MATON_API_KEY"]}') print(json.dumps(json.load(urllib.request.urlopen(req)), indent=2)) EOF ``` **Response:** ```json { "connection": { "connection_id": "67b77f19-206e-494c-82c2-8668396fc1f1", "status": "ACTIVE", "creation_time": "2026-02-06T03:13:17.061608Z", "last_updated_time": "2026-02-06T03:13:17.061617Z", "url": "https://connect.maton.ai/?session_token=...", "app": "attio", "metadata": {} } } ``` Open the returned `url` in a browser to complete OAuth authorization. ### Delete Connection ```bash python <<'EOF' import urllib.request, os, json req = urllib.request.Request('https://ctrl.maton.ai/connections/{connection_id}', method='DELETE') req.add_header('Authorization', f'Bearer {os.environ["MATON_API_KEY"]}') print(json.dumps(json.load(urllib.request.urlopen(req)), indent=2)) EOF ``` ### Specifying Connection If you have multiple Attio connections, specify which one to use with the `Maton-Connection` header: ```bash python <<'EOF' import urllib.request, os, json req = urllib.request.Request('https://gateway.maton.ai/attio/v2/objects') req.add_header('Authorization', f'Bearer {os.environ["MATON_API_KEY"]}') req.add_header('Maton-Connection', '67b77f19-206e-494c-82c2-8668396fc1f1') print(json.dumps(json.load(urllib.request.urlopen(req)), indent=2)) EOF ``` If omitted, the gateway uses the default (oldest) active connection. ## API Reference ### Objects Objects are the schema definitions (like People, Companies, or custom objects). #### List Objects ```bash GET /attio/v2/objects ``` Returns all system-defined and custom objects in your workspace. #### Get Object ```bash GET /attio/v2/objects/{object} ``` Get a specific object by slug (e.g., `people`, `companies`) or UUID. ### Attributes Attributes define the fields on objects. #### List Attributes ```bash GET /attio/v2/objects/{object}/attributes ``` Returns all attributes for an object. ### Records Records are the actual data entries (people, companies, etc.). #### Query Records ```bash POST /attio/v2/objects/{object}/records/query Content-Type: application/json { "limit": 50, "offset": 0, "filter": {}, "sorts": [] } ``` Query parameters in body: - `limit`: Maximum results (default 500) - `offset`: Number of results to skip - `filter`: Filter criteria object - `sorts`: Array of sort specifications #### Get Record ```bash GET /attio/v2/objects/{object}/records/{record_id} ``` #### Create Record ```bash POST /attio/v2/objects/{object}/records Content-Type: application/json { "data": { "values": { "name": [{"first_name": "John", "last_name": "Doe", "full_name": "John Doe"}], "email_addresses": ["john@example.com"] } } } ``` Note: For `personal-name` type attributes (like `name` on people), you must include `full_name` along with `first_name` and `last_name`. #### Update Record ```bash PATCH /attio/v2/objects/{object}/records/{record_id} Content-Type: application/json { "data": { "values": { "job_title": "Software Engineer" } } } ``` #### Delete Record ```bash DELETE /attio/v2/objects/{object}/records/{record_id} ``` ### Tasks #### List Tasks ```bash GET /attio/v2/tasks?limit=50 ``` Query parameters: - `limit`: Maximum results (default 500) - `offset`: Number to skip - `sort`: `created_at:asc` or `created_at:desc` - `linked_object`: Filter by object type (e.g., `people`) - `linked_record_id`: Filter by specific record - `assignee`: Filter by assignee email/ID - `is_completed`: Filter by completion status (true/false) #### Get Task ```bash GET /attio/v2/tasks/{task_id} ``` #### Create Task ```bash POST /attio/v2/tasks Content-Type: application/json { "data": { "content": "Follow up with customer", "format": "plaintext", "deadline_at": "2026-02-15T00:00:00.000000000Z", "is_completed": false, "assignees": [], "linked_records": [ { "target_object": "companies", "target_record_id": "16f2fc57-5d22-48b8-b9db-8b0e6d99e9bc" } ] } } ``` Required fields: `content`, `format`, `assignees` #### Update Task ```bash PATCH /attio/v2/tasks/{task_id} Content-Type: application/json { "data": { "is_completed": true } } ``` #### Delete Task ```bash DELETE /attio/v2/tasks/{task_id} ``` ### Workspace Members #### List Workspace Members ```bash GET /attio/v2/workspace_members ``` #### Get Workspace Member ```bash GET /attio/v2/workspace_members/{workspace_member_id} ``` ### Self (Token Info) #### Identify Current Token ```bash GET /attio/v2/self ``` Returns workspace info and OAuth scopes for the current access token. ### Comments #### Create Comment ```bash POST /attio/v2/comments Content-Type: application/json { "data": { "format": "plaintext", "content": "This is a comment", "author": { "type": "workspace-member", "id": "{workspace_member_id}" }, "record": { "object": "companies", "record_id": "{record_id}" } } } ``` ### Lists (Requires list_configuration:read scope) #### List All Lists ```bash GET /attio/v2/lists ``` ### Notes (Requires note:read scope) #### List Notes ```bash GET /attio/v2/notes?limit=50 ``` Query parameters: - `limit`: Maximum results (default 10, max 50) - `offset`: Number to skip - `parent_object`: Object slug containing notes - `parent_record_id`: Filter by specific record ## Pagination Attio supports two pagination methods: ### Limit/Offset Pagination ```bash GET /attio/v2/tasks?limit=50&offset=0 GET /attio/v2/tasks?limit=50&offset=50 GET /attio/v2/tasks?limit=50&offset=100 ``` ### Cursor-Based Pagination (for some endpoints) ```bash GET /attio/v2/meetings?limit=50 GET /attio/v2/meetings?limit=50&cursor={next_cursor} ``` Response includes `pagination.next_cursor` when more results exist. ## Code Examples ### JavaScript ```javascript // Query company records const response = await fetch( 'https://gateway.maton.ai/attio/v2/objects/companies/records/query', { method: 'POST', headers: { 'Authorization': `Bearer ${process.env.MATON_API_KEY}`, 'Content-Type': 'application/json' }, body: JSON.stringify({ limit: 10 }) } ); const data = await response.json(); ``` ### Python ```python import os import requests # Query company records response = requests.post( 'https://gateway.maton.ai/attio/v2/objects/companies/records/query', headers={'Authorization': f'Bearer {os.environ["MATON_API_KEY"]}'}, json={'limit': 10} )