Stream cohort
Stream a cohort as JSON with two fields:
- `name` - Cohort name (1-50 characters)
- `users` - Array of user records (1-1000)
**When to use**
Stream cohort adds contacts to a campaign programmatically (up to 1000 users per request). Use it when your system already has user records and you do not need to upload a CSV.
- **CRM integration** - sync leads or customers from Salesforce, HubSpot, Zoho, or your own database into a campaign
- **Webhooks and automation** - push contacts from form submissions, payment events, or internal workflows
- **Active campaigns** - queue new contacts to dial within the current schedule (same as Add cohort in the dashboard)
- **Scheduled or paused campaigns** - load contacts before the campaign starts, or while it is paused
- **Incremental batches** - send multiple API calls over time instead of one large CSV upload
For CSV files, use **Upload cohort** instead.
The campaign must be **active**, **scheduled**, or **paused**. Processing is asynchronous - poll **Get cohort** until `status` is `completed` or `failed`.
**Limits and rules:**
- `user_phone_number` is required for every user (E.164 preferred; 10-digit Indian numbers are normalized automatically)
- `app_variables` must match variables configured on the agent
- `app_overrides` supports only: `initial_language_name`, `initial_state_name`, `initial_bot_message`
**Common validation errors:**
- No users, or more than 1000 users
- Invalid cohort name
- Missing `user_phone_number`
- Unsupported `app_overrides` key
- Unknown `app_variables` for the selected agent.
Path parameters
org_id
workspace_id
campaign_id
Request
This endpoint expects an object.
name
Cohort name (1-50 characters). Letters, numbers, spaces, underscores, and hyphens only.
users
List of user records (1-1000).
Response
Successful Response
name
Name of the resource
cohort_id
Unique identifier for the cohort
status
Current status
source_type
How the cohort was uploaded
created_by
User who created this resource
created_at
Timestamp when the resource was created (ISO 8601)
updated_at
Timestamp when the resource was last updated (ISO 8601)
result
Processing result with record counts
updated_by
User who last updated this resource
Errors
422
Unprocessable Entity Error