USSD API Overview

The AfriRoute USSD API lets you build interactive, session-based mobile applications that run on any phone — no internet or app install required. USSD is ideal for mobile banking, airtime top-ups, surveys, and agent tools across 50+ African countries. This page introduces the model, endpoints, and how the USSD docs fit together.

📱 How USSD Works

USSD interactions are session-based. A user dials a shortcode (e.g. *123#), which opens a real-time session. Your application returns a menu, the user replies with a selection, and the session continues until your app ends it or it times out (default 90 seconds).

There are two integration styles:

1. Server-initiated — you push menus with /v1/ussd/send and advance with /v1/ussd/continue.
2. Callback-driven — the user dials your shortcode and AfriRoute forwards each input to your webhook, which replies with the next screen. See Callbacks.

🚀 Quick Start

curl -X POST https://api.afriroute.ai/api/v1/ussd/send \
  -H "Authorization: Bearer $AFRIROUTE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "phone": "+251911234567",
    "shortcode": "*123#",
    "message": "Welcome!\n1. Check Balance\n2. Send Money\n0. Exit",
    "session_id": "sess_abc123"
  }'

🔑 Authentication

Authorization: Bearer $AFRIROUTE_API_KEY

Manage keys in the dashboard. Base URL for all endpoints: https://api.afriroute.ai.

📡 Endpoints

Method	Path	Purpose	Reference
POST	/v1/ussd/send	Start a session and show the first menu	Menus
POST	/v1/ussd/continue	Advance the session after user input	Sessions
GET	/v1/ussd/sessions/{session_id}	Retrieve session state	Sessions
POST	/v1/ussd/sessions/{session_id}/end	End a session	Sessions

🔄 Session Lifecycle

State	Meaning
initiated	Session created, first menu shown
active	User is navigating menus
expired	Timed out due to inactivity
completed	Ended by your app or the user

⚙️ Key Constraints

• Message length: up to 182 characters per screen.
• Default timeout: 90 seconds (configurable up to 180).
• Navigation: keep menus shallow; use consistent keys (e.g. 0 home, 00 back).

🌍 Country Coverage

Country	Shortcode Format	Operators
🇪🇹 Ethiopia	*123#	Ethio Telecom
🇰🇪 Kenya	*123#	Safaricom, Airtel
🇳🇬 Nigeria	*123#	MTN, Glo, Airtel, 9mobile
🇿🇦 South Africa	*120#	All major operators
🇬🇭 Ghana	*170#	MTN, Vodafone, AirtelTigo

View full coverage →

🧩 SDK Example

const afriroute = require('@afriroute/sdk');
const client = new afriroute.Client('$AFRIROUTE_API_KEY');

await client.ussd.send({
  phone: '+251911234567',
  shortcode: '*123#',
  message: 'Welcome!\n1. Balance\n2. Transfer\n0. Exit',
  session_id: crypto.randomUUID()
});

💡 Best Practices

• Keep menus short — 182-character screens fill quickly.
• Persist state per session_id, not per phone number.
• Handle invalid input gracefully without ending the session.
• Mind the timeout — long PIN entry flows can expire.

📚 Related Resources

• Sessions
• Menus
• Callbacks

---

Last Updated: May 2026 · Need help? Contact Support →