Attio
by @byungkyu
Attio API integration with managed OAuth. Manage CRM data including people, companies, and custom objects. Use this skill when users want to create, read, up...
clawhub install attio-apiπ About This Skill
name: attio description: | Attio API integration with managed OAuth. Manage CRM data including people, companies, and custom objects. Use this skill when users want to create, read, update, or delete records in Attio, manage tasks, notes, comments, lists, meetings, or query CRM data. For other third party apps, use the api-gateway skill (https://clawhub.ai/byungkyu/api-gateway). compatibility: Requires network access and valid Maton API key metadata: author: maton version: "1.0" clawdbot: emoji: π§ requires: env: - MATON_API_KEY
Attio
Access the Attio REST API with managed OAuth authentication. Manage CRM objects, records, tasks, notes, comments, lists, list entries, meetings, call recordings, and workspace data.
Quick Start
# List all objects in workspace
python <<'EOF'
import urllib.request, os, json
req = urllib.request.Request('https://api.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://api.maton.ai/attio/{native-api-path}
Maton 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:
export MATON_API_KEY="YOUR_API_KEY"
Getting Your API Key
1. Sign in or create an account at maton.ai 2. Go to maton.ai/settings 3. Copy your API key
Connection Management
Manage your Attio OAuth connections at https://api.maton.ai.
List Connections
python <<'EOF'
import urllib.request, os, json
req = urllib.request.Request('https://api.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
python <<'EOF'
import urllib.request, os, json
data = json.dumps({'app': 'attio'}).encode()
req = urllib.request.Request('https://api.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
python <<'EOF'
import urllib.request, os, json
req = urllib.request.Request('https://api.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:
{
"connection": {
"connection_id": "{connection_id}",
"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
python <<'EOF'
import urllib.request, os, json
req = urllib.request.Request('https://api.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:
python <<'EOF'
import urllib.request, os, json
req = urllib.request.Request('https://api.maton.ai/attio/v2/objects')
req.add_header('Authorization', f'Bearer {os.environ["MATON_API_KEY"]}')
req.add_header('Maton-Connection', '{connection_id}')
print(json.dumps(json.load(urllib.request.urlopen(req)), indent=2))
EOF
If you have multiple connections, always include this header to ensure requests go to the intended account.
Security & Permissions
API Reference
Objects
Objects are the schema definitions (like People, Companies, or custom objects).
#### List Objects
GET /attio/v2/objects
Returns all system-defined and custom objects in your workspace.
#### Get Object
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
GET /attio/v2/objects/{object}/attributes
Returns all attributes for an object.
Records
Records are the actual data entries (people, companies, etc.).
#### Query Records
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 skipfilter: Filter criteria objectsorts: Array of sort specifications#### Get Record
GET /attio/v2/objects/{object}/records/{record_id}
#### Create Record
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
PATCH /attio/v2/objects/{object}/records/{record_id}
Content-Type: application/json{
"data": {
"values": {
"job_title": "Software Engineer"
}
}
}
#### Delete Record
DELETE /attio/v2/objects/{object}/records/{record_id}
Tasks
#### List Tasks
GET /attio/v2/tasks?limit=50
Query parameters:
limit: Maximum results (default 500)offset: Number to skipsort: created_at:asc or created_at:desclinked_object: Filter by object type (e.g., people)linked_record_id: Filter by specific recordassignee: Filter by assignee email/IDis_completed: Filter by completion status (true/false)#### Get Task
GET /attio/v2/tasks/{task_id}
#### Create Task
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, deadline_at, assignees, linked_records
#### Update Task
PATCH /attio/v2/tasks/{task_id}
Content-Type: application/json{
"data": {
"is_completed": true
}
}
#### Delete Task
DELETE /attio/v2/tasks/{task_id}
Workspace Members
#### List Workspace Members
GET /attio/v2/workspace_members
#### Get Workspace Member
GET /attio/v2/workspace_members/{workspace_member_id}
Self (Token Info)
#### Identify Current Token
GET /attio/v2/self
Returns workspace info and OAuth scopes for the current access token.
Comments
#### Create Comment on Record
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}"
}
}
}
Required fields: format, content, author
Plus one of:
record: Object with object slug and record_id (for record comments)entry: Object with list slug and entry_id (for list entry comments)thread_id: UUID of existing thread (for replies)#### Reply to Comment Thread
POST /attio/v2/comments
Content-Type: application/json{
"data": {
"format": "plaintext",
"content": "This is a reply",
"author": {
"type": "workspace-member",
"id": "{workspace_member_id}"
},
"thread_id": "{thread_id}"
}
}
Lists
#### List All Lists
GET /attio/v2/lists
#### Get List
GET /attio/v2/lists/{list_id}
List Entries
#### Query List Entries
POST /attio/v2/lists/{list}/entries/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 skipfilter: Filter criteria objectsorts: Array of sort specifications#### Create List Entry
POST /attio/v2/lists/{list}/entries
Content-Type: application/json{
"data": {
"parent_record_id": "{record_id}",
"parent_object": "companies",
"entry_values": {}
}
}
#### Get List Entry
GET /attio/v2/lists/{list}/entries/{entry_id}
#### Update List Entry
PATCH /attio/v2/lists/{list}/entries/{entry_id}
Content-Type: application/json{
"data": {
"entry_values": {
"status": "Active"
}
}
}
#### Delete List Entry
DELETE /attio/v2/lists/{list}/entries/{entry_id}
Notes
#### List Notes
GET /attio/v2/notes?limit=50
Query parameters:
limit: Maximum results (default 10, max 50)offset: Number to skipparent_object: Object slug containing notesparent_record_id: Filter by specific record#### Get Note
GET /attio/v2/notes/{note_id}
#### Create Note
POST /attio/v2/notes
Content-Type: application/json{
"data": {
"format": "plaintext",
"title": "Meeting Summary",
"content": "Discussed Q1 goals and roadmap priorities.",
"parent_object": "companies",
"parent_record_id": "{record_id}",
"created_by_actor": {
"type": "workspace-member",
"id": "{workspace_member_id}"
}
}
}
Required fields: format, content, parent_object, parent_record_id
#### Delete Note
DELETE /attio/v2/notes/{note_id}
Meetings
#### List Meetings
GET /attio/v2/meetings?limit=50
Query parameters:
limit: Maximum results (default 50, max 200)cursor: Pagination cursor from previous responseUses cursor-based pagination.
#### Get Meeting
GET /attio/v2/meetings/{meeting_id}
Call Recordings
Call recordings are accessed through meetings.
#### List Call Recordings for Meeting
GET /attio/v2/meetings/{meeting_id}/call_recordings?limit=50
Query parameters:
limit: Maximum results (default 50, max 200)cursor: Pagination cursor from previous response#### Get Call Recording
GET /attio/v2/meetings/{meeting_id}/call_recordings/{call_recording_id}
Pagination
Attio supports two pagination methods:
Limit/Offset Pagination
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)
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
// Query company records
const response = await fetch(
'https://api.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
import os
import requestsQuery company records
response = requests.post(
'https://api.maton.ai/attio/v2/objects/companies/records/query',
headers={'Authorization': f'Bearer {os.environ["MATON_API_KEY"]}'},
json={'limit': 10}
)
data = response.json()
Usage Notes
people, companies)full_name when creating recordsformat: "plaintext", deadline_at, assignees array (can be empty), and linked_records array (can be empty)format, content, parent_object, and parent_record_idformat, content, author, plus one of record, entry, or thread_idlimit and offset parameters (or cursor for meetings)curl -g when URLs contain brackets to disable glob parsingjq or other commands, environment variables like $MATON_API_KEY may not expand correctly in some shell environmentsError Handling
| Status | Meaning | |--------|---------| | 400 | Missing Attio connection or validation error | | 401 | Invalid or missing Maton API key | | 403 | Insufficient OAuth scopes | | 404 | Resource not found | | 429 | Rate limited | | 4xx/5xx | Passthrough error from Attio API |
Troubleshooting: API Key Issues
1. Check that the MATON_API_KEY environment variable is set:
echo $MATON_API_KEY
2. Verify the API key is valid by listing connections:
python <<'EOF'
import urllib.request, os, json
req = urllib.request.Request('https://api.maton.ai/connections')
req.add_header('Authorization', f'Bearer {os.environ["MATON_API_KEY"]}')
print(json.dumps(json.load(urllib.request.urlopen(req)), indent=2))
EOF
Troubleshooting: Insufficient Scopes
If you receive a 403 error about missing scopes, contact Maton support at support@maton.ai with the specific operations/APIs you need and your use-case.
Troubleshooting: Invalid App Name
1. Ensure your URL path starts with attio. For example:
https://api.maton.ai/attio/v2/objectshttps://api.maton.ai/v2/objectsResources
π‘ Examples
# List all objects in workspace
python <<'EOF'
import urllib.request, os, json
req = urllib.request.Request('https://api.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
π Tips & Best Practices
#### List Notes
GET /attio/v2/notes?limit=50
Query parameters:
limit: Maximum results (default 10, max 50)offset: Number to skipparent_object: Object slug containing notesparent_record_id: Filter by specific record#### Get Note
GET /attio/v2/notes/{note_id}
#### Create Note
POST /attio/v2/notes
Content-Type: application/json{
"data": {
"format": "plaintext",
"title": "Meeting Summary",
"content": "Discussed Q1 goals and roadmap priorities.",
"parent_object": "companies",
"parent_record_id": "{record_id}",
"created_by_actor": {
"type": "workspace-member",
"id": "{workspace_member_id}"
}
}
}
Required fields: format, content, parent_object, parent_record_id
#### Delete Note
DELETE /attio/v2/notes/{note_id}
Meetings
#### List Meetings
GET /attio/v2/meetings?limit=50
Query parameters:
limit: Maximum results (default 50, max 200)cursor: Pagination cursor from previous responseUses cursor-based pagination.
#### Get Meeting
GET /attio/v2/meetings/{meeting_id}
Call Recordings
Call recordings are accessed through meetings.
#### List Call Recordings for Meeting
GET /attio/v2/meetings/{meeting_id}/call_recordings?limit=50
Query parameters:
limit: Maximum results (default 50, max 200)cursor: Pagination cursor from previous response#### Get Call Recording
GET /attio/v2/meetings/{meeting_id}/call_recordings/{call_recording_id}