---
title: "POST /v1/workspaces/{workspaceId}/audience/segments"
method: POST
path: "/v1/workspaces/{workspaceId}/audience/segments"
---

# POST /v1/workspaces/{workspaceId}/audience/segments

`POST /v1/workspaces/{workspaceId}/audience/segments`

## Request

- Base URL: `https://api.bangermail.com`
- URL: `https://api.bangermail.com/v1/workspaces/{workspaceId}/audience/segments`
- Auth: HTTP bearer

## Headers

- `Idempotency-Key` string, required

## Request body

- object
  - `name` string, required
  - `filter` object, required
    - `status` 'subscribed' | 'unsubscribed' | 'bounced' | 'complained'
    - `attributes` object

## Response `200`

Canonical read-back or idempotent receipt. Provider acceptance is sent; delivered requires a delivery event and does not prove inbox placement.

- object
  - `data` object, required
    - `id` string, uuid, required
    - `name` string, required
    - `filter` ContactFilter, required: Conditions must reference declared contact fields and use operators supported by their type. set and not_set omit value; within_days uses 1–3650 days.
      - `status` 'subscribed' | 'unsubscribed' | 'bounced' | 'complained'
      - `attributes` object
      - `conditions` object[]
        - `field` string, required
        - `op` 'is' | 'is_not' | 'contains' | 'set' | 'not_set' | 'gt' | 'gte' | 'lt' | 'lte' | 'within_days' | 'any_of' | 'includes', required
        - `value` union
          - string
          - number
          - boolean
          - string[]
      - `match` 'all' | 'any'
    - `created_at` string, date-time, required
    - `updated_at` string, date-time, required
    - `count` integer, required
    - `missing_consent_evidence_count` integer, required
    - `sample` object[], required
      - `id` string, uuid, required
      - `email` string, required
      - `display_name` string, nullable, required
      - `attributes` object, required
    - `excluded` object, required
      - `suppressed` integer, required
      - `not_subscribed` integer, required
      - `missing_recipient_hash` integer, required
      - `missing_consent_evidence` integer, required
    - `replayed` boolean, required

## Other responses

- `400`: Invalid input or missing operating product.
- `403`: Existing OAuth scope or product boundary denied.
- `409`: Stale version or idempotency conflict.
- `422`: Consent, suppression, personalization, or readiness blocker.

---

[API](https://skmtc.dev/bangermail/apis/banger-api.md) · [All operations](https://skmtc.dev/bangermail/apis/banger-api/llms.txt) · [OpenAPI document](https://skmtc.dev/bangermail/apis/banger-api/revisions/a149909267f9?raw)