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.