Skip to main content
POST
Create or Upsert Contact
Creates a new contact or upserts an existing contact record if a matching phone number or email address is identified within your workspace.

Deduplication and upsert behavior

The endpoint evaluates duplicate candidates:
  • If a contact with the provided phone number or email already exists, their attributes, tags, and custom fields are updated.
  • If no match exists, a new contact record is created with HTTP status 201.

Required permissions

Requires an API key with the crm:write scope.

Authorizations

x-api-key
string
header
required

Workspace API key header. The key implicitly determines your workspace isolation. Scopes: crm:read for GET/HEAD/OPTIONS, crm:write for POST/PATCH/PUT/DELETE.

Body

application/json
first_name
string
required
Example:

"Jane"

phone_number
string
required

National number or full international format

Example:

"5551234567"

last_name
string
Example:

"Doe"

country_code
string

Country code prefix (e.g. +1, +44, +91)

Example:

"+1"

email
string<email>
Example:

"jane.doe@example.com"

tags
string[]
Example:
custom_fields
object
Example:

Response

Contact created or upserted successfully

Standard envelope returned by POST, PATCH, PUT, and DELETE (mutation) endpoints

success
boolean
required
Example:

true

data
object
required

The created or updated entity

error
null
required
Example:

null