---
title: "Create Segment"
method: POST
path: "/v1/segments"
tags: ["Segments"]
---

# Create Segment

`POST /v1/segments`

Create a customer segment.

> 🚧 Limit on static segments
>
> There is a cap on the number of customers that you can assign to a static segment: **20,000**. If you would like to create a bigger segment, then you can use the unlimited `auto-update` or `passive` segment instead and use some customer metadata to build this segment.

> 🚧 Limit on Active and Passive segments
>
> You can create a maximum of 100 passive and active segments.

## Request body

- union — Request body schema for **POST** `v1/segments`.
  - SegmentsCreateRequestBodyStatic — Request body schema for creating a static customer segment in **POST** `v1/segments`.
    - `name` string — Segment name.
    - `type` 'static' — Defines that the segment is static, meaning it includes only the manually selected customers.
    - `customers` string[] — Array of customer IDs.
  - SegmentsCreateRequestBodyDynamic — Request body schema for creating an active or passive customer segment in **POST** `v1/segments`.
    - `name` string — Segment name.
    - `type` 'auto-update' | 'passive' — Defines whether the segment is: - Active (`auto-update`): customers enter and leave the segment based on the defined filters and the `customer.segment.entered` and `customer.segment.left` events are triggered, - Passive (`passive`): customers enter and leave the segment based on the defined filters, but the `customer.segment.entered` and `customer.segment.left` events are not triggered.
    - `filter` object — Defines a set of criteria for an `auto-update` or `passive` segment type.

## Response `200`

Returns a customer segment object.

- SegmentsCreateResponseBody — This is an object representing a customer segment.
  - `id` string — Unique segment ID.
  - `name` string — Segment name.
  - `created_at` string, date-time — Timestamp representing the date and time when the segment was created. The value is shown in the ISO 8601 format.
  - `updated_at` string, date-time — Timestamp in ISO 8601 format indicating when the segment was updated.
  - `type` 'auto-update' | 'passive' | 'static' — Defines whether the segment is: - Active (`auto-update`): customers enter and leave the segment based on the defined filters and the `customer.segment.entered` and `customer.segment.left` events are triggered, - Passive (`passive`): customers enter and leave the segment based on the defined filters, but the `customer.segment.entered` and `customer.segment.left` events are not triggered, - Static (`static`): manually selected customers.
  - `filter` object, nullable — Defines a set of criteria for an `auto-update` or `passive` segment type.
  - `object` 'segment' — The type of the object represented by JSON. This object stores information about the customer segment.

---

[API](https://skmtc.net/voucherifyio/apis/voucherify-api-async-actions.md) · [All operations](https://skmtc.net/voucherifyio/apis/voucherify-api-async-actions/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/voucherifyio/voucherify-api-async-actions/revisions/4982266e0494/schema)