# List Apple Messages for Business suppressions

`GET /v1/amb/suppressions`

Returns a paginated list of the workspace's active Apple Messages for Business suppressions: customers who have opted out of one brand, or of the whole workspace. Episodes that have ended are left out; fetch one by ID to read it. Filter by `business_id` to see one brand's suppressions, including the workspace-wide ones that block it too.

## Code samples

**TypeScript**

```ts
const result = await bird.amb.suppressions.list({
  business_id: "abz_01krdgeqcxet5s7t44vh8rt9mg",
  limit: 2,
});
console.log(result);
```

Examples: [TypeScript](/docs/api/reference/list-amb-suppressions.ts.md) · [Python](/docs/api/reference/list-amb-suppressions.py.md) · [Go](/docs/api/reference/list-amb-suppressions.go.md) · [PHP](/docs/api/reference/list-amb-suppressions.php.md) · [CLI](/docs/api/reference/list-amb-suppressions.cli.md) · [MCP](/docs/api/reference/list-amb-suppressions.mcp.md) · [cURL](/docs/api/reference/list-amb-suppressions.curl.md)

## Example response `200`

```json
{
  "data": [
    {
      "created_at": "2026-05-20T09:14:52Z",
      "updated_at": "2026-05-25T16:42:01Z",
      "id": "asp_01krdgeqcxet5s7t44vh8rt9mg",
      "business_id": "abz_01krdgeqcxet5s7t44vh8rt9mg",
      "handle": "+15551234567",
      "handle_type": "opaque_user_id",
      "reason": "manual",
      "origin": "user",
      "applies_to": "all",
      "source_message_id": "amb_01krdgeqcxet5s7t44vh8rt9mg",
      "source_end_message_id": "amb_01krdgeqcxet5s7t44vh8rt9mg",
      "effective_at": "2026-08-12T09:00:00Z",
      "ended_at": null,
      "ended_reason": null,
      "ended_effective_at": null
    }
  ],
  "next_cursor": "eyJ2IjoxLCJzIjoiXCIyMDI2LTA1LTI1VDE0OjAzOjEwWlwiIiwiaSI6IjAxOTJmM2IxLTRjN2UtN2EyYi05ZDYxLThmM2E1YzJlN2I0MCJ9",
  "prev_cursor": null,
  "refresh_cursor": "eyJ2IjoxLCJzIjoiXCIyMDI2LTA1LTI1VDE2OjQyOjAxWlwiIiwiaSI6IjAxOTJmM2IxLTllMDQtN2NkMy1iODE3LTJhNmY0ZDFjOGUwOSJ9"
}
```

## Query parameters

- `business_id` (string): Keep only suppressions for this brand, including the workspace-wide ones that block it too. Omit to see suppressions for every brand in the workspace.
- `handle` (string): Prefix filter on the suppressed phone number or opaque identifier (case-insensitive). A complete value returns only that handle; a partial value returns every match.
- `handle_type` (string)

  Keep only suppressions of this kind.

  Possible values: `phone_number`, `opaque_user_id`
- `reason` (string)

  Keep only suppressions with this reason.

  Possible values (may grow over time): `manual`, `opted_out`
- `limit` (integer): Maximum number of items to return per page.
- `starting_after` (string): Cursor from the `next_cursor` field of a previous list response. Returns items immediately after the cursor position in the current sort order.
- `ending_before` (string): Cursor from the `prev_cursor` or `refresh_cursor` field of a previous list response. Returns items immediately before the cursor position in the current sort order. `prev_cursor` returns the preceding page. `refresh_cursor` anchors at the first row of that response, which on a newest-first sort is how to fetch the items that have appeared since.

## Response body

- `data` (array of object, required): Active suppression episodes for the workspace, most recently effective first. Episodes that have ended are left out; fetch one by ID to read it.
- `data.created_at` (string, required)
- `data.updated_at` (string, required)
- `data.id` (string, required): Unique identifier for the suppression episode.
- `data.business_id` (nullable string): The brand this episode applies to, or null when it covers every brand in the workspace. Apple requires that a brand not message someone who opted out of it, so an episode scoped to one brand does not suppress a sibling brand in the same workspace.
- `data.handle` (string, required): The suppressed phone number or opaque identifier. `handle_type` says which. For a phone number this is canonical E.164 with a leading plus sign.
- `data.handle_type` (string, required)

  What kind of value `handle` holds.

  - `phone_number` means `handle` is the customer's phone number. Apple's CloseSession event carries a phone number rather than an opaque identifier, so a suppression opened by a close on a conversation identified by phone number takes this kind.
  - `opaque_user_id` means `handle` is the opaque identifier Apple assigns to the customer's conversation with the business, stable across a close and a later re-initiation.

  Possible values: `phone_number`, `opaque_user_id`
- `data.reason` (string, required)

  Why the handle is suppressed. `manual` means it was added directly through this API or the dashboard. `opted_out` covers every case where Apple or the customer signaled they should not be contacted: a close, a permanent delivery failure, a declined invitation, or a stop keyword. This list grows over time, so treat an unknown value as informational rather than rejecting the record.

  Possible values (may grow over time): `manual`, `opted_out`
- `data.origin` (string, required)

  How this episode came to exist.

  - `user` means a dashboard user added it directly.
  - `api_key` means an API caller added it directly.
  - `close_session` means the customer sent Apple's close event, ending the conversation.
  - `gone` means a send to the handle returned Apple's permanent-failure response, which Bird treats as the same signal as a close.
  - `invitation_declined` means the customer declined an invitation. No operation writes this value yet; it starts once invitations ship.
  - `keyword` means the customer sent a stop keyword. No operation writes this value yet; it starts once keyword automation ships.

  Possible values: `user`, `api_key`, `close_session`, `gone`, `invitation_declined`, `keyword`
- `data.applies_to` (string, required)

  What this episode blocks. `all` blocks every outbound path: operator and automated replies, API sends, typing indicators, and invitations. `invitations` blocks only a new invitation to the handle, leaving replies in a conversation the customer opens directly unaffected; no operation writes this value yet, since invitations are a future feature. This list grows over time, so treat an unknown value as blocking.

  Possible values (may grow over time): `all`, `invitations`
- `data.source_message_id` (nullable string): ID of what opened this episode. A permanent delivery failure on send names the message that failed, an `amb_` id. A close names the conversation event Bird recorded for it instead, an `aev_` id, because a close carries no message of its own. Null for an episode opened directly through this API or by a phone-addressed close that has no conversation event.
- `data.source_end_message_id` (nullable string): ID of the inbound message that ended this episode by re-initiating the conversation. Null while the episode is still in force, and null for an episode ended through this API instead.
- `data.effective_at` (string, required): When this episode started blocking outbound messages.
- `data.ended_at` (nullable string): When this episode stopped applying. Null while it is still blocking outbound messages, which is the case for every episode the list returns.
- `data.ended_reason` (nullable string)

  What ended it. `reinitiated` means the same customer started the conversation again: this ends an episode opened by `close_session` or `gone` automatically, with no API call, and does not apply to one opened by `invitation_declined`, which needs an explicit re-subscription instead. `user` and `api_key` mean this API ended it directly, which works for an episode of any origin. Null while the episode is still in force.

  Possible values (may grow over time): `user`, `api_key`, `reinitiated`
- `data.ended_effective_at` (nullable string): When the ended state took effect, which can differ from `ended_at` when the record of an end arrives later than the event that caused it.
- `next_cursor` (nullable string, required): Cursor for the next page. Pass back as `starting_after` to advance forward. `null` when no next page exists.
- `prev_cursor` (nullable string, required): Cursor for the previous page. Pass back as `ending_before` to step backward. `null` when no previous page exists.
- `refresh_cursor` (nullable string, required): Refresh anchor, the first row of this response. Pass back as `ending_before` to fetch what precedes it in the current sort order. On a newest-first sort those are the items that have appeared since; on any other sort they are the items that sort earlier, so refreshing such a list means re-fetching it instead. Non-`null` whenever `data` is non-empty; `null` only on an empty page. Distinct from `prev_cursor`.

## Related resources

- [Should I use a Bird SDK or call the API directly?](/explained/platform/should-i-use-an-sdk-or-call-the-api-directly) (answer)
- [Build your first integration](/learn/paths/integration) (course)
- [Send your first email](/docs/get-started/send-your-first-email) (docs)

[Get an implementation brief](/learn/workspace?topic=api-basics)