API reference

Segments

Build dynamic segments by tag, attribute, opt-in, channel or last interaction, preview the count and a sample before saving, and edit saved ones.

6 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 saved segments

GET/v2/segments

Returns the org's saved segments (dynamic contact lists). Supports name search + pagination.

Parameters

Field	In	Type	Description
`q`optional	query	`string`	Filter segments by name substring.
`limit`optional	query	`integer`	Page size (default 50).
`skip`optional	query	`integer`	Offset for pagination.

Responses

200Default Response
Response fields and example
JSON
```
{}
```
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/segments' \  -H "Authorization: Bearer $CCX_API_KEY"

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

Create a saved segment

POST/v2/segments

Persists a named, filter-based dynamic list. filters is an AND-joined array of leaf conditions (tag / attribute / optIn / lastInteraction / channel); at least one is required.

For nested AND/OR logic, send the recursive filterTree instead — when present it takes precedence over filters.

Request body`application/json`

Field	Type	Description
`name`required	`string`
`description`optional	`string`
`filters`required	`object[]`
`filters[].field`optional	`string`	Values:`channel`
`filters[].operator`optional	`string`	Values:`has`
`filters[].value`optional	`string`	Values:`whatsappemail`
`filters[].key`optional	`string`
`filterTree`optional	`object`
`filterTree.kind`optional	`string`	Values:`group`
`filterTree.filter`optional	`object`
`filterTree.filter.field`optional	`string`	Values:`channel`
`filterTree.filter.operator`optional	`string`	Values:`has`
`filterTree.filter.value`optional	`string`	Values:`whatsappemail`
`filterTree.filter.key`optional	`string`
`filterTree.operator`optional	`string`	Values:`andor`
`filterTree.nodes`optional	`any[]`

Full body example

JSON

{  "name": "string",  "description": "string",  "filters": [    {      "field": "tag",      "operator": "is",      "value": "string"    }  ],  "filterTree": {    "kind": "leaf",    "filter": {      "field": "tag",      "operator": "is",      "value": "string"    }  }}

Responses

200Default Response
Response fields and example
JSON
```
{}
```
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).

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/segments' \  -H "Authorization: Bearer $CCX_API_KEY" \  -H "Content-Type: application/json" \  -d '{    "name": "string",    "filters": [      {        "field": "tag",        "operator": "is",        "value": "string"      }    ]  }'

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

Get a saved segment

GET/v2/segments/{segmentId}

Returns a single segment by id. Cross-tenant ids return 404.

Parameters

Field	In	Type	Description
`segmentId`required	path	`string`	Segment id (`seg_…`).

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

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

Update a saved segment

PATCH/v2/segments/{segmentId}

Partial update. Any of name, description, filters, filterTree may be sent; omitted fields are unchanged.

Parameters

Field	In	Type	Description
`segmentId`required	path	`string`	Segment id (`seg_…`).

Request body`application/json`

Field	Type	Description
`name`optional	`string`
`description`optional	`string`
`filters`optional	`object[]`
`filters[].field`optional	`string`	Values:`channel`
`filters[].operator`optional	`string`	Values:`has`
`filters[].value`optional	`string`	Values:`whatsappemail`
`filters[].key`optional	`string`
`filterTree`optional	`object`
`filterTree.kind`optional	`string`	Values:`group`
`filterTree.filter`optional	`object`
`filterTree.filter.field`optional	`string`	Values:`channel`
`filterTree.filter.operator`optional	`string`	Values:`has`
`filterTree.filter.value`optional	`string`	Values:`whatsappemail`
`filterTree.filter.key`optional	`string`
`filterTree.operator`optional	`string`	Values:`andor`
`filterTree.nodes`optional	`any[]`

Full body example

JSON

{  "name": "string",  "description": "string",  "filters": [    {      "field": "tag",      "operator": "is",      "value": "string"    }  ],  "filterTree": {    "kind": "leaf",    "filter": {      "field": "tag",      "operator": "is",      "value": "string"    }  }}

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).
409RFC 7807 problem details for CONFLICT (409).
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 PATCH 'https://api.messages.ccxcompany.co/v2/segments/<segmentId>' \  -H "Authorization: Bearer $CCX_API_KEY" \  -H "Content-Type: application/json" \  -d '{}'

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

Delete a saved segment

DELETE/v2/segments/{segmentId}

Hard delete. Returns 204 with no body.

Parameters

Field	In	Type	Description
`segmentId`required	path	`string`	Segment id (`seg_…`).

Responses

204Default Response
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 -X DELETE 'https://api.messages.ccxcompany.co/v2/segments/<segmentId>' \  -H "Authorization: Bearer $CCX_API_KEY"

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

Preview a segment (count + sample) without persisting

POST/v2/segments/preview

Evaluate a tentative filter set and get back the match count + a sample of contact ids, without saving a segment. Same filters / filterTree shape as create.

Request body`application/json`

Field	Type	Description
`filters`required	`object[]`
`filters[].field`optional	`string`	Values:`channel`
`filters[].operator`optional	`string`	Values:`has`
`filters[].value`optional	`string`	Values:`whatsappemail`
`filters[].key`optional	`string`
`filterTree`optional	`object`
`filterTree.kind`optional	`string`	Values:`group`
`filterTree.filter`optional	`object`
`filterTree.filter.field`optional	`string`	Values:`channel`
`filterTree.filter.operator`optional	`string`	Values:`has`
`filterTree.filter.value`optional	`string`	Values:`whatsappemail`
`filterTree.filter.key`optional	`string`
`filterTree.operator`optional	`string`	Values:`andor`
`filterTree.nodes`optional	`any[]`

Full body example

JSON

{  "filters": [    {      "field": "tag",      "operator": "is",      "value": "string"    }  ],  "filterTree": {    "kind": "leaf",    "filter": {      "field": "tag",      "operator": "is",      "value": "string"    }  }}

Responses

200Default Response
Response fields and example
JSON
```
{}
```
401RFC 7807 problem details for UNAUTHORIZED (401).
403RFC 7807 problem details for FORBIDDEN (403).
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/segments/preview' \  -H "Authorization: Bearer $CCX_API_KEY" \  -H "Content-Type: application/json" \  -d '{    "filters": [      {        "field": "tag",        "operator": "is",        "value": "string"      }    ]  }'

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

Segments

List saved segments

Parameters

Responses

curl example

Create a saved segment

Request bodyapplication/json

Responses

curl example

Get a saved segment

Parameters

Responses

curl example

Update a saved segment

Parameters

Request bodyapplication/json

Responses

curl example

Delete a saved segment

Parameters

Responses

curl example

Preview a segment (count + sample) without persisting

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`