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

# Sender IDs

> Send with the default UGATEXT Sender ID or register your own approved brand name in Uganda, Kenya, or DR Congo.

Under Uganda Communications Commission (UCC) regulations and operator routing agreements, every SMS must use an approved alphanumeric Sender ID.

## Default Sender ID

`UGATEXT` is approved and provisioned on every account. Pass it in the `sender_id` field:

```json theme={null}
{
  "to": "+256700000000",
  "sender_id": "UGATEXT",
  "message": "Hello from UgaText"
}
```

> [!NOTE]
>
> `sender_id` is required. Missing, blank, or unapproved values are rejected with `403 SENDER_ID_NOT_APPROVED`. Accepted field aliases are `senderId` and `from`.

## Pricing and approval times

Custom Sender IDs are available in Uganda, Kenya, and DR Congo.

| Country | `network` value | Coverage | Fees | Approval time |
| - | - | - | - | - |
| Uganda | `both` | MTN + Airtel | UGX 750,000 setup + UGX 250,000 per month MTN recurring (UGX 1,000,000 initial total) | 5 to 10 working days |
| Uganda | `mtn` | MTN Uganda only | UGX 500,000 setup + UGX 250,000 per month recurring (UGX 750,000 initial total) | 3 to 7 working days |
| Uganda | `airtel` | Airtel Uganda only | UGX 750,000 one-time (UGX 500,000 integration + UGX 250,000 Airtel one-time, no recurring fee) | 5 to 10 working days |
| Kenya | `both_ke` | Safaricom + Airtel Kenya | KES 14,100 one-time | 7 to 14 working days |
| Kenya | `safaricom` or `airtel_ke` | Single operator | KES 8,700 one-time | 7 to 14 working days |
| DR Congo | `all_cd` | All DRC networks (Vodacom, Airtel, Orange, Africell) | USD 120 one-time | 5 to 10 working days |

You can keep sending with the default `UGATEXT` Sender ID while your request is under review.

## Register a custom Sender ID

A custom Sender ID shows your brand name (up to 11 characters, for example `MYSCHOOL`) to recipients.

**1. Check pricing**

`GET /sender-ids/pricing?country=Uganda` returns the current price list, setup fees, and lead times for Uganda, Kenya, or DR Congo (`country=DR Congo`). This endpoint does not require authentication.

**2. Create a request**

`POST /sender-ids/requests` with:

| Field | Required | Description |
| - | - | - |
| `sender_id` | Yes | 3 to 11 uppercase alphanumeric characters. |
| `purpose` | Yes | What you will send (max 1,000 characters). |
| `network` | No | `both` (default), `mtn`, `airtel`, `safaricom`, `airtel_ke`, or `both_ke`. |
| `country` | No | `Uganda`, `Kenya`, or `DR Congo`. |
| `is_default` | No | Make this your default Sender ID. |

The request is created in the `awaiting_payment` state. A `409` means the name is already registered by another account.

**3. Get an authorization letter**

`GET /sender-ids/letter-template/{network}` generates a pre-filled official telecom authorization letter.

| Parameter | Required | Description |
| - | - | - |
| `network` (path) | Yes | `mtn`, `airtel`, `safaricom`, `airtel_ke`, or `both_ke`. |
| `sender_id` | No | Sender ID to fill in. |
| `purpose` | No | Purpose to fill in. |
| `country` | No | Country to fill in. |
| `download` | No | Set to `true` to download the letter as a `.txt` file. |

Sign and stamp the letter, then upload it in the next step.

**4. Upload documents**

`POST /sender-ids/requests/{id}/documents` with a base64-encoded PDF, PNG, or JPG (max 5 MB).

| Field | Required | Description |
| - | - | - |
| `kind` | Yes | `mtn_letter`, `airtel_letter`, `kenya_letter`, `safaricom_letter`, `airtel_ke_letter`, `certificate_of_incorporation`, `tin_certificate`, `kra_pin`, or `other`. |
| `file_base64` | Yes | Base64-encoded file content. |
| `filename` | No | File name, for example `authorization_letter.pdf`. |
| `mime_type` | No | File type, for example `application/pdf`. |

`GET /sender-ids/documents/{docId}` downloads an uploaded document as a binary stream with its original `Content-Type`.

**5. Pay and submit**

`POST /sender-ids/requests/{id}/pay` debits your wallet and submits the request for telecom review. It returns `402 INSUFFICIENT_BALANCE` if your wallet is too low.

**6. Track status**

`GET /sender-ids` lists your Sender IDs with status and document counts. `GET /sender-ids/requests/{id}` returns details, documents, and audit history.

## Edit or discard a request

You can change or delete a request while it is a draft or unpaid (`awaiting_payment`).

| Action | Endpoint | Notes |
| - | - | - |
| Update a request | `PATCH /sender-ids/requests/{id}` | Accepts `sender_id`, `network`, `purpose`, `country`, `is_default`, and `status`. |
| Delete a request | `DELETE /sender-ids/requests/{id}` | Returns `400 CANNOT_DELETE_ACTIVE_REQUEST` if the request was already submitted or is active. |

## Manage active Sender IDs

| Action | Endpoint | Notes |
| - | - | - |
| Set as default | `POST /sender-ids/{id}/default` | Makes an active Sender ID the default for your account. |
| Renew | `POST /sender-ids/{id}/renew` | Renews an active or expired Sender ID for another 1-year validity period. |
| Revoke | `POST /sender-ids/{id}/revoke` | Permanently revokes an approved Sender ID. Sends using it are blocked immediately. |


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.