---
title: "Create segment"
method: POST
path: "/apps/{app_id}/segments"
---

# Create segment

`POST /apps/{app_id}/segments`

Programmatically create segments in your OneSignal app using flexible filters and targeting rules.

## Path parameters

- `app_id` string, required

## Headers

- `Authorization` string, required
- `Content-Type` string, required

## Request body

- object
  - `id` string — UUID of the segment. If left empty, it will be assigned automatically.
  - `name` string, required — An internal name you set to help organize and track Segments. Maximum 128 characters.
  - `description` string — Optional human-readable description for the segment. Maximum 255 characters.
  - `filters` union[], required — Filters define the segment based on user properties like tags, activity, or location using flexible AND/OR logic. Limited to 200 total entries, including fields and `OR` operators. See [Sending messages with the OneSignal API](/reference/create-message#filters).
    - union
      - object — Required. The fitler object.
        - `field` 'tag' | 'last_session' | 'first_session' | 'session_count' | 'session_time' | 'language' | 'app_version' | 'location' | 'country', required — The name of the filter to use.
        - `relation` '=' | '!=' | '>' | '<' | 'exists' | 'not_exists' | 'in_array' | 'not_in_array' | 'time_elapsed_gt' | 'time_elapsed_lt', required — Used with most filters. See details on the specific filter.
        - `key` string — Used with the `tag` filter. This is the tag `key`.
        - `value` string — The value of the `field` or tag `key` in which you want to filter with.
      - object
        - `operator` 'AND' | 'OR' — Chain filter conditions with implicit `AND` and `OR` logic. Never end your `filters` object with an `operator`. See [filters](/reference/create-message#filters) for more.

## Response `201`

201

- object
  - `success` boolean — true if the segment was created successfully, false otherwise.
  - `id` string — The UUID of the created segment.

## Other responses

- `400` — 400
- `403` — Forbidden. Your app's plan does not allow this segment operation, or the Authorization key does not have permission.
- `422` — Unprocessable Entity. The segment cannot be created because the app has reached an entitlement limit on segments (e.g., the maximum number of segments allowed for this plan). Distinct from 403 (which signals a permission denial); 422 is specifically a plan-limits failure.
- `429` — Rate limit exceeded. Wait the number of seconds in the `Retry-After` header before retrying.
- `503` — Service temporarily unavailable. Retry after a short backoff. The body may be empty or non-JSON in some failure modes.

---

[API](https://skmtc.net/onesignal/apis/api-onesignal-com.md) · [All operations](https://skmtc.net/onesignal/apis/api-onesignal-com/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/onesignal/api-onesignal-com/versions/0fc223f7e338/schema)