Create Contacts
POST /contacts
Create a contact, optionally adding it to a list.
The contact is created independent of any list. When list_id is
provided, the contact is added to that list AFTER it is created; when
omitted, the contact is created standalone. A company is resolved and
attached from company_domain when supplied.
Duplicate handling: when the submitted work_email / linkedin_url
(or the deterministic identity hash) already matches an existing contact,
the handler does NOT overwrite it — it writes nothing and skips the
list_id linkage. This endpoint mirrors the in-app create and responds
409 Conflict with the matched contact_id and a field_diff under
detail (rather than a misleading 201 success). The 409 is NOT
cached under the Idempotency-Key, so a later create of the same
identity is re-evaluated fresh. The 409 detail also carries hint,
upsert and update, which name the idempotent create-or-update route
PUT /contacts/assert and the PATCH /contacts/{id} for the matched
contact. To create-or-update in one call, use PUT /contacts/assert.
Supports optional Stripe-style idempotency via the Idempotency-Key
header — a safe retry of the same key replays the first SUCCESSFUL response
(flagged Idempotent-Replay: true) rather than creating duplicate
contacts.
Authorizations
Parameters
Header Parameters
Request Body required
Request body for creating contacts.
object
When true, custom_fields keys that match no existing column are created as NEW custom columns (list-scoped when list_id is set) and then written.
Responses
201
Successful Response
object
object
How a write path handled the request’s custom (dynamic) column keys.
Shared by every Developer API write surface that accepts custom columns
(POST /contacts, PUT /contacts/assert[/batch],
PUT /companies/assert[/batch]).
Every field defaults to empty, so a client that ignores this object sees no
behavioural change. It exists because these keys were previously dropped
with NO caller-visible signal — the only trace was a server-side
logger.warning in append_to_audience.
object
Caller keys for which a NEW custom column was created by this request.
Caller keys that matched no custom column and were NOT written. Create the column first (POST /fields) or pass create_missing_fields=true.
Caller keys that resolved to a custom column and were written.
Advisory notes about values saved as sent that look wrong (e.g. an unrecognised seniority or country). Empty when the input is clean.
object
Whether there are more pages
Items per page
Current page number (1-indexed)
Total number of items
422
Validation Error