Sign inGet Started
Aan de slag
Gidsen
API Reference
SDK's
CLI
Kennisbank
Changelog

List what a sender needs to send

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

Parameters

sender_idstring

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

Queryparameters

country_codestring

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

Response Payload

data
array of object
verplicht

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.

Onderliggende attributen tonen
data.sender_id
string
verplicht

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

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

data.sender_id_behavior
string
verplicht

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
verplicht

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.

Onderliggende attributen tonen
data.next.kind
string
verplicht

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
verplicht

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
verplicht

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
verplicht

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
verplicht

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
verplicht

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.

Onderliggende attributen tonen

Gerelateerde bronnen

Ga verder met de documentatie, handleidingen en voorbeelden voor dit onderwerp.

Ontvang een implementatieoverzicht