Create 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.