---
title: "Update a segment"
method: PATCH
path: "/audience/segments/{segmentId}"
tags: ["Audience"]
---

# Update a segment

`PATCH /audience/segments/{segmentId}`

## Request

- Base URL: `https://app.lettr.com/api`
- URL: `https://app.lettr.com/api/audience/segments/{segmentId}`
- Auth: HTTP bearer

Partially update a segment. Requires the `audience:write` scope and is blocked for sandbox API keys.

## Path parameters

- `segmentId` string, uuid, required

## Request body

- UpdateAudienceSegmentRequest: Update a segment. All fields are optional.
  - `name` string
  - `list_id` string, uuid, nullable
  - `conditions` SegmentConditionsInput
    - `groups` SegmentConditionGroup[], required
      - `conditions` SegmentCondition[], required
        - `field` string, required: Field to match: `email`, `status`, `created_at`, `properties.<name>` for a custom property, or `topics` / `lists` (by name, `equals` and `not_equals` only). Any other field or operator combination is rejected with `422`.
        - `operator` 'contains' | 'not_contains' | 'equals' | 'not_equals' | 'starts_with' | 'not_starts_with' | 'ends_with' | 'not_ends_with' | 'is_true' | 'is_false' | 'is_empty' | 'is_not_empty' | 'greater_than' | 'greater_than_or_equal' | 'less_than' | 'less_than_or_equal' | 'before' | 'after', required: Segment condition operator
        - `value` string, nullable: Value to compare against. Required for all operators except `is_true` and `is_false`, which evaluate the field's truthiness and accept no value (may be omitted or `null`).

## Response `200`

Updated

- ShowAudienceSegmentResponse
  - `message` string, required
  - `data` AudienceSegmentView, required
    - `id` string, uuid, required
    - `name` string, required
    - `list_id` string, uuid, nullable, required: Restrict segment to a single list (null = all lists)
    - `list_name` string, nullable, required
    - `condition_groups` SegmentConditionGroup[], required
      - `conditions` SegmentCondition[], required
        - `field` string, required: Field to match: `email`, `status`, `created_at`, `properties.<name>` for a custom property, or `topics` / `lists` (by name, `equals` and `not_equals` only). Any other field or operator combination is rejected with `422`.
        - `operator` 'contains' | 'not_contains' | 'equals' | 'not_equals' | 'starts_with' | 'not_starts_with' | 'ends_with' | 'not_ends_with' | 'is_true' | 'is_false' | 'is_empty' | 'is_not_empty' | 'greater_than' | 'greater_than_or_equal' | 'less_than' | 'less_than_or_equal' | 'before' | 'after', required: Segment condition operator
        - `value` string, nullable: Value to compare against. Required for all operators except `is_true` and `is_false`, which evaluate the field's truthiness and accept no value (may be omitted or `null`).
    - `cached_contacts_count` integer, nullable, required: Last computed contacts count (may be stale)
    - `created_at` string, date-time, required

## Other responses

- `401`: Unauthorized - Missing or invalid API key
- `403`: Forbidden - API key does not have the required scope
- `404`: Resource not found
- `422`: Validation error
- `500`: Internal server error
- `503`: Service unavailable - the API key could not be verified, so the request was not processed. This does not mean the key is invalid; retry after the delay given in the Retry-After header.

---

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