API reference

WhatsApp numbers

List your organization's WhatsApp numbers, check each one's status, quality and messaging tier straight from Meta, and track send volume over time.

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

List WABA numbers in the current organization

GET/numbers

Returns a paginated list. Filters: status, qualityRating, limit, skip. Sorted by createdAt desc.

Parameters

Field	In	Type	Description
`status`optional	query	`string`	Values:`availableconnecteddisconnectedflaggedpending`
`qualityRating`optional	query	`string`	Values:`greenyellowredunknown`
`limit`optional	query	`integer`
`skip`optional	query	`integer`

Responses

200Default Response

Response fields and example

Field	Type	Description
`items`required	`object[]`
`items[].id`required	`string`	Branded Number id (`num_` prefix + 21 nano-id chars).
`items[].organizationId`required	`string`	Branded Organization id (`org_` prefix + 21 nano-id chars).
`items[].phoneNumberId`required	`string`	Meta phone_number_id from the WABA Graph API.
`items[].wabaId`required	`string`	Meta WhatsApp Business Account id.
`items[].displayPhone`required	`string`	E.164 phone number — PII_SENSITIVE, masked in cross-tenant responses.
`items[].status`required	`string`	Values:`availableconnecteddisconnectedflaggedpending`
`items[].qualityRating`required	`string`	Values:`greenyellowredunknown`
`items[].messagingTier`required	`string`	Values:`tier_250tier_1ktier_2ktier_10ktier_100kunlimited`
`items[].rateLimit`required	`object`
`items[].rateLimit.perSecond`required	`integer`
`items[].rateLimit.perDay`required	`integer`
`items[].meta`required	`object`
`items[].meta.verifiedName`optional	`string`	Display name registered with WhatsApp Business.
`items[].meta.byo`optional	`boolean`	True when the number runs under the customer's own WABA.
`items[].meta.nameStatus`optional	`string`	Situação do nome de exibição na Meta. Ausente ⇒ desconhecido (número sem sync). Não deduza aprovação da presença de `verifiedName`: a Meta devolve o nome mesmo quando o recusa.Values:`approvedpendingrejectedexpirednone`
`items[].meta.partnerRemovedAt`optional	`string \| null · date-time`	When Meta reported (`account_update` `PARTNER_REMOVED` or `PARTNER_APP_UNINSTALLED`) that the customer removed CCX from this number's account. Only a mark: status and history are untouched, but sending through this number is expected to fail. `null`/absent = no such report pending.
`items[].meta.partnerRemovedReason`optional	`string \| null`	Which Meta event set `partnerRemovedAt`; set and cleared together with it: - `PARTNER_REMOVED` — the customer stopped sharing the account with CCX. - `PARTNER_APP_UNINSTALLED` — the customer uninstalled the CCX app (or removed its permissions), which revokes the token CCX sends with.Values:`PARTNER_REMOVEDPARTNER_APP_UNINSTALLED`
`items[].profile`optional	`object`
`items[].profile.about`optional	`string`
`items[].profile.address`optional	`string`
`items[].profile.email`optional	`string`
`items[].profile.website`optional	`string`
`items[].profile.vertical`optional	`string`
`items[].profile.profilePictureUrl`optional	`string`
`items[].lastMetaSyncAt`optional	`string \| null · date-time`
`items[].createdAt`required	`string · date-time`	ISO-8601 timestamp in UTC.
`items[].updatedAt`required	`string · date-time`	ISO-8601 timestamp in UTC.
`total`required	`integer`

JSON

{  "items": [    {      "id": "num_aB3xY9zQ1pTkLmNoPqRsT",      "organizationId": "org_pGgniw5L7CTDSZDwjDrQ2",      "phoneNumberId": "1234567890123456",      "wabaId": "9876543210987654",      "displayPhone": "+5511999998888",      "status": "connected",      "qualityRating": "green",      "messagingTier": "tier_1k",      "rateLimit": {        "perSecond": 80,        "perDay": 100000      },      "meta": {        "verifiedName": "Acme Sales",        "byo": false,        "nameStatus": "rejected",        "partnerRemovedAt": "2026-10-16T12:00:00.000Z",        "partnerRemovedReason": "PARTNER_REMOVED"      },      "profile": {        "about": "string",        "address": "string",        "email": "string",        "website": "string",        "vertical": "string",        "profilePictureUrl": "string"      },      "lastMetaSyncAt": "2026-10-16T12:00:00.000Z",      "createdAt": "2026-04-07T17:30:00.000Z",      "updatedAt": "2026-04-07T17:30:00.000Z"    }  ],  "total": 3}

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/numbers' \  -H "Authorization: Bearer $CCX_API_KEY"

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

Get a single WABA number

GET/numbers/{id}

Returns the full Number record for the given id. Tenant isolation is enforced by the Mongo Guardian filter — a request from another org receives 404, not the doc.

Parameters

Field	In	Type	Description
`id`required	path	`string`	Branded Number id (`num_` prefix + 21 nano-id chars).

Responses

200Default Response

Response fields and example

Field	Type	Description
`id`required	`string`	Branded Number id (`num_` prefix + 21 nano-id chars).
`organizationId`required	`string`	Branded Organization id (`org_` prefix + 21 nano-id chars).
`phoneNumberId`required	`string`	Meta phone_number_id from the WABA Graph API.
`wabaId`required	`string`	Meta WhatsApp Business Account id.
`displayPhone`required	`string`	E.164 phone number — PII_SENSITIVE, masked in cross-tenant responses.
`status`required	`string`	Values:`availableconnecteddisconnectedflaggedpending`
`qualityRating`required	`string`	Values:`greenyellowredunknown`
`messagingTier`required	`string`	Values:`tier_250tier_1ktier_2ktier_10ktier_100kunlimited`
`rateLimit`required	`object`
`rateLimit.perSecond`required	`integer`
`rateLimit.perDay`required	`integer`
`meta`required	`object`
`meta.verifiedName`optional	`string`	Display name registered with WhatsApp Business.
`meta.byo`optional	`boolean`	True when the number runs under the customer's own WABA.
`meta.nameStatus`optional	`string`	Situação do nome de exibição na Meta. Ausente ⇒ desconhecido (número sem sync). Não deduza aprovação da presença de `verifiedName`: a Meta devolve o nome mesmo quando o recusa.Values:`approvedpendingrejectedexpirednone`
`meta.partnerRemovedAt`optional	`string \| null · date-time`	When Meta reported (`account_update` `PARTNER_REMOVED` or `PARTNER_APP_UNINSTALLED`) that the customer removed CCX from this number's account. Only a mark: status and history are untouched, but sending through this number is expected to fail. `null`/absent = no such report pending.
`meta.partnerRemovedReason`optional	`string \| null`	Which Meta event set `partnerRemovedAt`; set and cleared together with it: - `PARTNER_REMOVED` — the customer stopped sharing the account with CCX. - `PARTNER_APP_UNINSTALLED` — the customer uninstalled the CCX app (or removed its permissions), which revokes the token CCX sends with.Values:`PARTNER_REMOVEDPARTNER_APP_UNINSTALLED`
`profile`optional	`object`
`profile.about`optional	`string`
`profile.address`optional	`string`
`profile.email`optional	`string`
`profile.website`optional	`string`
`profile.vertical`optional	`string`
`profile.profilePictureUrl`optional	`string`
`lastMetaSyncAt`optional	`string \| null · date-time`
`createdAt`required	`string · date-time`	ISO-8601 timestamp in UTC.
`updatedAt`required	`string · date-time`	ISO-8601 timestamp in UTC.

JSON

{  "id": "num_aB3xY9zQ1pTkLmNoPqRsT",  "organizationId": "org_pGgniw5L7CTDSZDwjDrQ2",  "phoneNumberId": "1234567890123456",  "wabaId": "9876543210987654",  "displayPhone": "+5511999998888",  "status": "connected",  "qualityRating": "green",  "messagingTier": "tier_1k",  "rateLimit": {    "perSecond": 80,    "perDay": 100000  },  "meta": {    "verifiedName": "Acme Sales",    "byo": false,    "nameStatus": "rejected",    "partnerRemovedAt": "2026-10-16T12:00:00.000Z",    "partnerRemovedReason": "PARTNER_REMOVED"  },  "profile": {    "about": "string",    "address": "string",    "email": "string",    "website": "string",    "vertical": "string",    "profilePictureUrl": "string"  },  "lastMetaSyncAt": "2026-10-16T12:00: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).

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/numbers/num_aB3xY9zQ1pTkLmNoPqRsT' \  -H "Authorization: Bearer $CCX_API_KEY"

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

Real-time health check from Meta

GET/numbers/{id}/health

Fetches current number status, quality, messaging tier, and business profile directly from Meta Graph API.

Parameters

Field	In	Type	Description
`id`required	path	`string`	Branded Number id (`num_` prefix + 21 nano-id chars).

Responses

200Default Response
Response fields and example
JSON
```
{}
```
401RFC 7807 problem details for UNAUTHORIZED (401).
403RFC 7807 problem details for FORBIDDEN (403).
404RFC 7807 problem details for NOT_FOUND (404).

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/numbers/num_aB3xY9zQ1pTkLmNoPqRsT/health' \  -H "Authorization: Bearer $CCX_API_KEY"

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

Envios reais deste número na janela pedida (default 24h)

GET/numbers/{id}/usage

Agrega messages (outbound, numberId) na janela. Aceita ?window=24h|7d|30d.

Parameters

Field	In	Type	Description
`window`optional	query	`string`
`id`required	path	`string`	Branded Number id (`num_` prefix + 21 nano-id chars).

Responses

200Default Response
Response fields and example
Field Type Description
windowrequired string
sentrequired integer
marketingSentoptional integer | null
sincerequired string · date-time
untilrequired string · date-time
JSON
```
{  "window": "string",  "sent": 0,  "marketingSent": 0,  "since": "2026-10-16T12:00:00.000Z",  "until": "2026-10-16T12:00:00.000Z"}
```
401RFC 7807 problem details for UNAUTHORIZED (401).
403RFC 7807 problem details for FORBIDDEN (403).
404RFC 7807 problem details for NOT_FOUND (404).

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/numbers/num_aB3xY9zQ1pTkLmNoPqRsT/usage' \  -H "Authorization: Bearer $CCX_API_KEY"

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

Timeseries de envios (buckets pra sparkline)

GET/numbers/{id}/usage/timeseries

Retorna points[] alinhados no bucket pedido (hour|day). Buckets vazios entram como sent: 0 — o cliente pode desenhar direto.

Parameters

Field	In	Type	Description
`window`optional	query	`string`
`bucket`optional	query	`string`	Values:`hourday`
`id`required	path	`string`	Branded Number id (`num_` prefix + 21 nano-id chars).

Responses

200Default Response

Response fields and example

Field	Type	Description
`window`required	`string`
`bucket`required	`string`	Values:`hourday`
`since`required	`string · date-time`
`until`required	`string · date-time`
`points`required	`object[]`
`points[].at`required	`string · date-time`
`points[].sent`required	`integer`

JSON

{  "window": "string",  "bucket": "hour",  "since": "2026-10-16T12:00:00.000Z",  "until": "2026-10-16T12:00:00.000Z",  "points": [    {      "at": "2026-10-16T12:00:00.000Z",      "sent": 0    }  ]}

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

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/numbers/num_aB3xY9zQ1pTkLmNoPqRsT/usage/timeseries' \  -H "Authorization: Bearer $CCX_API_KEY"

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

Field	Type	Description
`window`required	`string`
`sent`required	`integer`
`marketingSent`optional	`integer \| null`
`since`required	`string · date-time`
`until`required	`string · date-time`

WhatsApp numbers

List WABA numbers in the current organization

Parameters

Responses

curl example

Get a single WABA number

Parameters

Responses

curl example

Real-time health check from Meta

Parameters

Responses

curl example

Envios reais deste número na janela pedida (default 24h)

Parameters

Responses

curl example

Timeseries de envios (buckets pra sparkline)

Parameters

Responses

curl example

Other API areas

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