Sign inGet Started
Get started
Guides
API Reference
SDKs
CLI
Knowledge Base
Changelog

Create a sender registration for a country

POST
/v1/sms/senders/{sender_id}/registrations
await bird.smsSenderRegistrations.create("snd_01krdgeqcxet5s7t44vh8rt9mg", {country_code: "NL"});
Response201
{
  "id": "scr_01krdgeqcxet5s7t44vh8rt9mg",
  "country_code": "US",
  "registration_mode": "none",
  "sender_id_behavior": "unknown",
  "program": "10dlc",
  "category": "transactional",
  "status": "pending"
}

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.

Parameters

sender_idstring

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

Request Payload

country_code
string
required

ISO 3166-1 alpha-2 country code.

category
string

Message category to register the sender for. Omit to register the sender for all categories.

Possible values: transactional, marketing, authentication, service

Response Payload

id
string
required

Identifier of this country registration.

country_code
string
required

ISO 3166-1 alpha-2 country code.

registration_mode
string

Current registration policy for this destination and sender type. Omitted if the policy or sender is no longer available.

Possible values: none, optional, required

sender_id_behavior
string

Expected sender ID behavior for this registration's message categories. Optional registration preserves the sender ID once approved. Required registration can still use an overwritten sender ID after approval. Omitted if the policy or sender is no longer available.

Possible values: unknown, preserved, overwritten

program
nullable string

The registration program behind this row. Null for a country that required none, which is the state a row records rather than a program called "none".

category
nullable string

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

Possible values (may grow over time): transactional, marketing, authentication, service

status
string
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.

Possible values (may grow over time): pending, under_review, bird_approved, carrier_pending, approved, rejected, suspended, registration_required, not_required

program_ref
nullable string

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_reason
nullable string

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

created_at
string
required
updated_at
string
required

Related resources

Continue with the documentation, guides and examples for this topic.

Get an implementation brief