Create segment

Description

Create a new segment.

Request URL

Method: POST

https://example.com/api/v1.1/segments/add/

Request parameters

Parameter	Type	Example	Required	Description
token	string	"abcdefghijklmnqrstuvwxyz"	Yes	API token
format	string	"json"	No	Response data format (by default – "json")
name	string	"New segment"	Yes	Segment name
list_id	int	5	Yes, for static segments	Database ID from which profiles will be taken. For dynamic and updatable segments, specify inside the segment array
segment	JSON array		Yes, for dynamic and updatable segments	Segmentation conditions. The array must contain at least one object. Not used for static segments.
is_refresh_daily	bool	true	No	Flag to activate segment schedule. By default false. Used only for updatable segments.

Segment type is determined by a combination of parameters:

• is_static is false — the segment is dynamic
• is_static is true and no conditions — the segment is static
• is_static is true and conditions present — the segment is updatable. Schedule activity is determined by the is_refresh_daily parameter

Parameters of the segment array

Parameter	Type	Example	Required	Description
condition	string	"and"	Yes	Logical condition for combining queries. Possible values: and, or
limit	int	0	No	Limit the number of profiles in the segment (0 - no limit)
list_id	int	2	Yes	Database ID
percent_from	int	0	No	Start of the sample percentage range (0-99)
percent_to	int	99	No	End of the sample percentage range (1-100)
queries	JSON array	-	Yes	Array of filter conditions

Parameters of the queries object

An object that is part of the queries array.

Parameter	Type	Example	Required	Description
compo	string	"default"	Yes	Source of the value for comparison
name	string	"_sex", "_region"	Yes	Field name for filtering
operator	string	"equal"	Yes	Comparison operator. Available values depend on the field type.
type	string	"enum"	Yes	Field type
value	array	[   {     "name": "default",     "value": 2   } ]	Yes	Value for filtering. Format depends on the field type.

Request example

For static segments

JSON

{
    "name": "Static segment",
    "is_static": true,
    "list_id": 5,
    "is_refresh_daily": false,
    "token": "abcdefghijklmnqrstuvwxyz"
}

XML

<xml>
  <list_id>5</list_id>
  <name>Static segment</name>
  <is_static>true</is_static>
  <is_refresh_daily>false</is_refresh_daily>
  <token>abcdefghijklmnqrstuvwxyz</token>
</xml>

For dynamic segments

JSON

{
  "name": "Dynamic segment",
  "is_static": false,
  "segment": [
    {
      "condition": "or",
      "limit": 0,
      "list_id": 2,
      "percent_from": 0,
      "percent_to": 99,
      "queries": [
        {
          "compo": "default",
          "name": "_sex",
          "operator": "equal",
          "type": "enum",
          "value": [
            {
              "name": "default",
              "value": 1
            }
          ]
        },
        {
          "compo": "default",
          "name": "_sex",
          "operator": "equal",
          "type": "enum",
          "value": [
            {
              "name": "default",
              "value": 2
            }
          ]
        }
      ]
    }
  ],
  "token": "abcdefghijklmnqrstuvwxyz"
}

XML

<xml>
  <name>Dynamic segment</name>
  <is_static>false</is_static>
  <segment>
    <condition>or</condition>
    <limit>0</limit>
    <list_id>2</list_id>
    <percent_from>0</percent_from>
    <percent_to>99</percent_to>
    <queries>
      <compo>default</compo>
      <name>_sex</name>
      <operator>equal</operator>
      <type>enum</type>
      <value>
        <name>default</name>
        <value>1</value>
      </value>
    </queries>
    <queries>
      <compo>default</compo>
      <name>_sex</name>
      <operator>equal</operator>
      <type>enum</type>
      <value>
        <name>default</name>
        <value>2</value>
      </value>
    </queries>
  </segment>
  <token>abcdefghijklmnqrstuvwxyz</token>
</xml>

For updatable segments

JSON

{
  "name": "Updatable segment",
  "is_static": true,
  "is_refresh_daily": true,
  "segment": [
        {
            "condition": "or",
            "limit": 0,
            "list_id": 2,
            "percent_from": 0,
            "percent_to": 99,
            "queries": [
                {
                    "compo": "default",
                    "name": "_sex",
                    "operator": "equal",
                    "type": "enum",
                    "value": [
                        {
                            "name": "default",
                            "value": 1
                        }
                    ]
                },
                {
                    "compo": "default",
                    "name": "_sex",
                    "operator": "equal",
                    "type": "enum",
                    "value": [
                        {
                            "name": "default",
                            "value": 2
                        }
                    ]
                }
            ]
        }
    ],
  "token": "abcdefghijklmnqrstuvwxyz"
}

XML

<xml>
  <name>Updatable segment</name>
  <is_static>true</is_static>
  <is_refresh_daily>true</is_refresh_daily>
  <segment>
    <condition>or</condition>
    <limit>0</limit>
    <list_id>2</list_id>
    <percent_from>0</percent_from>
    <percent_to>99</percent_to>
    <queries>
      <compo>default</compo>
      <name>_sex</name>
      <operator>equal</operator>
      <type>enum</type>
      <value>
        <name>default</name>
        <value>1</value>
      </value>
    </queries>
    <queries>
      <compo>default</compo>
      <name>_sex</name>
      <operator>equal</operator>
      <type>enum</type>
      <value>
        <name>default</name>
        <value>2</value>
      </value>
    </queries>
  </segment>
  <token>abcdefghijklmnqrstuvwxyz</token>
</xml>

Response example

JSON

{
  "data": {
    "saved_id": 1
  },
  "error": 0,
  "error_text": "Successful operation"
}

XML

<xml>
  <data>
    <saved_id>1</saved_id>
  </data>
  <error>0</error>
  <error_text>Successful operation</error_text>
</xml>

Response parameters

Parameter	Type	Description
error	int	Error code
error_text	string	Error message
saved_id	int	New segment ID