> ## Documentation Index
> Fetch the complete documentation index at: https://docs.open.cx/llms.txt
> Use this file to discover all available pages before exploring further.

# Introduction to companies

> Group contacts under the company they belong to, and attach the account data your agents need during a conversation.

## What is a company?

A **company** is an account record that contacts belong to. If three people from Acme Retail open sessions, they can all point at one Acme Retail company instead of each carrying their own copy of the plan tier, the CSM's name, and the account id.

A contact can belong to several companies, and a company can have any number of contacts.

## Identity is your key, not ours

Every company is identified by `external_id` — whatever you already call it in your own system. A Zoho account id, a merchant id, a tenant slug. Writes resolve on that key, so the same `POST /companies` call creates the company the first time and updates it every time after.

`name` is for display only. It is not unique, so two merchants can both be called "Acme" and renaming one is never a collision.

## The four things you can do

* **Create or update a company** → [Upsert a company](/api-reference/companies/upsert)
* **Add a company to a contact** → [Link a contact](/api-reference/contacts/companies/link)
* **Read a contact's companies** → [List a contact's companies](/api-reference/contacts/companies/list)
* **Remove one company from a contact** → [Unlink a contact](/api-reference/contacts/companies/unlink)

Linking is strict: the `external_id` must already exist. An unknown key returns a 400 rather than creating a company, so a typo in a sync script cannot quietly fill your account list with junk.

## Attributes

`custom_data` holds flat key/value attributes — strings, numbers, and booleans. Sending an attribute merges it into what is already there, and sending it as `null` clears that one key. Keys you do not mention are left alone.

```json theme={"dark"}
{
  "external_id": "acct_88213",
  "name": "Acme Retail",
  "custom_data": { "plan": "growth", "seats": 40, "csm": "sara@acme.test" }
}
```

<Note>
  Company attributes are not visible to the AI agent. They are available to your
  workflows through the **Get Contact Companies** action, and to your agents in
  the inbox, but they are never added to the model's prompt.
</Note>

## Syncing from a CRM

A CRM sync usually pushes many links at once. [Link many contacts](/api-reference/companies/bulk-link) takes up to 100 in a single call and isolates failures: a row naming a company that was never created returns its own error, and the other 99 links still land. Results come back in request order with a summary.

Name each contact whichever way you already hold it — `contact_id`, `contact_email`, or `contact_phone`, exactly one per row — so you don't have to resolve every contact to an OpenCX id first. Each result carries the resolved `contact_id`, which is worth storing against your own record to skip the lookup next time.

```json theme={"dark"}
{
  "links": [
    { "contact_email": "sara@acme.test", "external_id": "acct_88213" },
    { "contact_phone": "+15551234567", "external_id": "acct_88213" },
    { "contact_id": "8f3c...", "external_id": "acct_44100" }
  ]
}
```

Phone matching is forgiving about spelling: `+15551234567` and `15551234567` find the same contact. If a number matches more than one contact, that row reports an error instead of guessing — name that contact by `contact_id`.

## Scopes

Reads need `companies:read`; writes need `companies:write`.

These are separate from `contacts:*` on purpose. Company records usually carry data pulled from your CRM, so a key that manages contacts does not automatically get to read or rewrite the account graph.

## Companies in workflows

Four workflow actions cover the same ground without any API calls:

* **Create or Update Company**
* **Link Contact to Company**
* **Get Contact Companies** — returns `found`, `count`, and the list, so you can branch on a contact having no company
* **Unlink Contact from Company** — removes one company and leaves the contact's others alone

Linking a contact does not fire the **Contact Updated** trigger. Nothing on the contact record changes, and a workflow that links on Contact Updated would otherwise re-trigger itself.