Imported from jeremylongshore/tons-of-skills-marketplace (plugins/saas-packs/attio-pack/skills/attio-core-workflow-a/SKILL.md). Install upstream with npx skills add jeremylongshore/tons-of-skills-marketplace --skill attio-core-workflow-a. Copyright stays with the author (MIT).

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: object_configuration:read, record_permission: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,
        }],
      },
    },
  }
);

Output

Following this guide produces the Attio integration outcome for its topic—configuration, validation evidence, operational recovery, or a documented migration result. Record command output and relevant identifiers so a failed step is traceable.

Examples

Start with the smallest applicable command or code example in the relevant section, using a dedicated test record or workspace and non-production credentials. Confirm the expected response or validation result before applying the pattern to production.

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.