Skip to content

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.

Creates a contact. Requires the contacts:write scope.

POST https://api.erreos.com/api/v1/contacts
Authorization: Bearer erre_pk_...
Content-Type: application/json

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.

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

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

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 key
body: 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 nothing
async function onSubmit(e) {
const externalId = crypto.randomUUID();
await fetch(url, {
/* ... */
});
}
// ✓ One id per form-fill, reused by every retry of it
let 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:

  1. 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.com does not cover example.com.
  2. 400 unknown_field. A form field went to the top level. Move it into metadata.
  3. 401 unauthorized. The token is truncated, revoked, or from a different workspace. Copy it again.
  4. 403 forbidden_scope. Real token, wrong permissions: it lacks contacts:write.

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.

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.externalId is 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 externalId that has been seen before reuses that company and attaches the new person to it.
  • Omit the company externalId and 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.

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.

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 new stage.
  • 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.

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.