Create a new Dynamic Group Segment

Create a dynamic customer segment from a filter, the same kind of segment built from Customers → Add Filter in the dashboard.

Before you call

  • name is required, up to 255 characters, and must be unique in the account. description is optional, up to 1000 characters.
  • filters.filterGroups is required: 1 to 25 filter groups.
  • Tags and select options used in conditions must already exist. Tag names must match exactly, including case.
  • You need the Manage Customer segments permission.
  • Do not send type. This endpoint always creates a dynamic segment.

How it works

  • The segment stores the 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.
  • The response returns the segment's id, name, description, type, filters and userPreference.
  • Sending the same name twice, even at the same time, creates one segment; the other request fails with "already exists".

Filter groups

  • Each group holds one or more conditions. Conditions inside a group are joined with AND.
  • Every group after the first can set joinWithPrevious to AND (default) or OR. It is not allowed on the first group.
  • Groups are evaluated left to right, with no AND-before-OR precedence: A OR B AND C means (A OR B) AND C.
  • A field can be used only once per group. Use another group to filter the same field again.

Example: (Name contains "a" AND created in the last 30 days) OR (tagged VIP) is two groups, the second with joinWithPrevious: "OR".

Conditions

Each condition names a field by the name shown in the dashboard (id) with its type, an operator and a value.

Fieldtype
Name, Phone Numbertext
Tagsarray
Customer custom fieldstext, number, date, boolean, single_select, multi_select
typeOperators
textIS_SET, IS_NOT_SET, EQUALS, CONTAINS, NOT_CONTAINS, STARTS_WITH, ENDS_WITH
arrayANY_OF, ALL_OF, NONE_OF, NOT_EQUALS, NOT_CONTAINS, IS_SET, IS_NOT_SET
numberIS_SET, IS_NOT_SET, EQUALS, NOT_EQUALS, LESS_THAN, LESS_THAN_EQUAL_TO, GREATER_THAN, GREATER_THAN_EQUAL_TO, BETWEEN, NOT_BETWEEN
booleanIS_SET, IS_NOT_SET, EQUALS, NOT_EQUALS
dateIS_SET, IS_NOT_SET, ON_DATE, NOT_ON_DATE, BEFORE_DATE, AFTER_DATE, BETWEEN, NOT_BETWEEN, IN_THE_LAST, NOT_IN_THE_LAST
single_selectIS_SET, IS_NOT_SET, EQUALS, NOT_EQUALS, ANY_OF, NONE_OF
multi_selectIS_SET, IS_NOT_SET, ANY_OF, ALL_OF, NONE_OF, NOT_EQUALS

Values

The operator decides the shape of value:

Operatorsvalue
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" }; value greater than 0; suffix is seconds, minutes, hours, days, weeks, months or 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: true or false.
  • date: ISO 8601 date and time with an offset, for example 2026-01-31T00:00:00+05:30. Dates are returned in UTC. ON_DATE and NOT_ON_DATE are stored as 12:00 of that day.
  • tags and select fields: a text, or a list of 1 to 1000 texts of up to 255 characters each.

Columns and sort (optional)

  • userPreference sets the segment's columns (fieldIds) and sort, using the same field names.
  • It is saved for the API key's user and 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.

Rate limit

  • 10 requests per minute.
Recent Requests
Log in to see full request history
TimeStatusUser Agent
Retrieving recent requests…
LoadingLoading…
Body Params
string
required
length ≤ 255
string
length ≤ 1000
filters
object
required
userPreference
object
Responses

401

Invalid or missing API key

Language
Credentials
Header
LoadingLoading…
Response
Click Try It! to start a request and see the response here! Or choose an example:
application/json