Build static or dynamic contact segments using explicit contact IDs or filter groups.
Required parameters
| Parameter | Location | Type | Required | Description |
|---|---|---|---|---|
name | Body | string | Yes | Segment name. |
refreshType | Body | integer | Yes | Segment type. Use 1 for Static and 2 for Dynamic. |
Body fields
| Field | Type | Required | Description |
|---|---|---|---|
name | string | Yes | Segment name. |
refreshType | integer | Yes | Use 1 for Static or 2 for Dynamic. |
groups | array of objects | Conditionally | A set of filtering condition groups used to filter contacts. Required when refreshType = 2. Optional when refreshType = 1, but for static segments you must provide either groups or contactIds. |
contactIds | array | Conditionally | List of contact IDs used to directly define members in a static segment. For static segments, provide contactIds or groups. |
useUploadedContact | boolean | No | Indicates whether to use the uploaded contacts logic for the downstream CDP segment API. Defaults to false when not provided. |
Group structure
Each item in groups contains a conditions array.
Each condition includes:
attribute— field name, such as a contact field or custom attribute likenameorphoneoperator— comparison operator, such as==value— comparison value
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.
Error responses
400
Invalid 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.
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.
429
The 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.
500
The 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.
See the endpoint reference for the full request and response schemas.