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.
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.
422
Validation Error