Attio Hello World
Overview
Five progressively deeper API calls that exercise the Attio object/record model. Every call targets https://api.attio.com/v2 and returns JSON.
Prerequisites
- Completed
attio-install-auth (valid ATTIO_API_KEY in env)
- Scopes:
object_configuration:read, record_permission:read, record_permission:read-write
Instructions
Step 1: List Workspace Objects
Every Attio workspace has system objects (people, companies) and optional objects (deals, users, workspaces). Custom objects can be created.
curl -s https://api.attio.com/v2/objects \
-H "Authorization: Bearer ${ATTIO_API_KEY}" | jq '.data[] | {slug: .api_slug, singular: .singular_noun}'
{"slug": "people", "singular": "Person"}
{"slug": "companies", "singular": "Company"}
{"slug": "deals", "singular": "Deal"}
Step 2: List Attributes on an Object
Objects have attributes (fields). Use the slug from Step 1.
curl -s "https://api.attio.com/v2/objects/people/attributes" \
-H "Authorization: Bearer ${ATTIO_API_KEY}" | jq '.data[] | {slug: .api_slug, type: .type}'
Common people attributes: name (personal-name), email_addresses (email-address), phone_numbers (phone-number), description (text), primary_location (location), company (record-reference).
Step 3: Create a Person Record
const person = await attioFetch<{ data: { id: { record_id: string } } }>({
method: "POST",
path: "/objects/people/records",
body: {
data: {
values: {
email_addresses: ["ada@example.com"],
name: [
{
first_name: "Ada",
last_name: "Lovelace",
full_name: "Ada Lovelace",
},
],
description: ["First computer programmer"],
},
},
},
});
console.log("Created person:", person.data.id.record_id);
Key detail: Values are keyed by attribute slug. Most attributes accept an array (Attio supports multiselect by default). String shortcuts work for emails and domains.
Step 4: Query Records with Filters
const results = await attioFetch<{
data: Array<{ id: { record_id: string }; values: Record<string, any> }>;
}>({
method: "POST",
path: "/objects/people/records/query",
body: {
filter: {
email_addresses: {
email_address: { $contains: "example.com" },
},
},
sorts: [
{
attribute: "created_at",
field: "created_at",
direction: "desc",
},
],
limit: 10,
},
});
console.log(`Found ${results.data.length} people`);
Step 5: Create a Company and Link It
const company = await attioFetch<{ data: { id: { record_id: string } } }>({
method: "POST",
path: "/objects/companies/records",
body: {
data: {
values: {
name: ["Acme Corp"],
domains: ["acme.com"],
description: ["Enterprise widget manufacturer"],
},
},
},
});
await attioFetch({
method: "PATCH",
path: `/objects/people/records/${person.data.id.record_id}`,
body: {
data: {
values: {
company: [
{
target_object: "companies",
target_record_id: company.data.id.record_id,
},
],
},
},
},
});
Attio Data Model Quick Reference
Workspace
└── Objects (people, companies, deals, custom)
├── Attributes (name, email, phone, custom)
└── Records (individual people, companies)
└── Values (attribute data on each record)
└── Lists (pipelines, boards, custom groupings)
└── Entries (records added to a list with list-specific attributes)
Error Handling
| Error | Status | Cause | Solution |
|---|
not_found | 404 | Wrong object slug or record ID | Verify slug with GET /v2/objects |
validation_error | 422 | Invalid attribute value format | Check attribute type in docs |
insufficient_scopes | 403 | Token missing write scope | Add record_permission:read-write |
duplicate_record | 409 | Record with same unique field exists | Use PUT (assert) instead |
Resources
Next Steps
Proceed to attio-local-dev-loop for development workflow, or attio-core-workflow-a for record CRUD patterns.
