---
title: "List what a sender needs to send"
canonical: "https://bird.com/docs/api/reference/list-workspace-sms-sender-requirements"
---

# List what a sender needs to send

`GET /v1/sms/senders/{sender_id}/requirements`

Returns the countries a sender can reach, each country's requirements, and the current registration status. Omit `country_code` for the full list. An empty filtered result means the sender has no route to that country.

`registration_mode` distinguishes optional registration from registration required before sending. `status` reports registration progress. Optional registration can be pending while messages are accepted with an overwritten sender ID. `sender_id_behavior` reports the effective behavior without overwrite details; those are published in the country messaging context. Check `destination_enabled` and other sending restrictions before sending.

Each row's `next` lists actions for that country, including starting an optional registration. An empty list means there is no next registration action; an absent one means this read does not report it.

The operation depends on `program`: `alpha` and `numeric` use compliance submissions, `tfn` uses toll-free verification, and `10dlc` uses campaign assignment. `short_code` is filed and maintained by Bird: no API action exists, and a rejected one is resolved through support, as the row's `next` says. Read each row's `next` after each operation for the next step.

## Code samples

**TypeScript**

```ts
await bird.smsSenderRequirements.list("snd_01krdgeqcxet5s7t44vh8rt9mg");
```

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

## Example response `200`

```json
{
  "data": [
    {
      "sender_id": "snd_01krdgeqcxet5s7t44vh8rt9mg",
      "country_code": "US",
      "registration_mode": "none",
      "sender_id_behavior": "unknown",
      "program": "10dlc",
      "status": "pending",
      "next": [
        {
          "kind": "operation"
        }
      ],
      "category": "transactional",
      "registration_id": "scr_01krdgeqcxet5s7t44vh8rt9mg",
      "program_entry": "none"
    }
  ],
  "programs": [
    {
      "program": "10dlc",
      "countries": [
        "US"
      ],
      "status": "pending"
    }
  ]
}
```

## Path parameters

- `sender_id` (string): ID of the SMS sender (`snd_` prefix), as returned when the sender was created.

## Query parameters

- `country_code` (string): Ask about one destination country. Omit to return every country relevant to the sender.

## Response body

- `data` (array of object, required): One entry per destination country this sender can reach, which is the level the decision to carry your message is made at. Ask this list whether you can send somewhere, and what it takes first. A country missing from it is one this sender has no route to at all, so no registration would open it.
- `data.sender_id` (string, required): The sender these requirements are for, the same one you asked about. It is repeated on every row so a row is complete on its own: what a country needs is addressed by the sender and the country together, and a step that registers this sender needs both.
- `data.country_code` (string, required)
- `data.registration_mode` (string, required): Whether country registration is absent, optional, or required before sending.
- `data.sender_id_behavior` (string, required): The effective sender ID behavior for this sender and destination. An approved optional registration changes `overwritten` to `preserved` for its permitted message categories. Required registration does not change the configured sender ID behavior after approval. `unknown` means no behavior is published. This is expected behavior, not confirmation of what a recipient saw. Overwrite details are published in the country messaging context.
- `data.program` (nullable string): The registration program available for this destination, including optional registration. An existing registration retains its own program.
- `data.status` (string, required)

  Where this sender stands with this country's registration programme. The `approved` and `not_required` statuses satisfy it. Every other status leaves it unsatisfied: the `registration_required` status means the required registration has not started, the `pending` status means something required is still owed by you, and `under_review` means it is all with us. Read `next` for what to do about any of it.

  Registration blocks sending when `registration_mode` is `required`. Optional registration can be pending while sending remains available with `sender_id_behavior` set to `overwritten`. Check `destination_enabled` too, which is independent of registration progress.
- `data.next` (array of object)

  What to do next about this country, given the state it is in. Each entry names one action
  and says why it is worth taking, so you can act on this response without working out the
  order yourself. Present on reads that compute it: an empty list means there is nothing to
  do, and the field is absent entirely on responses that do not report next actions.

  This routes rather than advises: it names where to go to act on this country, and the
  resource it names carries what to do there. So a country under carrier review names the
  verification to read, rather than restating a verdict that resource owns.
- `data.next.kind` (string, required)

  What you do about this step.

  - `operation`: call the operation named in `operation`, then
    read again.
  - `external`: act somewhere this API does not reach, then read
    again.
  - `wait`: nothing is asked of you, so read again later.
  - `terminal`: nothing you do resolves this, so stop retrying.

  Tolerate a value you do not recognize: show the `description` and
  offer no action.

  Possible values (may grow over time): `operation`, `external`, `wait`, `terminal`
- `data.next.description` (string, required): A short, human-readable label for the step, suitable for display.
- `data.next.operation` (string): The operationId to call. Present only when `kind` is `operation`. The operation's own schema says how to call it; this says only which one, and what to address it with.
- `data.next.params` (object): The parameters that address the operation, by name: `{"sender_id": "…"}` for an operation on `/v1/sms/senders/{sender_id}/requirements`. A parameter the operation takes in its query string is given the same way, so an operation addressed as `?subject_id=` carries `{"subject_id": "…"}`. Every parameter the call needs is here, whether its value came from the thing you were acting on or is fixed for this step, so you can make the call from this object alone. Present only when `kind` is `operation` and the operation names a subject. A request body, when the operation takes one, is described by the operation's own schema and never appears here.
- `data.next.url` (string): A URL to open. Present only when `kind` is `external`, and only when the step has one. An external step whose `description` says to go and do something with no URL to open is normal.
- `data.destination_enabled` (boolean, required): Whether your workspace has this destination country turned on. This is a workspace setting rather than anything about this sender, and it is checked before the sender is even considered, so a country can be fully registered and still refuse your messages because it is switched off here. Turn it on with [Update SMS destinations](/docs/api/reference/update-workspace-sms-destinations).
- `data.has_compliance_requirements` (boolean, required): Whether registering this sender for this country continues at compliance requirements you answer with a submission. When true, read them with [Get what a registration needs](/docs/api/reference/get-workspace-compliance-requirements) once the registration exists; the one-off setup fee is charged when you submit, and the monthly charge starts once the registration is approved. False in three cases: the country takes no registration (`registration_mode` is `none`); its programme runs its own flow, such as US 10DLC, toll-free, and short codes, which `next` routes to; or the registration goes to review with nothing to submit, and both charges are made once it is approved.
- `data.category` (nullable string)

  Message category the registration covering this country is approved for. Null when the registration admits any category, and null before you register.

  Possible values (may grow over time): `transactional`, `marketing`, `authentication`, `service`
- `data.registration_id` (nullable string): The registration covering this country, once one exists. Null before you register. Where the country's requirements are collected as a form, this is the `subject_id` to pass to `GET /v1/compliance/requirements`.
- `data.program_entry` (string, required)

  The resource this country's walk continues at. `none` means the first one is still to be
  created; every other value names what to read next, whose id is `program_entry_ref`.

  Every programme names its entry. US 10DLC enters at a `10dlc_brand` or a `10dlc_campaign` and
  continues at the `10dlc_campaign_number_link` a number hangs off. US toll-free both enters and
  continues at its `tfn_verification`. A programme answered by filling in a form enters at the
  `compliance_submission` holding your answers, the only entry that names something you filled in
  rather than something a carrier holds. Read the entry whenever you need the detail behind a
  country: it carries why a registration was refused, which this row reports only as a status.

  The values are programme-prefixed where a programme owns them, so one vocabulary reads the same
  wherever an entry is reported. Tolerate a value you do not recognize: read `program_entry_ref`
  as the id of a resource to fetch, and read `next` for what to do about the country.

  Computed on this read, so it is never stale and never absent. That matters most where a row
  cannot answer for itself: a toll-free verification you have started but not submitted is named
  here even though no registration exists for it yet, which is what tells you to finish that one
  rather than start a second.

  Possible values (may grow over time): `none`, `10dlc_brand`, `10dlc_campaign`, `10dlc_campaign_number_link`, `tfn_verification`, `compliance_submission`
- `data.program_entry_ref` (nullable string): The id of the resource `program_entry` names, or null when it names none. Where the workspace holds several to choose from, this is the one to start from: the only brand or campaign if there is one, otherwise the most recently approved, and otherwise the most recent.
- `data.rejection_reason` (nullable string): Why the registration was rejected, when it was. Null otherwise.
- `data.obligation_due_at` (nullable string): When this country's registration must be brought up to date by, if it must. Null when nothing is outstanding, which is the ordinary case. The sender keeps sending until the date passes; `GET /v1/compliance/requirements` says what is being asked for.
- `data.timeline_min_days` (nullable integer): Shortest time approval usually takes, in business days. Null when the country publishes no estimate.
- `data.timeline_max_days` (nullable integer): Longest time approval usually takes, in business days. Null when the country publishes no estimate.
- `data.registration_types` (array of string): Registration categories this country's program accepts.
- `programs` (array of object, required): The same countries seen as the registrations they belong to, one entry per registration, with the countries each one covers. Ask this list what to do next: an entry whose status is `registration_required` is a registration you still have to make, and its countries are the ones it would open. Every other entry is a registration you have already made, so this list is the whole picture rather than only the part you have finished.
- `programs.program` (nullable string, required): The program this registration runs. Null for the countries that asked for no registration at all, which are grouped together because the only thing they have in common is that you registered nothing for them.
- `programs.program_ref` (nullable string, required): The resource this registration produced, which `program` tells you how to read: a toll-free verification for `tfn`, or a campaign number link for `10dlc`. The link connects this number to its campaign. Get the campaign from `GET /v1/sms/10dlc/campaign-number-links/{link_id}`. Null for a program that issues none, and for one you have not registered yet. Follow it when the status is under_review, because only that resource distinguishes a carrier still reviewing from one waiting on more information from you.
- `programs.countries` (array of string, required): Every country this one registration covers. Some programs open several at once, so a single toll-free verification or campaign registration can be what permits four destinations.
- `programs.status` (nullable string, required): Where this registration stands, for all of the countries it covers. `registration_required` means you have not made it yet and every country listed is waiting on it. Null in the one case where the countries have diverged and no single answer is true: read those countries individually.

## 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)