Campaign Segments
A campaign segment is a saved audience: the contacts that match a set of rules, for one sending channel. Campaigns and automations send to segments. A segment is built either with the visual builder (builder_type: "manual", rules in query) or with AI (builder_type: "ai", a SQL selector in ai_sql_query).
Endpoints
| Method | Path | Description |
|---|---|---|
GET | /campaign-segments | List segments |
GET | /campaign-segments/:id | Get a segment |
PATCH | /campaign-segments/:id | Update a segment |
DELETE | /campaign-segments/:id | Delete a segment |
POST | /contacts-segments-schema-builder | Get the fields you can filter on |
POST | /contacts-segments-run-query | Preview the contacts of a segment |
Reads are limited to your API key's organization. Creating and splitting segments is currently only available in the AchieveApex app.
The segment object
json
Fields
| Field | Type | Description |
|---|---|---|
id | integer | Read-only. Unique ID. |
organization_id | integer | Read-only. Organization that owns the segment. |
created_by_user_id | integer | Read-only. User who created the segment. |
name | string | Segment name. |
channel | string | whatsapp, instagram, messenger, email, automation, sms or ai_calling. Only contacts reachable on this channel are included. |
builder_type | string | manual (rules in query) or ai (selector in ai_sql_query). |
query | object | null | Manual rules (see below). |
ai_sql_query | string | null | AI segments: a read-only SELECT that returns a contact_id column, up to 20000 characters. It is validated and test-run, scoped to your organization, before it is saved; only allowed tables can be used. |
ai_explanation | string | null | AI segments: plain-language explanation of the selector, up to 5000 characters. |
ai_prompt | string | null | AI segments: the request the selector was generated from, up to 5000 characters. |
total_persons | string | integer | Read-only. Number of contacts that currently match, computed on list and get. |
created_at | string (date-time) | Read-only. Creation timestamp. |
updated_at | string (date-time) | Read-only. Last update timestamp. |
deleted_at | string (date-time) | null | Read-only. Set when the segment is deleted. |
The query object
json
| Key | Description |
|---|---|
operator | and or or, combines conditions. |
conditions[] | A condition, or a nested group { "type": "group", "operator", "conditions" }. |
conditions[].entity | contacts (default), deals, companies or conversation_events. |
conditions[].field | Field name from the schema builder. tags matches a tag name (equals / not_equals). phone_country takes ISO country codes (in, not_in, equals, not_equals). |
conditions[].isCustomField / customFieldId | Filter on a custom field by its ID. |
conditions[].operator | equals, not_equals, contains, not_contains, greater, less, between, not_between, is_empty, is_not_empty. |
conditions[].value | The value to compare. between takes { "start", "end" }; is_empty / is_not_empty take none. |
destination_countries | SMS and AI calling only: limit to these phone countries (within your organization's allowed destinations). |
Related
Report an issue with this documentation
Please log in to report issues with our documentation.