Skip to main content

​
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

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.
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.

​
Syncing from a CRM

A CRM sync usually pushes many links at once. Link many contacts 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.
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.