Contacts and companies
Post a lead straight from a website form into the workspace’s CRM. No backend of your own is required. It is designed to be called from browser JavaScript with a publishable token.
Read Authentication first for tokens, status codes and origin allowlisting.
POST /api/v1/contacts
Section titled “POST /api/v1/contacts”Creates a contact. Requires the contacts:write scope.
POST https://api.erreos.com/api/v1/contactsAuthorization: Bearer erre_pk_...Content-Type: application/jsonFields
Section titled “Fields”name is the only required field. Everything else is optional. Send what the
form actually collected and omit the rest.
| Field | Type | Max | Notes |
|---|---|---|---|
name |
string | 200 | Required. |
email |
string | 320 | |
phone |
string | 40 | |
address |
string | 500 | |
source |
string | 100 | Where the lead came from, such as "website" or "landing-page-q3". Your label, not a fixed vocabulary. |
description |
string | 4000 | Free text. The visitor’s message. |
externalId |
string | 200 | Your own id for this submission. See externalId. |
metadata |
array | 20 entries | Everything else the form asked. See Custom fields. |
uploads |
boolean | true to send files with this contact. Needs the files:write scope. See Uploads. |
Each metadata entry is { "label": string, "value": string }. The label is capped
at 64 and the value at 500. Both must be strings. Numbers, booleans, nested objects and
null are rejected inside metadata; convert before sending.
A top-level field set to null is treated as if you had omitted it, so
{ "name": "Jane", "email": null } is accepted. Only name may not be empty.
Request bodies are capped at 32 KB.
Responses
Section titled “Responses”Created:
{ "ok": true, "id": "j57d8k2m4n6p8q0r2s4t6u8v" }201 Created
Already existed, because you sent an externalId that was seen before:
{ "ok": true, "id": "j57d8k2m4n6p8q0r2s4t6u8v", "deduplicated": true }200 OK
A deduplicated request changes nothing. The existing contact is returned untouched. A second submission does not update the first.
The snippet
Section titled “The snippet”The shortest thing that works, plus the one branch you must not omit:
<script> document.querySelector('#contact-form').addEventListener('submit', async (e) => { e.preventDefault(); const form = new FormData(e.target);
const res = await fetch('https://api.erreos.com/api/v1/contacts', { method: 'POST', headers: { Authorization: 'Bearer erre_pk_...', 'Content-Type': 'application/json' }, body: JSON.stringify({ name: form.get('name'), phone: form.get('phone'), email: form.get('email'), metadata: [{ label: 'Service', value: form.get('service') }] }) });
if (!res.ok) { // The submission was NOT saved. Show the visitor an error and log this. console.error('ErreOS ingest failed', res.status, await res.json()); return; } });</script>The same call with curl:
curl -X POST https://api.erreos.com/api/v1/contacts \ -H "Authorization: Bearer erre_pk_..." \ -H "Content-Type: application/json" \ -d '{ "name": "Jane Doe", "phone": "+1 555 0100", "email": "jane@example.com", "description": "Looking for a quote on a back patio.", "metadata": [ { "label": "Service", "value": "permeable-pavers" }, { "label": "Budget", "value": "$10-25k" } ] }'Do not drop the !res.ok branch. A form that posts and ignores the response
looks like it works while silently losing every lead it fails to send. If you
write nothing else, write that branch.
Three things that catch people out
Section titled “Three things that catch people out”Custom fields go in metadata
Section titled “Custom fields go in metadata”Unknown top-level keys are rejected, not ignored:
{ "error": "unknown_field", "message": "\"service\" is not a field on this endpoint" }That rejection is deliberate. Silently dropping a field would lose data permanently and invisibly. But it means this common shortcut fails:
// ✗ Rejected: sends every form input as a top-level keybody: JSON.stringify(Object.fromEntries(new FormData(form)));Map the known fields, and put everything else in metadata:
// ✓const form = new FormData(e.target);body: JSON.stringify({ name: form.get('name'), email: form.get('email'), metadata: [ { label: 'Service', value: form.get('service') }, { label: 'How did you hear about us?', value: form.get('referrer') } ]});metadata is an array, not an object, because the order is preserved: it
renders in the CRM in the order your form asked the questions.
externalId must be generated once per form-fill
Section titled “externalId must be generated once per form-fill”Send an externalId and a repeat submission with the same value returns the
original contact instead of creating a second one. This protects against a
double-clicked submit button or a retry after a flaky connection.
It only works if the id is stable across those retries:
// ✗ A new id on every attempt, so it dedupes nothingasync function onSubmit(e) { const externalId = crypto.randomUUID(); await fetch(url, { /* ... */ });}// ✓ One id per form-fill, reused by every retry of itlet externalId = crypto.randomUUID();
async function onSubmit(e) { await fetch(url, { /* ... */ });}
function onFormReset() { externalId = crypto.randomUUID();}Omitting externalId is fine. Every submission then creates a new contact,
which is the right behaviour for most forms. The same person legitimately
enquiring twice should appear twice.
Handle the rejection you will actually hit
Section titled “Handle the rejection you will actually hit”Wiring up a new form, in order of likelihood:
- CORS error in the console, no status code. Your site is not on the
token’s origin allowlist. Add it in Settings, then API. Remember
*.example.comdoes not coverexample.com. 400 unknown_field. A form field went to the top level. Move it intometadata.401 unauthorized. The token is truncated, revoked, or from a different workspace. Copy it again.403 forbidden_scope. Real token, wrong permissions: it lackscontacts:write.
POST /api/v1/companies
Section titled “POST /api/v1/companies”Creates a company. Requires the companies:write scope, which is only available
to B2B workspaces. If the workspace is B2C, this scope cannot be granted and
the endpoint will answer 403 forbidden_scope.
| Field | Type | Max | Notes |
|---|---|---|---|
name |
string | 200 | Required. |
industry |
string | 100 | |
website |
string | 500 | |
address |
string | 500 | |
source |
string | 100 | |
externalId |
string | 200 | Same dedupe behaviour as contacts. |
Companies take no email, phone or metadata of their own. A company’s
contact details live on its contacts, the people you actually talk to. If your
form collects both a company and a person, send one request with the person
nested under contact; see below.
The top-level field sets differ on purpose: posting a contact’s body to
/companies fails immediately with unknown_field rather than quietly discarding
half of it.
Companies are created at the lead stage.
Sending the company and the person together
Section titled “Sending the company and the person together”Add a contact object. Its fields are exactly the fields of
POST /api/v1/contacts: same names, same caps, same metadata rules, name
still required. A body that works on one route works inside contact on the
other.
{ "name": "Acme Millwork", "industry": "General Contractor", "website": "acme.example", "externalId": "acme.example", "contact": { "name": "Jane Doe", "email": "jane@acme.example", "phone": "770-555-0134", "description": "Need 24 units repriced per-unit.", "externalId": "b3f1c9e2-5a77-4c31-9f0e-2d6a8b4e1c07" }}This requires both companies:write and contacts:write. A key holding only
companies:write can still post a plain company; sending contact without
contacts:write answers 403 forbidden_scope.
Errors inside contact name their path, so you can tell which half was rejected:
{ "error": "unknown_field", "message": "\"contact.role\" is not a field on this endpoint" }The contact becomes the company’s primary contact only if that company has no
contacts yet. Post a second person against the same company and they are added
as an ordinary contact, and the existing primary is never changed. There is no
isPrimary field; who the main point of contact is belongs to the workspace.
The two externalIds
Section titled “The two externalIds”They are separate keys and they answer different questions.
| Key | Identifies | Good value |
|---|---|---|
externalId |
the company | something stable, such as a domain or your own company id |
contact.externalId |
this form-fill | a fresh crypto.randomUUID() per submission |
contact.externalIdis checked first. If it has been seen before, the whole request is a no-op: no company is created, no contact is created, nothing is modified. This is what makes a retry safe.- A company
externalIdthat has been seen before reuses that company and attaches the new person to it. - Omit the company
externalIdand a new company is always created. We never look a company up by its name, not exactly and not case-insensitively. Two submissions naming the same company produce two companies, and someone in the workspace merges them. This is deliberate: name-matching in a contract you have already shipped to a live page cannot be corrected later.
If you have a stable company key, send it. It is the difference between a tidy CRM and one where every enquiry from the same customer forks another row.
Responses
Section titled “Responses”Both created (201 Created):
{ "ok": true, "id": "<companyId>", "contact": { "id": "<contactId>" } }Company already existed, person is new (also 201 Created, because something
was created):
{ "ok": true, "id": "<companyId>", "deduplicated": true, "contact": { "id": "<contactId>" } }Whole submission already seen (200 OK, nothing written):
{ "ok": true, "id": null, "deduplicated": true, "contact": { "id": "<contactId>", "deduplicated": true }}⚠️ id can be null on that last response only. Nothing was written, so the
only company we can honestly name is whichever one that contact already belongs
to, and it may belong to none. If you read id without checking, guard it.
What the workspace type changes
Section titled “What the workspace type changes”The workspace is either B2C or B2B, and that shapes the contact record, not the payload you send. The fields above are identical either way.
- On a B2C workspace, the contact lands directly in the sales pipeline at the
newstage. - On a B2B workspace, the contact lands without a stage and without a company attached. Someone in the workspace links it to the right company by hand. It is visible in the contacts list immediately.
You do not need to know which type a workspace is to post to /api/v1/contacts.
If your form has a company field, post to /api/v1/companies with contact
instead. That connects the two for you. /api/v1/contacts is for forms that
collect a person and nothing else; on a B2B workspace it will produce a contact
with no company attached, which is correct when there was no company to attach,
and merely untidy when there was.
What happens after a successful post
Section titled “What happens after a successful post”The contact is saved, and the workspace is notified with an in-app activity entry plus an email to the addresses its admins configured.
Notification is not part of your request’s outcome. If the response says
201, the contact is saved, whether or not the email went out. Never retry a
201 on the assumption that a notification failed.