Referência da API

Contatos

Crie, atualize, importe em lote e apague contatos, registre quem pediu para não receber mensagens e consulte os campos disponíveis na sua base.

8 operações
URL basehttps://api.messages.ccxcompany.co
AutenticaçãoBearer com a sua chave de API

O texto técnico abaixo vem do contrato público, o openapi.json, no idioma em que o contrato foi escrito.

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	Onde	Tipo	Descrição
`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`

Respostas

200Default Response

Campos e exemplo da resposta

Campo	Tipo	Descrição
`items`obrigatório	`object[]`
`items[].id`obrigatório	`string`	Branded Contact id (`cnt_` prefix + 21 nano-id chars).
`items[].organizationId`obrigatório	`string`	Branded Organization id (`org_` prefix + 21 nano-id chars).
`items[].phone`obrigatório	`string`	E.164 phone (PII_SENSITIVE — masked unless caller has `pii:full`).
`items[].phoneHash`obrigatório	`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`obrigatório	`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`obrigatório	`string`
`items[].debtorGroups[].company`obrigatório	`string`
`items[].debtorGroups[].phones`obrigatório	`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`obrigatório	`string[]`
`items[].optIn`obrigatório	`object`
`items[].optIn.status`obrigatório	`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`obrigatório	`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`obrigatório	`string · date-time`	ISO-8601 timestamp in UTC.
`items[].updatedAt`obrigatório	`string · date-time`	ISO-8601 timestamp in UTC.
`total`obrigatório	`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).

As respostas de erro seguem o formato RFC 7807 (application/problem+json), com um código estável no campo code. Ver os códigos de erro

Exemplo em curl

cURL

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

Só os campos obrigatórios. Troque os valores de exemplo pelos seus.

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).

Corpo da requisição`application/json`

Campo	Tipo	Descrição
`phone`obrigatório	`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`obrigatório	`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`Padrão:`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`.

Exemplo completo do corpo

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"}

Respostas

201Default Response

Campos e exemplo da resposta

Campo	Tipo	Descrição
`id`obrigatório	`string`	Branded Contact id (`cnt_` prefix + 21 nano-id chars).
`organizationId`obrigatório	`string`	Branded Organization id (`org_` prefix + 21 nano-id chars).
`phone`obrigatório	`string`	E.164 phone (PII_SENSITIVE — masked unless caller has `pii:full`).
`phoneHash`obrigatório	`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`obrigatório	`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`obrigatório	`string`
`debtorGroups[].company`obrigatório	`string`
`debtorGroups[].phones`obrigatório	`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`obrigatório	`string[]`
`optIn`obrigatório	`object`
`optIn.status`obrigatório	`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`obrigatório	`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`obrigatório	`string · date-time`	ISO-8601 timestamp in UTC.
`updatedAt`obrigatório	`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).

As respostas de erro seguem o formato RFC 7807 (application/problem+json), com um código estável no campo code. Ver os códigos de erro

Exemplo em 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"  }'

Só os campos obrigatórios. Troque os valores de exemplo pelos seus.

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	Onde	Tipo	Descrição
`id`obrigatório	caminho	`string`	Branded Contact id (`cnt_` prefix + 21 nano-id chars).

Respostas

200Default Response

Campos e exemplo da resposta

Campo	Tipo	Descrição
`id`obrigatório	`string`	Branded Contact id (`cnt_` prefix + 21 nano-id chars).
`organizationId`obrigatório	`string`	Branded Organization id (`org_` prefix + 21 nano-id chars).
`phone`obrigatório	`string`	E.164 phone (PII_SENSITIVE — masked unless caller has `pii:full`).
`phoneHash`obrigatório	`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`obrigatório	`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`obrigatório	`string`
`debtorGroups[].company`obrigatório	`string`
`debtorGroups[].phones`obrigatório	`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`obrigatório	`string[]`
`optIn`obrigatório	`object`
`optIn.status`obrigatório	`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`obrigatório	`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`obrigatório	`string · date-time`	ISO-8601 timestamp in UTC.
`updatedAt`obrigatório	`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).

As respostas de erro seguem o formato RFC 7807 (application/problem+json), com um código estável no campo code. Ver os códigos de erro

Exemplo em curl

cURL

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

Só os campos obrigatórios. Troque os valores de exemplo pelos seus.

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	Onde	Tipo	Descrição
`id`obrigatório	caminho	`string`	Branded Contact id (`cnt_` prefix + 21 nano-id chars).

Corpo da requisição`application/json`

Campo	Tipo	Descrição
`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`obrigatório	`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`

Exemplo completo do corpo

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"}

Respostas

200Default Response

Campos e exemplo da resposta

Campo	Tipo	Descrição
`id`obrigatório	`string`	Branded Contact id (`cnt_` prefix + 21 nano-id chars).
`organizationId`obrigatório	`string`	Branded Organization id (`org_` prefix + 21 nano-id chars).
`phone`obrigatório	`string`	E.164 phone (PII_SENSITIVE — masked unless caller has `pii:full`).
`phoneHash`obrigatório	`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`obrigatório	`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`obrigatório	`string`
`debtorGroups[].company`obrigatório	`string`
`debtorGroups[].phones`obrigatório	`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`obrigatório	`string[]`
`optIn`obrigatório	`object`
`optIn.status`obrigatório	`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`obrigatório	`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`obrigatório	`string · date-time`	ISO-8601 timestamp in UTC.
`updatedAt`obrigatório	`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).

As respostas de erro seguem o formato RFC 7807 (application/problem+json), com um código estável no campo code. Ver os códigos de erro

Exemplo em 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 '{}'

Só os campos obrigatórios. Troque os valores de exemplo pelos seus.

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	Onde	Tipo	Descrição
`id`obrigatório	caminho	`string`	Branded Contact id (`cnt_` prefix + 21 nano-id chars).

Respostas

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

As respostas de erro seguem o formato RFC 7807 (application/problem+json), com um código estável no campo code. Ver os códigos de erro

Exemplo em curl

cURL

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

Só os campos obrigatórios. Troque os valores de exemplo pelos seus.

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.

Corpo da requisição`application/json`

Campo	Tipo	Descrição
`rows`obrigatório	`object[]`	Up to 1000 rows per request. Async worker import (CSV upload + S3) lands in Step 18.
`rows[].phone`obrigatório	`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`obrigatório	`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`Padrão:`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.Padrão:`true`

Exemplo completo do corpo

JSON

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

Respostas

200Default Response

Campos e exemplo da resposta

Campo	Tipo	Descrição
`inserted`obrigatório	`integer`
`updated`obrigatório	`integer`
`skipped`obrigatório	`integer`
`errors`obrigatório	`object[]`
`errors[].row`obrigatório	`integer`
`errors[].reason`obrigatório	`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`obrigatório	`integer`
`results[].id`obrigatório	`string`	Branded Contact id (`cnt_` prefix + 21 nano-id chars).
`results[].action`obrigatório	`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).

As respostas de erro seguem o formato RFC 7807 (application/problem+json), com um código estável no campo code. Ver os códigos de erro

Exemplo em 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"        }      }    ]  }'

Só os campos obrigatórios. Troque os valores de exemplo pelos seus.

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	Onde	Tipo	Descrição
`id`obrigatório	caminho	`string`	Branded Contact id (`cnt_` prefix + 21 nano-id chars).

Corpo da requisição`application/json`

Campo	Tipo	Descrição
`reason`opcional	`string`
`source`opcional	`string`

Exemplo completo do corpo

JSON

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

Respostas

200Default Response

Campos e exemplo da resposta

Campo	Tipo	Descrição
`id`obrigatório	`string`	Branded Contact id (`cnt_` prefix + 21 nano-id chars).
`organizationId`obrigatório	`string`	Branded Organization id (`org_` prefix + 21 nano-id chars).
`phone`obrigatório	`string`	E.164 phone (PII_SENSITIVE — masked unless caller has `pii:full`).
`phoneHash`obrigatório	`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`obrigatório	`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`obrigatório	`string`
`debtorGroups[].company`obrigatório	`string`
`debtorGroups[].phones`obrigatório	`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`obrigatório	`string[]`
`optIn`obrigatório	`object`
`optIn.status`obrigatório	`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`obrigatório	`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`obrigatório	`string · date-time`	ISO-8601 timestamp in UTC.
`updatedAt`obrigatório	`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).

As respostas de erro seguem o formato RFC 7807 (application/problem+json), com um código estável no campo code. Ver os códigos de erro

Exemplo em 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 '{}'

Só os campos obrigatórios. Troque os valores de exemplo pelos seus.

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.

Respostas

200Default Response

Campos e exemplo da resposta

Campo	Tipo	Descrição
`campos`obrigatório	`object[]`
`campos[].chave`obrigatório	`string`
`campos[].rotulo`obrigatório	`string`
`campos[].grupo`obrigatório	`string`	Valores:`padraopropriedadeem_uso`
`campos[].tipo`obrigatório	`string`	Valores:`textonumerosim_naodatalista`
`campos[].proibido`obrigatório	`boolean`
`campos[].obrigatorio`opcional	`boolean`
`campos[].emUso`opcional	`integer`
`amostra`obrigatório	`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).

As respostas de erro seguem o formato RFC 7807 (application/problem+json), com um código estável no campo code. Ver os códigos de erro

Exemplo em curl

cURL

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

Só os campos obrigatórios. Troque os valores de exemplo pelos seus.

Travou em alguma rota? Fale com quem mantém a API.

Criar conta grátis Falar com vendas

Criando a conta pelo site, você ganha R$ 10 de crédito de teste.

Contatos

Parâmetros

Respostas

Exemplo em curl

Corpo da requisiçãoapplication/json

Respostas

Exemplo em curl

Parâmetros

Respostas

Exemplo em curl

Parâmetros

Corpo da requisiçãoapplication/json

Respostas

Exemplo em curl

Parâmetros

Respostas

Exemplo em curl

Corpo da requisiçãoapplication/json

Respostas

Exemplo em curl

Parâmetros

Corpo da requisiçãoapplication/json

Respostas

Exemplo em curl

Respostas

Exemplo em curl

Outras áreas da API

Travou em alguma rota? Fale com quem mantém a API.

Corpo da requisição`application/json`

Corpo da requisição`application/json`

Corpo da requisição`application/json`

Corpo da requisição`application/json`