Attio Hello World

Overview

Five progressively deeper API calls that exercise the Attio object/record model. Every call targets

https://api.attio.com/v2

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

email_addresses

phone_numbers

description

primary_location

company

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

// List people whose email contains "example.com"
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

// Create company
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"],
      },
    },
  },
});

// Update person to link to company via record-reference
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

not_found

GET /v2/objects

validation_error

insufficient_scopes

record_permission:read-write

duplicate_record

PUT

Resources

• Attio Create Record
• Attio List Records
• Attio Attribute Types
• Attio Slugs and IDs

Next Steps

Proceed to

attio-local-dev-loop

attio-core-workflow-a