# SMS sender IDs

A sender is the `from` a recipient sees on your SMS. Your workspace holds one sender per identity it can send from, and each destination country decides which kinds of sender it accepts and what it wants registered first. Holding a sender is not the same as being allowed to send from it: the two are separate steps, and this guide covers both.

Senders live on the [**Senders**](https://bird.com/dashboard/w/sms/senders) page, one row per sender, with its status and how many destinations are active, pending, or need your attention. The send call itself, including how a `from` value is validated, is in [Sending SMS](/docs/guides/sms/sending-sms#sender).

## Sender types

A sender's `sender_type` is the kind of identity it is, and it decides what each country asks of it:

- **Alphanumeric sender ID**: a short brand string such as `BIRD`, 1 to 11 letters, digits, spaces, dashes, or underscores, with at least one letter. Recipients see your name instead of a number and cannot reply to it. Many countries want it registered before it carries traffic, and some, including the United States, do not accept one at all. You claim this kind yourself.
- **Long code**: an ordinary number you hold, which can send and receive. A US long code needs a registered brand and campaign before it carries application-to-person traffic; see [10DLC registration](/docs/guides/sms/10dlc).
- **Toll-free number**: a number the called party pays for, which in North America can also carry messaging. Sending from one there means completing toll-free verification first.
- **Short code**: four to six digits with the highest messaging throughput in North America. Bird allocates short codes rather than selling them, so this kind is not self-serve.

A sender also reports `source_kind`, which says what backs it: `alpha` for a sender string you claimed, `number` for a dedicated number you hold, and `shared_number` for a Bird-managed number your workspace sends from. The dashboard labels these **Alphanumeric**, **Dedicated number**, and **Shared number**. [Number types](/docs/guides/numbers/number-types) covers how a number's own type is chosen, and [Buy and release a number](/docs/guides/numbers/buying-numbers) covers allocating one.

Which kinds a country accepts, and whether it reviews them, shifts as carriers and regulators revise their rules. [SMS destinations](/products/sms/destinations) publishes the current position per country; read it there rather than assuming a country behaves like its neighbors.

## Claim an alphanumeric sender ID

Claiming a sender string costs nothing and takes effect immediately. On the [**Senders**](https://bird.com/dashboard/w/sms/senders) page, open **Add sender** and choose **Add sender ID**, then enter the string. Over the API:

```cli
bird sms senders create --type alpha --sender BIRD
```

The response carries the new sender's `id`, prefixed `snd_`, and every other operation in this guide takes that id. A successful claim leaves the sender able to reach the countries that ask for no registration, once those destinations are enabled on your workspace; everywhere else it needs a registration first.

Two refusals come up here. A `412` means your organization has not finished the identity verification this operation requires: complete it in [**Identity Center**](https://bird.com/dashboard/w/trust), then retry. A `409` means the sender string is already claimed.

`alpha` is the only kind this call creates. A dedicated number becomes a sender when you allocate it from inventory, so buying the number brings its sender with it. Short codes and shared numbers reach a workspace by allocation from Bird rather than by purchase.

## Check what a country requires

One read answers what each country asks of a sender. It returns a row per country the sender can reach, and each row is complete on its own:

```cli
bird sms senders requirements snd_01krdgeqcxet5s7t44vh8rt9mg
bird sms senders requirements snd_01krdgeqcxet5s7t44vh8rt9mg --country-code NL
```

Omit `--country-code` for every country relevant to the sender. An empty filtered result means the sender has no route to that country.

Read four fields on a row before you send:

- **`required`** says whether the country needs a registration before this sender can send there. `false` means you can send today, either because the country asks for none or because it stopped asking while you already held one.
- **`status`** says where the sender stands with the country's registration program. The `approved` and `not_required` values satisfy it; every other value leaves it unsatisfied. [Registration statuses](#registration-statuses) lists each one.
- **`destination_enabled`** says whether your workspace has that country turned on. This is a workspace setting rather than anything about the sender, and it is checked first, so a fully approved registration still refuses messages while the destination is off. Turn countries on under [**Destinations**](https://bird.com/dashboard/w/sms/destinations); [Sending SMS](/docs/guides/sms/sending-sms#before-you-send-enable-the-destination-country) covers the allowlist.
- **`next`** lists what advances that country, in order. An empty list means nothing is outstanding. Each entry names one action and says why it is worth taking, so a country under carrier review names the resource to read instead of restating a verdict that resource owns.

Rows also carry `timeline_min_days` and `timeline_max_days`, the shortest and longest a country's approval usually takes in business days, and `null` where the country publishes no estimate. Where a registration was refused, `rejection_reason` says why.

The same information is on each sender's detail page in the dashboard, as a **Destinations** table with a **Status**, **Country**, and **Category** column. A country you have not switched on and have not registered for is left out of that table, because nothing is outstanding there.

## Register a sender for a country

Registration is per country, and the call takes the sender and the country together:

```cli
bird sms senders registrations create snd_01krdgeqcxet5s7t44vh8rt9mg --country-code NL
bird sms senders registrations create snd_01krdgeqcxet5s7t44vh8rt9mg --country-code NL --category marketing
```

`--category` restricts the registration to one of `transactional`, `marketing`, `authentication`, or `service`. Omit it to register for every category. The dashboard runs the same call from the **Register** button on the sender's country row.

What happens next depends on the country. Where the country reviews registrations, the record comes back `pending` and nothing is charged yet. Where the country reviews nothing, it is approved on this call. Registering a number is free; a priced alphanumeric sender carries a setup fee and a recurring monthly charge, billed at the moment the registration is approved, so a reviewed registration is created unbilled. Neither this call nor the requirements read quotes a price, so ask whoever owns the account what a registration costs before you make it.

Where a program collects your answers as a form, the registration sits at `pending` until you fill it in. The sender's country row then offers **Complete**, which opens the questions that program asks about your business and your messaging.

Four refusals to handle:

| Response | What it means                                                                                                                                                                                       |
| :------- | :-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `402`    | The wallet could not cover what was owed when billing ran. Top up, then retry.                                                                                                                      |
| `409`    | A registration for this country already exists in some state other than rejected or suspended, including one still `pending` review. This does not mean the sender can send there: read its status. |
| `412`    | Your organization has an unmet identity-verification requirement. Complete it in [**Identity Center**](https://bird.com/dashboard/w/trust), then retry.                                             |
| `422`    | The sender is covered by a program with its own path, such as US 10DLC, toll-free verification, or a short code. See [Programs with their own path](#programs-with-their-own-path).                 |

A rejected registration is resubmitted, and a suspended one reactivated, by calling this same operation again rather than by a separate one.

## Registration statuses

A country registration moves through the states below. The dashboard shows each as a sentence-case label on the sender's row:

| Status                  | What it means and what to do                                                                                                                                                                                  |
| :---------------------- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `registration_required` | No required registration has started. Register the sender for the country.                                                                                                                                    |
| `pending`               | Registration work has started. Where the program asks for a form, finish it from **Complete** on the country's row.                                                                                           |
| `under_review`          | Submitted information is being reviewed, or it needs changes. The row's `program_ref` points at the program's own resource, the only place a review still running is distinguishable from one waiting on you. |
| `bird_approved`         | Bird's review passed and carrier approval is outstanding. Nothing is asked of you.                                                                                                                            |
| `carrier_pending`       | Submitted to the approving carrier or registry. Nothing is asked of you.                                                                                                                                      |
| `approved`              | Approved for sending.                                                                                                                                                                                         |
| `rejected`              | The registration was refused. Read `rejection_reason`, correct it, and register again from **Resubmit**.                                                                                                      |
| `suspended`             | A previously active registration is suspended. Register again from **Register again** to reactivate it.                                                                                                       |
| `not_required`          | The country requires no registration.                                                                                                                                                                         |

New statuses are added as registration programs change, so treat an unfamiliar value as one your code does not handle yet rather than as an error, and read the row's `next` for what to do about the country.

Some programs open several countries with one registration, so a single toll-free verification or campaign registration can be what permits several destinations.

## Sender status and next actions

A sender's own `status` covers what the sender holds, which is a different question from whether a given country will accept a message:

- **`active`**: nothing this sender holds is outstanding. A sender that has registered nowhere reads `active`, even where every country it can reach wants a registration first.
- **`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 is settled. [Numbers overview](/docs/guides/numbers/overview#the-status-of-an-allocated-number) covers that lifecycle.
- **`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.

Alongside it, `destinations` groups the countries the sender is set up for by whose move is next, and the [**Senders**](https://bird.com/dashboard/w/sms/senders) list shows the three groups as columns:

- **Active**: countries you can send to today, switched on in your destination settings and either asking for no registration or holding an approved one.
- **Pending**: countries whose registration is under way and waiting on Bird or on a carrier. Nothing is asked of you; these move to **Active** on approval.
- **Needs attention**: countries you have registered for that are not working and are waiting on you, because the registration was refused or withdrawn, or because it is approved while the destination is switched off.

These three groups cover only countries you hold a registration for, so a country you could register for and have not appears in none of them. For everything the sender can reach and what each country would take, read [what a country requires](#check-what-a-country-requires).

A sender read that computes next actions returns them in `next`, the same routing field the requirement rows carry. A sender only knows about itself, so where the work is per country it names the requirements read rather than guessing which country you meant.

## Programs with their own path

A country's `program` names the registration scheme it runs for a sender type. Two of them are answered by the registration call in this guide, and three have their own path:

| Program           | What it applies to        | Where it happens                                                                                                      |
| :---------------- | :------------------------ | :-------------------------------------------------------------------------------------------------------------------- |
| `alpha`           | an alphanumeric sender ID | [Register a sender for a country](#register-a-sender-for-a-country), plus the form the country asks for               |
| `numeric`         | a long code               | [Register a sender for a country](#register-a-sender-for-a-country), plus the form the country asks for               |
| `10dlc`           | a US long code            | Register a brand and campaign, then link the number: [10DLC registration](/docs/guides/sms/10dlc)                     |
| `tfn`             | a US toll-free number     | Toll-free verification, on the [**Toll-free verifications**](https://bird.com/dashboard/w/sms/tfn-verifications) page |
| `ctia_short_code` | a US short code           | Bird manages the application; no action is asked of you                                                               |

Calling the registration operation for a sender covered by `10dlc`, `tfn`, or `ctia_short_code` returns `422`. Use the program instead.

Toll-free verification starts as a draft you fill in over one or more updates, then submit for the carrier to review. It moves through `draft`, `submitted`, `under_review`, `info_requested`, `approved`, and `rejected`. A verification at `info_requested` can be edited and resubmitted; a rejected one can be resubmitted while its resubmission window is open. Submitting hands the dossier to the carrier for a non-refundable fee, so a person authorizes that step: the CLI and Bird's MCP server can draft and correct a verification, and the submit itself happens in the dashboard.

## Stop sending from a sender

Three teardowns differ in what they keep, and all three are dashboard actions on the sender's detail page. Setup fees already charged are not refunded by any of them:

| Action                    | What it does                                                                                                                                                                                                                                                                                                      |
| :------------------------ | :---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Deregister** a country  | Cancels the recurring charge and keeps the registration. Registering that country again resumes the same registration without paying the setup fee twice. Where the country requires a registration, sends there stop; where registration is optional, sends continue, because the registration never gated them. |
| **Remove** a registration | Removes the country registration entirely, cancels the recurring charge, and stops listing the destination for the sender. Registering the country again is a new registration and pays the setup fee again.                                                                                                      |
| Delete the sender         | Releases an alphanumeric sender. Every country registration on it is removed, its recurring charge is canceled, and it stops being usable. Claiming the same string later creates a new sender with new registrations, and pays the setup fees a second time.                                                     |

A sender backed by a number is not deleted here: release the dedicated number instead, which tears down its sender with it. A sender on a Bird-managed shared number cannot be removed.

A 10DLC or toll-free row is undone through its own program, by unlinking the campaign or canceling the verification, rather than by deregistering.

## Next steps

| Page                                                            | What it covers                                                              |
| --------------------------------------------------------------- | --------------------------------------------------------------------------- |
| [Sending SMS](/docs/guides/sms/sending-sms)                     | The send call, the `from` formats it accepts, and the destination allowlist |
| [10DLC registration](/docs/guides/sms/10dlc)                    | The brand, campaign, and number model behind US A2P sending                 |
| [Number types](/docs/guides/numbers/number-types)               | Choosing between mobile, local, national, toll-free, and short-code numbers |
| [SMS destinations](/products/sms/destinations)                  | Which sender kinds each country accepts and which of them need registration |
| [Opt-outs and keywords](/docs/guides/sms/opt-outs-and-keywords) | The keyword replies a sender has to honor and the suppressions they create  |