> ## Documentation Index
> Fetch the complete documentation index at: https://docs.orbit.devotel.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Sender-ID Registration

> Register alphanumeric Sender IDs per country on Orbit, track approval status, and understand why some destinations block unregistered senders.

# Sender-ID Registration

An **alphanumeric Sender ID** is a short brand name (for example
`MyBrand`) that appears as the "from" on an SMS instead of a phone
number. Many countries require you to **register** a Sender ID with
the local regulator or carriers before traffic using it will be
delivered — and some block unregistered alphanumeric senders outright.

Orbit lets you record your Sender-ID registrations per country, attach
the supporting KYC documents, and track each country's approval
status. Send-time gates then enforce that traffic only flows where a
Sender ID is approved.

All endpoints below are rooted at
`https://api.orbit.devotel.io/api/v1/compliance`.

<Note>
  Registering a Sender ID in Orbit submits it into our compliance
  workflow; **final approval is granted by the regulator/carrier in
  each country**, not instantly by the platform. Plan lead time —
  some markets take days to weeks.
</Note>

***

## Sender-ID format rules

| Rule               | Value                                                  |
| ------------------ | ------------------------------------------------------ |
| Length             | 3–11 characters                                        |
| Allowed characters | letters, digits, space, hyphen (`-`), underscore (`_`) |

The 11-character ceiling is the GSM 7-bit hard limit; regulators such
as ANATEL (Brazil), OFCOM (UK), AGCOM (Italy), and BTRC (Bangladesh)
reject Sender IDs shorter than 3 characters.

***

## Register or update a Sender ID

`POST /compliance/sender-id-registrations` (admin/owner) submits a
Sender ID for one or more countries. Each country entry references
pre-uploaded compliance documents by their `doc_…` IDs — you do not
upload files here.

```bash theme={null}
curl -X POST https://api.orbit.devotel.io/api/v1/compliance/sender-id-registrations \
  -H "Authorization: Bearer $ORBIT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "sender_id": "MyBrand",
    "countries": [
      {
        "country": "BR",
        "document_refs": ["doc_abc123def456"],
        "notes": "Retail brand, transactional + OTP use case"
      }
    ]
  }'
```

| Field                                  | Type      | Notes                                                                       |
| -------------------------------------- | --------- | --------------------------------------------------------------------------- |
| `sender_id`                            | string    | 3–11 chars, see format rules above.                                         |
| `countries`                            | array     | 1–20 entries.                                                               |
| `countries[].country`                  | string    | ISO-3166-1 alpha-2 (uppercase).                                             |
| `countries[].document_refs`            | string\[] | 1–20 IDs of the form `doc_…` referencing previously uploaded KYC documents. |
| `countries[].registration_provider_id` | string    | Optional downstream/provider reference (≤ 200).                             |
| `countries[].notes`                    | string    | Optional free text, e.g. use case (≤ 2000).                                 |

Returns the registration view with each country's `status`:

```json theme={null}
{
  "data": {
    "id": "sidreg_xyz",
    "sender_id": "MyBrand",
    "countries": [
      {
        "country": "BR",
        "status": "pending",
        "document_refs": ["doc_abc123def456"],
        "registered_at": null,
        "expires_at": null,
        "registration_provider_id": null,
        "notes": "Retail brand, transactional + OTP use case"
      }
    ]
  },
  "meta": { "request_id": "…", "timestamp": "2026-06-08T12:00:00.000Z" }
}
```

The submission is an **idempotent upsert** keyed on
`(organization, sender_id)`. Re-submitting:

* adds new countries at `status: pending`;
* for a country already `approved`, **keeps the approval** while
  refreshing its documents, provider reference, and notes;
* for a country that was `rejected` or `expired`, **resets it to
  `pending`** so it is re-reviewed.

This lets you safely add countries to an existing Sender ID without
losing approvals you already hold.

***

## List your registrations

`GET /compliance/sender-id-registrations` returns every Sender ID and
its per-country status. Available to any authenticated user.

```json theme={null}
{
  "data": {
    "entries": [
      {
        "id": "sidreg_xyz",
        "sender_id": "MyBrand",
        "countries": [
          {
            "country": "BR",
            "status": "approved",
            "document_refs": ["doc_abc123def456"],
            "registered_at": "2026-06-05T00:00:00.000Z",
            "expires_at": "2027-06-05T00:00:00.000Z"
          }
        ]
      }
    ],
    "total": 1
  },
  "meta": { "request_id": "…", "timestamp": "2026-06-08T12:00:00.000Z" }
}
```

***

## Status lifecycle

| Status     | Meaning                                                           |
| ---------- | ----------------------------------------------------------------- |
| `pending`  | Submitted, awaiting review/approval.                              |
| `approved` | Cleared — traffic with this Sender ID is allowed for the country. |
| `rejected` | Declined; fix the issue and re-submit to reset to `pending`.      |
| `expired`  | The registration's validity window closed; re-submit to renew.    |

When a country entry is `approved` it carries `registered_at` and
`expires_at`. Renew before `expires_at` to avoid a lapse.

<Warning>
  Send-time gates enforce registration: A2P SMS to a country that
  requires a registered Sender ID is **blocked** unless that country's
  entry is `approved`. Register and get approved before launching
  traffic to a new market.
</Warning>

<Note>
  On tenants created before the Sender-ID migration, the list endpoint
  returns an empty set and `POST` returns `409 TENANT_NOT_MIGRATED` —
  contact support to enable the feature.
</Note>

***

## India is different

India does **not** use this generic Sender-ID flow. Indian SMS
Sender IDs ("Headers") are registered through the DLT/TRAI system —
see [DLT-India Onboarding](/compliance/dlt-india).

***

## Related references

* [Country Compliance Requirements](/compliance/country-requirements) —
  which sender types each country accepts and whether registration is
  required, plus the documents to supply.
* [DLT-India Onboarding](/compliance/dlt-india) — Sender-ID
  ("Header") registration for India.
* [Send Gates](/compliance/send-gates) — the country rules and gates
  that enforce registration at send time.
* [Consent Management](/compliance/consent-management) — the consent
  layer that pairs with Sender-ID compliance.
* [API Reference → Compliance](/api-reference/compliance) — full
  request/response schemas (regenerated from the live API).