sms-senders

Create an SMS sender

Changed on

Claims an alphanumeric sender string for your workspace. Country and sender-type policies determine whether registration is unavailable, optional, or required before sending.

post/v1/sms/senders

Request

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

Headers

Idempotency-Keystring

Client-supplied key. On operations supporting request deduplication, a retained response is replayed for duplicate requests with the same key within the idempotency window (3 hours by default). This protection requires a workspace, organization, or staff-account scope. User-only and unscoped unauthenticated operations, streams, and operations with a separate replay contract do not use this response replay.

On a supported operation, if idempotency protection is unavailable before execution, the API returns 503 IdempotencyUnavailable (E01033) without executing this attempt. Retry with backoff using the same key and request. An operation that takes effect before its response is retained can still execute again on retry.

Two distinct 409 errors signal misuse:

  • request_in_progress (E01004): The same key is currently being processed by a concurrent request. Wait briefly and retry. The lock expires within 30 seconds.
  • idempotency_key_reuse (E01005): The same key has already completed against a different request body or method. Generate a new key.

Recommended key format is <event-type>/<entity-id> (for example welcome-user/usr_abc123).

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.

Request body

type'alpha' required

The kind of sender to create. Only alpha (an alphanumeric sender string) is customer-creatable. Dedicated numbers become senders when you allocate them from inventory. This endpoint cannot create their senders.

senderstring required

The alphanumeric sender string to create, for example "BIRD". 3–11 letters, digits, spaces, dashes, underscores, or dots, at least one of them a letter, and no separator at either end.

Example request

{
  "sender": "BIRD"
}

Response

The claimed sender.

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