API reference

Static lists

Keep static contact lists in sync with your system: create, rename and delete lists, and add, replace or remove up to 50,000 members per call.

8 operations
Base URLhttps://api.messages.ccxcompany.co
AuthenticationBearer with your API key

The technical text below comes from the public contract, openapi.json, in the language the contract was written in.

Lista as listas estáticas

GET/v2/lists

Listas estáticas são audiências mantidas pelo SEU sistema: quem está nelas é quem a API colocou. Cada item traz size, o número de contatos na lista agora. Para os contatos, use GET /contacts?listId=.

Permissão: contacts:read.

Responses

200Default Response

Response fields and example

Field	Type	Description
`items`required	`object[]`
`items[].id`required	`string`
`items[].name`required	`string`
`items[].description`optional	`string`
`items[].size`required	`integer`
`items[].createdAt`required	`string`
`items[].updatedAt`required	`string`

JSON

{  "items": [    {      "id": "string",      "name": "string",      "description": "string",      "size": 0,      "createdAt": "string",      "updatedAt": "string"    }  ]}

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

Error responses follow RFC 7807 (application/problem+json), with a stable code in the code field. See the error codes

curl example

cURL

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

Required fields only. Swap the sample values for your own.

Cria uma lista estática

POST/v2/lists

O nome é único na organização (409 se repetir).

Permissão: contacts:write.

Request body`application/json`

Field	Type	Description
`name`required	`string`	Nome da lista — único na organização.
`description`optional	`string`

Full body example

JSON

{  "name": "string",  "description": "string"}

Responses

201Default Response
Response fields and example
Field Type Description
idrequired string
namerequired string
descriptionoptional string
sizerequired integer
createdAtrequired string
updatedAtrequired string
JSON
```
{  "id": "string",  "name": "string",  "description": "string",  "size": 0,  "createdAt": "string",  "updatedAt": "string"}
```
400RFC 7807 problem details for BAD_REQUEST (400).
401RFC 7807 problem details for UNAUTHORIZED (401).
403RFC 7807 problem details for FORBIDDEN (403).
404RFC 7807 problem details for NOT_FOUND (404).
409RFC 7807 problem details for CONFLICT (409).
422RFC 7807 problem details for VALIDATION_ERROR (422).

Field	Type	Description
`id`required	`string`
`name`required	`string`
`description`optional	`string`
`size`required	`integer`
`createdAt`required	`string`
`updatedAt`required	`string`

Error responses follow RFC 7807 (application/problem+json), with a stable code in the code field. See the error codes

curl example

cURL

curl -X POST 'https://api.messages.ccxcompany.co/v2/lists' \  -H "Authorization: Bearer $CCX_API_KEY" \  -H "Content-Type: application/json" \  -d '{    "name": "string"  }'

Required fields only. Swap the sample values for your own.

Lê uma lista estática

GET/v2/lists/{id}

Permissão: contacts:read.

Parameters

Field	In	Type	Description
`id`required	path	`string`

Responses

200Default Response
Response fields and example
Field Type Description
idrequired string
namerequired string
descriptionoptional string
sizerequired integer
createdAtrequired string
updatedAtrequired string
JSON
```
{  "id": "string",  "name": "string",  "description": "string",  "size": 0,  "createdAt": "string",  "updatedAt": "string"}
```
400RFC 7807 problem details for BAD_REQUEST (400).
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).

Field	Type	Description
`id`required	`string`
`name`required	`string`
`description`optional	`string`
`size`required	`integer`
`createdAt`required	`string`
`updatedAt`required	`string`

Error responses follow RFC 7807 (application/problem+json), with a stable code in the code field. See the error codes

curl example

cURL

curl 'https://api.messages.ccxcompany.co/v2/lists/<id>' \  -H "Authorization: Bearer $CCX_API_KEY"

Required fields only. Swap the sample values for your own.

Renomeia ou descreve uma lista estática

PATCH/v2/lists/{id}

Permissão: contacts:write.

Parameters

Field	In	Type	Description
`id`required	path	`string`

Request body`application/json`

Field	Type	Description
`name`optional	`string`
`description`optional	`string`

Full body example

JSON

{  "name": "string",  "description": "string"}

Responses

200Default Response
Response fields and example
Field Type Description
idrequired string
namerequired string
descriptionoptional string
sizerequired integer
createdAtrequired string
updatedAtrequired string
JSON
```
{  "id": "string",  "name": "string",  "description": "string",  "size": 0,  "createdAt": "string",  "updatedAt": "string"}
```
400RFC 7807 problem details for BAD_REQUEST (400).
401RFC 7807 problem details for UNAUTHORIZED (401).
403RFC 7807 problem details for FORBIDDEN (403).
404RFC 7807 problem details for NOT_FOUND (404).
409RFC 7807 problem details for CONFLICT (409).
422RFC 7807 problem details for VALIDATION_ERROR (422).

Field	Type	Description
`id`required	`string`
`name`required	`string`
`description`optional	`string`
`size`required	`integer`
`createdAt`required	`string`
`updatedAt`required	`string`

Error responses follow RFC 7807 (application/problem+json), with a stable code in the code field. See the error codes

curl example

cURL

curl -X PATCH 'https://api.messages.ccxcompany.co/v2/lists/<id>' \  -H "Authorization: Bearer $CCX_API_KEY" \  -H "Content-Type: application/json" \  -d '{}'

Required fields only. Swap the sample values for your own.

Apaga uma lista estática

DELETE/v2/lists/{id}

Apaga a lista; os contatos continuam na base, só deixam de estar nela.

Permissão: contacts:write.

Parameters

Field	In	Type	Description
`id`required	path	`string`

Responses

204Default Response
400RFC 7807 problem details for BAD_REQUEST (400).
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).

Error responses follow RFC 7807 (application/problem+json), with a stable code in the code field. See the error codes

curl example

cURL

curl -X DELETE 'https://api.messages.ccxcompany.co/v2/lists/<id>' \  -H "Authorization: Bearer $CCX_API_KEY"

Required fields only. Swap the sample values for your own.

Adiciona membros à lista

POST/v2/lists/{id}/members

Entra quem veio; ninguém sai. Quem já estava não conta em added.

Identificadores aceitos, juntos ou separados: externalIds (o Customer ID do seu sistema), contactIds (cnt_…) e phones (E.164). Até 50.000 por chamada; lista maior entra em lotes de POST …/members.

Quem não existe na base não é criado: volta em notFound (amostra de até 100 por tipo) e em notFoundCount. Para criar, importe antes com POST /contacts/import.

Permissão: contacts:write.

Parameters

Field	In	Type	Description
`id`required	path	`string`

Request body`application/json`

Field	Type	Description
`externalIds`optional	`string[]`	Customer IDs do seu sistema (o `externalId` do contato).
`contactIds`optional	`string[]`	Ids CCX (`cnt_…`).
`phones`optional	`string[]`	Telefones em E.164.

Full body example

JSON

{  "externalIds": [    "string"  ],  "contactIds": [    "string"  ],  "phones": [    "string"  ]}

Responses

200Default Response

Response fields and example

Field	Type	Description
`listId`required	`string`
`matched`required	`integer`
`added`required	`integer`
`removed`required	`integer`
`total`required	`integer`
`notFoundCount`required	`integer`
`notFound`required	`object`
`notFound.externalIds`required	`string[]`
`notFound.contactIds`required	`string[]`
`notFound.phones`required	`string[]`

JSON

{  "listId": "string",  "matched": 0,  "added": 0,  "removed": 0,  "total": 0,  "notFoundCount": 0,  "notFound": {    "externalIds": [      "string"    ],    "contactIds": [      "string"    ],    "phones": [      "string"    ]  }}

400RFC 7807 problem details for BAD_REQUEST (400).
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).

Error responses follow RFC 7807 (application/problem+json), with a stable code in the code field. See the error codes

curl example

cURL

curl -X POST 'https://api.messages.ccxcompany.co/v2/lists/<id>/members' \  -H "Authorization: Bearer $CCX_API_KEY" \  -H "Content-Type: application/json" \  -d '{}'

Required fields only. Swap the sample values for your own.

Substitui os membros da lista

PUT/v2/lists/{id}/members

A lista passa a ser exatamente quem veio: entra quem não estava, sai quem não veio. Se nenhum identificador achar contato, a chamada é recusada com 422 e a lista não muda (para esvaziar, use …/members/remove).

Quem não existe na base não é criado: volta em notFound (amostra de até 100 por tipo) e em notFoundCount. Para criar, importe antes com POST /contacts/import.

Permissão: contacts:write.

Parameters

Field	In	Type	Description
`id`required	path	`string`

Request body`application/json`

Field	Type	Description
`externalIds`optional	`string[]`	Customer IDs do seu sistema (o `externalId` do contato).
`contactIds`optional	`string[]`	Ids CCX (`cnt_…`).
`phones`optional	`string[]`	Telefones em E.164.

Full body example

JSON

{  "externalIds": [    "string"  ],  "contactIds": [    "string"  ],  "phones": [    "string"  ]}

Responses

200Default Response

Response fields and example

Field	Type	Description
`listId`required	`string`
`matched`required	`integer`
`added`required	`integer`
`removed`required	`integer`
`total`required	`integer`
`notFoundCount`required	`integer`
`notFound`required	`object`
`notFound.externalIds`required	`string[]`
`notFound.contactIds`required	`string[]`
`notFound.phones`required	`string[]`

JSON

{  "listId": "string",  "matched": 0,  "added": 0,  "removed": 0,  "total": 0,  "notFoundCount": 0,  "notFound": {    "externalIds": [      "string"    ],    "contactIds": [      "string"    ],    "phones": [      "string"    ]  }}

400RFC 7807 problem details for BAD_REQUEST (400).
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).

Error responses follow RFC 7807 (application/problem+json), with a stable code in the code field. See the error codes

curl example

cURL

curl -X PUT 'https://api.messages.ccxcompany.co/v2/lists/<id>/members' \  -H "Authorization: Bearer $CCX_API_KEY" \  -H "Content-Type: application/json" \  -d '{}'

Required fields only. Swap the sample values for your own.

Remove membros da lista

POST/v2/lists/{id}/members/remove

Sai quem veio. Os contatos continuam na base.

Quem não existe na base não é criado: volta em notFound (amostra de até 100 por tipo) e em notFoundCount. Para criar, importe antes com POST /contacts/import.

Permissão: contacts:write.

Parameters

Field	In	Type	Description
`id`required	path	`string`

Request body`application/json`

Field	Type	Description
`externalIds`optional	`string[]`	Customer IDs do seu sistema (o `externalId` do contato).
`contactIds`optional	`string[]`	Ids CCX (`cnt_…`).
`phones`optional	`string[]`	Telefones em E.164.

Full body example

JSON

{  "externalIds": [    "string"  ],  "contactIds": [    "string"  ],  "phones": [    "string"  ]}

Responses

200Default Response

Response fields and example

Field	Type	Description
`listId`required	`string`
`matched`required	`integer`
`added`required	`integer`
`removed`required	`integer`
`total`required	`integer`
`notFoundCount`required	`integer`
`notFound`required	`object`
`notFound.externalIds`required	`string[]`
`notFound.contactIds`required	`string[]`
`notFound.phones`required	`string[]`

JSON

{  "listId": "string",  "matched": 0,  "added": 0,  "removed": 0,  "total": 0,  "notFoundCount": 0,  "notFound": {    "externalIds": [      "string"    ],    "contactIds": [      "string"    ],    "phones": [      "string"    ]  }}

400RFC 7807 problem details for BAD_REQUEST (400).
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).

Error responses follow RFC 7807 (application/problem+json), with a stable code in the code field. See the error codes

curl example

cURL

curl -X POST 'https://api.messages.ccxcompany.co/v2/lists/<id>/members/remove' \  -H "Authorization: Bearer $CCX_API_KEY" \  -H "Content-Type: application/json" \  -d '{}'

Required fields only. Swap the sample values for your own.

Stuck on a route? Talk to the people who run the API.

Start free Talk to sales

Static lists

Responses

curl example

Request bodyapplication/json

Responses

curl example

Parameters

Responses

curl example

Parameters

Request bodyapplication/json

Responses

curl example

Parameters

Responses

curl example

Parameters

Request bodyapplication/json

Responses

curl example

Parameters

Request bodyapplication/json

Responses

curl example

Parameters

Request bodyapplication/json

Responses

curl example

Other API areas

Stuck on a route? Talk to the people who run the API.

Request body`application/json`

Request body`application/json`

Request body`application/json`

Request body`application/json`

Request body`application/json`