Contacts API
The Contact object
The following fields are accepted on write via POST /api/v1/contacts.
| Field | Type | Notes |
|---|---|---|
id | string | CUID, assigned on create (read-only) |
name | string (required) | Max 200 characters |
title | string | null | Job title (max 200 chars) |
company | string | null | Free-text company name; auto-links to a defined Company when the name matches one (max 200 chars) |
companyId | string | null | Link directly to an existing company by ID |
companyExternalId | string | null | Resolve the linked company by its externalId instead of companyId (max 200 chars) — the row fails if no match is found |
email | string | null | Max 320 characters |
phone | string | null | Max 64 characters |
status | string | One of NEW, ACTIVE, CUSTOMER, DORMANT (default NEW) |
lifecycleStage | string | null | One of SUBSCRIBER, LEAD, MARKETING_QUALIFIED_LEAD, SALES_QUALIFIED_LEAD, OPPORTUNITY, CUSTOMER, EVANGELIST, OTHER |
source | string | null | Lead source, e.g. "Referral" or "Webinar" (max 200 chars) |
category | string | null | Max 200 characters |
buyerType | string | null | Max 200 characters |
website | string | null | Max 500 characters |
city | string | null | Max 200 characters |
state | string | null | Max 200 characters |
country | string | null | Max 200 characters |
externalId | string | null | Your system's ID — upsert key and dedupe handle (max 200 chars) |
customFields | object | null | Workspace-defined custom field values |
createdAt | string (ISO 8601) | Assigned on create (read-only) |
updatedAt | string (ISO 8601) | Updated on every write (read-only) |
Example object
{
"id": "cmq2abc2def3ghi4jkl5",
"name": "Jane Buyer",
"title": "Head of Procurement",
"company": "Acme Corp",
"companyId": "cmq1abc2def3ghi4jkl5",
"email": "jane@acme.com",
"phone": null,
"status": "NEW",
"lifecycleStage": "LEAD",
"source": null,
"category": null,
"buyerType": null,
"website": null,
"city": null,
"state": null,
"country": null,
"externalId": "SHOP-C-1",
"customFields": null,
"createdAt": "2025-06-01T12:00:00.000Z",
"updatedAt": "2025-06-01T12:00:00.000Z"
}Notes on specific fields
name is the only required field. All other fields are optional on write.
Company linking — three ways to associate a contact with a company, in priority order:
companyId— a direct id; wins if present and valid in the workspace.companyExternalId— resolved against a company'sexternalId; the row fails (no contact created) if no match is found in the workspace.company— a free-text name; auto-linked when it matches an existing company's name, otherwise stored as plain text with no link.
externalId is the upsert key. A row with an externalId that matches an existing contact in the workspace updates that contact instead of creating a duplicate.
customFields are validated against the workspace's custom field definitions for the Contact entity; unknown keys are dropped.