Create Segment - Sequenzy

POST

api

segments

Create Segment

curl --request POST \
  --url https://api.sequenzy.com/api/v1/segments \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "name": "<string>",
  "filters": [
    {}
  ],
  "filterJoinOperator": "<string>",
  "root": {}
}
'

import requests

url = "https://api.sequenzy.com/api/v1/segments"

payload = {
    "name": "<string>",
    "filters": [{}],
    "filterJoinOperator": "<string>",
    "root": {}
}
headers = {
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: JSON.stringify({name: '<string>', filters: [{}], filterJoinOperator: '<string>', root: {}})
};

fetch('https://api.sequenzy.com/api/v1/segments', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.sequenzy.com/api/v1/segments",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    'name' => '<string>',
    'filters' => [
        [
                
        ]
    ],
    'filterJoinOperator' => '<string>',
    'root' => [
        
    ]
  ]),
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <token>",
    "Content-Type: application/json"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://api.sequenzy.com/api/v1/segments"

	payload := strings.NewReader("{\n  \"name\": \"<string>\",\n  \"filters\": [\n    {}\n  ],\n  \"filterJoinOperator\": \"<string>\",\n  \"root\": {}\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("Authorization", "Bearer <token>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.post("https://api.sequenzy.com/api/v1/segments")
  .header("Authorization", "Bearer <token>")
  .header("Content-Type", "application/json")
  .body("{\n  \"name\": \"<string>\",\n  \"filters\": [\n    {}\n  ],\n  \"filterJoinOperator\": \"<string>\",\n  \"root\": {}\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api.sequenzy.com/api/v1/segments")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"name\": \"<string>\",\n  \"filters\": [\n    {}\n  ],\n  \"filterJoinOperator\": \"<string>\",\n  \"root\": {}\n}"

response = http.request(request)
puts response.read_body

{
  "success": true,
  "segment": {
    "id": "seg_active_non_buyers",
    "name": "Active non-buyers",
    "filters": [
      {
        "id": "filter-1",
        "field": "attribute",
        "operator": "gte",
        "value": "last_login_days_ago:90"
      },
      {
        "id": "filter-2",
        "field": "event",
        "operator": "is_not",
        "value": "saas.purchase:30d"
      },
      {
        "id": "filter-3",
        "field": "segment",
        "operator": "is_not",
        "value": "seg_paying_customers"
      }
    ],
    "filterJoinOperator": "and",
    "format": "v2",
    "root": {
      "kind": "group",
      "id": "root",
      "joinOperator": "and",
      "children": [
        {
          "kind": "filter",
          "id": "filter-1",
          "field": "attribute",
          "operator": "gte",
          "value": "last_login_days_ago:90"
        },
        {
          "kind": "group",
          "id": "group-1",
          "joinOperator": "or",
          "children": [
            {
              "kind": "filter",
              "id": "filter-2",
              "field": "event",
              "operator": "is_not",
              "value": "saas.purchase:30d"
            },
            {
              "kind": "filter",
              "id": "filter-3",
              "field": "segment",
              "operator": "is_not",
              "value": "seg_paying_customers"
            }
          ]
        }
      ]
    }
  }
}

{
  "success": false,
  "error": "Provide either root or filters, not both"
}

{
  "success": false,
  "error": "Invalid segment filters: root.children[1].children: must be an array of filters and groups",
  "issues": [
    {
      "path": "root.children[1].children",
      "message": "must be an array of filters and groups"
    }
  ]
}

{
  "success": false,
  "error": "Segment must have at least one filter"
}

{
  "success": false,
  "error": "Operator \"is not\" is not supported for Tag filters. Use one of: contains, does not contain, is empty, is not empty."
}

{
  "success": false,
  "code": "SEGMENT_NAME_ALREADY_EXISTS",
  "error": "Segment name already exists",
  "title": "Segment name already exists",
  "description": "A saved segment named \"Active non-buyers\" already exists in this company. Segment names are unique per company, so another create_segment call with this exact name will fail.",
  "resolution": "Use the existing segment id \"seg_active_non_buyers\", call list_segments before creating, or retry create_segment with a different name.",
  "docsUrl": "https://docs.sequenzy.com/api-reference/segments/create",
  "details": {
    "segmentName": "Active non-buyers",
    "existingSegment": {
      "id": "seg_active_non_buyers",
      "name": "Active non-buyers"
    }
  }
}

{
  "success": false,
  "error": "Unauthorized"
}

Create a segment from either the legacy flat filter array or a nested root filter group. You must provide exactly one of filters or root, and it must contain at least one filter.

Request

string

required

Segment name.

FilterLeaf[]

Legacy v1 filter array. Use with filterJoinOperator.

string

default:"and"

and requires every v1 filter to match. or matches any v1 filter.

FilterGroup

Nested v2 filter group. Use this for nested AND/OR logic, event filters, or segment filters. Groups need kind: "group" and a children array. Filters need field, operator and a string value; omit value only for is_empty and is_not_empty. A child without kind is read as a filter.

A segment filter matches the members of another saved segment. Counting follows up to 16 levels of segment-to-segment references and 1,000 references in total; past either limit, counting the segment returns SEGMENT_REFERENCE_DEPTH_EXCEEDED or SEGMENT_REFERENCE_COUNT_EXCEEDED. Stripe trial subfilters stay under field: "stripeTrialProduct": prod_123:is_canceled, prod_123:end_at:2026-05-26, or prod_123:start_at:7 days ago. Every filter field validates its own operator set:

status, segment, smsStatus: is, is_not
phone: is_empty, is_not_empty
tag: contains, not_contains, is_empty, is_not_empty
email: contains, not_contains (domain or substring), is, is_not (exact, case-insensitive address)
emailProvider, list: is, is_not, is_empty, is_not_empty
firstName, lastName: contains, not_contains, is_empty, is_not_empty
added: less_than, more_than
attribute: equality, empty checks, numeric/date comparisons, and contains checks
event, email engagement fields: is, is_not, at_least, less_than_count
emailBounced: also supports is_temporary_bounce, is_permanent_bounce
Stripe product fields: product-specific purchase/current/trial/date operators
commerceProduct, commerceCollection: is, is_not, at_least, less_than_count

For smsStatus, use subscribed, unsubscribed, pending, or not_subscribed. Phone presence filters use an empty value string. Commerce values use provider:productId or provider:collectionKey, for example shopify:42 or shopify:summer. Count operators append an order threshold, for example shopify:42:3; omitting the threshold means 1. A bare product ID or collection key matches across providers. Prefer provider-qualified values to avoid collisions between stores. Email engagement values can target any email (24h, 30d, all; hour windows accept whole hours from 1h to 8760h), one campaign (campaign:<campaign_id>), or a delivery policy. Use marketing:<timeRange> for marketing-policy campaigns, automations, and Send API traffic, and transactional:<timeRange> for transactional sends. For example, {"field":"emailOpened","operator":"is","value":"marketing:all"} matches contacts who have ever opened a marketing email. Policy scopes work with presence and bounce-subtype operators, not count operators. Attribute filter names are matched case-sensitively against synced subscriber attributes. When a filter references a custom attribute no subscriber has a synced value for, the segment is still created but the response includes a warnings array explaining that the filter currently matches no subscribers (or every subscriber for exclusion operators like is_empty), with a casing suggestion when a close match exists. For arrays of objects, use wildcard paths such as history_events[].eventvenue_id:2103. Two or more positive attribute filters on the same array path that are connected only by AND must be satisfied by one shared array element. A venue match on one history entry cannot combine with a date match on another entry. Negative filters (is_not, not_contains, and is_empty) remain independent because each asserts that no array element matches its condition.

curl -X POST "https://api.sequenzy.com/api/v1/segments" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Active non-buyers",
    "root": {
      "kind": "group",
      "id": "root",
      "joinOperator": "and",
      "children": [
        {
          "kind": "filter",
          "id": "filter-1",
          "field": "attribute",
          "operator": "gte",
          "value": "last_login_days_ago:90"
        },
        {
          "kind": "group",
          "id": "group-1",
          "joinOperator": "or",
          "children": [
            {
              "kind": "filter",
              "id": "filter-2",
              "field": "event",
              "operator": "is_not",
              "value": "saas.purchase:30d"
            },
            {
              "kind": "filter",
              "id": "filter-3",
              "field": "segment",
              "operator": "is_not",
              "value": "seg_paying_customers"
            }
          ]
        }
      ]
    }
  }'

Responses

{
  "success": true,
  "segment": {
    "id": "seg_active_non_buyers",
    "name": "Active non-buyers",
    "filters": [
      {
        "id": "filter-1",
        "field": "attribute",
        "operator": "gte",
        "value": "last_login_days_ago:90"
      },
      {
        "id": "filter-2",
        "field": "event",
        "operator": "is_not",
        "value": "saas.purchase:30d"
      },
      {
        "id": "filter-3",
        "field": "segment",
        "operator": "is_not",
        "value": "seg_paying_customers"
      }
    ],
    "filterJoinOperator": "and",
    "format": "v2",
    "root": {
      "kind": "group",
      "id": "root",
      "joinOperator": "and",
      "children": [
        {
          "kind": "filter",
          "id": "filter-1",
          "field": "attribute",
          "operator": "gte",
          "value": "last_login_days_ago:90"
        },
        {
          "kind": "group",
          "id": "group-1",
          "joinOperator": "or",
          "children": [
            {
              "kind": "filter",
              "id": "filter-2",
              "field": "event",
              "operator": "is_not",
              "value": "saas.purchase:30d"
            },
            {
              "kind": "filter",
              "id": "filter-3",
              "field": "segment",
              "operator": "is_not",
              "value": "seg_paying_customers"
            }
          ]
        }
      ]
    }
  }
}

{
  "success": false,
  "error": "Provide either root or filters, not both"
}

A malformed root or filters returns 400 with issues, one entry per failing path:

{
  "success": false,
  "error": "Invalid segment filters: root.children[1].children: must be an array of filters and groups",
  "issues": [
    {
      "path": "root.children[1].children",
      "message": "must be an array of filters and groups"
    }
  ]
}

{
  "success": false,
  "error": "Segment must have at least one filter"
}

{
  "success": false,
  "error": "Operator \"is not\" is not supported for Tag filters. Use one of: contains, does not contain, is empty, is not empty."
}

{
  "success": false,
  "code": "SEGMENT_NAME_ALREADY_EXISTS",
  "error": "Segment name already exists",
  "title": "Segment name already exists",
  "description": "A saved segment named \"Active non-buyers\" already exists in this company. Segment names are unique per company, so another create_segment call with this exact name will fail.",
  "resolution": "Use the existing segment id \"seg_active_non_buyers\", call list_segments before creating, or retry create_segment with a different name.",
  "docsUrl": "https://docs.sequenzy.com/api-reference/segments/create",
  "details": {
    "segmentName": "Active non-buyers",
    "existingSegment": {
      "id": "seg_active_non_buyers",
      "name": "Active non-buyers"
    }
  }
}

{
  "success": false,
  "error": "Unauthorized"
}

Create Segment

curl --request POST \
  --url https://api.sequenzy.com/api/v1/segments \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "name": "<string>",
  "filters": [
    {}
  ],
  "filterJoinOperator": "<string>",
  "root": {}
}
'

import requests

url = "https://api.sequenzy.com/api/v1/segments"

payload = {
    "name": "<string>",
    "filters": [{}],
    "filterJoinOperator": "<string>",
    "root": {}
}
headers = {
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: JSON.stringify({name: '<string>', filters: [{}], filterJoinOperator: '<string>', root: {}})
};

fetch('https://api.sequenzy.com/api/v1/segments', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.sequenzy.com/api/v1/segments",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    'name' => '<string>',
    'filters' => [
        [
                
        ]
    ],
    'filterJoinOperator' => '<string>',
    'root' => [
        
    ]
  ]),
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <token>",
    "Content-Type: application/json"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://api.sequenzy.com/api/v1/segments"

	payload := strings.NewReader("{\n  \"name\": \"<string>\",\n  \"filters\": [\n    {}\n  ],\n  \"filterJoinOperator\": \"<string>\",\n  \"root\": {}\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("Authorization", "Bearer <token>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.post("https://api.sequenzy.com/api/v1/segments")
  .header("Authorization", "Bearer <token>")
  .header("Content-Type", "application/json")
  .body("{\n  \"name\": \"<string>\",\n  \"filters\": [\n    {}\n  ],\n  \"filterJoinOperator\": \"<string>\",\n  \"root\": {}\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api.sequenzy.com/api/v1/segments")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"name\": \"<string>\",\n  \"filters\": [\n    {}\n  ],\n  \"filterJoinOperator\": \"<string>\",\n  \"root\": {}\n}"

response = http.request(request)
puts response.read_body

{
  "success": true,
  "segment": {
    "id": "seg_active_non_buyers",
    "name": "Active non-buyers",
    "filters": [
      {
        "id": "filter-1",
        "field": "attribute",
        "operator": "gte",
        "value": "last_login_days_ago:90"
      },
      {
        "id": "filter-2",
        "field": "event",
        "operator": "is_not",
        "value": "saas.purchase:30d"
      },
      {
        "id": "filter-3",
        "field": "segment",
        "operator": "is_not",
        "value": "seg_paying_customers"
      }
    ],
    "filterJoinOperator": "and",
    "format": "v2",
    "root": {
      "kind": "group",
      "id": "root",
      "joinOperator": "and",
      "children": [
        {
          "kind": "filter",
          "id": "filter-1",
          "field": "attribute",
          "operator": "gte",
          "value": "last_login_days_ago:90"
        },
        {
          "kind": "group",
          "id": "group-1",
          "joinOperator": "or",
          "children": [
            {
              "kind": "filter",
              "id": "filter-2",
              "field": "event",
              "operator": "is_not",
              "value": "saas.purchase:30d"
            },
            {
              "kind": "filter",
              "id": "filter-3",
              "field": "segment",
              "operator": "is_not",
              "value": "seg_paying_customers"
            }
          ]
        }
      ]
    }
  }
}

{
  "success": false,
  "error": "Provide either root or filters, not both"
}

{
  "success": false,
  "error": "Invalid segment filters: root.children[1].children: must be an array of filters and groups",
  "issues": [
    {
      "path": "root.children[1].children",
      "message": "must be an array of filters and groups"
    }
  ]
}

{
  "success": false,
  "error": "Segment must have at least one filter"
}

{
  "success": false,
  "error": "Operator \"is not\" is not supported for Tag filters. Use one of: contains, does not contain, is empty, is not empty."
}

{
  "success": false,
  "code": "SEGMENT_NAME_ALREADY_EXISTS",
  "error": "Segment name already exists",
  "title": "Segment name already exists",
  "description": "A saved segment named \"Active non-buyers\" already exists in this company. Segment names are unique per company, so another create_segment call with this exact name will fail.",
  "resolution": "Use the existing segment id \"seg_active_non_buyers\", call list_segments before creating, or retry create_segment with a different name.",
  "docsUrl": "https://docs.sequenzy.com/api-reference/segments/create",
  "details": {
    "segmentName": "Active non-buyers",
    "existingSegment": {
      "id": "seg_active_non_buyers",
      "name": "Active non-buyers"
    }
  }
}

{
  "success": false,
  "error": "Unauthorized"
}

​Request

​Responses

Request

Responses