---
title: "Create a segment"
method: POST
path: "/api/v1/segments"
tags: ["Segments"]
---

# Create a segment

`POST /api/v1/segments`

Create a segment from a filter expression. It starts empty until evaluated. Validate and preview the filter first.

## Request body

- object
  - `name` string, required — Display name.
  - `slug` string, required — Permanent identifier, lowercase-kebab-case, unique in your organization. Cannot be changed after creation.
  - `description` string, nullable
  - `filterExpression` object, required — The audience filter: a tree of predicates over person attributes, related data, and events. Discover valid `attr` tokens and operators with segments_catalog (GET /api/v1/segments/catalog).
    - `kind` 'person', required
    - `op` 'AND' | 'OR', required
    - `predicates` union[], required
      - union
        - object
          - `kind` 'has_relationship', required
          - `connector` 'AND' | 'OR'
          - `customObjectType` string, required
          - `attributeFilters` object[], required
            - `attr` string, required
            - `path` string[]
            - `type` 'STRING' | 'NUMBER' | 'BOOLEAN' | 'DATE' | 'JSON' | 'ARRAY', required
            - `op` 'eq' | 'neq' | 'in' | 'not_in' | 'contains' | 'not_contains' | 'starts_with' | 'ends_with' | 'gt' | 'gte' | 'lt' | 'lte' | 'on' | 'before' | 'after' | 'between' | 'in_last_n' | 'in_next_n' | 'more_than_n_ago' | 'more_than_n_from_now' | 'exactly_n_from_today' | 'is_null' | 'is_not_null', required
            - `value` union
              - …
          - `path` object[]
            - `customObjectType` string, required
            - `direction` 'parent_to_child' | 'child_to_parent'
            - `relationshipType` string
            - `attributeFilters` object[], required
              - …
        - object
          - `kind` 'person_attribute', required
          - `connector` 'AND' | 'OR'
          - `attr` string, required
          - `path` string[]
          - `type` 'STRING' | 'NUMBER' | 'BOOLEAN' | 'DATE' | 'JSON' | 'ARRAY', required
          - `op` 'eq' | 'neq' | 'in' | 'not_in' | 'contains' | 'not_contains' | 'starts_with' | 'ends_with' | 'gt' | 'gte' | 'lt' | 'lte' | 'on' | 'before' | 'after' | 'between' | 'in_last_n' | 'in_next_n' | 'more_than_n_ago' | 'more_than_n_from_now' | 'exactly_n_from_today' | 'is_null' | 'is_not_null', required
          - `value` union
            - string
            - number
            - boolean
            - union[]
              - …
            - object
              - …
            - object
              - …
            - object
              - …
        - object
          - `kind` 'person_group', required
          - `connector` 'AND' | 'OR'
          - `filters` object[], required
            - `attr` string, required
            - `path` string[]
            - `type` 'STRING' | 'NUMBER' | 'BOOLEAN' | 'DATE' | 'JSON' | 'ARRAY', required
            - `op` 'eq' | 'neq' | 'in' | 'not_in' | 'contains' | 'not_contains' | 'starts_with' | 'ends_with' | 'gt' | 'gte' | 'lt' | 'lte' | 'on' | 'before' | 'after' | 'between' | 'in_last_n' | 'in_next_n' | 'more_than_n_ago' | 'more_than_n_from_now' | 'exactly_n_from_today' | 'is_null' | 'is_not_null', required
            - `value` union
              - …
        - object
          - `kind` 'event', required
          - `connector` 'AND' | 'OR'
          - `eventName` string, required
          - `occurred` boolean, required
          - `propertyFilters` object[]
            - `key` string, required
            - `path` string[]
            - `type` 'STRING' | 'NUMBER' | 'BOOLEAN' | 'DATE' | 'JSON' | 'ARRAY', required
            - `op` 'eq' | 'neq' | 'in' | 'not_in' | 'contains' | 'not_contains' | 'starts_with' | 'ends_with' | 'gt' | 'gte' | 'lt' | 'lte' | 'on' | 'before' | 'after' | 'between' | 'in_last_n' | 'in_next_n' | 'more_than_n_ago' | 'more_than_n_from_now' | 'exactly_n_from_today' | 'is_null' | 'is_not_null', required
            - `value` union
              - …
          - `window` object
            - `op` 'in_last_n' | 'more_than_n_ago' | 'between' | 'before' | 'after' | 'on', required
            - `value` union
              - …
  - `evaluationCadence` 'REACTIVE_ONLY' | 'HOURLY' | 'DAILY' — How often the segment re-evaluates. Defaults to REACTIVE_ONLY — evaluate on demand with segments_evaluate.
  - `dailyEvaluationHour` integer, nullable — For DAILY cadence: the hour (0-23, in your organization timezone) the segment evaluates.
  - `skipWeekendEvaluation` boolean — When true, the segment is not evaluated on weekends.
  - `outputColumns` object — Optional extra columns to project for each member when the segment feeds downstream automations.
    - `person` object
      - `columns` string[]
      - `attributes` string[]
    - `customObjects` object[]
      - `typeName` string, required
      - `attributes` string[], required
    - `computed` string[]

## Response `201`

Success

- object
  - `slug` string, required — Unique identifier within your organization.
  - `name` string, required
  - `description` string, nullable, required
  - `evaluationCadence` 'REACTIVE_ONLY' | 'HOURLY' | 'DAILY', required — How often the segment is re-evaluated. REACTIVE_ONLY segments only change when evaluated explicitly.
  - `memberCount` integer, required — Live count of currently active members.
  - `lastEvaluatedAt` string, nullable, required — ISO 8601 timestamp; null if the segment has never evaluated.
  - `createdAt` string, required — ISO 8601 timestamp.

## Other responses

- `400` — Validation failed or the request cannot proceed.
- `401` — Missing, malformed, or revoked API key.
- `404` — The resource does not exist in this organization.
- `409` — Conflicts with the current state (duplicates, wrong lifecycle state).
- `422` — The request is well-formed but semantically invalid.
- `429` — Rate limit exceeded — retry after `Retry-After`.
- `500` — Internal server error.
- `503` — Transient error — retry with a narrower request.

---

[API](https://skmtc.net/useboom/apis/boom-api.md) · [All operations](https://skmtc.net/useboom/apis/boom-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/useboom/boom-api/revisions/00f873e07076/schema)