Docs / API Reference / Cohorts

Cohorts

Define reusable audience segments with contact filter queries. Cohorts are evaluated at send time, so broadcasts always reach the contacts that currently match.

POST /v1/cohorts

Create cohort

Create a saved audience segment defined by a contact filter query. Cohorts are used as broadcast audiences.

Parameters

name string required

Cohort name. Max 255 characters.

query object required

Filter query object describing which contacts belong to the cohort (attribute conditions combined with and/or logic).

type string

Cohort type (e.g. query, csv).

csv_url string

Source CSV URL for CSV-backed cohorts.

description string

Human-readable description of the segment.

Request

cURL

curl -X POST https://api.boltly.online/v1/cohorts \
  -H "X-API-Key: $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "US customers",
    "description": "Contacts tagged customer in the US",
    "query": {
      "and": [
        { "attribute": "country", "operator": "eq", "value": "US" },
        { "attribute": "tags", "operator": "contains", "value": "customer" }
      ]
    }
  }'

Response

JSON

{
  "data": {
    "id": "3b8e5c1d-...",
    "organization_id": "7a1f9d2c-...",
    "name": "US customers",
    "description": "Contacts tagged customer in the US",
    "query": {
      "and": [
        { "attribute": "country", "operator": "eq", "value": "US" },
        { "attribute": "tags", "operator": "contains", "value": "customer" }
      ]
    },
    "contact_count": 0,
    "created_at": "2026-04-03T12:00:00Z",
    "updated_at": "2026-04-03T12:00:00Z"
  }
}

POST /v1/cohorts/preview-query

Preview cohort

Evaluate a filter query without saving it and return the number of contacts it currently matches.