Skip to main content
POST
Create or update contact

Authorizations

Authorization
string
header
required

JWT authentication token

Headers

x-company-id
string

Target company identifier. Required only for global API keys (type=global). Ignored for company API keys and human users.

Body

application/json
name
string
required

The contact's full name. Required. If a contact with the same phone already exists, its name is preserved.

Minimum string length: 1
country_code
string
required

Country calling code (1-3 digits). Examples: 55 (Brazil), 1 (USA), 351 (Portugal). Together with phone_number, it identifies the contact: if the company already has a contact with this phone, that contact is updated instead of a new one being created.

Required string length: 1 - 3
Pattern: ^\d{1,3}$
phone_number
string
required

Phone number without formatting, digits only (area code + number, without the country code). Example: 11999998888. A phone that doesn't form a valid number with the country_code is rejected with 400.

Minimum string length: 1
Pattern: ^\d+$
email
string

The contact's email address. Optional. Not used to find the contact; on an existing contact, it replaces the current email.

linkedin_identifier
string

The contact's LinkedIn identifier (profile name). Example: joao-silva-123. Not used to find the contact; on an existing contact, it replaces the current value.

job_title
string

The contact's job title. Example: Sales Manager. Saved on creation; on an existing contact, updated when sent.

seniority
string

The contact's seniority level. Example: Senior, Junior, Mid-level. Saved on creation; on an existing contact, updated when sent.

department
string

The contact's department. Example: Sales, IT, Marketing. Saved on creation; on an existing contact, updated when sent.

country
string

The contact's country. Example: Brazil. Saved on creation; on an existing contact, updated when sent.

region
string

The contact's state or region. Example: São Paulo. Saved on creation; on an existing contact, updated when sent.

city
string

The contact's city. Example: São Paulo. Saved on creation; on an existing contact, updated when sent.

experience
string

The contact's professional experience. Saved on creation; on an existing contact, updated when sent.

additional_attributes
object

The contact's custom fields. Format: { "field_slug": value }. Slugs must match custom fields registered with the CONTACT context. Invalid or nonexistent slugs are silently ignored. Values must be primitives (string, number, boolean or null). On an existing contact, only the slugs sent are updated (merge); the others stay as they are. Example: { "cpf": "12345678900", "data_nascimento": "1990-01-15", "valor_total": 1500.50 }

Response

Contact created, or existing contact with the same phone updated

name
string
required

Contact name

company
any
required

Contact's company

_id
string

Contact ID

id
string

Contact ID (same value as _id)

country_code
string

Country code of the number. Absent, along with the phone, when the contact only has a WhatsApp identifier.

email
string

Contact's email

last_activity_at
any

Date of the contact's last activity

phone_number
string

The contact's phone number. Absent when the contact only has a WhatsApp identifier.

linkedin_identifier
string

LinkedIn profile identifier

job_title
string

Contact's job title

seniority
string

Contact's seniority level

department
string

Contact's department

country
string

Contact's country

region
string

Contact's state or region

city
string

Contact's city

experience
string

Contact's professional experience

skills
string

Contact's skills

additional_attributes
object

Values of the contact's custom fields, by slug. When saved via additional_attributes, the value comes in the envelope { id, value, type, updatedAt }. When saved via custom_fields (PUT), it comes raw: the option_id (select), the list of option_id (multi_select) or the text (text).

business
string | null

ID of the Business the contact belongs to

notes
object[]

Notes recorded on the contact

marketing_opt_out
object

Marketing opt-out per communication channel (whatsapp, email, linkedin). Absent or empty when the contact hasn't opted out of any channel.

whatsapp_user_id
string

The contact's WhatsApp identifier (BSUID), assigned by Meta. Opaque string.

whatsapp_username
string

The contact's WhatsApp @username, as Meta sends it

whatsapp_parent_user_id
string

The contact's WhatsApp parent_user_id, as Meta sends it

createdAt
any

Contact creation date

updatedAt
any

Contact update date