Attio Records CRUD (Core Workflow A)

Overview

Complete record lifecycle on the Attio REST API. Records are instances of objects (people, companies, deals, custom). Values are keyed by attribute slug and are always arrays (Attio supports multiselect natively).

Prerequisites

• attio-install-auth completed
• Scopes: objectconfiguration:read, recordpermission:read, record_permission:read-write
• Understanding of Attio attribute types (see reference table below)

Attio Attribute Type Reference

Instructions

Step 1: Create Records

// Create a person
const person = await client.post<{ data: AttioRecord }>(
  "/objects/people/records",
  {
    data: {
      values: {
        email_addresses: ["ada@example.com"],
        name: [{ first_name: "Ada", last_name: "Lovelace", full_name: "Ada Lovelace" }],
        phone_numbers: [{ original_phone_number: "+14155551234" }],
        primary_location: ["London, UK"],
        description: ["Mathematician and first programmer"],
      },
    },
  }
);

// Create a company
const company = await client.post<{ data: AttioRecord }>(
  "/objects/companies/records",
  {
    data: {
      values: {
        name: ["Babbage Analytical Engines"],
        domains: ["babbage.io"],
        description: ["Mechanical computing pioneer"],
        primary_location: ["London, UK"],
      },
    },
  }
);

Step 2: Read a Single Record

// GET /v2/objects/{object_slug}/records/{record_id}
const record = await client.get<{ data: AttioRecord }>(
  `/objects/people/records/${person.data.id.record_id}`
);

// Access values (always arrays)
const fullName = record.data.values.name?.[0]?.full_name;
const email = record.data.values.email_addresses?.[0]?.email_address;

Step 3: Update Records (PATCH vs PUT)

// PATCH: Append to multiselect values
await client.patch<{ data: AttioRecord }>(
  `/objects/people/records/${recordId}`,
  {
    data: {
      values: {
        email_addresses: ["ada.new@example.com"], // Adds to existing emails
      },
    },
  }
);

// PUT: Overwrite (assert) -- replaces all values for specified attributes
await client.put<{ data: AttioRecord }>(
  `/objects/people/records/${recordId}`,
  {
    data: {
      values: {
        email_addresses: ["only-this@example.com"], // Replaces all emails
      },
    },
  }
);

Step 4: Query with Filters and Sorts

// POST /v2/objects/{object}/records/query
const results = await client.post<{ data: AttioRecord[] }>(
  "/objects/companies/records/query",
  {
    // Shorthand filter (equality check)
    filter: {
      domains: "acme.com",
    },
    limit: 25,
  }
);

// Verbose filter with operators
const filtered = await client.post<{ data: AttioRecord[] }>(
  "/objects/people/records/query",
  {
    filter: {
      $and: [
        { email_addresses: { email_address: { $contains: "example.com" } } },
        { name: { last_name: { $eq: "Lovelace" } } },
      ],
    },
    sorts: [
      { attribute: "created_at", field: "created_at", direction: "desc" },
    ],
    limit: 50,
    offset: 0,
  }
);

Available filter operators: $eq, $not_empty, $contains, $gt, $gte, $lt, $lte, $in, $and, $or.

Step 5: Fuzzy Search Across Objects

// POST /v2/records/search -- searches across all objects
const search = await client.post<{ data: AttioRecord[] }>(
  "/records/search",
  {
    query: "Ada Lovelace",
    limit: 10,
  }
);

Step 6: Delete a Record

// DELETE /v2/objects/{object}/records/{record_id}
await client.delete(`/objects/people/records/${recordId}`);

Step 7: Link Records via Record-Reference

// Link a person to a company
await client.patch<{ data: AttioRecord }>(
  `/objects/people/records/${personId}`,
  {
    data: {
      values: {
        company: [{
          target_object: "companies",
          target_record_id: companyId,
        }],
      },
    },
  }
);

Error Handling

Resources

• Attio Create Record
• Attio List Records
• Attio Search Records
• Attio Filtering and Sorting
• Attio Attribute Types

Next Steps

For list/entry operations (pipelines, boards), see attio-core-workflow-b.