sms-senders

Create a sender registration for a country

Changed on

Registers a sender for a destination country. If the country requires review, the sender can send there after approval. If registration is optional, it takes effect immediately and records the intended message category.

A priced alphanumeric sender incurs a setup fee and a recurring monthly charge, and needs enough balance for both when it is billed: on this call where the country approves immediately, or on approval where the country reviews, so a reviewed registration is created unbilled. Insufficient balance at that moment returns 402. Registering a number is free. A 412 means required identity verification is incomplete or organization eligibility prevents registration. Follow the error's recovery guidance: complete missing verification, or contact support about an eligibility review or denial. An eligibility assessment still in progress returns 503; retry later. A registration that already exists for the country and is neither rejected nor suspended returns 409, and that includes one still pending review; a rejected registration is resubmitted, and a suspended one reactivated, by calling this again.

A sender covered by a dedicated program, such as a US 10DLC campaign or toll-free verification, returns 422 and must use that program instead. Short-code registrations are ones we manage, and they also return 422.

post/v1/sms/senders/{sender_id}/registrations

Request

  • Base URL: https://us1.platform.bird.com
  • URL: https://us1.platform.bird.com/v1/sms/senders/{sender_id}/registrations
  • 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

country_codestring required

ISO 3166-1 alpha-2 country code.

category'transactional' | 'marketing' | 'authentication' | 'service'

Content classification: why you are sending. Carriers see it, and where a destination country requires the sender to be registered, that registration is approved for a category: a send outside what it covers returns a 422 SenderCategoryNotPermitted. A registration approved for marketing covers all four values; one approved for transactional, authentication, or service covers those three and not marketing. Use authentication for a one-time passcode and marketing for a promotion; otherwise pick the value matching the message's purpose.

Example request

{
  "country_code": "US"
}

Response

The sender's new country registration.

idstring required
country_codestring required

ISO 3166-1 alpha-2 country code.

registration_mode'none' | 'optional' | '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'

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.
programstring

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.
categorystring nullable

Message category this registration is approved for. Null means the registration is unrestricted and admits any category.

statusstring 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.
program_refstring nullable

The program artifact that decided this registration, null where none produced it. Which resource it names follows from program, and its id prefix tells you too: 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 a 10DLC campaign number link. Worth following when the status is under_review, because that value covers both the carrier still reviewing and the carrier waiting on more information from you, and only the program's own resource tells those apart.

rejection_reasonstring nullable

Reason the registration was rejected, shown when the status is rejected. Null for registrations that were never rejected.

created_atstring date-time required
updated_atstring date-time required

Example response

{
  "id": "scr_01krdgeqcxet5s7t44vh8rt9mg",
  "country_code": "US"
}

Changes