--- title: "Create a sender registration for a country" method: POST path: "/v1/sms/senders/{sender_id}/registrations" tags: ["sms-senders"] --- # Create a sender registration for a country `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` 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`. ## Headers - `Idempotency-Key` string - `X-Workspace-Id` string - `X-Organization-Id` string ## Request body - SMSCountryRegistrationCreate - `country_code` string, 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. ## Response `201` The sender's new country registration. - SMSCountryRegistration - `id` string, required - `country_code` string, 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. - `program` string: 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. - `category` string, nullable: Message category this registration is approved for. Null means the registration is unrestricted and admits any category. - `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. - `program_ref` string, 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](/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` string, nullable: Reason the registration was rejected, shown when the status is `rejected`. Null for registrations that were never rejected. - `created_at` string, date-time, required - `updated_at` string, date-time, required ## Other responses - `400`: Bad request - `401`: Authentication required - `402`: Insufficient balance - `403`: Insufficient permissions - `404`: Resource not found - `409`: Resource conflict - `412`: Precondition failed - `422`: The request has invalid field values, violates a business rule, or carries a query parameter the endpoint does not declare. Field validation errors use `type: validation_error` and include the affected fields in `details`. Business-rule errors identify the failed rule in `type`. - `429`: Rate limit exceeded - `500`: Internal server error - `503`: The service is temporarily unavailable. If `Retry-After` is present, wait for that delay before retrying; otherwise, retry with exponential backoff. Reuse the same idempotency key and request when retrying a mutation. ## Changes - **2026-10-20** `7fc2ff366468`: 11 info - added the optional property `error/quota` to the response with the `400` status - added the optional property `error/quota` to the response with the `401` status - added the optional property `error/quota` to the response with the `402` status - added the optional property `error/quota` to the response with the `403` status - …7 more - **2026-10-20** `a1977645a499`: 1 info - endpoint added - **2026-10-20** `6cec81ac4862`: 1 breaking - api path removed without deprecation - **2026-10-20** `3e2a50466454`: 1 info - endpoint added [Operation history](https://skmtc.dev/messagebird/apis/bird-api/changes/v1/sms/senders/:sender_id/registrations/post.md) --- [API](https://skmtc.dev/messagebird/apis/bird-api.md) · [All operations](https://skmtc.dev/messagebird/apis/bird-api/llms.txt) · [OpenAPI document](https://skmtc.dev/messagebird/apis/bird-api/revisions/7fc2ff366468?raw)