# Audience segments

## Endpoints

- `POST /platform/audience-segments`: [Create audience segment](https://docs.polymorfa.com/api/audience-segments/create-audience-segment)
- `GET /platform/audience-segments`: [List audience segments](https://docs.polymorfa.com/api/audience-segments/list-audience-segments)
- `GET /platform/audience-segments/{segmentId}`: [Get audience segment](https://docs.polymorfa.com/api/audience-segments/get-audience-segment)
- `PATCH /platform/audience-segments/{segmentId}`: [Update audience segment](https://docs.polymorfa.com/api/audience-segments/update-audience-segment)
- `POST /platform/audience-segments/preview`: [Preview audience segment rules](https://docs.polymorfa.com/api/audience-segments/preview-audience-segment-rules)
- `GET /platform/audience-segments/{segmentId}/preview`: [Preview audience segment](https://docs.polymorfa.com/api/audience-segments/preview-audience-segment)
- `DELETE /platform/audience-segments/{segmentId}`: [Delete audience segment](https://docs.polymorfa.com/api/audience-segments/delete-audience-segment)

## The audience segment object

### Attributes

- `id` (string (uuid), required, format uuid). Identifier for this resource.
- `name` (string, required, length 1–100). Human-readable name for this resource.
- `revision` (integer, required, min 1). Specifies revision for this management audience segment.
- `rules` (object, required). Specifies rules for this management audience segment.
  - `match` (string, required). Specifies match for this management audience segment rule. Values: `all`, `any`.
  - `groups` (array of object, required, items 1–10). Groups associated with this management audience segment rule.
    - `match` (string, required). Specifies match for this group. Values: `all`, `any`.
    - `negate` (boolean). Inverts the group's result. Defaults to false.
    - `conditions` (array of object, required, items 1–20). Conditions associated with this group.
      - One of:
        - `Option 1` (object). The profile has this tag.
          - `field` (string, required). Specifies field for this one of. Values: `tag`.
          - `operator` (string, required). Specifies operator for this one of. Values: `contains`.
          - `value` (string, required, min length 1). 1-48 UTF-8 bytes without control characters. The byte limit can be reached before 48 Unicode characters.
        - `Option 2` (object). The profile has at least one of these tags.
          - `field` (string, required). Specifies field for this one of. Values: `tag`.
          - `operator` (string, required). Specifies operator for this one of. Values: `in`.
          - `values` (array of string, required, items 1–50, item min length 1). Values associated with this one of.
        - `Option 3` (object). The profile has at least one tag.
          - `field` (string, required). Specifies field for this one of. Values: `tag`.
          - `operator` (string, required). Specifies operator for this one of. Values: `exists`.
        - `Option 4` (object). The attribute equals this value, with the same type.
          - `field` (string, required). Specifies field for this one of. Values: `attribute`.
          - `name` (string, required, pattern ^[A-Za-z_][A-Za-z0-9_]{0,47}$). Human-readable name for this resource.
          - `operator` (string, required). Specifies operator for this one of. Values: `equals`.
          - `value` (one of, required). Value assigned to this field.
        - `Option 5` (object). The text attribute contains this text, ignoring case.
          - `field` (string, required). Specifies field for this one of. Values: `attribute`.
          - `name` (string, required, pattern ^[A-Za-z_][A-Za-z0-9_]{0,47}$). Human-readable name for this resource.
          - `operator` (string, required). Specifies operator for this one of. Values: `contains`.
          - `value` (string, required, min length 1). 1-256 UTF-8 bytes. The byte limit can be reached before 256 Unicode characters.
        - `Option 6` (object). The attribute equals one of these values.
          - `field` (string, required). Specifies field for this one of. Values: `attribute`.
          - `name` (string, required, pattern ^[A-Za-z_][A-Za-z0-9_]{0,47}$). Human-readable name for this resource.
          - `operator` (string, required). Specifies operator for this one of. Values: `in`.
          - `values` (array of one of, required, items 1–50). Values associated with this one of.
        - `Option 7` (object). The number attribute is greater or less than this number.
          - `field` (string, required). Specifies field for this one of. Values: `attribute`.
          - `name` (string, required, pattern ^[A-Za-z_][A-Za-z0-9_]{0,47}$). Human-readable name for this resource.
          - `operator` (string, required). Specifies operator for this one of. Values: `greater_than`, `less_than`.
          - `value` (number, required). Value assigned to this field.
        - `Option 8` (object). The date attribute is before or after this instant. Both bounds are exclusive.
          - `field` (string, required). Specifies field for this one of. Values: `attribute`.
          - `name` (string, required, pattern ^[A-Za-z_][A-Za-z0-9_]{0,47}$). Human-readable name for this resource.
          - `operator` (string, required). Specifies operator for this one of. Values: `before`, `after`.
          - `value` (string, required, max length 40). ISO 8601 date (`YYYY-MM-DD`, read as midnight UTC) or date-time with `Z` or an offset.
        - `Option 9` (object). The attribute is set and not null.
          - `field` (string, required). Specifies field for this one of. Values: `attribute`.
          - `name` (string, required, pattern ^[A-Za-z_][A-Za-z0-9_]{0,47}$). Human-readable name for this resource.
          - `operator` (string, required). Specifies operator for this one of. Values: `exists`.
        - `consent` (object). The profile's latest campaign consent assertion has this `allowed` value.
          - `field` (string, required). Specifies field for this one of. Values: `consent`.
          - `operator` (string, required). Specifies operator for this one of. Values: `equals`.
          - `value` (boolean, required). Value assigned to this field.
        - `campaign` (object). The phone was a recipient of this team campaign with this outcome, with the same meaning as a retargeting audience.
          - `field` (string, required). Specifies field for this one of. Values: `campaign`.
          - `campaignId` (string (uuid), required, format uuid). Identifier for the campaign.
          - `outcome` (string, required). Specifies outcome for this one of. Values: `delivered`, `not_delivered`, `read`, `not_read`, `replied`, `not_replied`, `failed`.
- `createdAt` (integer, required, min 0). Unix timestamp in milliseconds when this resource was created.
- `updatedAt` (integer, required, min 0). Unix timestamp in milliseconds when this resource was last updated.
```json
{
  "id": "00000000-0000-4000-8000-000000000000",
  "name": "string",
  "revision": 1,
  "rules": {
    "match": "all",
    "groups": [
      {
        "match": "all",
        "negate": true,
        "conditions": [
          {
            "field": "tag",
            "operator": "contains",
            "value": null
          }
        ]
      }
    ]
  },
  "createdAt": 0,
  "updatedAt": 0
}
```

## Create audience segment

`POST https://api.polymorfa.com/platform/audience-segments` (Platform API)

Required permission: `campaigns:manage`

Saves a named rule set over the team's audience profiles. A team holds at most 100 segments. Every campaign a rule names must belong to the team. Both audience betas, `campaigns.audience-profiles` and `campaigns.segments`, must be available; otherwise the request answers `403 feature_unavailable`.

Team keys require `campaigns:manage`. Project tokens are not accepted.

### Body

- `name` (string, required, length 1–100). Human-readable name for this resource.
- `rules` (object, required). Specifies rules for this schema.
  - `match` (string, required). Specifies match for this management audience segment rule. Values: `all`, `any`.
  - `groups` (array of object, required, items 1–10). Groups associated with this management audience segment rule.
    - `match` (string, required). Specifies match for this group. Values: `all`, `any`.
    - `negate` (boolean). Inverts the group's result. Defaults to false.
    - `conditions` (array of object, required, items 1–20). Conditions associated with this group.
      - One of:
        - `Option 1` (object). The profile has this tag.
          - `field` (string, required). Specifies field for this one of. Values: `tag`.
          - `operator` (string, required). Specifies operator for this one of. Values: `contains`.
          - `value` (string, required, min length 1). 1-48 UTF-8 bytes without control characters. The byte limit can be reached before 48 Unicode characters.
        - `Option 2` (object). The profile has at least one of these tags.
          - `field` (string, required). Specifies field for this one of. Values: `tag`.
          - `operator` (string, required). Specifies operator for this one of. Values: `in`.
          - `values` (array of string, required, items 1–50, item min length 1). Values associated with this one of.
        - `Option 3` (object). The profile has at least one tag.
          - `field` (string, required). Specifies field for this one of. Values: `tag`.
          - `operator` (string, required). Specifies operator for this one of. Values: `exists`.
        - `Option 4` (object). The attribute equals this value, with the same type.
          - `field` (string, required). Specifies field for this one of. Values: `attribute`.
          - `name` (string, required, pattern ^[A-Za-z_][A-Za-z0-9_]{0,47}$). Human-readable name for this resource.
          - `operator` (string, required). Specifies operator for this one of. Values: `equals`.
          - `value` (one of, required). Value assigned to this field.
        - `Option 5` (object). The text attribute contains this text, ignoring case.
          - `field` (string, required). Specifies field for this one of. Values: `attribute`.
          - `name` (string, required, pattern ^[A-Za-z_][A-Za-z0-9_]{0,47}$). Human-readable name for this resource.
          - `operator` (string, required). Specifies operator for this one of. Values: `contains`.
          - `value` (string, required, min length 1). 1-256 UTF-8 bytes. The byte limit can be reached before 256 Unicode characters.
        - `Option 6` (object). The attribute equals one of these values.
          - `field` (string, required). Specifies field for this one of. Values: `attribute`.
          - `name` (string, required, pattern ^[A-Za-z_][A-Za-z0-9_]{0,47}$). Human-readable name for this resource.
          - `operator` (string, required). Specifies operator for this one of. Values: `in`.
          - `values` (array of one of, required, items 1–50). Values associated with this one of.
        - `Option 7` (object). The number attribute is greater or less than this number.
          - `field` (string, required). Specifies field for this one of. Values: `attribute`.
          - `name` (string, required, pattern ^[A-Za-z_][A-Za-z0-9_]{0,47}$). Human-readable name for this resource.
          - `operator` (string, required). Specifies operator for this one of. Values: `greater_than`, `less_than`.
          - `value` (number, required). Value assigned to this field.
        - `Option 8` (object). The date attribute is before or after this instant. Both bounds are exclusive.
          - `field` (string, required). Specifies field for this one of. Values: `attribute`.
          - `name` (string, required, pattern ^[A-Za-z_][A-Za-z0-9_]{0,47}$). Human-readable name for this resource.
          - `operator` (string, required). Specifies operator for this one of. Values: `before`, `after`.
          - `value` (string, required, max length 40). ISO 8601 date (`YYYY-MM-DD`, read as midnight UTC) or date-time with `Z` or an offset.
        - `Option 9` (object). The attribute is set and not null.
          - `field` (string, required). Specifies field for this one of. Values: `attribute`.
          - `name` (string, required, pattern ^[A-Za-z_][A-Za-z0-9_]{0,47}$). Human-readable name for this resource.
          - `operator` (string, required). Specifies operator for this one of. Values: `exists`.
        - `consent` (object). The profile's latest campaign consent assertion has this `allowed` value.
          - `field` (string, required). Specifies field for this one of. Values: `consent`.
          - `operator` (string, required). Specifies operator for this one of. Values: `equals`.
          - `value` (boolean, required). Value assigned to this field.
        - `campaign` (object). The phone was a recipient of this team campaign with this outcome, with the same meaning as a retargeting audience.
          - `field` (string, required). Specifies field for this one of. Values: `campaign`.
          - `campaignId` (string (uuid), required, format uuid). Identifier for the campaign.
          - `outcome` (string, required). Specifies outcome for this one of. Values: `delivered`, `not_delivered`, `read`, `not_read`, `replied`, `not_replied`, `failed`.

### Request

```bash
curl -X POST "https://api.polymorfa.com/platform/audience-segments" \
  -H "Authorization: Bearer <POLYMORFA_API_KEY>" \
  -H "Polymorfa-Version: 2026-09-22" \
  -H "Content-Type: application/json" \
  -d '{
  "name": "string",
  "rules": {
    "match": "all",
    "groups": [
      {
        "match": "all",
        "conditions": [
          {
            "field": "tag",
            "operator": "contains",
            "value": null
          }
        ]
      }
    ]
  }
}'
```

### Responses

#### 200

Success
- `data` (object, required). Structured data carried by this object.
  - `id` (string (uuid), required, format uuid). Identifier for this resource.
  - `name` (string, required, length 1–100). Human-readable name for this resource.
  - `revision` (integer, required, min 1). Specifies revision for this management audience segment.
  - `rules` (object, required). Specifies rules for this management audience segment.
    - `match` (string, required). Specifies match for this management audience segment rule. Values: `all`, `any`.
    - `groups` (array of object, required, items 1–10). Groups associated with this management audience segment rule.
      - `match` (string, required). Specifies match for this group. Values: `all`, `any`.
      - `negate` (boolean). Inverts the group's result. Defaults to false.
      - `conditions` (array of object, required, items 1–20). Conditions associated with this group.
        - One of:
          - `Option 1` (object). The profile has this tag.
          - `Option 2` (object). The profile has at least one of these tags.
          - `Option 3` (object). The profile has at least one tag.
          - `Option 4` (object). The attribute equals this value, with the same type.
          - `Option 5` (object). The text attribute contains this text, ignoring case.
          - `Option 6` (object). The attribute equals one of these values.
          - `Option 7` (object). The number attribute is greater or less than this number.
          - `Option 8` (object). The date attribute is before or after this instant. Both bounds are exclusive.
          - `Option 9` (object). The attribute is set and not null.
          - `consent` (object). The profile's latest campaign consent assertion has this `allowed` value.
          - `campaign` (object). The phone was a recipient of this team campaign with this outcome, with the same meaning as a retargeting audience.
  - `createdAt` (integer, required, min 0). Unix timestamp in milliseconds when this resource was created.
  - `updatedAt` (integer, required, min 0). Unix timestamp in milliseconds when this resource was last updated.

Headers:

- `X-Request-Id` (string). Stable request correlation identifier.
- `X-Trace-Id` (string, pattern ^[0-9a-f]{32}$). W3C trace ID of this request. Your `traceparent` trace ID when you sent a valid one.
- `Polymorfa-Version` (string). API version applied to this response.

```json
{
  "data": {
    "id": "00000000-0000-4000-8000-000000000000",
    "name": "string",
    "revision": 1,
    "rules": {
      "match": "all",
      "groups": [
        {
          "match": "all",
          "conditions": [
            null
          ]
        }
      ]
    },
    "createdAt": 0,
    "updatedAt": 0
  }
}
```

#### 400

A path, query, or request-body value did not pass validation.
- `error` (object, required). Error details returned when the operation fails.
  - `type` (string, required). Type discriminator for this object. Values: `invalid_request_error`, `authentication_error`, `permission_error`, `billing_error`, `conflict_error`, `rate_limit_error`, `api_error`, `upstream_error`.
  - `code` (string, required). Stable failure code. Use this value for programmatic handling.
  - `message` (string, required). Safe explanation of the failure.
  - `param` (string, required, nullable). Invalid request field, or null when no field applies.
  - `request_id` (string, required). Matches the X-Request-Id response header. Include it when you contact support.
  - `request_log_url` (string (uri), format uri). Console page that shows this request. Returned only to team and project credentials whose request was logged.
- `data` (string, required, nullable). Always null for a failed request.
- `docs` (string (uri), required, format uri). Documentation link to this failure code.

Headers:

- `X-Request-Id`, `X-Trace-Id`, `Polymorfa-Version`: described under 200.

```json
{
  "error": {
    "type": "invalid_request_error",
    "code": "invalid_parameter",
    "message": "Correct the invalid request field.",
    "param": null,
    "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30"
  },
  "data": null,
  "docs": "https://docs.polymorfa.com/api/errors#invalid-parameter"
}
```

#### 401

Missing/invalid credential for this audience.
Same fields as 400.

Headers:

- `X-Request-Id`, `X-Trace-Id`, `Polymorfa-Version`: described under 200.

```json
{
  "error": {
    "type": "authentication_error",
    "code": "invalid_credential",
    "message": "Supply a valid credential.",
    "param": null,
    "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30"
  },
  "data": null,
  "docs": "https://docs.polymorfa.com/api/errors#invalid-credential"
}
```

#### 403

Authenticated but lacks the required scope/role/audience.
Same fields as 400.

Headers:

- `X-Request-Id`, `X-Trace-Id`, `Polymorfa-Version`: described under 200.

```json
{
  "error": {
    "type": "permission_error",
    "code": "permission_denied",
    "message": "The credential does not have access to this resource.",
    "param": null,
    "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30"
  },
  "data": null,
  "docs": "https://docs.polymorfa.com/api/errors#permission-denied"
}
```

#### 409

The request conflicts with the resource's current state.
Same fields as 400.

Headers:

- `X-Request-Id`, `X-Trace-Id`, `Polymorfa-Version`: described under 200.

```json
{
  "error": {
    "type": "conflict_error",
    "code": "state_conflict",
    "message": "The request conflicts with the resource state.",
    "param": null,
    "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30"
  },
  "data": null,
  "docs": "https://docs.polymorfa.com/api/errors#state-conflict"
}
```

## List audience segments

`GET https://api.polymorfa.com/platform/audience-segments` (Platform API)

Required permission: `campaigns:read`

Lists the team's saved segments with cursor pagination. Reads stay available after beta withdrawal.

Team keys require `campaigns:read`. Project tokens are not accepted.

### Query parameters

- `cursor` (string). Specifies cursor for this query parameter.
- `limit` (integer, range 1–100). Specifies limit for this query parameter. Default: `25`.

### Request

```bash
curl "https://api.polymorfa.com/platform/audience-segments" \
  -H "Authorization: Bearer <POLYMORFA_API_KEY>" \
  -H "Polymorfa-Version: 2026-09-22"
```

### Responses

#### 200

Success
- `data` (array of object, required). Structured data carried by this object.
  - `id` (string (uuid), required, format uuid). Identifier for this resource.
  - `name` (string, required, length 1–100). Human-readable name for this resource.
  - `revision` (integer, required, min 1). Specifies revision for this management audience segment.
  - `rules` (object, required). Specifies rules for this management audience segment.
    - `match` (string, required). Specifies match for this management audience segment rule. Values: `all`, `any`.
    - `groups` (array of object, required, items 1–10). Groups associated with this management audience segment rule.
      - `match` (string, required). Specifies match for this group. Values: `all`, `any`.
      - `negate` (boolean). Inverts the group's result. Defaults to false.
      - `conditions` (array of one of, required, items 1–20). Conditions associated with this group.
  - `createdAt` (integer, required, min 0). Unix timestamp in milliseconds when this resource was created.
  - `updatedAt` (integer, required, min 0). Unix timestamp in milliseconds when this resource was last updated.
- `page` (object, required). Specifies page for this schema.
  - `nextCursor` (string, required, nullable). Specifies next cursor for this management cursor page metadata.
  - `hasMore` (boolean, required). Whether more.

Headers:

- `X-Request-Id` (string). Stable request correlation identifier.
- `X-Trace-Id` (string, pattern ^[0-9a-f]{32}$). W3C trace ID of this request. Your `traceparent` trace ID when you sent a valid one.
- `Polymorfa-Version` (string). API version applied to this response.

```json
{
  "data": [
    {
      "id": "00000000-0000-4000-8000-000000000000",
      "name": "string",
      "revision": 1,
      "rules": {
        "match": "all",
        "groups": [
          {
            "match": "all",
            "conditions": [
              null
            ]
          }
        ]
      },
      "createdAt": 0,
      "updatedAt": 0
    }
  ],
  "page": {
    "nextCursor": "string",
    "hasMore": true
  }
}
```

#### 400

A path, query, or request-body value did not pass validation.
- `error` (object, required). Error details returned when the operation fails.
  - `type` (string, required). Type discriminator for this object. Values: `invalid_request_error`, `authentication_error`, `permission_error`, `billing_error`, `conflict_error`, `rate_limit_error`, `api_error`, `upstream_error`.
  - `code` (string, required). Stable failure code. Use this value for programmatic handling.
  - `message` (string, required). Safe explanation of the failure.
  - `param` (string, required, nullable). Invalid request field, or null when no field applies.
  - `request_id` (string, required). Matches the X-Request-Id response header. Include it when you contact support.
  - `request_log_url` (string (uri), format uri). Console page that shows this request. Returned only to team and project credentials whose request was logged.
- `data` (string, required, nullable). Always null for a failed request.
- `docs` (string (uri), required, format uri). Documentation link to this failure code.

Headers:

- `X-Request-Id`, `X-Trace-Id`, `Polymorfa-Version`: described under 200.

```json
{
  "error": {
    "type": "invalid_request_error",
    "code": "invalid_parameter",
    "message": "Correct the invalid request field.",
    "param": null,
    "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30"
  },
  "data": null,
  "docs": "https://docs.polymorfa.com/api/errors#invalid-parameter"
}
```

#### 401

Missing/invalid credential for this audience.
Same fields as 400.

Headers:

- `X-Request-Id`, `X-Trace-Id`, `Polymorfa-Version`: described under 200.

```json
{
  "error": {
    "type": "authentication_error",
    "code": "invalid_credential",
    "message": "Supply a valid credential.",
    "param": null,
    "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30"
  },
  "data": null,
  "docs": "https://docs.polymorfa.com/api/errors#invalid-credential"
}
```

#### 403

Authenticated but lacks the required scope/role/audience.
Same fields as 400.

Headers:

- `X-Request-Id`, `X-Trace-Id`, `Polymorfa-Version`: described under 200.

```json
{
  "error": {
    "type": "permission_error",
    "code": "permission_denied",
    "message": "The credential does not have access to this resource.",
    "param": null,
    "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30"
  },
  "data": null,
  "docs": "https://docs.polymorfa.com/api/errors#permission-denied"
}
```

## Get audience segment

`GET https://api.polymorfa.com/platform/audience-segments/{segmentId}` (Platform API)

Required permission: `campaigns:read`

Returns one saved segment.

Team keys require `campaigns:read`. Project tokens are not accepted.

### Path parameters

- `segmentId` (string, required). Identifier for the segment.

### Request

```bash
curl "https://api.polymorfa.com/platform/audience-segments/<segmentId>" \
  -H "Authorization: Bearer <POLYMORFA_API_KEY>" \
  -H "Polymorfa-Version: 2026-09-22"
```

### Responses

#### 200

Success
- `data` (object, required). Structured data carried by this object.
  - `id` (string (uuid), required, format uuid). Identifier for this resource.
  - `name` (string, required, length 1–100). Human-readable name for this resource.
  - `revision` (integer, required, min 1). Specifies revision for this management audience segment.
  - `rules` (object, required). Specifies rules for this management audience segment.
    - `match` (string, required). Specifies match for this management audience segment rule. Values: `all`, `any`.
    - `groups` (array of object, required, items 1–10). Groups associated with this management audience segment rule.
      - `match` (string, required). Specifies match for this group. Values: `all`, `any`.
      - `negate` (boolean). Inverts the group's result. Defaults to false.
      - `conditions` (array of object, required, items 1–20). Conditions associated with this group.
        - One of:
          - `Option 1` (object). The profile has this tag.
          - `Option 2` (object). The profile has at least one of these tags.
          - `Option 3` (object). The profile has at least one tag.
          - `Option 4` (object). The attribute equals this value, with the same type.
          - `Option 5` (object). The text attribute contains this text, ignoring case.
          - `Option 6` (object). The attribute equals one of these values.
          - `Option 7` (object). The number attribute is greater or less than this number.
          - `Option 8` (object). The date attribute is before or after this instant. Both bounds are exclusive.
          - `Option 9` (object). The attribute is set and not null.
          - `consent` (object). The profile's latest campaign consent assertion has this `allowed` value.
          - `campaign` (object). The phone was a recipient of this team campaign with this outcome, with the same meaning as a retargeting audience.
  - `createdAt` (integer, required, min 0). Unix timestamp in milliseconds when this resource was created.
  - `updatedAt` (integer, required, min 0). Unix timestamp in milliseconds when this resource was last updated.

Headers:

- `X-Request-Id` (string). Stable request correlation identifier.
- `X-Trace-Id` (string, pattern ^[0-9a-f]{32}$). W3C trace ID of this request. Your `traceparent` trace ID when you sent a valid one.
- `Polymorfa-Version` (string). API version applied to this response.

```json
{
  "data": {
    "id": "00000000-0000-4000-8000-000000000000",
    "name": "string",
    "revision": 1,
    "rules": {
      "match": "all",
      "groups": [
        {
          "match": "all",
          "conditions": [
            null
          ]
        }
      ]
    },
    "createdAt": 0,
    "updatedAt": 0
  }
}
```

#### 400

A path, query, or request-body value did not pass validation.
- `error` (object, required). Error details returned when the operation fails.
  - `type` (string, required). Type discriminator for this object. Values: `invalid_request_error`, `authentication_error`, `permission_error`, `billing_error`, `conflict_error`, `rate_limit_error`, `api_error`, `upstream_error`.
  - `code` (string, required). Stable failure code. Use this value for programmatic handling.
  - `message` (string, required). Safe explanation of the failure.
  - `param` (string, required, nullable). Invalid request field, or null when no field applies.
  - `request_id` (string, required). Matches the X-Request-Id response header. Include it when you contact support.
  - `request_log_url` (string (uri), format uri). Console page that shows this request. Returned only to team and project credentials whose request was logged.
- `data` (string, required, nullable). Always null for a failed request.
- `docs` (string (uri), required, format uri). Documentation link to this failure code.

Headers:

- `X-Request-Id`, `X-Trace-Id`, `Polymorfa-Version`: described under 200.

```json
{
  "error": {
    "type": "invalid_request_error",
    "code": "invalid_parameter",
    "message": "Correct the invalid request field.",
    "param": null,
    "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30"
  },
  "data": null,
  "docs": "https://docs.polymorfa.com/api/errors#invalid-parameter"
}
```

#### 401

Missing/invalid credential for this audience.
Same fields as 400.

Headers:

- `X-Request-Id`, `X-Trace-Id`, `Polymorfa-Version`: described under 200.

```json
{
  "error": {
    "type": "authentication_error",
    "code": "invalid_credential",
    "message": "Supply a valid credential.",
    "param": null,
    "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30"
  },
  "data": null,
  "docs": "https://docs.polymorfa.com/api/errors#invalid-credential"
}
```

#### 403

Authenticated but lacks the required scope/role/audience.
Same fields as 400.

Headers:

- `X-Request-Id`, `X-Trace-Id`, `Polymorfa-Version`: described under 200.

```json
{
  "error": {
    "type": "permission_error",
    "code": "permission_denied",
    "message": "The credential does not have access to this resource.",
    "param": null,
    "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30"
  },
  "data": null,
  "docs": "https://docs.polymorfa.com/api/errors#permission-denied"
}
```

#### 404

The requested resource was not found inside the authenticated team or project scope.
Same fields as 400.

Headers:

- `X-Request-Id`, `X-Trace-Id`, `Polymorfa-Version`: described under 200.

```json
{
  "error": {
    "type": "invalid_request_error",
    "code": "resource_not_found",
    "message": "The resource is unavailable to this caller.",
    "param": null,
    "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30"
  },
  "data": null,
  "docs": "https://docs.polymorfa.com/api/errors#resource-not-found"
}
```

## Update audience segment

`PATCH https://api.polymorfa.com/platform/audience-segments/{segmentId}` (Platform API)

Required permission: `campaigns:manage`

Replaces the name, the rules or both at the observed revision; a stale revision answers `409`. A draft campaign that uses the segment evaluates the new rules when it launches. Campaigns already launched keep their recipients. Both audience betas, `campaigns.audience-profiles` and `campaigns.segments`, must be available; otherwise the request answers `403 feature_unavailable`.

Team keys require `campaigns:manage`. Project tokens are not accepted.

### Path parameters

- `segmentId` (string, required). Identifier for the segment.

### Body

- `expectedRevision` (integer, required, min 1). Specifies expected revision for this schema.
- `name` (string, length 1–100). Human-readable name for this resource.
- `rules` (object). Specifies rules for this schema.
  - `match` (string, required). Specifies match for this management audience segment rule. Values: `all`, `any`.
  - `groups` (array of object, required, items 1–10). Groups associated with this management audience segment rule.
    - `match` (string, required). Specifies match for this group. Values: `all`, `any`.
    - `negate` (boolean). Inverts the group's result. Defaults to false.
    - `conditions` (array of object, required, items 1–20). Conditions associated with this group.
      - One of:
        - `Option 1` (object). The profile has this tag.
          - `field` (string, required). Specifies field for this one of. Values: `tag`.
          - `operator` (string, required). Specifies operator for this one of. Values: `contains`.
          - `value` (string, required, min length 1). 1-48 UTF-8 bytes without control characters. The byte limit can be reached before 48 Unicode characters.
        - `Option 2` (object). The profile has at least one of these tags.
          - `field` (string, required). Specifies field for this one of. Values: `tag`.
          - `operator` (string, required). Specifies operator for this one of. Values: `in`.
          - `values` (array of string, required, items 1–50, item min length 1). Values associated with this one of.
        - `Option 3` (object). The profile has at least one tag.
          - `field` (string, required). Specifies field for this one of. Values: `tag`.
          - `operator` (string, required). Specifies operator for this one of. Values: `exists`.
        - `Option 4` (object). The attribute equals this value, with the same type.
          - `field` (string, required). Specifies field for this one of. Values: `attribute`.
          - `name` (string, required, pattern ^[A-Za-z_][A-Za-z0-9_]{0,47}$). Human-readable name for this resource.
          - `operator` (string, required). Specifies operator for this one of. Values: `equals`.
          - `value` (one of, required). Value assigned to this field.
        - `Option 5` (object). The text attribute contains this text, ignoring case.
          - `field` (string, required). Specifies field for this one of. Values: `attribute`.
          - `name` (string, required, pattern ^[A-Za-z_][A-Za-z0-9_]{0,47}$). Human-readable name for this resource.
          - `operator` (string, required). Specifies operator for this one of. Values: `contains`.
          - `value` (string, required, min length 1). 1-256 UTF-8 bytes. The byte limit can be reached before 256 Unicode characters.
        - `Option 6` (object). The attribute equals one of these values.
          - `field` (string, required). Specifies field for this one of. Values: `attribute`.
          - `name` (string, required, pattern ^[A-Za-z_][A-Za-z0-9_]{0,47}$). Human-readable name for this resource.
          - `operator` (string, required). Specifies operator for this one of. Values: `in`.
          - `values` (array of one of, required, items 1–50). Values associated with this one of.
        - `Option 7` (object). The number attribute is greater or less than this number.
          - `field` (string, required). Specifies field for this one of. Values: `attribute`.
          - `name` (string, required, pattern ^[A-Za-z_][A-Za-z0-9_]{0,47}$). Human-readable name for this resource.
          - `operator` (string, required). Specifies operator for this one of. Values: `greater_than`, `less_than`.
          - `value` (number, required). Value assigned to this field.
        - `Option 8` (object). The date attribute is before or after this instant. Both bounds are exclusive.
          - `field` (string, required). Specifies field for this one of. Values: `attribute`.
          - `name` (string, required, pattern ^[A-Za-z_][A-Za-z0-9_]{0,47}$). Human-readable name for this resource.
          - `operator` (string, required). Specifies operator for this one of. Values: `before`, `after`.
          - `value` (string, required, max length 40). ISO 8601 date (`YYYY-MM-DD`, read as midnight UTC) or date-time with `Z` or an offset.
        - `Option 9` (object). The attribute is set and not null.
          - `field` (string, required). Specifies field for this one of. Values: `attribute`.
          - `name` (string, required, pattern ^[A-Za-z_][A-Za-z0-9_]{0,47}$). Human-readable name for this resource.
          - `operator` (string, required). Specifies operator for this one of. Values: `exists`.
        - `consent` (object). The profile's latest campaign consent assertion has this `allowed` value.
          - `field` (string, required). Specifies field for this one of. Values: `consent`.
          - `operator` (string, required). Specifies operator for this one of. Values: `equals`.
          - `value` (boolean, required). Value assigned to this field.
        - `campaign` (object). The phone was a recipient of this team campaign with this outcome, with the same meaning as a retargeting audience.
          - `field` (string, required). Specifies field for this one of. Values: `campaign`.
          - `campaignId` (string (uuid), required, format uuid). Identifier for the campaign.
          - `outcome` (string, required). Specifies outcome for this one of. Values: `delivered`, `not_delivered`, `read`, `not_read`, `replied`, `not_replied`, `failed`.

### Request

```bash
curl -X PATCH "https://api.polymorfa.com/platform/audience-segments/<segmentId>" \
  -H "Authorization: Bearer <POLYMORFA_API_KEY>" \
  -H "Polymorfa-Version: 2026-09-22" \
  -H "Content-Type: application/json" \
  -d '{
  "expectedRevision": 1
}'
```

### Responses

#### 200

Success
- `data` (object, required). Structured data carried by this object.
  - `id` (string (uuid), required, format uuid). Identifier for this resource.
  - `name` (string, required, length 1–100). Human-readable name for this resource.
  - `revision` (integer, required, min 1). Specifies revision for this management audience segment.
  - `rules` (object, required). Specifies rules for this management audience segment.
    - `match` (string, required). Specifies match for this management audience segment rule. Values: `all`, `any`.
    - `groups` (array of object, required, items 1–10). Groups associated with this management audience segment rule.
      - `match` (string, required). Specifies match for this group. Values: `all`, `any`.
      - `negate` (boolean). Inverts the group's result. Defaults to false.
      - `conditions` (array of object, required, items 1–20). Conditions associated with this group.
        - One of:
          - `Option 1` (object). The profile has this tag.
          - `Option 2` (object). The profile has at least one of these tags.
          - `Option 3` (object). The profile has at least one tag.
          - `Option 4` (object). The attribute equals this value, with the same type.
          - `Option 5` (object). The text attribute contains this text, ignoring case.
          - `Option 6` (object). The attribute equals one of these values.
          - `Option 7` (object). The number attribute is greater or less than this number.
          - `Option 8` (object). The date attribute is before or after this instant. Both bounds are exclusive.
          - `Option 9` (object). The attribute is set and not null.
          - `consent` (object). The profile's latest campaign consent assertion has this `allowed` value.
          - `campaign` (object). The phone was a recipient of this team campaign with this outcome, with the same meaning as a retargeting audience.
  - `createdAt` (integer, required, min 0). Unix timestamp in milliseconds when this resource was created.
  - `updatedAt` (integer, required, min 0). Unix timestamp in milliseconds when this resource was last updated.

Headers:

- `X-Request-Id` (string). Stable request correlation identifier.
- `X-Trace-Id` (string, pattern ^[0-9a-f]{32}$). W3C trace ID of this request. Your `traceparent` trace ID when you sent a valid one.
- `Polymorfa-Version` (string). API version applied to this response.

```json
{
  "data": {
    "id": "00000000-0000-4000-8000-000000000000",
    "name": "string",
    "revision": 1,
    "rules": {
      "match": "all",
      "groups": [
        {
          "match": "all",
          "conditions": [
            null
          ]
        }
      ]
    },
    "createdAt": 0,
    "updatedAt": 0
  }
}
```

#### 400

A path, query, or request-body value did not pass validation.
- `error` (object, required). Error details returned when the operation fails.
  - `type` (string, required). Type discriminator for this object. Values: `invalid_request_error`, `authentication_error`, `permission_error`, `billing_error`, `conflict_error`, `rate_limit_error`, `api_error`, `upstream_error`.
  - `code` (string, required). Stable failure code. Use this value for programmatic handling.
  - `message` (string, required). Safe explanation of the failure.
  - `param` (string, required, nullable). Invalid request field, or null when no field applies.
  - `request_id` (string, required). Matches the X-Request-Id response header. Include it when you contact support.
  - `request_log_url` (string (uri), format uri). Console page that shows this request. Returned only to team and project credentials whose request was logged.
- `data` (string, required, nullable). Always null for a failed request.
- `docs` (string (uri), required, format uri). Documentation link to this failure code.

Headers:

- `X-Request-Id`, `X-Trace-Id`, `Polymorfa-Version`: described under 200.

```json
{
  "error": {
    "type": "invalid_request_error",
    "code": "invalid_parameter",
    "message": "Correct the invalid request field.",
    "param": null,
    "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30"
  },
  "data": null,
  "docs": "https://docs.polymorfa.com/api/errors#invalid-parameter"
}
```

#### 401

Missing/invalid credential for this audience.
Same fields as 400.

Headers:

- `X-Request-Id`, `X-Trace-Id`, `Polymorfa-Version`: described under 200.

```json
{
  "error": {
    "type": "authentication_error",
    "code": "invalid_credential",
    "message": "Supply a valid credential.",
    "param": null,
    "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30"
  },
  "data": null,
  "docs": "https://docs.polymorfa.com/api/errors#invalid-credential"
}
```

#### 403

Authenticated but lacks the required scope/role/audience.
Same fields as 400.

Headers:

- `X-Request-Id`, `X-Trace-Id`, `Polymorfa-Version`: described under 200.

```json
{
  "error": {
    "type": "permission_error",
    "code": "permission_denied",
    "message": "The credential does not have access to this resource.",
    "param": null,
    "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30"
  },
  "data": null,
  "docs": "https://docs.polymorfa.com/api/errors#permission-denied"
}
```

#### 404

The requested resource was not found inside the authenticated team or project scope.
Same fields as 400.

Headers:

- `X-Request-Id`, `X-Trace-Id`, `Polymorfa-Version`: described under 200.

```json
{
  "error": {
    "type": "invalid_request_error",
    "code": "resource_not_found",
    "message": "The resource is unavailable to this caller.",
    "param": null,
    "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30"
  },
  "data": null,
  "docs": "https://docs.polymorfa.com/api/errors#resource-not-found"
}
```

#### 409

The request conflicts with the resource's current state.
Same fields as 400.

Headers:

- `X-Request-Id`, `X-Trace-Id`, `Polymorfa-Version`: described under 200.

```json
{
  "error": {
    "type": "conflict_error",
    "code": "state_conflict",
    "message": "The request conflicts with the resource state.",
    "param": null,
    "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30"
  },
  "data": null,
  "docs": "https://docs.polymorfa.com/api/errors#state-conflict"
}
```

## Preview audience segment rules

`POST https://api.polymorfa.com/platform/audience-segments/preview` (Platform API)

Required permission: `campaigns:manage`

Evaluates unsaved rules now and returns counts and up to five masked matching profiles. Nothing is saved. A campaign evaluates its segment again when it launches, so counts can change. Both audience betas, `campaigns.audience-profiles` and `campaigns.segments`, must be available; otherwise the request answers `403 feature_unavailable`.

Team keys require `campaigns:manage`. Project tokens are not accepted.

### Body

- `rules` (object, required). Specifies rules for this schema.
  - `match` (string, required). Specifies match for this management audience segment rule. Values: `all`, `any`.
  - `groups` (array of object, required, items 1–10). Groups associated with this management audience segment rule.
    - `match` (string, required). Specifies match for this group. Values: `all`, `any`.
    - `negate` (boolean). Inverts the group's result. Defaults to false.
    - `conditions` (array of object, required, items 1–20). Conditions associated with this group.
      - One of:
        - `Option 1` (object). The profile has this tag.
          - `field` (string, required). Specifies field for this one of. Values: `tag`.
          - `operator` (string, required). Specifies operator for this one of. Values: `contains`.
          - `value` (string, required, min length 1). 1-48 UTF-8 bytes without control characters. The byte limit can be reached before 48 Unicode characters.
        - `Option 2` (object). The profile has at least one of these tags.
          - `field` (string, required). Specifies field for this one of. Values: `tag`.
          - `operator` (string, required). Specifies operator for this one of. Values: `in`.
          - `values` (array of string, required, items 1–50, item min length 1). Values associated with this one of.
        - `Option 3` (object). The profile has at least one tag.
          - `field` (string, required). Specifies field for this one of. Values: `tag`.
          - `operator` (string, required). Specifies operator for this one of. Values: `exists`.
        - `Option 4` (object). The attribute equals this value, with the same type.
          - `field` (string, required). Specifies field for this one of. Values: `attribute`.
          - `name` (string, required, pattern ^[A-Za-z_][A-Za-z0-9_]{0,47}$). Human-readable name for this resource.
          - `operator` (string, required). Specifies operator for this one of. Values: `equals`.
          - `value` (one of, required). Value assigned to this field.
        - `Option 5` (object). The text attribute contains this text, ignoring case.
          - `field` (string, required). Specifies field for this one of. Values: `attribute`.
          - `name` (string, required, pattern ^[A-Za-z_][A-Za-z0-9_]{0,47}$). Human-readable name for this resource.
          - `operator` (string, required). Specifies operator for this one of. Values: `contains`.
          - `value` (string, required, min length 1). 1-256 UTF-8 bytes. The byte limit can be reached before 256 Unicode characters.
        - `Option 6` (object). The attribute equals one of these values.
          - `field` (string, required). Specifies field for this one of. Values: `attribute`.
          - `name` (string, required, pattern ^[A-Za-z_][A-Za-z0-9_]{0,47}$). Human-readable name for this resource.
          - `operator` (string, required). Specifies operator for this one of. Values: `in`.
          - `values` (array of one of, required, items 1–50). Values associated with this one of.
        - `Option 7` (object). The number attribute is greater or less than this number.
          - `field` (string, required). Specifies field for this one of. Values: `attribute`.
          - `name` (string, required, pattern ^[A-Za-z_][A-Za-z0-9_]{0,47}$). Human-readable name for this resource.
          - `operator` (string, required). Specifies operator for this one of. Values: `greater_than`, `less_than`.
          - `value` (number, required). Value assigned to this field.
        - `Option 8` (object). The date attribute is before or after this instant. Both bounds are exclusive.
          - `field` (string, required). Specifies field for this one of. Values: `attribute`.
          - `name` (string, required, pattern ^[A-Za-z_][A-Za-z0-9_]{0,47}$). Human-readable name for this resource.
          - `operator` (string, required). Specifies operator for this one of. Values: `before`, `after`.
          - `value` (string, required, max length 40). ISO 8601 date (`YYYY-MM-DD`, read as midnight UTC) or date-time with `Z` or an offset.
        - `Option 9` (object). The attribute is set and not null.
          - `field` (string, required). Specifies field for this one of. Values: `attribute`.
          - `name` (string, required, pattern ^[A-Za-z_][A-Za-z0-9_]{0,47}$). Human-readable name for this resource.
          - `operator` (string, required). Specifies operator for this one of. Values: `exists`.
        - `consent` (object). The profile's latest campaign consent assertion has this `allowed` value.
          - `field` (string, required). Specifies field for this one of. Values: `consent`.
          - `operator` (string, required). Specifies operator for this one of. Values: `equals`.
          - `value` (boolean, required). Value assigned to this field.
        - `campaign` (object). The phone was a recipient of this team campaign with this outcome, with the same meaning as a retargeting audience.
          - `field` (string, required). Specifies field for this one of. Values: `campaign`.
          - `campaignId` (string (uuid), required, format uuid). Identifier for the campaign.
          - `outcome` (string, required). Specifies outcome for this one of. Values: `delivered`, `not_delivered`, `read`, `not_read`, `replied`, `not_replied`, `failed`.

### Request

```bash
curl -X POST "https://api.polymorfa.com/platform/audience-segments/preview" \
  -H "Authorization: Bearer <POLYMORFA_API_KEY>" \
  -H "Polymorfa-Version: 2026-09-22" \
  -H "Content-Type: application/json" \
  -d '{
  "rules": {
    "match": "all",
    "groups": [
      {
        "match": "all",
        "conditions": [
          {
            "field": "tag",
            "operator": "contains",
            "value": null
          }
        ]
      }
    ]
  }
}'
```

### Responses

#### 200

Success
- `data` (object, required). Structured data carried by this object.
  - `matchedCount` (integer, required, min 0). Profiles that match the rules.
  - `optedOutCount` (integer, required, min 0). Matched profiles whose number is on the team's opt-out list.
  - `consentWithheldCount` (integer, required, min 0). Matched profiles, not opted out, whose latest consent assertion is `allowed: false`. Launch leaves them out.
  - `eligibleCount` (integer, required, min 0). Matched profiles a launch now would send to.
  - `sample` (array of object, required, max items 5). Up to five eligible profiles with the phone masked.
    - `phone` (string, required). Masked phone, for example `+49*******12`.
    - `tags` (array of string, required). Tags associated with this sample.
  - `evaluatedAt` (integer, required, min 0). Evaluation time in Unix milliseconds.

Headers:

- `X-Request-Id` (string). Stable request correlation identifier.
- `X-Trace-Id` (string, pattern ^[0-9a-f]{32}$). W3C trace ID of this request. Your `traceparent` trace ID when you sent a valid one.
- `Polymorfa-Version` (string). API version applied to this response.

```json
{
  "data": {
    "matchedCount": 0,
    "optedOutCount": 0,
    "consentWithheldCount": 0,
    "eligibleCount": 0,
    "sample": [
      {
        "phone": "string",
        "tags": [
          "string"
        ]
      }
    ],
    "evaluatedAt": 0
  }
}
```

#### 400

A path, query, or request-body value did not pass validation.
- `error` (object, required). Error details returned when the operation fails.
  - `type` (string, required). Type discriminator for this object. Values: `invalid_request_error`, `authentication_error`, `permission_error`, `billing_error`, `conflict_error`, `rate_limit_error`, `api_error`, `upstream_error`.
  - `code` (string, required). Stable failure code. Use this value for programmatic handling.
  - `message` (string, required). Safe explanation of the failure.
  - `param` (string, required, nullable). Invalid request field, or null when no field applies.
  - `request_id` (string, required). Matches the X-Request-Id response header. Include it when you contact support.
  - `request_log_url` (string (uri), format uri). Console page that shows this request. Returned only to team and project credentials whose request was logged.
- `data` (string, required, nullable). Always null for a failed request.
- `docs` (string (uri), required, format uri). Documentation link to this failure code.

Headers:

- `X-Request-Id`, `X-Trace-Id`, `Polymorfa-Version`: described under 200.

```json
{
  "error": {
    "type": "invalid_request_error",
    "code": "invalid_parameter",
    "message": "Correct the invalid request field.",
    "param": null,
    "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30"
  },
  "data": null,
  "docs": "https://docs.polymorfa.com/api/errors#invalid-parameter"
}
```

#### 401

Missing/invalid credential for this audience.
Same fields as 400.

Headers:

- `X-Request-Id`, `X-Trace-Id`, `Polymorfa-Version`: described under 200.

```json
{
  "error": {
    "type": "authentication_error",
    "code": "invalid_credential",
    "message": "Supply a valid credential.",
    "param": null,
    "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30"
  },
  "data": null,
  "docs": "https://docs.polymorfa.com/api/errors#invalid-credential"
}
```

#### 403

Authenticated but lacks the required scope/role/audience.
Same fields as 400.

Headers:

- `X-Request-Id`, `X-Trace-Id`, `Polymorfa-Version`: described under 200.

```json
{
  "error": {
    "type": "permission_error",
    "code": "permission_denied",
    "message": "The credential does not have access to this resource.",
    "param": null,
    "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30"
  },
  "data": null,
  "docs": "https://docs.polymorfa.com/api/errors#permission-denied"
}
```

#### 409

The request conflicts with the resource's current state.
Same fields as 400.

Headers:

- `X-Request-Id`, `X-Trace-Id`, `Polymorfa-Version`: described under 200.

```json
{
  "error": {
    "type": "conflict_error",
    "code": "state_conflict",
    "message": "The request conflicts with the resource state.",
    "param": null,
    "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30"
  },
  "data": null,
  "docs": "https://docs.polymorfa.com/api/errors#state-conflict"
}
```

## Preview audience segment

`GET https://api.polymorfa.com/platform/audience-segments/{segmentId}/preview` (Platform API)

Required permission: `campaigns:read`

Evaluates the saved segment now and returns counts, up to five masked matching profiles and the evaluated `revision`. Both audience betas, `campaigns.audience-profiles` and `campaigns.segments`, must be available; otherwise the request answers `403 feature_unavailable`.

Team keys require `campaigns:read`. Project tokens are not accepted.

### Path parameters

- `segmentId` (string, required). Identifier for the segment.

### Request

```bash
curl "https://api.polymorfa.com/platform/audience-segments/<segmentId>/preview" \
  -H "Authorization: Bearer <POLYMORFA_API_KEY>" \
  -H "Polymorfa-Version: 2026-09-22"
```

### Responses

#### 200

Success
- `data` (object, required). Structured data carried by this object.
  - `matchedCount` (integer, required, min 0). Profiles that match the rules.
  - `optedOutCount` (integer, required, min 0). Matched profiles whose number is on the team's opt-out list.
  - `consentWithheldCount` (integer, required, min 0). Matched profiles, not opted out, whose latest consent assertion is `allowed: false`. Launch leaves them out.
  - `eligibleCount` (integer, required, min 0). Matched profiles a launch now would send to.
  - `sample` (array of object, required, max items 5). Up to five eligible profiles with the phone masked.
    - `phone` (string, required). Masked phone, for example `+49*******12`.
    - `tags` (array of string, required). Tags associated with this sample.
  - `evaluatedAt` (integer, required, min 0). Evaluation time in Unix milliseconds.
  - `revision` (integer, required, min 1). Specifies revision for this data.

Headers:

- `X-Request-Id` (string). Stable request correlation identifier.
- `X-Trace-Id` (string, pattern ^[0-9a-f]{32}$). W3C trace ID of this request. Your `traceparent` trace ID when you sent a valid one.
- `Polymorfa-Version` (string). API version applied to this response.

```json
{
  "data": {
    "matchedCount": 0,
    "optedOutCount": 0,
    "consentWithheldCount": 0,
    "eligibleCount": 0,
    "sample": [
      {
        "phone": "string",
        "tags": [
          "string"
        ]
      }
    ],
    "evaluatedAt": 0,
    "revision": 1
  }
}
```

#### 400

A path, query, or request-body value did not pass validation.
- `error` (object, required). Error details returned when the operation fails.
  - `type` (string, required). Type discriminator for this object. Values: `invalid_request_error`, `authentication_error`, `permission_error`, `billing_error`, `conflict_error`, `rate_limit_error`, `api_error`, `upstream_error`.
  - `code` (string, required). Stable failure code. Use this value for programmatic handling.
  - `message` (string, required). Safe explanation of the failure.
  - `param` (string, required, nullable). Invalid request field, or null when no field applies.
  - `request_id` (string, required). Matches the X-Request-Id response header. Include it when you contact support.
  - `request_log_url` (string (uri), format uri). Console page that shows this request. Returned only to team and project credentials whose request was logged.
- `data` (string, required, nullable). Always null for a failed request.
- `docs` (string (uri), required, format uri). Documentation link to this failure code.

Headers:

- `X-Request-Id`, `X-Trace-Id`, `Polymorfa-Version`: described under 200.

```json
{
  "error": {
    "type": "invalid_request_error",
    "code": "invalid_parameter",
    "message": "Correct the invalid request field.",
    "param": null,
    "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30"
  },
  "data": null,
  "docs": "https://docs.polymorfa.com/api/errors#invalid-parameter"
}
```

#### 401

Missing/invalid credential for this audience.
Same fields as 400.

Headers:

- `X-Request-Id`, `X-Trace-Id`, `Polymorfa-Version`: described under 200.

```json
{
  "error": {
    "type": "authentication_error",
    "code": "invalid_credential",
    "message": "Supply a valid credential.",
    "param": null,
    "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30"
  },
  "data": null,
  "docs": "https://docs.polymorfa.com/api/errors#invalid-credential"
}
```

#### 403

Authenticated but lacks the required scope/role/audience.
Same fields as 400.

Headers:

- `X-Request-Id`, `X-Trace-Id`, `Polymorfa-Version`: described under 200.

```json
{
  "error": {
    "type": "permission_error",
    "code": "permission_denied",
    "message": "The credential does not have access to this resource.",
    "param": null,
    "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30"
  },
  "data": null,
  "docs": "https://docs.polymorfa.com/api/errors#permission-denied"
}
```

#### 404

The requested resource was not found inside the authenticated team or project scope.
Same fields as 400.

Headers:

- `X-Request-Id`, `X-Trace-Id`, `Polymorfa-Version`: described under 200.

```json
{
  "error": {
    "type": "invalid_request_error",
    "code": "resource_not_found",
    "message": "The resource is unavailable to this caller.",
    "param": null,
    "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30"
  },
  "data": null,
  "docs": "https://docs.polymorfa.com/api/errors#resource-not-found"
}
```

#### 409

The request conflicts with the resource's current state.
Same fields as 400.

Headers:

- `X-Request-Id`, `X-Trace-Id`, `Polymorfa-Version`: described under 200.

```json
{
  "error": {
    "type": "conflict_error",
    "code": "state_conflict",
    "message": "The request conflicts with the resource state.",
    "param": null,
    "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30"
  },
  "data": null,
  "docs": "https://docs.polymorfa.com/api/errors#state-conflict"
}
```

## Delete audience segment

`DELETE https://api.polymorfa.com/platform/audience-segments/{segmentId}` (Platform API)

Required permission: `campaigns:manage`

Deletes the segment at the observed revision. Answers `409` while an unlaunched draft campaign uses it as its audience. Launched campaigns keep their recipients and `segmentSnapshot`; their `segmentId` becomes null. Deletion stays available after beta withdrawal.

Team keys require `campaigns:manage`. Project tokens are not accepted.

### Path parameters

- `segmentId` (string, required). Identifier for the segment.

### Query parameters

- `expectedRevision` (integer, required, range 1–9007199254740991). Specifies expected revision for this query parameter.

### Request

```bash
curl -X DELETE "https://api.polymorfa.com/platform/audience-segments/<segmentId>?expectedRevision=<expectedRevision>" \
  -H "Authorization: Bearer <POLYMORFA_API_KEY>" \
  -H "Polymorfa-Version: 2026-09-22"
```

### Responses

#### 200

Success
- `data` (object, required). Structured data carried by this object.
  - `deleted` (boolean, required). Whether deleted. Values: `true`.
  - `id` (string (uuid), required, format uuid). Identifier for this resource.

Headers:

- `X-Request-Id` (string). Stable request correlation identifier.
- `X-Trace-Id` (string, pattern ^[0-9a-f]{32}$). W3C trace ID of this request. Your `traceparent` trace ID when you sent a valid one.
- `Polymorfa-Version` (string). API version applied to this response.

```json
{
  "data": {
    "deleted": true,
    "id": "00000000-0000-4000-8000-000000000000"
  }
}
```

#### 400

A path, query, or request-body value did not pass validation.
- `error` (object, required). Error details returned when the operation fails.
  - `type` (string, required). Type discriminator for this object. Values: `invalid_request_error`, `authentication_error`, `permission_error`, `billing_error`, `conflict_error`, `rate_limit_error`, `api_error`, `upstream_error`.
  - `code` (string, required). Stable failure code. Use this value for programmatic handling.
  - `message` (string, required). Safe explanation of the failure.
  - `param` (string, required, nullable). Invalid request field, or null when no field applies.
  - `request_id` (string, required). Matches the X-Request-Id response header. Include it when you contact support.
  - `request_log_url` (string (uri), format uri). Console page that shows this request. Returned only to team and project credentials whose request was logged.
- `data` (string, required, nullable). Always null for a failed request.
- `docs` (string (uri), required, format uri). Documentation link to this failure code.

Headers:

- `X-Request-Id`, `X-Trace-Id`, `Polymorfa-Version`: described under 200.

```json
{
  "error": {
    "type": "invalid_request_error",
    "code": "invalid_parameter",
    "message": "Correct the invalid request field.",
    "param": null,
    "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30"
  },
  "data": null,
  "docs": "https://docs.polymorfa.com/api/errors#invalid-parameter"
}
```

#### 401

Missing/invalid credential for this audience.
Same fields as 400.

Headers:

- `X-Request-Id`, `X-Trace-Id`, `Polymorfa-Version`: described under 200.

```json
{
  "error": {
    "type": "authentication_error",
    "code": "invalid_credential",
    "message": "Supply a valid credential.",
    "param": null,
    "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30"
  },
  "data": null,
  "docs": "https://docs.polymorfa.com/api/errors#invalid-credential"
}
```

#### 403

Authenticated but lacks the required scope/role/audience.
Same fields as 400.

Headers:

- `X-Request-Id`, `X-Trace-Id`, `Polymorfa-Version`: described under 200.

```json
{
  "error": {
    "type": "permission_error",
    "code": "permission_denied",
    "message": "The credential does not have access to this resource.",
    "param": null,
    "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30"
  },
  "data": null,
  "docs": "https://docs.polymorfa.com/api/errors#permission-denied"
}
```

#### 404

The requested resource was not found inside the authenticated team or project scope.
Same fields as 400.

Headers:

- `X-Request-Id`, `X-Trace-Id`, `Polymorfa-Version`: described under 200.

```json
{
  "error": {
    "type": "invalid_request_error",
    "code": "resource_not_found",
    "message": "The resource is unavailable to this caller.",
    "param": null,
    "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30"
  },
  "data": null,
  "docs": "https://docs.polymorfa.com/api/errors#resource-not-found"
}
```

#### 409

The request conflicts with the resource's current state.
Same fields as 400.

Headers:

- `X-Request-Id`, `X-Trace-Id`, `Polymorfa-Version`: described under 200.

```json
{
  "error": {
    "type": "conflict_error",
    "code": "state_conflict",
    "message": "The request conflicts with the resource state.",
    "param": null,
    "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30"
  },
  "data": null,
  "docs": "https://docs.polymorfa.com/api/errors#state-conflict"
}
```
