Audiences

Audiences are named groups of contacts. Campaigns are run against an audience.

The Audience Object

{
  "id": "aud_abc123",
  "name": "Mumbai Premium - March 2026",
  "description": "Hindi-speaking premium customers in Mumbai",
  "organizationId": "org_1",
  "contactCount": 250,
  "createdAt": "2026-03-01T10:00:00.000Z",
  "updatedAt": "2026-03-10T14:00:00.000Z"
}

List Audiences

GET /v1/audiences

Query Parameters:

Response:

{
  "data": [/* Audience objects */],
  "total": 12,
  "page": 1,
  "limit": 20,
  "totalPages": 1
}

Get an Audience

GET /v1/audiences/:id

Response: A single Audience object.

Create an Audience

POST /v1/audiences

Request Body:

Example:

{
  "name": "Mumbai Premium - March 2026",
  "description": "Hindi-speaking premium customers in Mumbai"
}

Response: 201 Created with the Audience object.

Update an Audience

PATCH /v1/audiences/:id

Request Body: Any subset of { name, description }.

Delete an Audience

DELETE /v1/audiences/:id

Returns 200 OK with { "success": true }.

You cannot delete an audience linked to an active or in-progress campaign.

Get Audience Contacts

GET /v1/audiences/:id/contacts

Query Parameters: page, limit, search

Response: Paginated list of Contact objects in this audience.

Add Contacts to Audience

POST /v1/audiences/:id/contacts

Request Body:

{
  "contactIds": ["clxxx123", "clxxx456"]
}

Response: 200 OK with updated contactCount.

Remove Contacts from Audience

DELETE /v1/audiences/:id/contacts

Request Body:

{
  "contactIds": ["clxxx123"]
}

Or via POST (alternative endpoint):

POST /v1/audiences/:id/contacts/remove

Response: 200 OK with updated contactCount.

Get Available Contacts

GET /v1/audiences/:id/available-contacts

Returns contacts from your organization that are not yet in this audience. Useful for building a UI picker.

Query Parameters: page, limit, search

Response: Paginated list of Contact objects.