Create Custom Segment (Available in Pro/Business plan)

post

https://live-mt-server.wati.io/{tenantId}/api/v1/createCustomSegment

Retained legacy exception: Persist a saved segment; V3 reads/evaluation do not create one.

Create Custom Segment (Available in Pro/Business plan). POST /{tenantId}/api/v1/createCustomSegment.

Filter conditions can use filterType: 0 for contact attributes, 1 for profile signals, or 3 for Shopify events. For Shopify events, supply a supported eventType; use a numeric operator code when comparing an event parameter. eventPresence is done (default) or not_done, and timeWindowDays limits events to the last N days. An event-only condition can omit the parameter path and comparison value. Operator 104 (Between) requires value and secondValue. Shopify event availability and matching depend on account configuration and event data; successful creation does not guarantee that any contacts match.

Permissions

For API access tokens and OIDC tokens, satisfy at least one of: api, wati_integration:write. API access tokens may satisfy a listed scope through the configured scope hierarchy; OIDC tokens are checked against their scope claims. Legacy JWT authentication does not use this scope check. Authentication, role, tenant, and applicable feature or plan checks still apply. For HTTP 403, check the credential type, applicable scopes, roles, and workspace access; 403 does not always mean a missing scope. Authentication/authorization failures do not guarantee a JSON response body. Allowed roles: DEVELOPER, ADMINISTRATOR, EXTERNAL_ADMINISTRATOR, PARTNER_ADMINISTRATOR, AI_OPERATOR, or API_TOKEN. FLEXI_TRIAL and FLEXI_PAID are denied. Billing-related restrictions can also block access.

Recent Requests

Time	Status	User Agent
Retrieving recent requests…

Loading…

Path Params

tenantId

string

required

Your WATI workspace (tenant) ID. This required path segment identifies the WATI account for legacy v1 and v2 API requests.

Body Params

CreateSegmentRequest

RefreshType:

allowed values: 1 = Static, 2 = Dynamic

Shopify event conditions use filterType 3, eventType, optional attributePath, dataType (0 string, 1 number, 2 boolean, 3 datetime), numeric operator code, value, optional secondValue for Between, eventPresence, and timeWindowDays. Set groups[].rulesOperator to or for OR; other values default to and.

Data model with fields: name, refreshType, description, groups, contactIds....

name

string | null

refreshType

int32

enum

Allowed:

description

string | null

groups

array of objects | null

groups

contactIds

array of strings | null

contactIds

useUploadedContact

boolean

createFrom

string | null

Headers

string

enum

Defaults to application/json

Generated from available response content types

Allowed:

content-type

string

enum

Defaults to application/json-patch+json

Generated from available request content types

Allowed:

Responses

403

Authorization failed. Check the Permissions section for the credential-specific scope rules, and check roles and workspace access. The response may have no body; do not require a JSON error envelope.

Language

Credentials

Bearer

Loading…

Response

Click Try It! to start a request and see the response here! Or choose an example:

text/plain

application/json

text/json

200OK

400Invalid segment input, maximum active segments reached, or a CDP segment business-rule error. The info field describes the error. This status also covers disabled custom segments or a plan below Pro.

429The custom-segment per-user request limit was reached. Retry after a minute. The configured default is 60 requests per UTC minute; a nonpositive configured limit or an absent user identity disables this specific limiter.

500The controller could not create the segment or caught an unexpected exception during creation. The examples show its explicit error branches; failures outside those branches can use a different error response.