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

MethodPathDescription
GET/campaign-segmentsList segments
GET/campaign-segments/:idGet a segment
PATCH/campaign-segments/:idUpdate a segment
DELETE/campaign-segments/:idDelete a segment
POST/contacts-segments-schema-builderGet the fields you can filter on
POST/contacts-segments-run-queryPreview 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

FieldTypeDescription
idintegerRead-only. Unique ID.
organization_idintegerRead-only. Organization that owns the segment.
created_by_user_idintegerRead-only. User who created the segment.
namestringSegment name.
channelstringwhatsapp, instagram, messenger, email, automation, sms or ai_calling. Only contacts reachable on this channel are included.
builder_typestringmanual (rules in query) or ai (selector in ai_sql_query).
queryobject | nullManual rules (see below).
ai_sql_querystring | nullAI 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_explanationstring | nullAI segments: plain-language explanation of the selector, up to 5000 characters.
ai_promptstring | nullAI segments: the request the selector was generated from, up to 5000 characters.
total_personsstring | integerRead-only. Number of contacts that currently match, computed on list and get.
created_atstring (date-time)Read-only. Creation timestamp.
updated_atstring (date-time)Read-only. Last update timestamp.
deleted_atstring (date-time) | nullRead-only. Set when the segment is deleted.

The query object

json
KeyDescription
operatorand or or, combines conditions.
conditions[]A condition, or a nested group { "type": "group", "operator", "conditions" }.
conditions[].entitycontacts (default), deals, companies or conversation_events.
conditions[].fieldField 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 / customFieldIdFilter on a custom field by its ID.
conditions[].operatorequals, not_equals, contains, not_contains, greater, less, between, not_between, is_empty, is_not_empty.
conditions[].valueThe value to compare. between takes { "start", "end" }; is_empty / is_not_empty take none.
destination_countriesSMS 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.