Create a segment

Prerequisites

• Role with users:read and push:read (content_manager, superadmin).

A segment is a named, reusable query against the user base. Segments are the audience layer for push campaigns and can also be attached to promos.

Where

Users → Segments (/users/segments).

Segment fields

Field	Type	Notes
Name	string, ≤80	Human-readable, unique.
Description	string, ≤500	What this segment is for.
Query	JSON	The filter DSL: see below.
Cached size	int	Last-computed audience size (updated on estimate).
Cached at	ISO datetime	Freshness stamp.

The query DSL

Segments use a small AND/OR DSL over user + event attributes. Example: “Registered users in EG who purchased in the last 14 days AND haven’t hit their coin balance in 7 days”:

{
  "and": [
    { "field": "status", "op": "eq", "value": "active" },
    { "field": "isGuest", "op": "eq", "value": false },
    { "field": "countryCode", "op": "eq", "value": "EG" },
    { "field": "purchasedInDays", "op": "lte", "value": 14 },
    { "field": "balanceMovementInDays", "op": "gt", "value": 7 }
  ]
}

Supported fields:

Field	Type	Ops
status	enum	eq, neq, in
isGuest	bool	eq
countryCode	string	eq, in
language	string	eq, in
createdAtDays	int (days ago)	lte, gte, between
lastSeenDays	int	lte, gte
totalSpendCents	int	lte, gte
balanceTotal	int	lte, gte
hasActiveSubscription	bool	eq
purchasedInDays	int	lte, gte
unlockedInDays	int	lte, gte
balanceMovementInDays	int	lte, gte
pushCategoryOptedOut	string	eq

Estimating audience

Estimate button: runs the query with a SELECT COUNT and caches the result. Estimates are approximate (±5%) at scale; for exact numbers, run the segment against actual push send.

Using segments

• Push campaigns: pick a segment as the audience.
• Promos: restrict a promo’s eligibility to a segment.
• Analytics ad-hoc: filter dashboards by segment (planned).

Segment freshness

Segments are evaluated at send time, not at creation time. If a segment says “users in EG”, a user who moves to another country stops matching by the next send.

Cached size is refreshed:

• Manually on Estimate
• Automatically before each push send (the composer shows the fresh number)

Gotchas

• Query size limits: the DSL supports up to 20 filter nodes. Deeper is refused at validation.
• Guest users: most segments implicitly filter to registered users. If you want a guest campaign, set isGuest=true explicitly.
• Delete-in-use: segments referenced by an active push campaign or promo can’t be deleted. Unlink first.

API calls

Action	Endpoint
List	GET /v1/admin/segments
Detail	GET /v1/admin/segments/:id
Create	POST /v1/admin/segments
Update	PUT /v1/admin/segments/:id
Delete	DELETE /v1/admin/segments/:id
Estimate size	POST /v1/admin/segments/:id/estimate
Estimate ad-hoc	POST /v1/admin/segments/estimate (pass query in body)

Full details in API: Engagement.