Create a new dynamic group segment.
A dynamic segment stores a filter, not a list of customers. Membership is evaluated every time the segment is viewed or used for a broadcast, so customers who are added, edited or tagged later enter or leave the segment automatically. Segments created here open and behave the same way as segments built from Customers → Add Filter in the dashboard.
How filters work
filters.filterGroupsis a list of 1 to 25 filter groups.- Each group holds one or more
conditions. Conditions inside a group are joined with AND. - Every group after the first can set
joinWithPrevioustoAND(default) orOR. It is not allowed on the first group. - Groups are evaluated strictly left to right, with no AND-before-OR precedence:
A OR B AND Cmeans(A OR B) AND C. - A field can be used only once per group. Use another group to filter the same field again.
Single filter group: send one group. All its conditions must match (AND).
Multiple filter groups: send several groups and join them with joinWithPrevious, for example (Name contains "a" AND created in the last 30 days) OR (tagged VIP).
Conditions
Each condition names a field by the name shown in the dashboard (id) together with its type, an operator and a value.
| Field | type |
|---|---|
Name, Phone Number | text |
Tags (tags must already exist, case-sensitive) | array |
| Customer custom fields | text, number, date, boolean, single_select, multi_select |
type | Operators |
|---|---|
text | IS_SET, IS_NOT_SET, EQUALS, CONTAINS, NOT_CONTAINS, STARTS_WITH, ENDS_WITH |
array | ANY_OF, ALL_OF, NONE_OF, NOT_EQUALS, NOT_CONTAINS, IS_SET, IS_NOT_SET |
number | IS_SET, IS_NOT_SET, EQUALS, NOT_EQUALS, LESS_THAN, LESS_THAN_EQUAL_TO, GREATER_THAN, GREATER_THAN_EQUAL_TO, BETWEEN, NOT_BETWEEN |
boolean | IS_SET, IS_NOT_SET, EQUALS, NOT_EQUALS |
date | IS_SET, IS_NOT_SET, ON_DATE, NOT_ON_DATE, BEFORE_DATE, AFTER_DATE, BETWEEN, NOT_BETWEEN, IN_THE_LAST, NOT_IN_THE_LAST |
single_select | IS_SET, IS_NOT_SET, EQUALS, NOT_EQUALS, ANY_OF, NONE_OF |
multi_select | IS_SET, IS_NOT_SET, ANY_OF, ALL_OF, NONE_OF, NOT_EQUALS |
Values
The shape of value is decided by the operator:
| Operators | value |
|---|---|
BETWEEN, NOT_BETWEEN | { "type": "BETWEEN", "start": ..., "end": ... }, end must be greater than start |
IN_THE_LAST, NOT_IN_THE_LAST | { "type": "DATE_PERIOD", "value": 30, "suffix": "days" }, suffix is one of seconds, minutes, hours, days, weeks, months, years |
IS_SET, IS_NOT_SET | { "type": "NO_VALUE" }, or leave value out |
| All other operators | { "type": "VALUE", "value": ... } |
- text: non-blank text, up to 255 characters.
- number: a number, or a plain decimal text such as
"9". - boolean:
trueorfalse. - date: ISO 8601 date and time with an offset, for example
2026-01-31T00:00:00+05:30. Dates are returned in UTC.ON_DATEandNOT_ON_DATEare stored as 12:00 of that day. - tags and select fields: a text or a list of 1 to 1000 texts. The tags and options must already exist.
Columns and sort (optional)
userPreference sets the columns and sort of the segment for the person who created the API key. Other dashboard users see the default columns (Name, Phone Number) sorted by Name. If it is left out, the defaults are used.
Limits
- Name up to 255 characters, unique in the account. Description up to 1000 characters.
- Up to 25 filter groups.
- 10 requests per minute per account.
- The caller needs the Manage Customer segments permission.
| Time | Status | User Agent | |
|---|---|---|---|
Retrieving recent requests… | |||
Invalid or missing API key