Skip to main content
The Upsert Contact endpoint creates a contact if one does not exist for the given identifier, or updates the existing contact’s fields if one is found. This makes it ideal for syncing contacts from external CRM systems, webhooks, or data pipelines where you cannot always guarantee whether a contact already exists in your Workspace. The response returns the full contact object regardless of whether it was created or updated.
POST /api/v1/contacts/{identifier}/upsert

Path Parameters

string
required
A contact lookup string used to find an existing contact or create a new one. Minimum length: 1 character.

Request Body

All fields are optional. When a contact is found, only the fields you include are updated; omitted fields remain unchanged. When a new contact is created, any fields you provide are set at creation time.
string
Contact’s first name. Maximum 100 characters.
string
Contact’s last name. Maximum 100 characters.
string
Contact’s email address. Must be a valid email format.
string
Contact’s phone number. Must be 10–20 digits. Pattern: \+?\d{10,20}.
string
URL of the contact’s profile image.
string
One of: male, female, unknown.

Code Examples

Response Fields

string
required
Unique contact ID.
string (date-time)
required
When the contact was created.
string (date-time)
required
When the contact was last updated.
string | null
required
Profile image URL.
string | null
required
Contact’s phone number.
string | null
required
Contact’s email address.
boolean
required
Whether the email has been verified.
boolean
required
Whether the contact opted in to email communications.
string | null
required
Contact’s first name.
string | null
required
Contact’s last name.
string | null
required
Computed full name.
string | null
required
One of male, female, unknown.
string
required
ID of the owning Workspace.
array
required
Custom field values.
array
required
Tags applied to the contact.
array
required
Notes attached to the contact.
array
required
Active inbox connections.
object | null
required
Most recent conversation, or null.

Example Response