USSD gateway API

Endpoint reference for the IXO USSD gateway: the session endpoint telecom gateways call, its validation rules and responses, and the debug and health endpoints.

The IXO USSD gateway lets people use a service from a basic phone by dialling a short code. It exposes a single session endpoint that telecom gateways call for each user interaction, plus debug and health endpoints for operators.

Use this page when you connect a telecom gateway to a server you run, or operate one. It lists every endpoint, the request fields and validation rules, the response format and the errors.

Overview

All endpoints accept and return JSON unless otherwise noted. The main session endpoint returns plain text in the USSD response format.

Authentication

The /api/ussd endpoint does not require authentication by default. It is intended to be called by your telecom gateway server, not directly from a browser. Restrict access at the network or reverse-proxy layer in production.

Base URL

http://YOUR_SERVER:3000

The default port is 3000. Set PORT in your environment to override.

Session endpoint

POST /api/ussd

Processes a USSD interaction. Called by the telecom gateway once per user input during a session.

Request

{
  "sessionId": "string",
  "serviceCode": "string",
  "phoneNumber": "string",
  "text": "string"
}
FieldTypeRequiredDescription
sessionIdstringyesUnique session identifier assigned by the telecom gateway.
serviceCodestringyesUSSD service code the user dialled, for example *1234#.
phoneNumberstringyesUser phone number in E.164 international format, for example +260971234567.
textstringyesUser input accumulated during the session. Empty string on initial dial.

Validation rules

FieldRule
phoneNumberMust be E.164 format
serviceCodeMust match USSD format, for example *1234# or *123*456#
textMaximum 182 characters (USSD protocol limit)
sessionIdMaximum 100 characters

Response

Plain text. The first word indicates whether the session continues or ends.

CON <menu text>
END <closing message>
First wordMeaning
CONSession continues. Display the menu and wait for the next input.
ENDSession closed. Display the message and end the USSD session.

Example: initial dial

curl -X POST http://localhost:3000/api/ussd \
  -H "Content-Type: application/json" \
  -d '{
    "sessionId": "session-001",
    "serviceCode": "*1234#",
    "phoneNumber": "+260971234567",
    "text": ""
  }'

Response:

CON Welcome to IXO USSD
1. Know More
2. Account Menu
*. Exit

Example: user selects option 1

curl -X POST http://localhost:3000/api/ussd \
  -H "Content-Type: application/json" \
  -d '{
    "sessionId": "session-001",
    "serviceCode": "*1234#",
    "phoneNumber": "+260971234567",
    "text": "1"
  }'

Response:

CON Information Center
1. About this service
2. Pricing
3. Delivery
*. Exit

Debug endpoints

GET /api/ussd/debug/:sessionId

Returns the current state and context for an active session. Intended for operator debugging only. Do not expose it publicly.

Response

{
  "sessionId": "session-001",
  "debugInfo": {
    "state": "preMenu",
    "context": {
      "sessionId": "session-001",
      "phoneNumber": "+260971234567",
      "message": "Welcome to IXO USSD...",
      "isAuthenticated": false
    },
    "status": "active"
  },
  "activeSessions": ["session-001"]
}

GET /api/ussd/sessions

Returns the IDs of all active sessions.

{
  "activeSessions": ["session-001", "session-002"],
  "count": 2
}

Health endpoints

GET /health

Returns application health with database connectivity status.

{
  "status": "ok",
  "environment": "production",
  "timestamp": "2026-04-22T10:00:00.000Z",
  "uptime": 3600,
  "database": "connected"
}

GET /

Basic health check for platform-as-a-service health probes.

{
  "status": "ok",
  "message": "ixo-ussd-server running",
  "environment": "production",
  "timestamp": "2026-04-22T10:00:00.000Z"
}

Errors

ErrorCauseWhat to do
END Invalid input. Please try again.Request failed validation.Check that the phone number is E.164, the service code format, and the text length.
END Service temporarily unavailable. Please try again later.Server or database error.Check /health for database connectivity.
Session not found on GET /debug/:sessionIdSession expired or never started.Sessions expire after inactivity. The user must dial again.

Rate limiting

100 requests per minute per IP address. Requests exceeding this return HTTP 429.

For generic HTTP status handling (retries, 5xx, client errors), see Errors. For environment-specific service URLs and auth, see Networks and endpoints and the Authentication matrix.

Security notes

  • User PINs are encrypted at rest with AES-256 using the PIN_ENCRYPTION_KEY environment variable.
  • All inputs are validated and sanitised before processing.
  • Set TRUST_PROXY_ENABLED=true when running behind a reverse proxy so rate limiting uses the real client IP.