Audiences

Audiences are named groups of contacts. You assign contacts to audiences, then target an audience when creating a campaign.

---

Create audience

POST /v1/audiences

Requires full_access scope.

Request body

{
  "name": "Newsletter Subscribers"
}

Response

{
  "id": "aud_abc123",
  "name": "Newsletter Subscribers",
  "contact_count": 0,
  "created_at": "2025-03-12T09:00:00Z"
}

---

Get audience

GET /v1/audiences/:id

Requires read_only scope.

---

List audiences

GET /v1/audiences

Requires read_only scope.

{
  "data": [
    {
      "id": "aud_abc123",
      "name": "Newsletter Subscribers",
      "contact_count": 4200,
      "created_at": "2025-03-12T09:00:00Z"
    }
  ],
  "has_more": false,
  "next_cursor": null
}

---

Update audience

PUT /v1/audiences/:id

Requires full_access scope.

---

Delete audience

DELETE /v1/audiences/:id

Requires full_access scope.

---

Add contacts to audience

POST /v1/audiences/:id/contacts

Requires sending_access scope.

{
  "contact_ids": ["con_abc123", "con_abc124"]
}

---

List contacts in audience

GET /v1/audiences/:id/contacts

Requires read_only scope. Returns the contacts that are members of this audience, using the standard contact list shape.

Query parameters

Parameter	Type	Default	Description
limit	number	50	Results per page (1-100).
cursor	string		Pagination cursor from the previous response's next_cursor.

Response

{
  "data": [
    {
      "id": "con_abc123",
      "email": "alice@example.com",
      "first_name": "Alice",
      "last_name": "Smith",
      "metadata": {"plan": "pro"},
      "unsubscribed": false,
      "properties": {},
      "created_at": "2025-03-12T09:00:00Z",
      "updated_at": "2025-03-12T09:00:00Z"
    }
  ],
  "has_more": false,
  "next_cursor": null
}

Pagination is cursor-based. Pass next_cursor as the cursor parameter to get the next page.

---

Remove contact from audience

DELETE /v1/audiences/:id/contacts/:contactId

Requires sending_access scope.

---

Plan limits

Plan	Audiences
Free	3
Pro	25
Business	Unlimited
Enterprise	Unlimited