REST API: Segments: Create

This endpoint creates a segment.

POST API url -> /v1/segments

Body Parameters

The following body parameters are possible:

Field	Type	Description	Required
name	String	Name of your segment	✅
description	String	Description of your segment	Optional
constraints	Array	Array of contstraints. Every constraint json object should contain fields: type: AND or OR constraints (array): each object must contain fields: field, value, relation	✅

Constraints Array Body Parameters

Field	Type	Description	Required
type	String	Specifies the logical operator used to evaluate the constraints within the group. • AND - all constraints in the group must be satisfied • OR - at least one constraint in the group must be satisfied	✅
constraints	Array (max size: 10)	An array of conditions that must be evaluated according to the group’s type operator. Each constraint defines a single rule based on a field, comparison relation, and expected value. Fields inside constraint: • field - the attribute being evaluated • relation - the comparison operator (e.g. EQUALS, CONTAINS) • value - the value used for comparison	✅

Array of constraint conditions

An array of constraint objects. By default, each object in the array is combined with the others using a logical AND.

So, if you have two objects like this:

[
    {
        "type": "AND",
        "constraints": [
        { "field": "deviceManufacturer", "value": "Xiaomi", "relation": "==" },
        { "field": "deviceModel", "value": "Redmi Note XXXXX", "relation": "==" }
        ]
    },
    {
        "type": "AND",
        "constraints": [
        { "field": "osVersion", "value": "13", "relation": "EQUALS" }
        ]
    }
]

They are evaluated as:

(deviceManufacturer = Xiaomi AND deviceModel = Redmi Note XXXXX) 
AND 
(osVersion = 13)

All possible relation values

Value	Description	Supported field type
exists	Exists	String
==	Equals	Int, Long, String
!=	Not Equals	Int, Long, String
starts_with	Starts with	String
ends_with	Ends with	String
contains	Contains	String
>	Higher than	Int, Long
>=	Higher than or equals	Int, Long
<	Smaller than	Int, Long
<=	Smaller than or equals	Int, Long

field possible values

Field	Type	Description
country	String	2-letter country codes defined by ISO 3166-1 alpha-2. Example: US, PL, `UK==
language	String	Languages must be provided using the ISO 639-2 alpha-3 format. Example: eng, `pol==
timezone	String	Time zones must be provided in the Area/Location format (IANA Time Zone Database). Example Europe/Warsaw.
appVersion	String	App version. Example 1.3.54
appVersionCode	Int	App version code. Example 5
osApi	String	Operating system API version. Example 35
osVersion	String	Operating system version. Example 1.0.1
customUserId	String	Custom user id from your backend.
email	String	Email. Example: [email protected]
type	String	Type of device. Accepted values: phone, tablet, smartwatch, desktop
firstSession	Long	First ever user session - Unix timestamp in milliseconds
lastSession	Long	Last user session - Unix timestamp in milliseconds
sessionCount	Int	Total number of device sessions
createdAt	Long	When a device was created - Unix timestamp in milliseconds
id	String	Device Id
pushToken	String	Device APN or FCM push token
unRegisteredAt	Long	When a device was unregistered - Unix timestamp in milliseconds
deviceModel	String	Device model. Example: Galaxy S26
deviceManufacturer	String	Device manufacturer. Example: Samsung
tags	String Array	Applied device tags

Constraints Examples

12

[
    {
        "type": "AND",
        "constraints": [
        {
            "field": "firstSession",
            "value": 1771924492768,
            "relation": "<="
        }
        ]
    },
    {
        "type": "AND",
        "constraints": [
        {
            "field": "lastSession",
            "value": 1771924492782,
            "relation": ">="
        }
        ]
    }
]

[
    {
        "type": "AND",
        "constraints": 
        [
            {
                "field": "deviceModel",
                "value": "Redmi Note XXXXX",
                "relation": "=="
            },
            {
                "field": "deviceModel",
                "value": "Galaxy S23",
                "relation": "=="
            }
        ]
    },
    {
        "type": "AND",
        "constraints": 
        [
            {
                "field": "deviceManufacturer",
                "value": "Xiaomi",
                "relation": "=="
            },
            {
                "field": "deviceManufacturer",
                "value": "Samsung",
                "relation": "=="
            },
            {
                "field": "type",
                "value": "phone",
                "relation": "=="
            }
        ]
    }
]

Response Examples

Returns segment id or error message

200304400

seg_jfe34NrGegjL3

No message

Error message