Sign inGet Started
Inizia ora
Guide
Riferimento API
SDK
CLI
Knowledge Base
Changelog

List what a sender needs to send

GET
/v1/sms/senders/{sender_id}/requirements
await bird.smsSenderRequirements.list("snd_01krdgeqcxet5s7t44vh8rt9mg");
Risposta200
{
  "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"
    }
  ]
}

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.

Parametri

sender_idstring

ID of the SMS sender (snd_ prefix), as returned when the sender was created.

Parametri di query

country_codestring

Ask about one destination country. Omit to return every country relevant to the sender.

Payload di risposta

data
array of object
obbligatorio

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.

Mostra attributi secondari
data.sender_id
string
obbligatorio

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
obbligatorio
data.registration_mode
string
obbligatorio

Whether country registration is absent, optional, or required before sending.

data.sender_id_behavior
string
obbligatorio

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
obbligatorio

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.

Mostra attributi secondari
data.destination_enabled
boolean
obbligatorio

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.

data.has_compliance_requirements
boolean
obbligatorio

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 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
obbligatorio

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
obbligatorio

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.

Mostra attributi secondari

Risorse correlate

Continua con la documentazione, le guide e gli esempi per questo argomento.

Ottieni un brief di implementazione