> ## Documentation Index
> Fetch the complete documentation index at: https://docs.sequenzy.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Create Segment

> Create a saved subscriber segment

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

<ParamField body="name" type="string" required>
  Segment name.
</ParamField>

<ParamField body="filters" type="FilterLeaf[]">
  Legacy v1 filter array. Use with `filterJoinOperator`.
</ParamField>

<ParamField body="filterJoinOperator" type="string" default="and">
  `and` requires every v1 filter to match. `or` matches any v1 filter.
</ParamField>

<ParamField body="root" type="FilterGroup">
  Nested v2 filter group. Use this for nested AND/OR logic, event filters, or
  segment filters.
</ParamField>

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`: `is`, `is_not`
* `tag`: `contains`, `not_contains`, `is_empty`, `is_not_empty`
* `email`: `contains`, `not_contains`
* `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

```bash theme={null}
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

<ResponseExample>
  ```json 200 theme={null}
  {
    "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"
              }
            ]
          }
        ]
      }
    }
  }
  ```

  ```json 400 theme={null}
  {
    "success": false,
    "error": "Provide either root or filters, not both"
  }
  ```

  ```json 400 theme={null}
  {
    "success": false,
    "error": "Segment must have at least one filter"
  }
  ```

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

  ```json 409 theme={null}
  {
    "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"
      }
    }
  }
  ```

  ```json 401 theme={null}
  {
    "success": false,
    "error": "Unauthorized"
  }
  ```
</ResponseExample>