---
title: "List what a sender needs to send"
method: GET
path: "/v1/sms/senders/{sender_id}/requirements"
tags: ["sms-senders"]
---

# List what a sender needs to send

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

## Request

- Base URL: `https://us1.platform.bird.com`
- URL: `https://us1.platform.bird.com/v1/sms/senders/{sender_id}/requirements`
- Auth: one of:
  - HTTP bearer
  - API key in cookie `bird_session`

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.

## Query parameters

- `country_code` string: ISO 3166-1 alpha-2 country code.

## Headers

- `X-Workspace-Id` string
- `X-Organization-Id` string

## Response `200`

What this sender needs, per country.

- SMSSenderRequirementList
  - `data` SMSSenderRequirement[], 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.
    - `sender_id` string, required
    - `country_code` string, required: ISO 3166-1 alpha-2 country code.
    - `registration_mode` 'none' | 'optional' | 'required', required: Whether the sender type has a registration path for this destination. - `none`: no country registration is needed. Where sender IDs are overwritten, registration is unavailable. - `optional`: registration is available, but unregistered sending remains possible. - `required`: registration must be approved before sending.
    - `sender_id_behavior` 'unknown' | 'preserved' | 'overwritten', required: What carriers do with the sender ID for this destination. - `unknown`: the outcome has not been confirmed. - `preserved`: the submitted sender ID reaches the recipient unchanged. - `overwritten`: the submitted sender ID is overwritten before delivery.
    - `program` string: The registration program a country runs for a sender type. - `10dlc`: US A2P brand and campaign registration. - `tfn`: US toll-free verification. - `alpha`: registers an alphanumeric sender. - `numeric`: registers a long code. - `short_code`: a short-code application, filed and maintained by Bird.
    - `status` string, required: Country-registration lifecycle state: - `pending`: Registration work has started. - `under_review`: Everything this country requires has been submitted and is being reviewed. Nothing is asked of you while it is. - `bird_approved`: Our review passed and carrier approval is still pending. - `carrier_pending`: Submitted to the approving carrier or registry. - `approved`: Approved for sending. - `rejected`: Registration was refused. - `suspended`: A previously active registration is suspended. - `registration_required`: No required registration has been started. - `not_required`: The country does not require registration.
    - `next` NextAction[]: 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.
      - `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.
      - `description` string, required: A short, human-readable label for the step, suitable for display.
      - `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.
      - `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.
      - `url` string, uri: 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.
    - `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).
    - `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.
    - `category` string, nullable: Message category the registration covering this country is approved for. Null when the registration admits any category, and null before you register.
    - `registration_id` string
    - `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.
    - `program_entry_ref` string, nullable: 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.
    - `rejection_reason` string, nullable: Why the registration was rejected, when it was. Null otherwise.
    - `obligation_due_at` string, date-time, nullable: 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.
    - `timeline_min_days` integer, nullable: Shortest time approval usually takes, in business days. Null when the country publishes no estimate.
    - `timeline_max_days` integer, nullable: Longest time approval usually takes, in business days. Null when the country publishes no estimate.
    - `registration_types` string[]: Registration categories this country's program accepts.
  - `programs` SMSSenderProgram[], 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.
    - `program` string, required: The registration program a country runs for a sender type. - `10dlc`: US A2P brand and campaign registration. - `tfn`: US toll-free verification. - `alpha`: registers an alphanumeric sender. - `numeric`: registers a long code. - `short_code`: a short-code application, filed and maintained by Bird.
    - `program_ref` string, nullable, 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.
    - `countries` CountryCode[], 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.
    - `status` string, required: Country-registration lifecycle state: - `pending`: Registration work has started. - `under_review`: Everything this country requires has been submitted and is being reviewed. Nothing is asked of you while it is. - `bird_approved`: Our review passed and carrier approval is still pending. - `carrier_pending`: Submitted to the approving carrier or registry. - `approved`: Approved for sending. - `rejected`: Registration was refused. - `suspended`: A previously active registration is suspended. - `registration_required`: No required registration has been started. - `not_required`: The country does not require registration.

## Other responses

- `400`: Bad request
- `401`: Authentication required
- `403`: Insufficient permissions
- `404`: Resource not found
- `422`: The request has invalid field values, violates a business rule, or carries a query parameter the endpoint does not declare. Field validation errors use `type: validation_error` and include the affected fields in `details`. Business-rule errors identify the failed rule in `type`.
- `429`: Rate limit exceeded
- `500`: Internal server error

## Changes

- **2026-10-20** `a1977645a499`: 1 info
  - endpoint added
- **2026-10-20** `6cec81ac4862`: 1 breaking
  - api path removed without deprecation
- **2026-10-20** `3e2a50466454`: 1 info
  - endpoint added

[Operation history](https://skmtc.dev/messagebird/apis/bird-api/changes/v1/sms/senders/:sender_id/requirements/get.md)

---

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