The companies in your CRM. A contact belongs to at most one company, and while the account links contacts by domain, a contact whose address is at a company's domain joins it by itself. Nothing here sends email.
| Method | Path | Description |
|---|---|---|
GET | /api/v1/companies | The account's companies, newest first. Search by name or domain. |
GET | /api/v1/companies/{id} | One company. |
POST | /api/v1/companies | Create a company from a name, a domain, or both. |
PATCH | /api/v1/companies/{id} | Change its name, domain or property values. |
DELETE | /api/v1/companies/{id} | Delete it. Its contacts stay, in no company. |
Reading needs the crm:read scope, writing crm:write. The account must have the CRM turned on, which someone in the team does once in PristineSend. Changes count against the CRM's own limit of 120 a minute per account. Send an Idempotency-Key on a create, so a retried request cannot make a second company (Idempotent requests). A field or parameter an endpoint does not take is refused, never ignored.
| Field | Type | Description |
|---|---|---|
id | string (uuid) | The company's id. |
name | string | Its name, up to 200 characters. |
domain | string | null | Its email domain, like acme.com: one company per domain in an account. |
source | string | How it was made: domain (from a contact's address), manual, import or api. |
contacts | number | How many contacts are in it now. |
properties | object | Its values of the account's company properties, by key. |
created_at / updated_at | string | When it was made, and last changed. |
| Parameter | Type | Description |
|---|---|---|
q | string | Companies whose name or domain contains this, up to 200 characters. |
domain | string | The company with exactly this domain. |
limit | number | 1 to 100, 50 when left out. |
cursor | string | next_cursor from the page before. |
The answer is a page: data, has_more and next_cursor (Pagination).
One company. Its notes, deals and the emails of its contacts are on its timeline.
| Field | Type | Description |
|---|---|---|
name | string | Its name, up to 200 characters. Left out on create: named after its domain. |
domain | string | null | Its email domain. Never a personal mailbox's (gmail.com, outlook.com and the like) or a reserved one. null takes it away. |
properties | object | Values of the account's company properties by key, up to 2,000 characters each; null clears one. A key the account does not have is refused. |
A name, a domain, or both. The answer is 201 with the company. When the company was saved but reading it back failed, the answer is still 201, with its id and a warning: read it with GET, and don't create it again.
Send only what changes: name, domain or properties, whose values are merged into the ones it has. Contacts already in the company stay when its domain changes; contacts at the new domain that are in no company join it.
Its contacts stay, in no company, and its deals stay without it. Add ?ignore_domain=true so that its domain never makes a company again. The answer is { data: { id, deleted: true, contacts_unlinked } }. A deleted company cannot be brought back.
A contact's company_id is on every contact the Contacts API answers. To put a contact in a company, or take it out, send company_id (an id, or null) in PATCH /api/v1/contacts/{id}, with a key that also has crm:write. A contact placed or taken out this way is left alone by the domain rule from then on.
| Status | code | When |
|---|---|---|
400 | missing_field | A new company with neither a name nor a domain. |
400 | invalid_field | A field or parameter the endpoint does not take, a domain that is not one or belongs to a personal mailbox, a name too long, a property the account does not have, or a value its type refuses, such as text for a number property (param names it). Nothing is written. |
400 | invalid_request | The body is not a JSON object, or a change names nothing to change. |
403 | insufficient_scope | The key lacks crm:read (reading) or crm:write (writing). |
403 | crm_not_enabled | Nobody has turned the CRM on for this account yet (Audience → Companies, in PristineSend). |
404 | not_found | This account has no company with that id. |
409 | conflict | Another company of the account already has that domain; the message gives its id. |
429 | rate_limited | 120 CRM changes a minute per account. Retry after Retry-After. |
503 | service_unavailable | A read or write behind the request failed: send the same request again. A change lands once however often it is sent. |
See Error codes for the envelope and the full list.