Skip to main content
POST
Create or update a contact based on phone (primary) or email (fallback) matching against active (non-deleted) contacts. Returns 201 for new contacts and 200 for updates. At least one of phone or email must be provided.
Matching only considers active contacts. If the only match is a soft-deleted contact, it is ignored and a brand new contact is created — the deleted record stays deleted with its data intact.
By default, on a match, provided values in the request overwrite the existing contact’s scalar fields and custom field values; fields you omit from the request are left untouched. Set preserveExisting: true to merge instead — only empty fields and missing custom field values are filled. Tags are always additive regardless of preserveExisting.
workspaceId is required for account-scoped API keys and inferred from the key for workspace-scoped keys. See Workspace ID and Request Scope.
​
string
Workspace UUID (required for account API keys, optional for workspace API keys)
​
string
First name
​
string
Last name
​
string
Email address (used for matching if phone is not provided)
​
string
Phone number in E.164 format (primary matching field)
​
string
IANA timezone identifier (e.g. America/New_York). Used by features that respect the contact’s local time.
  • Only applied when creating a new contact. When matching an existing contact, the existing timezone is preserved (or merged per preserveExisting); auto-derivation does not run on updates.
  • On create, when omitted, the timezone is auto-derived from the phone number with the workspace default as fallback. Caller-supplied values always win.
  • Must be a valid IANA timezone identifier; bogus strings are rejected with 400 Bad Request.
​
boolean
default:"false"
When true, populated fields on the matched contact are preserved — only empty fields and missing custom field values are filled in. When false (default), the request values overwrite the existing fields and custom field values. Tag attachment is always additive regardless of this flag.
​
boolean
Do Not Disturb. true turns it on. false turns it off only when the API or a person in the dashboard turned it on. If the contact asked for it (for example by replying STOP), or Lead Connector, a workflow or an import set it, it stays on and you get a 409 saying who set it. It also stays on with a 409 if the contact’s phone or email is on the Do Not Contact list (for example after a STOP reply). That includes a phone or email the same request sets. If the contact changes while DND is being turned off, you also get a 409. Send the request again.
​
string[]
Tag names to attach to the contact. Tags that don’t exist yet are auto-created in your workspace. Tags are always additive — this endpoint never removes a tag from a contact, regardless of preserveExisting. Names are matched case-sensitively, trimmed, and must be 1–255 characters. Tags in the response are returned in alphabetical order.Adding a tag fires a workflow trigger. On a new contact it fires Contact created with the tags already attached. On a matched existing contact it fires Contact tagged, once per tag the contact didn’t already have. Re-sending tags the contact already carries fires nothing, so repeated syncs of the same contact won’t re-trigger your workflows.
​
object
Custom field values keyed by the custom field name as displayed in the dashboard (e.g. "Lead Source" — including spaces and original casing; not a slug). Accepts string, number, boolean, or null (null clears a stored value). Behavior on a match follows preserveExisting: when false (default), provided values overwrite; when true, only fill custom fields the contact doesn’t have a value for. Unknown keys are rejected with a 400. Values are persisted as text and returned as strings.
This endpoint strictly validates the request body. Unknown top-level fields are rejected with 400 Bad Request. Custom field values must use the customFields object.