sms-senders

Get an SMS sender

Changed on

Returns one of your workspace's SMS senders with its per-country registration status.

get/v1/sms/senders/{sender_id}

Request

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

Headers

X-Workspace-Idstring

Workspace context for the request. Required for dashboard authentication and master keys. Workspace keys and access tokens already identify their workspace; send that workspace or omit the header. A different one is rejected.

X-Organization-Idstring

Organization context for the request. Required for dashboard authentication. An API key or access token carries its own organization, so send either that organization or no header at all; a different one is rejected.

Response

The requested sender with its registrations.

idstring required
senderstring required

The value messages are sent from: a number in E.164 format, a shortcode, or an alphanumeric sender string.

source_kindstring required

What backs an SMS sender: a dedicated number, a shared shortcode, or an alphanumeric sender string.

sender_type'long_code' | 'short_code' | 'alphanumeric' | 'toll_free'

The kind of sender identity a message was sent from: a standard long-code number, a short code, an alphanumeric sender ID, or a toll-free number. Toll-free is its own value rather than a kind of long code, because it carries a separate regulatory regime and both sending policy and pricing key on it directly.

country_codestring

ISO 3166-1 alpha-2 country code.

number_idstring

Identifier of a number allocated to your workspace, as returned in the id field of GET /v1/numbers.

status'active' | 'pending_number_ownership' | 'pending_registrations' required

Where a sender stands on its own setup: the ownership paperwork its number owes, and the registrations it holds.

  • active: nothing this sender holds is outstanding.
  • pending_number_ownership: the paperwork proving you own this sender's number is not in place, either because it has not been supplied or because the country that issued the number has not accepted it yet. Every send from this sender is refused until it does.
  • pending_registrations: the sender holds country registrations and none is approved yet. That covers a registration under review and one that was refused, so read next for which.

This is not whether a message will be accepted. That is decided per destination country, and Get sender requirements is the only read that answers it. A sender that has registered nowhere is active, even where every country it can reach wants a registration first. Read next for where to go from here.

created_atstring date-time required
updated_atstring date-time required

Example response

{
  "id": "snd_01krdgeqcxet5s7t44vh8rt9mg",
  "country_code": "US",
  "number_id": "nda_01krdgeqcxet5s7t44vh8rt9mg",
  "destinations": {
    "active": [
      "US"
    ],
    "pending": [
      "US"
    ],
    "needs_attention": [
      "US"
    ]
  }
}

Changes