Skip to main content
POST
Crear contacto (o reutilizar el existente)

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 el contacto ya existe, su nombre se conserva.

Minimum string length: 1
country_code
string

Código de país para llamadas (1-3 dígitos). Ejemplos: 55 (Brasil), 1 (EE. UU.), 351 (Portugal). Obligatorio cuando se envía phone_number; sin teléfono, no lo envíe.

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

Dirección de correo electrónico del contacto. Identifica el contacto por la forma normalizada (sin espacios en los extremos, en minúsculas), que es como se guarda. Los correos antiguos guardados con mayúsculas solo se reconocen con la misma grafía, hasta la normalización de la base. Solo cuenta como identificador si tiene "@". En un contacto existente, se actualiza cuando el contacto se encuentra por teléfono; encontrado por correo electrónico o LinkedIn, solo se completa si está vacío.

linkedin_identifier
string

Identificador de LinkedIn del contacto: URL del perfil o solo el nombre del perfil. Ejemplo: joao-silva-123. Identifica el contacto. En un contacto existente, se actualiza cuando el contacto se encuentra por teléfono; encontrado por correo electrónico o LinkedIn, solo se completa si está vacío.

phone_number
string

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. Identifica el contacto. Un teléfono que no forma un número válido con country_code se rechaza con 400. Opcional: el contacto necesita al menos un identificador entre teléfono, correo electrónico y LinkedIn.

Pattern: ^\d*$
job_title
string

Cargo del contacto. Ejemplo: Gerente de Ventas. Se guarda en la creación; en un contacto existente, se actualiza cuando el contacto se encuentra por teléfono; encontrado por correo electrónico o LinkedIn, solo se completa si está vacío.

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 el contacto se encuentra por teléfono; encontrado por correo electrónico o LinkedIn, solo se completa si está vacío.

department
string

Departamento del contacto. Ejemplo: Comercial, TI, Marketing. Se guarda en la creación; en un contacto existente, se actualiza cuando el contacto se encuentra por teléfono; encontrado por correo electrónico o LinkedIn, solo se completa si está vacío.

country
string

País del contacto. Ejemplo: Brasil. Se guarda en la creación; en un contacto existente, se actualiza cuando el contacto se encuentra por teléfono; encontrado por correo electrónico o LinkedIn, solo se completa si está vacío.

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 el contacto se encuentra por teléfono; encontrado por correo electrónico o LinkedIn, solo se completa si está vacío.

city
string

Ciudad del contacto. Ejemplo: São Paulo. Se guarda en la creación; en un contacto existente, se actualiza cuando el contacto se encuentra por teléfono; encontrado por correo electrónico o LinkedIn, solo se completa si está vacío.

experience
string

Experiencia profesional del contacto. Se guarda en la creación; en un contacto existente, se actualiza cuando el contacto se encuentra por teléfono; encontrado por correo electrónico o LinkedIn, solo se completa si está vacío.

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 encontrado por teléfono, los slugs enviados se actualizan (merge); encontrado por correo electrónico o LinkedIn, solo se completan los slugs vacíos. Los slugs no enviados se mantienen. Ejemplo: { "cpf": "12345678900", "data_nascimento": "1990-01-15", "valor_total": 1500.50 }

Respuesta

Contacto existente reutilizado (created: false). Encontrado por teléfono, los campos enviados se actualizaron; por correo electrónico o LinkedIn, solo se completaron los vacíos e ignored_fields indica lo que no se guardó.

name
string
requerido

Nombre del contacto

company
any
requerido

Empresa del contacto

created
boolean
requerido

true cuando el contacto se creó (201); false cuando se reutilizó (200).

matched_by
enum<string> | null
requerido

Identificador que coincidió

Opciones disponibles:
email,
linkedin,
phone
matches_count
number
requerido

Cuántos contactos de la empresa coincidieron por la clave matched_by (0 al crear). Por encima de 1, la empresa tiene contactos duplicados y se reutilizó el más antiguo.

ignored_fields
string[]
requerido

Campos enviados que NO se guardaron porque el contacto existente ya tenía otro valor (solo cuando se reutiliza por correo electrónico o LinkedIn). Ej.: email, phone_number, job_title, additional_attributes.<slug>. Vacío al crear y cuando se encuentra por teléfono.

_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