API Reference

Companies

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.

Overview

MethodPathDescription
GET/api/v1/companiesThe account's companies, newest first. Search by name or domain.
GET/api/v1/companies/{id}One company.
POST/api/v1/companiesCreate 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.

The company object

FieldTypeDescription
idstring (uuid)The company's id.
namestringIts name, up to 200 characters.
domainstring | nullIts email domain, like acme.com: one company per domain in an account.
sourcestringHow it was made: domain (from a contact's address), manual, import or api.
contactsnumberHow many contacts are in it now.
propertiesobjectIts values of the account's company properties, by key.
created_at / updated_atstringWhen it was made, and last changed.

List and read

GET/api/v1/companies
ParameterTypeDescription
qstringCompanies whose name or domain contains this, up to 200 characters.
domainstringThe company with exactly this domain.
limitnumber1 to 100, 50 when left out.
cursorstringnext_cursor from the page before.

The answer is a page: data, has_more and next_cursor (Pagination).

for await (const company of await ps.companies.list({ q: "acme" })) {
  console.log(company.name, company.domain)
}
GET/api/v1/companies/{id}

One company. Its notes, deals and the emails of its contacts are on its timeline.

Create a company

POST/api/v1/companies
FieldTypeDescription
namestringIts name, up to 200 characters. Left out on create: named after its domain.
domainstring | nullIts email domain. Never a personal mailbox's (gmail.com, outlook.com and the like) or a reserved one. null takes it away.
propertiesobjectValues 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.

import { PristineSend } from "pristinesend"

const ps = new PristineSend(process.env.PRISTINESEND_API_KEY!)

const { data: company } = await ps.companies.create({ name: "Acme", domain: "acme.com" })
console.log(company.id, company.contacts) // contacts at acme.com have joined it

Change a company

PATCH/api/v1/companies/{id}

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.

curl -X PATCH https://pristinesend.com/api/v1/companies/3f6c1a2e-9b4d-4c8e-a1f0-2d7b5e9c4a11 \
  -H "Authorization: Bearer ps_live_YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "properties": { "industry": "Manufacturing" } }'

Delete a company

DELETE/api/v1/companies/{id}

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

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.

Errors

StatuscodeWhen
400missing_fieldA new company with neither a name nor a domain.
400invalid_fieldA 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.
400invalid_requestThe body is not a JSON object, or a change names nothing to change.
403insufficient_scopeThe key lacks crm:read (reading) or crm:write (writing).
403crm_not_enabledNobody has turned the CRM on for this account yet (Audience → Companies, in PristineSend).
404not_foundThis account has no company with that id.
409conflictAnother company of the account already has that domain; the message gives its id.
429rate_limited120 CRM changes a minute per account. Retry after Retry-After.
503service_unavailableA 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.