---
title: "Create a sender registration for a country"
canonical: "https://bird.com/docs/api/reference/create-workspace-sms-sender-registration"
---

# Create a sender registration for a country

`POST /v1/sms/senders/{sender_id}/registrations`

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

## Code samples

**TypeScript**

```ts
await bird.smsSenderRegistrations.create("snd_01krdgeqcxet5s7t44vh8rt9mg", {country_code: "NL"});
```

Examples: [TypeScript](/docs/api/reference/create-workspace-sms-sender-registration.ts.md) · [Python](/docs/api/reference/create-workspace-sms-sender-registration.py.md) · [Go](/docs/api/reference/create-workspace-sms-sender-registration.go.md) · [PHP](/docs/api/reference/create-workspace-sms-sender-registration.php.md) · [CLI](/docs/api/reference/create-workspace-sms-sender-registration.cli.md) · [MCP](/docs/api/reference/create-workspace-sms-sender-registration.mcp.md) · [cURL](/docs/api/reference/create-workspace-sms-sender-registration.curl.md)

## Example response `201`

```json
{
  "id": "scr_01krdgeqcxet5s7t44vh8rt9mg",
  "country_code": "US",
  "registration_mode": "none",
  "sender_id_behavior": "unknown",
  "program": "10dlc",
  "category": "transactional",
  "status": "pending"
}
```

## Path parameters

- `sender_id` (string): ID of the SMS sender (`snd_` prefix), as returned when the sender was created.

## Request body

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

## Response body

- `id` (string, required): Identifier of this country registration.
- `country_code` (string, required)
- `registration_mode` (string): Current registration policy for this destination and sender type. Omitted if the policy or sender is no longer available.
- `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.
- `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)
- `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](/docs/api/reference/get-tcr-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

- [Should I use a Bird SDK or call the API directly?](/explained/platform/should-i-use-an-sdk-or-call-the-api-directly) (answer)
- [Build your first integration](/learn/paths/integration) (course)
- [Send your first email](/docs/get-started/send-your-first-email) (docs)

[Get an implementation brief](/learn/workspace?topic=api-basics)