Referencia de la API

Contactos

Crea, actualiza, importa en lote y borra contactos, registra quién pidió no recibir mensajes y consulta los campos disponibles en tu base de contactos.

8 operaciones
URL basehttps://api.messages.ccxcompany.co
AutenticaciónBearer con tu clave de API

El texto técnico de abajo viene del contrato público, openapi.json, en el idioma en que se escribió el contrato.

List contacts in the current organization

GET/contacts

Returns a paginated list. Filters: tag, optInStatus, source, externalId, listId, updatedSince, q, limit, skip.

`externalId=` acha o contato pelo Customer ID do seu sistema (igualdade exata, no máximo um resultado).

`q=` searches name, whatsappProfileName, email and phone (phone matches by DIGITS, so (11) 96459-8816 finds +5511964598816).

Until 2026-09-26 this filter was documented as requiring pii:full and being silently dropped otherwise. It was in fact never implemented in the repository layer — every caller, including pii:full ones, got the unfiltered list back.

PII_SENSITIVE fields (phone) are masked unless the caller has pii:full.

Parámetros

Campo	Dónde	Tipo	Descripción
`tag`opcional	query	`string`
`optInStatus`opcional	query	`string`	Valores:`granteddeniedunknown`
`source`opcional	query	`string`	Valores:`manualimportapiwebhook`
`externalId`opcional	query	`string`	Customer ID do seu sistema (DBM/CRM). Único na organização quando presente; aceita UUID, número, hash hex ou composto como `loja:45:cliente:123`.
`listId`opcional	query	`string`	Só os contatos desta lista estática (`lst_…`).
`q`opcional	query	`string`	Free-text prefix search on `name`/`email`. Requires `pii:full`; otherwise silently dropped and a `warnings` entry is emitted.
`updatedSince`opcional	query	`string · date-time`	ISO-8601 timestamp in UTC.
`limit`opcional	query	`integer`
`skip`opcional	query	`integer`

Respuestas

200Default Response

Campos y ejemplo de la respuesta

Campo	Tipo	Descripción
`items`obligatorio	`object[]`
`items[].id`obligatorio	`string`	Branded Contact id (`cnt_` prefix + 21 nano-id chars).
`items[].organizationId`obligatorio	`string`	Branded Organization id (`org_` prefix + 21 nano-id chars).
`items[].phone`obligatorio	`string`	E.164 phone (PII_SENSITIVE — masked unless caller has `pii:full`).
`items[].phoneHash`obligatorio	`string`	Deterministic blind index `sha256(orgId + ':' + e164phone)`.
`items[].name`opcional	`string`
`items[].email`opcional	`string · email`
`items[].avatarUrl`opcional	`string · uri`	Public avatar URL displayed in the chat list and contact card. Accepts http(s) URLs and inline `data:` URIs (≤64 KB) for click-to-upload avatars stored without external storage.
`items[].whatsappProfileName`opcional	`string`	Display name reported by WhatsApp on inbound messages (`contacts[0].profile.name`). Updated automatically; does not overwrite an operator-set `name`.
`items[].cpfCipher`opcional	`string`	PII_CRITICAL — encrypted CPF blob (JSON-serialized EncryptedBlob). Never returned plaintext via routes; decryption requires `reason` + `actor` audit at the service layer.
`items[].cnpjCipher`opcional	`string`	PII_CRITICAL — encrypted CNPJ.
`items[].birthDateCipher`opcional	`string`	PII_CRITICAL — encrypted birth date.
`items[].attributes`obligatorio	`object`	Free-form key/value attributes: text, number, boolean, null or a list of short texts (no nested objects).
`items[].documentos`opcional	`object`	Os documentos que o contato TEM, já mascarados no servidor (o valor completo nunca sai aqui). Só no GET de um único contato (`/contacts/:id`). Para ver um por inteiro: `POST /v2/contacts/:id/documentos/revelar` (só sessão, `contacts:pii`, auditado).
`items[].documentos.cpf`opcional	`string`
`items[].documentos.cnpj`opcional	`string`
`items[].documentos.nascimento`opcional	`string`
`items[].debtorGroups`opcional	`object[]`	Grupos de cobrança do contato: cada grupo é uma empresa devedora e os telefones daquele contexto.
`items[].debtorGroups[].id`obligatorio	`string`
`items[].debtorGroups[].company`obligatorio	`string`
`items[].debtorGroups[].phones`obligatorio	`string[]`
`items[].debtorGroups[].amountCents`opcional	`integer`	Valor em aberto daquela dívida, em centavos de BRL.
`items[].debtorGroups[].status`opcional	`string`	Situação da dívida daquele grupo.Valores:`vencidaem_atrasoem_dia`
`items[].debtorGroups[].reference`opcional	`string`	Referência livre: nº do contrato, dias de atraso, observação.
`items[].tags`obligatorio	`string[]`
`items[].optIn`obligatorio	`object`
`items[].optIn.status`obligatorio	`string`	Valores:`granteddeniedunknown`
`items[].optIn.source`opcional	`string`
`items[].optIn.at`opcional	`string · date-time`	ISO-8601 timestamp in UTC.
`items[].optIn.ip`opcional	`string`
`items[].optIn.userAgent`opcional	`string`
`items[].optIn.revokedAt`opcional	`string · date-time`	ISO-8601 timestamp in UTC.
`items[].optIn.revokedReason`opcional	`string`
`items[].source`obligatorio	`string`	Valores:`manualimportapiwebhook`
`items[].externalId`opcional	`string`	Customer ID do seu sistema (DBM/CRM). Único na organização quando presente; aceita UUID, número, hash hex ou composto como `loja:45:cliente:123`.
`items[].externalIds`opcional	`object`	Os ids do contato nos sistemas integrados (HubSpot, Pipedrive, RD Station, Zendesk) — a chave que a sincronização com cada um usa. Ausente = o contato não está em nenhuma integração.
`items[].externalIds.hubspot`opcional	`string`
`items[].externalIds.pipedrive`opcional	`string`
`items[].externalIds.rd_station`opcional	`string`
`items[].externalIds.zendesk`opcional	`string`
`items[].companyId`opcional	`string`	Empresa do CRM (`emp_` + 21 caracteres) — `GET /v2/companies`.
`items[].papelNaEmpresa`opcional	`string`	O papel do contato na empresa (`companyId`): decisor, financeiro, operacao ou outro.Valores:`decisorfinanceirooperacaooutro`
`items[].lastInteractionAt`opcional	`string · date-time`	ISO-8601 timestamp in UTC.
`items[].createdAt`obligatorio	`string · date-time`	ISO-8601 timestamp in UTC.
`items[].updatedAt`obligatorio	`string · date-time`	ISO-8601 timestamp in UTC.
`total`obligatorio	`integer`
`warnings`opcional	`string[]`	Set when a filter was silently dropped (e.g. `q=` without `pii:full`).

JSON

{  "items": [    {      "id": "cnt_aB3xY9zQ1pTkLmNoPqRsT",      "organizationId": "org_pGgniw5L7CTDSZDwjDrQ2",      "phone": "+5511999998888",      "phoneHash": "string",      "name": "Alice Andersen",      "email": "alice@example.com",      "avatarUrl": "https://cdn.example.com/avatars/alice.png",      "whatsappProfileName": "string",      "cpfCipher": "string",      "cnpjCipher": "string",      "birthDateCipher": "string",      "attributes": {},      "documentos": {        "cpf": "•••.456.789-••",        "cnpj": "••.•••.678/0001-••",        "nascimento": "••/••/1990"      },      "debtorGroups": [        {          "id": "grp_9f1c2a3b4d5e6f70",          "company": "Casas Bahia",          "phones": [            "+5511988887777",            "1140042000"          ],          "amountCents": 248000,          "status": "vencida",          "reference": "Contrato 8842-01 · atraso 47 dias"        }      ],      "tags": [        "string"      ],      "optIn": {        "status": "granted",        "source": "landing-page",        "at": "2026-04-07T17:30:00.000Z",        "ip": "203.0.113.42",        "userAgent": "string",        "revokedAt": "2026-04-07T17:30:00.000Z",        "revokedReason": "string"      },      "source": "manual",      "externalId": "123",      "externalIds": {        "hubspot": "9001",        "pipedrive": "string",        "rd_station": "string",        "zendesk": "string"      },      "companyId": "emp_aB3xY9zQ1pTkLmNoPqRsT",      "papelNaEmpresa": "decisor",      "lastInteractionAt": "2026-04-07T17:30:00.000Z",      "createdAt": "2026-04-07T17:30:00.000Z",      "updatedAt": "2026-04-07T17:30:00.000Z"    }  ],  "total": 42,  "warnings": [    "string"  ]}

401RFC 7807 problem details for UNAUTHORIZED (401).
403RFC 7807 problem details for FORBIDDEN (403).

Las respuestas de error siguen el formato RFC 7807 (application/problem+json), con un código estable en el campo code. Ver los códigos de error

Ejemplo en curl

cURL

curl 'https://api.messages.ccxcompany.co/contacts' \  -H "Authorization: Bearer $CCX_API_KEY"

Solo los campos obligatorios. Cambia los valores de ejemplo por los tuyos.

Create a contact

POST/contacts

Creates a contact record in the caller's org. Phone is the natural identity — duplicate phone in the same org returns 409.

externalId guarda o Customer ID do seu sistema; é único na organização (409 se já pertence a outro contato).

PII_CRITICAL fields (cpf, cnpj, birthDate) are accepted in plaintext on input and encrypted at rest by the PII guardian (AES-256-GCM, AAD bound to org+contact+field). The response shows them as opaque cipher blobs (cpfCipher, etc.) — they are never returned in plaintext via the API.

phoneHash is computed server-side as sha256(orgId + ':' + e164phone) and used for tenant-scoped phone lookups.

Consentimento: nascer com optIn.status diferente de unknown segue a regra da mudança de situação do PATCH — a data é a hora do servidor; com chave de API, at (concedido) ou revokedAt (negado) do corpo vale, para importar um consentimento antigo (acima de agora + 5 min é 422 DATA_DO_CONSENTIMENTO_NO_FUTURO); quem nasce denied pela chave guarda também o at informado (consentiu em A, recusou em R).

Grava o evento contact.consent_changed (dataInformada: true quando a data veio do corpo).

Cuerpo de la petición`application/json`

Campo	Tipo	Descripción
`phone`obligatorio	`string`	E.164 phone — IMMUTABLE after creation.
`name`opcional	`string`
`email`opcional	`string · email`
`avatarUrl`opcional	`string · uri`
`cpf`opcional	`string`	Plaintext CPF — service encrypts before persistence and stores as `cpfCipher`. PII_CRITICAL.
`cnpj`opcional	`string`	CNPJ com ou sem máscara, numérico ou alfanumérico (formato da Receita); guardado sem máscara e em maiúsculas. O dígito verificador não é conferido. PII_CRITICAL.
`birthDate`opcional	`string · date`
`attributes`opcional	`object`
`tags`opcional	`string[]`
`optIn`opcional	`object`
`optIn.status`obligatorio	`string`	Valores:`granteddeniedunknown`
`optIn.source`opcional	`string`
`optIn.at`opcional	`string · date-time`	ISO-8601 timestamp in UTC.
`optIn.ip`opcional	`string`
`optIn.userAgent`opcional	`string`
`optIn.revokedAt`opcional	`string · date-time`	ISO-8601 timestamp in UTC.
`optIn.revokedReason`opcional	`string`
`source`opcional	`string`	Valores:`manualimportapiwebhook`Por defecto:`manual`
`externalId`opcional	`string`	Customer ID do seu sistema (DBM/CRM). Único na organização quando presente; aceita UUID, número, hash hex ou composto como `loja:45:cliente:123`.

Ejemplo completo del cuerpo

JSON

{  "phone": "+5511999998888",  "name": "Alice Andersen",  "email": "alice@example.com",  "avatarUrl": "https://example.com",  "cpf": "12345678901",  "cnpj": "12.345.678/0001-90",  "birthDate": "1990-05-15",  "attributes": {    "plan": "gold",    "segment": "vip",    "lifetimeValue": 1234.56  },  "tags": [    "vip",    "newsletter"  ],  "optIn": {    "status": "granted",    "source": "landing-page",    "at": "2026-04-07T17:30:00.000Z",    "ip": "203.0.113.42",    "userAgent": "string",    "revokedAt": "2026-04-07T17:30:00.000Z",    "revokedReason": "string"  },  "source": "manual",  "externalId": "123"}

Respuestas

201Default Response

Campos y ejemplo de la respuesta

Campo	Tipo	Descripción
`id`obligatorio	`string`	Branded Contact id (`cnt_` prefix + 21 nano-id chars).
`organizationId`obligatorio	`string`	Branded Organization id (`org_` prefix + 21 nano-id chars).
`phone`obligatorio	`string`	E.164 phone (PII_SENSITIVE — masked unless caller has `pii:full`).
`phoneHash`obligatorio	`string`	Deterministic blind index `sha256(orgId + ':' + e164phone)`.
`name`opcional	`string`
`email`opcional	`string · email`
`avatarUrl`opcional	`string · uri`	Public avatar URL displayed in the chat list and contact card. Accepts http(s) URLs and inline `data:` URIs (≤64 KB) for click-to-upload avatars stored without external storage.
`whatsappProfileName`opcional	`string`	Display name reported by WhatsApp on inbound messages (`contacts[0].profile.name`). Updated automatically; does not overwrite an operator-set `name`.
`cpfCipher`opcional	`string`	PII_CRITICAL — encrypted CPF blob (JSON-serialized EncryptedBlob). Never returned plaintext via routes; decryption requires `reason` + `actor` audit at the service layer.
`cnpjCipher`opcional	`string`	PII_CRITICAL — encrypted CNPJ.
`birthDateCipher`opcional	`string`	PII_CRITICAL — encrypted birth date.
`attributes`obligatorio	`object`	Free-form key/value attributes: text, number, boolean, null or a list of short texts (no nested objects).
`documentos`opcional	`object`	Os documentos que o contato TEM, já mascarados no servidor (o valor completo nunca sai aqui). Só no GET de um único contato (`/contacts/:id`). Para ver um por inteiro: `POST /v2/contacts/:id/documentos/revelar` (só sessão, `contacts:pii`, auditado).
`documentos.cpf`opcional	`string`
`documentos.cnpj`opcional	`string`
`documentos.nascimento`opcional	`string`
`debtorGroups`opcional	`object[]`	Grupos de cobrança do contato: cada grupo é uma empresa devedora e os telefones daquele contexto.
`debtorGroups[].id`obligatorio	`string`
`debtorGroups[].company`obligatorio	`string`
`debtorGroups[].phones`obligatorio	`string[]`
`debtorGroups[].amountCents`opcional	`integer`	Valor em aberto daquela dívida, em centavos de BRL.
`debtorGroups[].status`opcional	`string`	Situação da dívida daquele grupo.Valores:`vencidaem_atrasoem_dia`
`debtorGroups[].reference`opcional	`string`	Referência livre: nº do contrato, dias de atraso, observação.
`tags`obligatorio	`string[]`
`optIn`obligatorio	`object`
`optIn.status`obligatorio	`string`	Valores:`granteddeniedunknown`
`optIn.source`opcional	`string`
`optIn.at`opcional	`string · date-time`	ISO-8601 timestamp in UTC.
`optIn.ip`opcional	`string`
`optIn.userAgent`opcional	`string`
`optIn.revokedAt`opcional	`string · date-time`	ISO-8601 timestamp in UTC.
`optIn.revokedReason`opcional	`string`
`source`obligatorio	`string`	Valores:`manualimportapiwebhook`
`externalId`opcional	`string`	Customer ID do seu sistema (DBM/CRM). Único na organização quando presente; aceita UUID, número, hash hex ou composto como `loja:45:cliente:123`.
`externalIds`opcional	`object`	Os ids do contato nos sistemas integrados (HubSpot, Pipedrive, RD Station, Zendesk) — a chave que a sincronização com cada um usa. Ausente = o contato não está em nenhuma integração.
`externalIds.hubspot`opcional	`string`
`externalIds.pipedrive`opcional	`string`
`externalIds.rd_station`opcional	`string`
`externalIds.zendesk`opcional	`string`
`companyId`opcional	`string`	Empresa do CRM (`emp_` + 21 caracteres) — `GET /v2/companies`.
`papelNaEmpresa`opcional	`string`	O papel do contato na empresa (`companyId`): decisor, financeiro, operacao ou outro.Valores:`decisorfinanceirooperacaooutro`
`lastInteractionAt`opcional	`string · date-time`	ISO-8601 timestamp in UTC.
`createdAt`obligatorio	`string · date-time`	ISO-8601 timestamp in UTC.
`updatedAt`obligatorio	`string · date-time`	ISO-8601 timestamp in UTC.

JSON

{  "id": "cnt_aB3xY9zQ1pTkLmNoPqRsT",  "organizationId": "org_pGgniw5L7CTDSZDwjDrQ2",  "phone": "+5511999998888",  "phoneHash": "string",  "name": "Alice Andersen",  "email": "alice@example.com",  "avatarUrl": "https://cdn.example.com/avatars/alice.png",  "whatsappProfileName": "string",  "cpfCipher": "string",  "cnpjCipher": "string",  "birthDateCipher": "string",  "attributes": {},  "documentos": {    "cpf": "•••.456.789-••",    "cnpj": "••.•••.678/0001-••",    "nascimento": "••/••/1990"  },  "debtorGroups": [    {      "id": "grp_9f1c2a3b4d5e6f70",      "company": "Casas Bahia",      "phones": [        "+5511988887777",        "1140042000"      ],      "amountCents": 248000,      "status": "vencida",      "reference": "Contrato 8842-01 · atraso 47 dias"    }  ],  "tags": [    "string"  ],  "optIn": {    "status": "granted",    "source": "landing-page",    "at": "2026-04-07T17:30:00.000Z",    "ip": "203.0.113.42",    "userAgent": "string",    "revokedAt": "2026-04-07T17:30:00.000Z",    "revokedReason": "string"  },  "source": "manual",  "externalId": "123",  "externalIds": {    "hubspot": "9001",    "pipedrive": "string",    "rd_station": "string",    "zendesk": "string"  },  "companyId": "emp_aB3xY9zQ1pTkLmNoPqRsT",  "papelNaEmpresa": "decisor",  "lastInteractionAt": "2026-04-07T17:30:00.000Z",  "createdAt": "2026-04-07T17:30:00.000Z",  "updatedAt": "2026-04-07T17:30:00.000Z"}

401RFC 7807 problem details for UNAUTHORIZED (401).
403RFC 7807 problem details for FORBIDDEN (403).
409RFC 7807 problem details for CONFLICT (409).
422RFC 7807 problem details for VALIDATION_ERROR (422).

Las respuestas de error siguen el formato RFC 7807 (application/problem+json), con un código estable en el campo code. Ver los códigos de error

Ejemplo en curl

cURL

curl -X POST 'https://api.messages.ccxcompany.co/contacts' \  -H "Authorization: Bearer $CCX_API_KEY" \  -H "Content-Type: application/json" \  -d '{    "phone": "+5511999998888"  }'

Solo los campos obligatorios. Cambia los valores de ejemplo por los tuyos.

Get a single contact

GET/contacts/{id}

Cross-tenant requests return 404 (Mongo Guardian filter masks existence). PII_CRITICAL ciphers are returned as opaque blobs.

documentos traz o CPF, o CNPJ e a data de nascimento que o contato tiver, já mascarados no servidor (•••.456.789-••, ••.•••.678/0001-••, ••/••/1990) — o valor completo nunca sai neste GET.

O CPF só sai mascarado, em `documentos.cpf` — para sessão e para chave de API. Este GET não devolve mais o campo cpf em claro (até a troca do menu do CRM v2, ele vinha para a sessão do painel). Ver o documento por inteiro é só pelo painel: POST /v2/contacts/:id/documentos/revelar (sessão com contacts:pii, auditado); chave de API não revela.

Gravar o CPF continua igual (cpf no corpo do POST e do PATCH).

Parámetros

Campo	Dónde	Tipo	Descripción
`id`obligatorio	ruta	`string`	Branded Contact id (`cnt_` prefix + 21 nano-id chars).

Respuestas

200Default Response

Campos y ejemplo de la respuesta

Campo	Tipo	Descripción
`id`obligatorio	`string`	Branded Contact id (`cnt_` prefix + 21 nano-id chars).
`organizationId`obligatorio	`string`	Branded Organization id (`org_` prefix + 21 nano-id chars).
`phone`obligatorio	`string`	E.164 phone (PII_SENSITIVE — masked unless caller has `pii:full`).
`phoneHash`obligatorio	`string`	Deterministic blind index `sha256(orgId + ':' + e164phone)`.
`name`opcional	`string`
`email`opcional	`string · email`
`avatarUrl`opcional	`string · uri`	Public avatar URL displayed in the chat list and contact card. Accepts http(s) URLs and inline `data:` URIs (≤64 KB) for click-to-upload avatars stored without external storage.
`whatsappProfileName`opcional	`string`	Display name reported by WhatsApp on inbound messages (`contacts[0].profile.name`). Updated automatically; does not overwrite an operator-set `name`.
`cpfCipher`opcional	`string`	PII_CRITICAL — encrypted CPF blob (JSON-serialized EncryptedBlob). Never returned plaintext via routes; decryption requires `reason` + `actor` audit at the service layer.
`cnpjCipher`opcional	`string`	PII_CRITICAL — encrypted CNPJ.
`birthDateCipher`opcional	`string`	PII_CRITICAL — encrypted birth date.
`attributes`obligatorio	`object`	Free-form key/value attributes: text, number, boolean, null or a list of short texts (no nested objects).
`documentos`opcional	`object`	Os documentos que o contato TEM, já mascarados no servidor (o valor completo nunca sai aqui). Só no GET de um único contato (`/contacts/:id`). Para ver um por inteiro: `POST /v2/contacts/:id/documentos/revelar` (só sessão, `contacts:pii`, auditado).
`documentos.cpf`opcional	`string`
`documentos.cnpj`opcional	`string`
`documentos.nascimento`opcional	`string`
`debtorGroups`opcional	`object[]`	Grupos de cobrança do contato: cada grupo é uma empresa devedora e os telefones daquele contexto.
`debtorGroups[].id`obligatorio	`string`
`debtorGroups[].company`obligatorio	`string`
`debtorGroups[].phones`obligatorio	`string[]`
`debtorGroups[].amountCents`opcional	`integer`	Valor em aberto daquela dívida, em centavos de BRL.
`debtorGroups[].status`opcional	`string`	Situação da dívida daquele grupo.Valores:`vencidaem_atrasoem_dia`
`debtorGroups[].reference`opcional	`string`	Referência livre: nº do contrato, dias de atraso, observação.
`tags`obligatorio	`string[]`
`optIn`obligatorio	`object`
`optIn.status`obligatorio	`string`	Valores:`granteddeniedunknown`
`optIn.source`opcional	`string`
`optIn.at`opcional	`string · date-time`	ISO-8601 timestamp in UTC.
`optIn.ip`opcional	`string`
`optIn.userAgent`opcional	`string`
`optIn.revokedAt`opcional	`string · date-time`	ISO-8601 timestamp in UTC.
`optIn.revokedReason`opcional	`string`
`source`obligatorio	`string`	Valores:`manualimportapiwebhook`
`externalId`opcional	`string`	Customer ID do seu sistema (DBM/CRM). Único na organização quando presente; aceita UUID, número, hash hex ou composto como `loja:45:cliente:123`.
`externalIds`opcional	`object`	Os ids do contato nos sistemas integrados (HubSpot, Pipedrive, RD Station, Zendesk) — a chave que a sincronização com cada um usa. Ausente = o contato não está em nenhuma integração.
`externalIds.hubspot`opcional	`string`
`externalIds.pipedrive`opcional	`string`
`externalIds.rd_station`opcional	`string`
`externalIds.zendesk`opcional	`string`
`companyId`opcional	`string`	Empresa do CRM (`emp_` + 21 caracteres) — `GET /v2/companies`.
`papelNaEmpresa`opcional	`string`	O papel do contato na empresa (`companyId`): decisor, financeiro, operacao ou outro.Valores:`decisorfinanceirooperacaooutro`
`lastInteractionAt`opcional	`string · date-time`	ISO-8601 timestamp in UTC.
`createdAt`obligatorio	`string · date-time`	ISO-8601 timestamp in UTC.
`updatedAt`obligatorio	`string · date-time`	ISO-8601 timestamp in UTC.

JSON

{  "id": "cnt_aB3xY9zQ1pTkLmNoPqRsT",  "organizationId": "org_pGgniw5L7CTDSZDwjDrQ2",  "phone": "+5511999998888",  "phoneHash": "string",  "name": "Alice Andersen",  "email": "alice@example.com",  "avatarUrl": "https://cdn.example.com/avatars/alice.png",  "whatsappProfileName": "string",  "cpfCipher": "string",  "cnpjCipher": "string",  "birthDateCipher": "string",  "attributes": {},  "documentos": {    "cpf": "•••.456.789-••",    "cnpj": "••.•••.678/0001-••",    "nascimento": "••/••/1990"  },  "debtorGroups": [    {      "id": "grp_9f1c2a3b4d5e6f70",      "company": "Casas Bahia",      "phones": [        "+5511988887777",        "1140042000"      ],      "amountCents": 248000,      "status": "vencida",      "reference": "Contrato 8842-01 · atraso 47 dias"    }  ],  "tags": [    "string"  ],  "optIn": {    "status": "granted",    "source": "landing-page",    "at": "2026-04-07T17:30:00.000Z",    "ip": "203.0.113.42",    "userAgent": "string",    "revokedAt": "2026-04-07T17:30:00.000Z",    "revokedReason": "string"  },  "source": "manual",  "externalId": "123",  "externalIds": {    "hubspot": "9001",    "pipedrive": "string",    "rd_station": "string",    "zendesk": "string"  },  "companyId": "emp_aB3xY9zQ1pTkLmNoPqRsT",  "papelNaEmpresa": "decisor",  "lastInteractionAt": "2026-04-07T17:30:00.000Z",  "createdAt": "2026-04-07T17:30:00.000Z",  "updatedAt": "2026-04-07T17:30:00.000Z"}

401RFC 7807 problem details for UNAUTHORIZED (401).
403RFC 7807 problem details for FORBIDDEN (403).
404RFC 7807 problem details for NOT_FOUND (404).

Las respuestas de error siguen el formato RFC 7807 (application/problem+json), con un código estable en el campo code. Ver los códigos de error

Ejemplo en curl

cURL

curl 'https://api.messages.ccxcompany.co/contacts/cnt_aB3xY9zQ1pTkLmNoPqRsT' \  -H "Authorization: Bearer $CCX_API_KEY"

Solo los campos obligatorios. Cambia los valores de ejemplo por los tuyos.

Patch a contact

PATCH/contacts/{id}

Partial update. Phone is IMMUTABLE (would break phoneHash). To change a phone, delete + recreate.

Scalar fields accept null to clear; tags and attributes are replaced wholesale.

Setting a critical field (cpf/cnpj/birthDate) re-encrypts at the service layer with a fresh IV/tag bound to the same org+contact+field AAD.

Empresa (CRM): companyId tem de ser uma empresa desta organização (422 VINCULO_INVALIDO); null solta a empresa e o papelNaEmpresa junto; trocar por OUTRA empresa sem mandar papelNaEmpresa tira o papel (era da empresa anterior). O papelNaEmpresa exige uma empresa — a gravada ou a deste PATCH (422 PAPEL_SEM_EMPRESA).

Consentimento: o optIn MESCLA com o gravado — ip, userAgent, source e revokedReason que não vierem ficam.

A data é do servidor: quando o status muda, ele carimba at (concedido) ou revokedAt (negado, ou revogado um concedido) com a hora dele; quando o status NÃO muda, at e revokedAt do corpo são ignorados e as datas gravadas ficam. Com chave de API, a data de uma mudança de status pode vir no corpo (at ao conceder, revokedAt ao revogar) — para importar um consentimento antigo; data acima de agora + 5 min é 422 DATA_DO_CONSENTIMENTO_NO_FUTURO.

Pela sessão do painel, a data do corpo é sempre ignorada. Re-conceder (denied → granted) limpa revokedAt e revokedReason. A mudança de situação grava o evento contact.consent_changed na auditoria (quem, de qual situação para qual e quando — nenhum dado do contato; dataInformada: true quando a data veio do corpo).

Parámetros

Campo	Dónde	Tipo	Descripción
`id`obligatorio	ruta	`string`	Branded Contact id (`cnt_` prefix + 21 nano-id chars).

Cuerpo de la petición`application/json`

Campo	Tipo	Descripción
`name`opcional	`string \| null`
`email`opcional	`string \| null · email`
`avatarUrl`opcional	`string \| null · uri`
`cpf`opcional	`string \| null`
`cnpj`opcional	`string \| null`
`birthDate`opcional	`string \| null · date`
`attributes`opcional	`object`
`tags`opcional	`string[]`
`optIn`opcional	`object`
`optIn.status`obligatorio	`string`	Valores:`granteddeniedunknown`
`optIn.source`opcional	`string`
`optIn.at`opcional	`string · date-time`	ISO-8601 timestamp in UTC.
`optIn.ip`opcional	`string`
`optIn.userAgent`opcional	`string`
`optIn.revokedAt`opcional	`string · date-time`	ISO-8601 timestamp in UTC.
`optIn.revokedReason`opcional	`string`
`externalId`opcional	`string \| null`	Customer ID do seu sistema (DBM/CRM). Único na organização quando presente; aceita UUID, número, hash hex ou composto como `loja:45:cliente:123`.
`companyId`opcional	`string \| null`	A empresa do contato (da MESMA organização: senão 422 `VINCULO_INVALIDO`). `null` solta a empresa e o papel junto; outra empresa sem `papelNaEmpresa` no mesmo PATCH tira o papel.
`papelNaEmpresa`opcional	`string \| null`	O papel na empresa; exige a empresa (a gravada ou a deste PATCH): senão 422 `PAPEL_SEM_EMPRESA`. `null` limpa.Valores:`decisorfinanceirooperacaooutro`

Ejemplo completo del cuerpo

JSON

{  "name": "string",  "email": "user@example.com",  "avatarUrl": "https://example.com",  "cpf": "string",  "cnpj": "string",  "birthDate": "2026-10-16",  "attributes": {},  "tags": [    "string"  ],  "optIn": {    "status": "granted",    "source": "landing-page",    "at": "2026-04-07T17:30:00.000Z",    "ip": "203.0.113.42",    "userAgent": "string",    "revokedAt": "2026-04-07T17:30:00.000Z",    "revokedReason": "string"  },  "externalId": "123",  "companyId": "emp_aB3xY9zQ1pTkLmNoPqRsT",  "papelNaEmpresa": "decisor"}

Respuestas

200Default Response

Campos y ejemplo de la respuesta

Campo	Tipo	Descripción
`id`obligatorio	`string`	Branded Contact id (`cnt_` prefix + 21 nano-id chars).
`organizationId`obligatorio	`string`	Branded Organization id (`org_` prefix + 21 nano-id chars).
`phone`obligatorio	`string`	E.164 phone (PII_SENSITIVE — masked unless caller has `pii:full`).
`phoneHash`obligatorio	`string`	Deterministic blind index `sha256(orgId + ':' + e164phone)`.
`name`opcional	`string`
`email`opcional	`string · email`
`avatarUrl`opcional	`string · uri`	Public avatar URL displayed in the chat list and contact card. Accepts http(s) URLs and inline `data:` URIs (≤64 KB) for click-to-upload avatars stored without external storage.
`whatsappProfileName`opcional	`string`	Display name reported by WhatsApp on inbound messages (`contacts[0].profile.name`). Updated automatically; does not overwrite an operator-set `name`.
`cpfCipher`opcional	`string`	PII_CRITICAL — encrypted CPF blob (JSON-serialized EncryptedBlob). Never returned plaintext via routes; decryption requires `reason` + `actor` audit at the service layer.
`cnpjCipher`opcional	`string`	PII_CRITICAL — encrypted CNPJ.
`birthDateCipher`opcional	`string`	PII_CRITICAL — encrypted birth date.
`attributes`obligatorio	`object`	Free-form key/value attributes: text, number, boolean, null or a list of short texts (no nested objects).
`documentos`opcional	`object`	Os documentos que o contato TEM, já mascarados no servidor (o valor completo nunca sai aqui). Só no GET de um único contato (`/contacts/:id`). Para ver um por inteiro: `POST /v2/contacts/:id/documentos/revelar` (só sessão, `contacts:pii`, auditado).
`documentos.cpf`opcional	`string`
`documentos.cnpj`opcional	`string`
`documentos.nascimento`opcional	`string`
`debtorGroups`opcional	`object[]`	Grupos de cobrança do contato: cada grupo é uma empresa devedora e os telefones daquele contexto.
`debtorGroups[].id`obligatorio	`string`
`debtorGroups[].company`obligatorio	`string`
`debtorGroups[].phones`obligatorio	`string[]`
`debtorGroups[].amountCents`opcional	`integer`	Valor em aberto daquela dívida, em centavos de BRL.
`debtorGroups[].status`opcional	`string`	Situação da dívida daquele grupo.Valores:`vencidaem_atrasoem_dia`
`debtorGroups[].reference`opcional	`string`	Referência livre: nº do contrato, dias de atraso, observação.
`tags`obligatorio	`string[]`
`optIn`obligatorio	`object`
`optIn.status`obligatorio	`string`	Valores:`granteddeniedunknown`
`optIn.source`opcional	`string`
`optIn.at`opcional	`string · date-time`	ISO-8601 timestamp in UTC.
`optIn.ip`opcional	`string`
`optIn.userAgent`opcional	`string`
`optIn.revokedAt`opcional	`string · date-time`	ISO-8601 timestamp in UTC.
`optIn.revokedReason`opcional	`string`
`source`obligatorio	`string`	Valores:`manualimportapiwebhook`
`externalId`opcional	`string`	Customer ID do seu sistema (DBM/CRM). Único na organização quando presente; aceita UUID, número, hash hex ou composto como `loja:45:cliente:123`.
`externalIds`opcional	`object`	Os ids do contato nos sistemas integrados (HubSpot, Pipedrive, RD Station, Zendesk) — a chave que a sincronização com cada um usa. Ausente = o contato não está em nenhuma integração.
`externalIds.hubspot`opcional	`string`
`externalIds.pipedrive`opcional	`string`
`externalIds.rd_station`opcional	`string`
`externalIds.zendesk`opcional	`string`
`companyId`opcional	`string`	Empresa do CRM (`emp_` + 21 caracteres) — `GET /v2/companies`.
`papelNaEmpresa`opcional	`string`	O papel do contato na empresa (`companyId`): decisor, financeiro, operacao ou outro.Valores:`decisorfinanceirooperacaooutro`
`lastInteractionAt`opcional	`string · date-time`	ISO-8601 timestamp in UTC.
`createdAt`obligatorio	`string · date-time`	ISO-8601 timestamp in UTC.
`updatedAt`obligatorio	`string · date-time`	ISO-8601 timestamp in UTC.

JSON

{  "id": "cnt_aB3xY9zQ1pTkLmNoPqRsT",  "organizationId": "org_pGgniw5L7CTDSZDwjDrQ2",  "phone": "+5511999998888",  "phoneHash": "string",  "name": "Alice Andersen",  "email": "alice@example.com",  "avatarUrl": "https://cdn.example.com/avatars/alice.png",  "whatsappProfileName": "string",  "cpfCipher": "string",  "cnpjCipher": "string",  "birthDateCipher": "string",  "attributes": {},  "documentos": {    "cpf": "•••.456.789-••",    "cnpj": "••.•••.678/0001-••",    "nascimento": "••/••/1990"  },  "debtorGroups": [    {      "id": "grp_9f1c2a3b4d5e6f70",      "company": "Casas Bahia",      "phones": [        "+5511988887777",        "1140042000"      ],      "amountCents": 248000,      "status": "vencida",      "reference": "Contrato 8842-01 · atraso 47 dias"    }  ],  "tags": [    "string"  ],  "optIn": {    "status": "granted",    "source": "landing-page",    "at": "2026-04-07T17:30:00.000Z",    "ip": "203.0.113.42",    "userAgent": "string",    "revokedAt": "2026-04-07T17:30:00.000Z",    "revokedReason": "string"  },  "source": "manual",  "externalId": "123",  "externalIds": {    "hubspot": "9001",    "pipedrive": "string",    "rd_station": "string",    "zendesk": "string"  },  "companyId": "emp_aB3xY9zQ1pTkLmNoPqRsT",  "papelNaEmpresa": "decisor",  "lastInteractionAt": "2026-04-07T17:30:00.000Z",  "createdAt": "2026-04-07T17:30:00.000Z",  "updatedAt": "2026-04-07T17:30:00.000Z"}

401RFC 7807 problem details for UNAUTHORIZED (401).
403RFC 7807 problem details for FORBIDDEN (403).
404RFC 7807 problem details for NOT_FOUND (404).
422RFC 7807 problem details for VALIDATION_ERROR (422).

Las respuestas de error siguen el formato RFC 7807 (application/problem+json), con un código estable en el campo code. Ver los códigos de error

Ejemplo en curl

cURL

curl -X PATCH 'https://api.messages.ccxcompany.co/contacts/cnt_aB3xY9zQ1pTkLmNoPqRsT' \  -H "Authorization: Bearer $CCX_API_KEY" \  -H "Content-Type: application/json" \  -d '{}'

Solo los campos obligatorios. Cambia los valores de ejemplo por los tuyos.

Hard-delete a contact

DELETE/contacts/{id}

Removes the row immediately. GDPR/LGPD purge across related collections (messages, conversations) is handled by the dedicated purge endpoint in Step 31. CRM links go first: the contact leaves every card (as main contact and from outrosContatos; the card stays in its pipeline with a system activity "Contato removido") and stops being the main contact of any company.

Parámetros

Campo	Dónde	Tipo	Descripción
`id`obligatorio	ruta	`string`	Branded Contact id (`cnt_` prefix + 21 nano-id chars).

Respuestas

204Contact removed.
401RFC 7807 problem details for UNAUTHORIZED (401).
403RFC 7807 problem details for FORBIDDEN (403).
404RFC 7807 problem details for NOT_FOUND (404).

Las respuestas de error siguen el formato RFC 7807 (application/problem+json), con un código estable en el campo code. Ver los códigos de error

Ejemplo en curl

cURL

curl -X DELETE 'https://api.messages.ccxcompany.co/contacts/cnt_aB3xY9zQ1pTkLmNoPqRsT' \  -H "Authorization: Bearer $CCX_API_KEY"

Solo los campos obligatorios. Cambia los valores de ejemplo por los tuyos.

Bulk import contacts (synchronous)

POST/contacts/import

Imports up to 1000 rows per request synchronously. For each row: if phoneHash already exists in the org, PATCHes when upsert=true, otherwise skips; otherwise creates.

Errors are collected per row and returned in the response — partial success is OK; the caller decides what to retry.

`externalId` (Customer ID): quando a linha traz, ele é gravado e passa a ser a chave do seu sistema. Se ele já pertence a OUTRO telefone, a linha vai para errors (telefone é imutável). results devolve o id CCX de cada linha que deu certo, na ordem do lote.

Empresa (CRM): a linha aceita companyId e papelNaEmpresa. A empresa tem de ser desta organização e o papel exige a empresa; senão a linha vai para errors, sem repetir o valor recebido.

Consentimento: o optIn da linha segue a regra do PATCH (e do cadastro, para o contato novo) — a data é a do servidor; com chave de API, a data de uma mudança de situação pode vir na linha (acima de agora + 5 min, a linha vai para errors).

Async worker import (CSV upload + S3 + queue) lands in Step 18.

Cuerpo de la petición`application/json`

Campo	Tipo	Descripción
`rows`obligatorio	`object[]`	Up to 1000 rows per request. Async worker import (CSV upload + S3) lands in Step 18.
`rows[].phone`obligatorio	`string`	E.164 phone — IMMUTABLE after creation.
`rows[].name`opcional	`string`
`rows[].email`opcional	`string · email`
`rows[].avatarUrl`opcional	`string · uri`
`rows[].cpf`opcional	`string`	Plaintext CPF — service encrypts before persistence and stores as `cpfCipher`. PII_CRITICAL.
`rows[].cnpj`opcional	`string`	CNPJ com ou sem máscara, numérico ou alfanumérico (formato da Receita); guardado sem máscara e em maiúsculas. O dígito verificador não é conferido. PII_CRITICAL.
`rows[].birthDate`opcional	`string · date`
`rows[].attributes`opcional	`object`
`rows[].tags`opcional	`string[]`
`rows[].optIn`opcional	`object`
`rows[].optIn.status`obligatorio	`string`	Valores:`granteddeniedunknown`
`rows[].optIn.source`opcional	`string`
`rows[].optIn.at`opcional	`string · date-time`	ISO-8601 timestamp in UTC.
`rows[].optIn.ip`opcional	`string`
`rows[].optIn.userAgent`opcional	`string`
`rows[].optIn.revokedAt`opcional	`string · date-time`	ISO-8601 timestamp in UTC.
`rows[].optIn.revokedReason`opcional	`string`
`rows[].source`opcional	`string`	Valores:`manualimportapiwebhook`Por defecto:`manual`
`rows[].externalId`opcional	`string`	Customer ID do seu sistema (DBM/CRM). Único na organização quando presente; aceita UUID, número, hash hex ou composto como `loja:45:cliente:123`.
`rows[].companyId`opcional	`string`	A empresa do contato, da MESMA organização (senão a linha vai para `errors`). Todas as linhas são conferidas numa consulta só.
`rows[].papelNaEmpresa`opcional	`string`	O papel na empresa; exige `companyId` na linha (ou, numa atualização, a empresa já gravada).Valores:`decisorfinanceirooperacaooutro`
`upsert`opcional	`boolean`	If true, existing rows are PATCHed; otherwise duplicates are skipped.Por defecto:`true`

Ejemplo completo del cuerpo

JSON

{  "rows": [    {      "phone": "+5511999998888",      "name": "Alice Andersen",      "email": "alice@example.com",      "tags": [        "vip"      ],      "optIn": {        "status": "granted",        "source": "landing-page"      }    }  ],  "upsert": true}

Respuestas

200Default Response

Campos y ejemplo de la respuesta

Campo	Tipo	Descripción
`inserted`obligatorio	`integer`
`updated`obligatorio	`integer`
`skipped`obligatorio	`integer`
`errors`obligatorio	`object[]`
`errors[].row`obligatorio	`integer`
`errors[].reason`obligatorio	`string`
`results`opcional	`object[]`	O id CCX de cada linha que deu certo, na ordem do lote (`row` é o índice da linha enviada).
`results[].row`obligatorio	`integer`
`results[].id`obligatorio	`string`	Branded Contact id (`cnt_` prefix + 21 nano-id chars).
`results[].action`obligatorio	`string`	Valores:`insertedupdatedskipped`

JSON

{  "inserted": 42,  "updated": 7,  "skipped": 0,  "errors": [    {      "row": 0,      "reason": "string"    }  ],  "results": [    {      "row": 0,      "id": "cnt_aB3xY9zQ1pTkLmNoPqRsT",      "action": "inserted"    }  ]}

401RFC 7807 problem details for UNAUTHORIZED (401).
403RFC 7807 problem details for FORBIDDEN (403).
422RFC 7807 problem details for VALIDATION_ERROR (422).

Las respuestas de error siguen el formato RFC 7807 (application/problem+json), con un código estable en el campo code. Ver los códigos de error

Ejemplo en curl

cURL

curl -X POST 'https://api.messages.ccxcompany.co/contacts/import' \  -H "Authorization: Bearer $CCX_API_KEY" \  -H "Content-Type: application/json" \  -d '{    "rows": [      {        "phone": "+5511999998888",        "name": "Alice Andersen",        "email": "alice@example.com",        "tags": [          "vip"        ],        "optIn": {          "status": "granted",          "source": "landing-page"        }      }    ]  }'

Solo los campos obligatorios. Cambia los valores de ejemplo por los tuyos.

Mark a contact as opted out

POST/contacts/{id}/opt-out

Sets optIn.status: "denied", records revokedAt (server time) and optional revokedReason / source (the stored ip and userAgent are kept). Repeating the opt-out of a contact already denied keeps the first revocation (its dates, source and revokedReason); only a missing revokedAt gets the server time. The transition to denied records the contact.consent_changed audit event.

Worker dispatch (Step 19) MUST honor this for any subsequent send to the contact.

Parámetros

Campo	Dónde	Tipo	Descripción
`id`obligatorio	ruta	`string`	Branded Contact id (`cnt_` prefix + 21 nano-id chars).

Cuerpo de la petición`application/json`

Campo	Tipo	Descripción
`reason`opcional	`string`
`source`opcional	`string`

Ejemplo completo del cuerpo

JSON

{  "reason": "user-requested",  "source": "dashboard"}

Respuestas

200Default Response

Campos y ejemplo de la respuesta

Campo	Tipo	Descripción
`id`obligatorio	`string`	Branded Contact id (`cnt_` prefix + 21 nano-id chars).
`organizationId`obligatorio	`string`	Branded Organization id (`org_` prefix + 21 nano-id chars).
`phone`obligatorio	`string`	E.164 phone (PII_SENSITIVE — masked unless caller has `pii:full`).
`phoneHash`obligatorio	`string`	Deterministic blind index `sha256(orgId + ':' + e164phone)`.
`name`opcional	`string`
`email`opcional	`string · email`
`avatarUrl`opcional	`string · uri`	Public avatar URL displayed in the chat list and contact card. Accepts http(s) URLs and inline `data:` URIs (≤64 KB) for click-to-upload avatars stored without external storage.
`whatsappProfileName`opcional	`string`	Display name reported by WhatsApp on inbound messages (`contacts[0].profile.name`). Updated automatically; does not overwrite an operator-set `name`.
`cpfCipher`opcional	`string`	PII_CRITICAL — encrypted CPF blob (JSON-serialized EncryptedBlob). Never returned plaintext via routes; decryption requires `reason` + `actor` audit at the service layer.
`cnpjCipher`opcional	`string`	PII_CRITICAL — encrypted CNPJ.
`birthDateCipher`opcional	`string`	PII_CRITICAL — encrypted birth date.
`attributes`obligatorio	`object`	Free-form key/value attributes: text, number, boolean, null or a list of short texts (no nested objects).
`documentos`opcional	`object`	Os documentos que o contato TEM, já mascarados no servidor (o valor completo nunca sai aqui). Só no GET de um único contato (`/contacts/:id`). Para ver um por inteiro: `POST /v2/contacts/:id/documentos/revelar` (só sessão, `contacts:pii`, auditado).
`documentos.cpf`opcional	`string`
`documentos.cnpj`opcional	`string`
`documentos.nascimento`opcional	`string`
`debtorGroups`opcional	`object[]`	Grupos de cobrança do contato: cada grupo é uma empresa devedora e os telefones daquele contexto.
`debtorGroups[].id`obligatorio	`string`
`debtorGroups[].company`obligatorio	`string`
`debtorGroups[].phones`obligatorio	`string[]`
`debtorGroups[].amountCents`opcional	`integer`	Valor em aberto daquela dívida, em centavos de BRL.
`debtorGroups[].status`opcional	`string`	Situação da dívida daquele grupo.Valores:`vencidaem_atrasoem_dia`
`debtorGroups[].reference`opcional	`string`	Referência livre: nº do contrato, dias de atraso, observação.
`tags`obligatorio	`string[]`
`optIn`obligatorio	`object`
`optIn.status`obligatorio	`string`	Valores:`granteddeniedunknown`
`optIn.source`opcional	`string`
`optIn.at`opcional	`string · date-time`	ISO-8601 timestamp in UTC.
`optIn.ip`opcional	`string`
`optIn.userAgent`opcional	`string`
`optIn.revokedAt`opcional	`string · date-time`	ISO-8601 timestamp in UTC.
`optIn.revokedReason`opcional	`string`
`source`obligatorio	`string`	Valores:`manualimportapiwebhook`
`externalId`opcional	`string`	Customer ID do seu sistema (DBM/CRM). Único na organização quando presente; aceita UUID, número, hash hex ou composto como `loja:45:cliente:123`.
`externalIds`opcional	`object`	Os ids do contato nos sistemas integrados (HubSpot, Pipedrive, RD Station, Zendesk) — a chave que a sincronização com cada um usa. Ausente = o contato não está em nenhuma integração.
`externalIds.hubspot`opcional	`string`
`externalIds.pipedrive`opcional	`string`
`externalIds.rd_station`opcional	`string`
`externalIds.zendesk`opcional	`string`
`companyId`opcional	`string`	Empresa do CRM (`emp_` + 21 caracteres) — `GET /v2/companies`.
`papelNaEmpresa`opcional	`string`	O papel do contato na empresa (`companyId`): decisor, financeiro, operacao ou outro.Valores:`decisorfinanceirooperacaooutro`
`lastInteractionAt`opcional	`string · date-time`	ISO-8601 timestamp in UTC.
`createdAt`obligatorio	`string · date-time`	ISO-8601 timestamp in UTC.
`updatedAt`obligatorio	`string · date-time`	ISO-8601 timestamp in UTC.

JSON

{  "id": "cnt_aB3xY9zQ1pTkLmNoPqRsT",  "organizationId": "org_pGgniw5L7CTDSZDwjDrQ2",  "phone": "+5511999998888",  "phoneHash": "string",  "name": "Alice Andersen",  "email": "alice@example.com",  "avatarUrl": "https://cdn.example.com/avatars/alice.png",  "whatsappProfileName": "string",  "cpfCipher": "string",  "cnpjCipher": "string",  "birthDateCipher": "string",  "attributes": {},  "documentos": {    "cpf": "•••.456.789-••",    "cnpj": "••.•••.678/0001-••",    "nascimento": "••/••/1990"  },  "debtorGroups": [    {      "id": "grp_9f1c2a3b4d5e6f70",      "company": "Casas Bahia",      "phones": [        "+5511988887777",        "1140042000"      ],      "amountCents": 248000,      "status": "vencida",      "reference": "Contrato 8842-01 · atraso 47 dias"    }  ],  "tags": [    "string"  ],  "optIn": {    "status": "granted",    "source": "landing-page",    "at": "2026-04-07T17:30:00.000Z",    "ip": "203.0.113.42",    "userAgent": "string",    "revokedAt": "2026-04-07T17:30:00.000Z",    "revokedReason": "string"  },  "source": "manual",  "externalId": "123",  "externalIds": {    "hubspot": "9001",    "pipedrive": "string",    "rd_station": "string",    "zendesk": "string"  },  "companyId": "emp_aB3xY9zQ1pTkLmNoPqRsT",  "papelNaEmpresa": "decisor",  "lastInteractionAt": "2026-04-07T17:30:00.000Z",  "createdAt": "2026-04-07T17:30:00.000Z",  "updatedAt": "2026-04-07T17:30:00.000Z"}

401RFC 7807 problem details for UNAUTHORIZED (401).
403RFC 7807 problem details for FORBIDDEN (403).
404RFC 7807 problem details for NOT_FOUND (404).
422RFC 7807 problem details for VALIDATION_ERROR (422).

Las respuestas de error siguen el formato RFC 7807 (application/problem+json), con un código estable en el campo code. Ver los códigos de error

Ejemplo en curl

cURL

curl -X POST 'https://api.messages.ccxcompany.co/contacts/cnt_aB3xY9zQ1pTkLmNoPqRsT/opt-out' \  -H "Authorization: Bearer $CCX_API_KEY" \  -H "Content-Type: application/json" \  -d '{}'

Solo los campos obligatorios. Cambia los valores de ejemplo por los tuyos.

Lista os campos do contato

GET/v2/contacts/fields

Todo campo do contato que pode ir numa mensagem, para montar o mapeamento de variáveis (variaveis.<slot>.campo na jornada, templateVarMap.<slot>.field na campanha).

padrao: nome, e-mail, telefone, ID externo, nome no WhatsApp, tags, cliente desde, última interação;
propriedade: os atributos declarados em Configurações › Atributos personalizados, com rótulo e tipo;
em_uso: chaves de attributes encontradas nos 2.000 contatos mais recentes sem declaração.

proibido: true marca dado sensível (documento, senha, cartão): ele aparece, mas qualquer mapa que o use é recusado. O resultado fica em cache por até 10 minutos. Permissão: contacts:read.

Respuestas

200Default Response

Campos y ejemplo de la respuesta

Campo	Tipo	Descripción
`campos`obligatorio	`object[]`
`campos[].chave`obligatorio	`string`
`campos[].rotulo`obligatorio	`string`
`campos[].grupo`obligatorio	`string`	Valores:`padraopropriedadeem_uso`
`campos[].tipo`obligatorio	`string`	Valores:`textonumerosim_naodatalista`
`campos[].proibido`obligatorio	`boolean`
`campos[].obrigatorio`opcional	`boolean`
`campos[].emUso`opcional	`integer`
`amostra`obligatorio	`integer`

JSON

{  "campos": [    {      "chave": "string",      "rotulo": "string",      "grupo": "padrao",      "tipo": "texto",      "proibido": true,      "obrigatorio": true,      "emUso": 0    }  ],  "amostra": 0}

401RFC 7807 problem details for UNAUTHORIZED (401).
403RFC 7807 problem details for FORBIDDEN (403).

Las respuestas de error siguen el formato RFC 7807 (application/problem+json), con un código estable en el campo code. Ver los códigos de error

Ejemplo en curl

cURL

curl 'https://api.messages.ccxcompany.co/v2/contacts/fields' \  -H "Authorization: Bearer $CCX_API_KEY"

Solo los campos obligatorios. Cambia los valores de ejemplo por los tuyos.

¿Atascado en una ruta? Habla con quienes mantienen la API.

Empieza gratis Habla con ventas

Si creas la cuenta desde la web, recibes 5 US$ de crédito de prueba.

Contactos

Parámetros

Respuestas

Ejemplo en curl

Cuerpo de la peticiónapplication/json

Respuestas

Ejemplo en curl

Parámetros

Respuestas

Ejemplo en curl

Parámetros

Cuerpo de la peticiónapplication/json

Respuestas

Ejemplo en curl

Parámetros

Respuestas

Ejemplo en curl

Cuerpo de la peticiónapplication/json

Respuestas

Ejemplo en curl

Parámetros

Cuerpo de la peticiónapplication/json

Respuestas

Ejemplo en curl

Respuestas

Ejemplo en curl

Otras áreas de la API

¿Atascado en una ruta? Habla con quienes mantienen la API.

Cuerpo de la petición`application/json`

Cuerpo de la petición`application/json`

Cuerpo de la petición`application/json`

Cuerpo de la petición`application/json`