Sender ID requests

Apply for your own branded alphanumeric sender name over the API — upload the required documents, track the review status, and start sending under your brand once each network approves it.

These endpoints live under /api/v1/ and authenticate with a scoped mbs_ token or portal JWT — see Authentication. Until your own sender is approved you can send with the shared MOBILESASA sender.

Before you apply: fund your wallet

Sender ID approvals are paid from your wallet

Each network charges a one-time registration fee for an alphanumeric sender ID, and that fee is deducted from your team's KES wallet when the application is approved — one fee per network you request. Keep a sufficient wallet balance from the moment you apply: the review team will hold an otherwise-ready approval if the wallet can't cover the fees. See Top up via M-Pesa and current fees on the pricing page. Adding a network to an approved sender later deducts that network's fee the same way.

Required documents

Networks require proof that you are entitled to the name you're registering. The application is a multipart/form-data request carrying:

Business registration certificate — file field business_registration (one file, applies to all networks). Certificate of incorporation or business name registration.
Authorisation letter per network — file field request_letter_safaricom, request_letter_airtel, etc. A signed letter on your company letterhead addressed to the network, requesting the sender name. A sample letter is available in the portal on the Sender IDs page.

PDF, JPG or PNG; maximum 10 MB per file.

Submit an application

POST/api/v1/sender-ids

Form fields (multipart/form-data)

Field	Type	Required	Description
sender_id	string	Yes	The name you want, up to 11 characters, letters and digits (e.g. DUKAPAY). Not required for shortcode applications — the number is assigned by the system.
sender_category	string	Yes	One of `alphanumeric`, `shortcode`, `long_number`. This page covers alphanumeric; see Applying for a shortcode for the rest.
networks	JSON array or repeated network field	Yes	Networks to register on: `["safaricom","airtel"]` — or repeat a `network` form field per value.
description	string	No	What you will send under this name — helps the reviewers and the networks.
dr_callback_url	string	No	HTTPS URL to receive delivery reports for messages sent under this sender.
business_registration	file	Yes	Business registration certificate (PDF/JPG/PNG, ≤ 10 MB).
request_letter_{network}	file	Yes	One signed authorisation letter per requested network, e.g. request_letter_safaricom.

curl -X POST https://api.mobilesasa.com/api/v1/sender-ids \
  -H "Authorization: Bearer $MOBILESASA_TOKEN" \
  -F "sender_id=DUKAPAY" \
  -F "sender_category=alphanumeric" \
  -F 'networks=["safaricom","airtel"]' \
  -F "description=Order confirmations and receipts for Dukapay customers" \
  -F "[email protected]" \
  -F "[email protected]" \
  -F "[email protected]"

Response — 200

{
  "success": true,
  "data": {
    "uuid": "9b2f6c1e-…",
    "name": "DUKAPAY",
    "sender_category": "alphanumeric",
    "status": "pending",
    "networks": ["safaricom", "airtel"],
    "created_at": "2026-07-11T09:30:00Z"
  }
}

Tracking the status

GET/api/v1/sender-ids

GET/api/v1/sender-ids/{uuid}

GET/api/v1/sender-ids/{uuid}/status-history

Poll the sender itself for its current status, or fetch the status history for the full audit trail with reviewer comments and timestamps:

curl "https://api.mobilesasa.com/api/v1/sender-ids/9b2f6c1e-…/status-history" \
  -H "Authorization: Bearer $MOBILESASA_TOKEN"

Status values

Field	Type	Required	Description
pending	initial	No	Application received; not yet picked up by the review team.
submitted	in review	No	Forwarded to the networks for registration.
under_review / in_progress	in review	No	Being processed by the review team or the networks. Nothing is needed from you unless a comment asks for it.
approved	final	No	Registered — you can send with this sender name. The per-network registration fees are deducted from your wallet at this point.
rejected	final	No	Declined — the status history carries the reason. Fix the issue (usually documents) and re-submit.

Re-submitting after rejection

POST/api/v1/sender-ids/{uuid}/status

A team can move a pending or rejected application (back) to submitted. Approval itself only ever happens system-side.

curl -X POST https://api.mobilesasa.com/api/v1/sender-ids/9b2f6c1e-…/status \
  -H "Authorization: Bearer $MOBILESASA_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "new_status": "submitted",
    "comment": "Re-uploaded the corrected authorisation letter"
  }'

Adding a network later

POST/api/v1/sender-ids/{uuid}/network-requests

GET/api/v1/sender-ids/{uuid}/network-requests

An approved sender can be expanded to another network. The expansion goes through its own review, and that network's registration fee is deducted from the wallet on approval.

curl -X POST https://api.mobilesasa.com/api/v1/sender-ids/9b2f6c1e-…/network-requests \
  -H "Authorization: Bearer $MOBILESASA_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "network": "telkom"
  }'

Timelines

Network registration is a manual process on the carrier side — typically a few business days per network. Apply for all the networks you need in one application; they are reviewed together.