Skip to main content
POST
Crear o actualizar contacto

Autorizaciones

Authorization
string
header
requerido

Token JWT de autenticación

Encabezados

x-company-id
string

Identificador de la empresa objetivo. Obligatorio solo para API keys globales (type=global). Se ignora para API keys de empresa y usuarios humanos.

Cuerpo

application/json
name
string
requerido

Nombre completo del contacto. Obligatorio. Si ya existe un contacto con el mismo teléfono, su nombre se conserva.

Minimum string length: 1
country_code
string
requerido

Código de país para llamadas (1-3 dígitos). Ejemplos: 55 (Brasil), 1 (EE. UU.), 351 (Portugal). Junto con phone_number, identifica el contacto: si la empresa ya tiene un contacto con ese teléfono, se actualiza en lugar de crearse uno nuevo.

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

Número de teléfono sin formato, solo dígitos (código de área + número, sin el código de país). Ejemplo: 11999998888. Un teléfono que no forma un número válido con el country_code se rechaza con 400.

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

Dirección de correo electrónico del contacto. Opcional. No se usa para encontrar el contacto; en un contacto existente, reemplaza el correo actual.

linkedin_identifier
string

Identificador de LinkedIn del contacto (nombre del perfil). Ejemplo: joao-silva-123. No se usa para encontrar el contacto; en un contacto existente, reemplaza el valor actual.

job_title
string

Cargo del contacto. Ejemplo: Gerente de Ventas. Se guarda en la creación; en un contacto existente, se actualiza cuando se envía.

seniority
string

Nivel de seniority del contacto. Ejemplo: Senior, Junior, Semi-senior. Se guarda en la creación; en un contacto existente, se actualiza cuando se envía.

department
string

Departamento del contacto. Ejemplo: Comercial, TI, Marketing. Se guarda en la creación; en un contacto existente, se actualiza cuando se envía.

country
string

País del contacto. Ejemplo: Brasil. Se guarda en la creación; en un contacto existente, se actualiza cuando se envía.

region
string

Estado o región del contacto. Ejemplo: São Paulo. Se guarda en la creación; en un contacto existente, se actualiza cuando se envía.

city
string

Ciudad del contacto. Ejemplo: São Paulo. Se guarda en la creación; en un contacto existente, se actualiza cuando se envía.

experience
string

Experiencia profesional del contacto. Se guarda en la creación; en un contacto existente, se actualiza cuando se envía.

additional_attributes
object

Campos personalizados del contacto. Formato: { "slug_del_campo": valor }. Los slugs deben corresponder a custom fields registrados con contexto CONTACT. Los slugs inválidos o inexistentes se ignoran en silencio. Los valores deben ser primitivos (string, number, boolean o null). En un contacto existente, solo se actualizan los slugs enviados (merge); los demás se mantienen. Ejemplo: { "cpf": "12345678900", "data_nascimento": "1990-01-15", "valor_total": 1500.50 }

Respuesta

Contacto creado, o contacto existente con el mismo teléfono actualizado

name
string
requerido

Nombre del contacto

company
any
requerido

Empresa del contacto

_id
string

ID del contacto

id
string

ID del contacto (mismo valor que _id)

country_code
string

Código de país del número. Ausente junto con el teléfono cuando el contacto solo tiene un identificador de WhatsApp.

email
string

Email del contacto

last_activity_at
any

Fecha de la última actividad del contacto

phone_number
string

Número de teléfono del contacto. Ausente cuando el contacto solo tiene un identificador de WhatsApp.

linkedin_identifier
string

Identificador del perfil de LinkedIn

job_title
string

Cargo del contacto

seniority
string

Nivel de seniority del contacto

department
string

Departamento del contacto

country
string

País del contacto

region
string

Estado o región del contacto

city
string

Ciudad del contacto

experience
string

Experiencia profesional del contacto

skills
string

Habilidades del contacto

additional_attributes
object

Valores de los campos personalizados del contacto, por slug. Si se guardó vía additional_attributes, el valor viene en el envoltorio { id, value, type, updatedAt }. Si se guardó vía custom_fields (PUT), viene sin envoltorio: el option_id (select), la lista de option_id (multi_select) o el texto (text).

business
string | null

ID del Business al que pertenece el contacto

notes
object[]

Notas registradas en el contacto

marketing_opt_out
object

Opt-out de marketing por medio de comunicación (whatsapp, email, linkedin). Ausente o vacío cuando el contacto no pidió salir de ningún medio.

whatsapp_user_id
string

Identificador del contacto en WhatsApp (BSUID), asignado por Meta. String opaco.

whatsapp_username
string

@username del contacto en WhatsApp, tal como lo envía Meta

whatsapp_parent_user_id
string

parent_user_id del contacto en WhatsApp, tal como lo envía Meta

createdAt
any

Fecha de creación del contacto

updatedAt
any

Fecha de actualización del contacto