Applying for a shortcode

A shortcode is a short dialable number (e.g. 40404) your customers can text — the foundation for keywords, two-way messaging and USSD-style surveys. You apply for one through the sender ID API with sender_category=shortcode.

Shortcode applications share the sender ID application flow— same endpoint, same documents, same status lifecycle — with two differences: you don't choose the number (the system assigns it), and you pick a service_type that decides what the shortcode is for.

Service types

Parameters

Field	Type	Required	Description
ondemand	service_type	No	Two-way messaging: customers text keywords in, you receive them on your webhook and reply. The usual choice for support lines, promos, and info services.
survey	service_type	No	Structured multi-question surveys over SMS. The shortcode is additionally registered as a sender ID on each requested network, so per-network registration fees apply on top of the deposit.

Fees — funded from the wallet

Deposit deducted on approval

Shortcode approval deducts a deposit (plus, for survey types, the per-network sender registration fees) from your team's KES wallet. A monthly service fee applies thereafter. Current amounts are on the pricing page — keep the wallet funded while your application is in review or approval will be held.

Apply

POST/api/v1/sender-ids

Form fields (multipart/form-data)

Field	Type	Required	Description
sender_category	string	Yes	Must be `shortcode`. No `sender_id` field — the number is assigned by the system on approval.
service_type	string	Yes	`ondemand` or `survey`.
networks	JSON array	Yes	Networks the shortcode must work on, e.g. `["safaricom","airtel"]`.
description	string	No	What the service does — used in the network paperwork.
callback_url	string	No	HTTPS URL to receive inbound texts — you can also set this later per keyword.
business_registration	file	Yes	Business registration certificate (PDF/JPG/PNG, ≤ 10 MB).
request_letter_{network}	file	Yes	Signed authorisation letter per network, e.g. request_letter_safaricom. Sample letter available in the portal.

curl -X POST https://api.mobilesasa.com/api/v1/sender-ids \
  -H "Authorization: Bearer $MOBILESASA_TOKEN" \
  -F "sender_category=shortcode" \
  -F "service_type=ondemand" \
  -F 'networks=["safaricom","airtel"]' \
  -F "description=Customer support and order-status line for Dukapay" \
  -F "[email protected]" \
  -F "[email protected]" \
  -F "[email protected]"

Track the application

Identical to sender IDs — poll the resource or its status history. Statuses run pending → submitted → under_review / in_progress → approved | rejected; the full table is on the sender ID page. On approval the assigned number appears in the name field.

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

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

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

Approved shortcode

{
  "success": true,
  "data": {
    "uuid": "3f0c8d12-…",
    "name": "40404",
    "sender_category": "shortcode",
    "service_type": "ondemand",
    "status": "approved",
    "networks": ["safaricom", "airtel"]
  }
}

After approval

Reserve keywords on the shortcode and point them at your webhook.
Receive customer texts on the inbound webhook — or poll the inbound API.
For survey shortcodes, build and activate a survey.