Attio Companies API

October 1, 2025 · View on GitHub

The Companies API allows you to manage company records in Attio. Companies are a standard object type that represents organizations in your CRM.

💡 Universal Tools Available: The MCP server now provides Universal Tools that consolidate company operations into 13 powerful tools with resource_type: 'companies'. See the Migration Guide for updating existing implementations.

Using Claude with the Companies API

Claude can help you interact with company records in Attio through the MCP server using both the direct API and the new universal tools system. Here are some common tasks and example prompts:

Universal Tools for Company Operations

The MCP server provides enhanced filtering capabilities for company records through the universal tools system. Key tools for companies include:

records.search with resource_type: 'companies' - Replaces search-companies
records.search_advanced with resource_type: 'companies' - Complex filtering with multiple conditions
records.get_details with resource_type: 'companies' - Replaces get-company-details
create-record with resource_type: 'companies' - Replaces create-company
records.batch with resource_type: 'companies' - Bulk company operations

Features:

Complex filtering with multiple conditions
Logical operators (AND/OR)
All comparison operators (equals, contains, starts_with, etc.)
Filtering by any company attribute including name, website, and industry
Consistent API across all resource types

See the Universal Tools API Reference for detailed schemas and the Advanced Filtering documentation for filtering capabilities.

Searching for Companies

You can ask Claude to search for companies using various criteria with both the direct API and universal tools:

Using Universal Tools (Recommended):

Find companies in the technology industry using records.search

Search for companies with "software" in their name using records.search_advanced

Using Direct API:

Look up Microsoft in our CRM

Viewing Company Details

Once Claude has found a company, you can ask for specific details using either approach:

Using Universal Tools (Recommended):

Get company details using records.get_details for attio://companies/record_01abcdefghijklmnopqrstuv

Get company contact info using records.get_info for Acme Corporation

Using Direct API:

What's the website for Acme Corporation?

Working with Company Notes

Claude can read and create notes for companies:

What are the recent notes for Acme Corporation?

Add a note to Microsoft about our recent sales call

Example Workflow

Here's an example of a complete workflow with Claude:

Search: "Find technology companies we added in the last month"
Select: "Tell me more about NewTech Inc."
Notes: "What notes do we have for them?"
Create: "Add a note that they're interested in our enterprise plan"

Version Information

API Version: v2
Last Updated: 2023-07-10

Required Scopes

Companies operations require the following scopes:

companies:read - For reading company records
companies:read-write - For creating, updating, or deleting company records

Endpoints

List Companies

GET /v2/companies

Retrieves a list of companies with pagination support.

Query Parameters

Parameter	Type	Description
page	number	Page number to retrieve (starting at 1)
pageSize	number	Number of items per page (default 25, max 100)
sort	string	Field to sort by (e.g., 'name', 'created_at')
order	string	Sort order ('asc' or 'desc', default 'asc')
query	string	Full-text search query
filter	object	Filter criteria in JSON format

Response

{
  "data": [
    {
      "id": "company_01abcdefghijklmnopqrstuv",
      "attributes": {
        "name": {
          "value": "Acme Corporation"
        },
        "domain": {
          "value": "acme.com"
        },
        "industry": {
          "value": "Technology"
        },
        "created_at": {
          "value": "2023-01-15T09:30:00.000Z"
        }
      }
    },
    {
      "id": "company_01wxyzabcdefghijklmnopq",
      "attributes": {
        "name": {
          "value": "XYZ Industries"
        },
        "domain": {
          "value": "xyzindustries.com"
        },
        "industry": {
          "value": "Manufacturing"
        },
        "created_at": {
          "value": "2023-02-20T14:45:00.000Z"
        }
      }
    }
  ],
  "meta": {
    "page": 1,
    "pageSize": 25,
    "total": 52
  }
}

Get Company

GET /v2/companies/{company_id}

Retrieves a specific company by ID.

Path Parameters

Parameter	Type	Description
company_id	string	The ID of the company to retrieve

Response

{
  "id": "company_01abcdefghijklmnopqrstuv",
  "attributes": {
    "name": {
      "value": "Acme Corporation"
    },
    "domain": {
      "value": "acme.com"
    },
    "description": {
      "value": "A leading provider of innovative solutions."
    },
    "industry": {
      "value": "Technology"
    },
    "size": {
      "value": "501-1000"
    },
    "linkedin_url": {
      "value": "https://www.linkedin.com/company/acme-corp"
    },
    "website": {
      "value": "https://www.acme.com"
    },
    "location": {
      "value": {
        "street": "123 Main St",
        "city": "San Francisco",
        "state": "CA",
        "postal_code": "94105",
        "country": "United States"
      }
    },
    "created_at": {
      "value": "2023-01-15T09:30:00.000Z"
    },
    "updated_at": {
      "value": "2023-06-10T16:20:00.000Z"
    }
  }
}

Create Company

POST /v2/companies

Creates a new company record.

Request Body

{
  "attributes": {
    "name": {
      "value": "New Horizons Ltd"
    },
    "domain": {
      "value": "newhorizons.com"
    },
    "industry": {
      "value": "Consulting"
    },
    "website": {
      "value": "https://www.newhorizons.com"
    },
    "location": {
      "value": {
        "city": "London",
        "country": "United Kingdom"
      }
    }
  }
}

Response

Returns the created company with a 201 status code.

Update Company

PATCH /v2/companies/{company_id}

Updates an existing company record.

Path Parameters

Parameter	Type	Description
company_id	string	The ID of the company to update

Request Body

{
  "attributes": {
    "industry": {
      "value": "Technology Consulting"
    },
    "size": {
      "value": "51-200"
    }
  }
}

Response

Returns the updated company record.

Delete Company

DELETE /v2/companies/{company_id}

Deletes a company record.

Path Parameters

Parameter	Type	Description
company_id	string	The ID of the company to delete

Response

Returns a 204 status code with no content on success.

Search Companies

POST /v2/companies/search

Performs an advanced search for companies.

Request Body

{
  "query": "technology",
  "filters": [
    {
      "attribute": "industry",
      "operator": "contains",
      "value": "tech"
    },
    {
      "attribute": "size",
      "operator": "equals",
      "value": "501-1000"
    }
  ],
  "sort": {
    "attribute": "created_at",
    "order": "desc"
  },
  "page": 1,
  "pageSize": 50
}

Response

Returns a list of matching companies with pagination.

Standard Attributes

Companies in Attio have the following standard attributes:

Attribute	Data Type	Description
name	text	Company name (required)
domain	text	Primary domain name
description	text	Company description
industry	select	Industry category
size	select	Company size (number of employees)
linkedin_url	url	LinkedIn company page URL
website	url	Company website URL
location	object	Company headquarters location
created_at	date	Record creation timestamp
updated_at	date	Record last update timestamp

Example Usage

Searching for Companies by Domain with JavaScript (Node.js)

const axios = require('axios');

async function findCompanyByDomain(domain) {
  try {
    const response = await axios.post(
      'https://api.attio.com/v2/companies/search',
      {
        filters: [
          {
            attribute: 'domain',
            operator: 'equals',
            value: domain,
          },
        ],
        pageSize: 1,
      },
      {
        headers: {
          Authorization: 'Bearer YOUR_API_KEY',
          'Content-Type': 'application/json',
        },
      }
    );

    return response.data.data[0] || null;
  } catch (error) {
    console.error('Error searching for company:', error);
    return null;
  }
}

// Example usage
findCompanyByDomain('acme.com').then((company) => {
  if (company) {
    console.log('Found company:', company.attributes.name.value);
  } else {
    console.log('No company found with that domain');
  }
});

Creating a Company with TypeScript

import axios from 'axios';
import { Company } from './types';

interface CompanyCreateParams {
  name: string;
  domain?: string;
  industry?: string;
  website?: string;
}

async function createCompany(params: CompanyCreateParams): Promise<Company> {
  const { name, domain, industry, website } = params;

  try {
    const response = await axios.post(
      'https://api.attio.com/v2/companies',
      {
        attributes: {
          name: { value: name },
          ...(domain && { domain: { value: domain } }),
          ...(industry && { industry: { value: industry } }),
          ...(website && { website: { value: website } }),
        },
      },
      {
        headers: {
          Authorization: 'Bearer YOUR_API_KEY',
          'Content-Type': 'application/json',
        },
      }
    );

    return response.data;
  } catch (error) {
    console.error('Error creating company:', error);
    throw error;
  }
}

Error Handling

The Companies API uses standard HTTP status codes and returns detailed error information:

{
  "error": {
    "type": "validation_error",
    "message": "Company name is required",
    "details": [
      {
        "field": "attributes.name",
        "message": "This field is required"
      }
    ]
  }
}

Testing

When testing the Companies API, you can use the test mode with the test API key:

// Headers for test mode
const headers = {
  Authorization: 'Bearer YOUR_TEST_API_KEY',
  'Content-Type': 'application/json',
  'X-Attio-Mode': 'test',
};

All operations performed in test mode will be isolated from your production data.

Migration to Universal Tools

For new implementations, consider using the Universal Tools system which provides:

Simplified Integration: Single tool names across all resource types
Better Performance: 68% reduction in tool count and faster AI evaluation
Future-Proof: Easy to add new resource types without API changes
Consistent Patterns: Same parameter structure across operations

Quick Migration Examples

Old Way (Deprecated):

// Multiple resource-specific tools
await client.callTool('search-companies', { query: 'tech' });
await client.callTool('get-company-details', { record_id: 'comp_123' });
await client.callTool('create-company', { record_data: {...} });

New Way (Universal Tools):

// Single tools with resource_type parameter
await client.callTool('records.search', { resource_type: 'companies', query: 'tech' });
await client.callTool('records.get_details', { resource_type: 'companies', record_id: 'comp_123' });
await client.callTool('create-record', { resource_type: 'companies', record_data: {...} });

See Also:

Universal Tools User Guide - Complete usage examples
Migration Guide - Step-by-step migration instructions
API Reference - Detailed schemas and parameters

People API - For managing individual contacts
Objects API - For customizing the Companies object schema
Lists API - For managing custom views of Companies