USSD API

USSD (Unstructured Supplementary Service Data) is the menu-over-dial-code channel for feature phones. A subscriber dials a short code such as *384*1#, the mobile network opens a synchronous session and posts each keypress to your application, and the application replies with the next screen. It needs no data plan, which makes it the reach channel for markets where a large share of devices are 2G feature phones. Orbit hosts the menu and the session engine for you. You configure a menu tree once, point your aggregator (for example Africa’s Talking) at the tenant-scoped callback, and Orbit resolves each step. Base path: /api/v1/ussd Authentication: API key (X-API-Key) or session JWT — except the aggregator callback, which is a public, tenant-scoped webhook.

How a session works

The engine speaks the de-facto African-aggregator protocol. On every step the aggregator sends the full accumulated input string, with each prior keypress joined by * (the initial dial is an empty string). Orbit replies with a plain-text body whose first token is:

CON — show the message and keep the session open for more input.
END — show the message and terminate the session.

Because the aggregator replays the entire input chain on each callback, the engine is stateless: the next screen is a deterministic function of (menu, accumulated input). There is no per-session storage to manage.

Endpoints

Method	Path	Auth	Purpose
`GET`	`/api/v1/ussd/menu`	API key / JWT	Fetch the tenant’s configured menu
`PUT`	`/api/v1/ussd/menu`	`owner` · `admin` · `developer`	Create or replace the menu
`POST`	`/api/v1/ussd/simulate`	API key / JWT	Preview a session step
`GET`	`/api/v1/ussd/push/config`	API key / JWT	Fetch the push-provider config
`PUT`	`/api/v1/ussd/push/config`	`owner` · `admin` · `developer`	Create or replace the push-provider config
`POST`	`/api/v1/ussd/push`	`owner` · `admin` · `developer`	Open a network-initiated (push) session
`POST`	`/api/v1/ussd/callback/{tenantId}`	Public webhook	Aggregator session callback

A menu is a tree of nodes (screens) navigated from a root node. Each branch node lists numbered options; a node with no options (or final: true) terminates the session.

Field	Type	Notes
`serviceCode`	string	Optional dial code this menu answers (documentation only, e.g. `3841#`).
`root`	string	Id of the node shown on the initial dial. Must reference an existing node.
`nodes`	array	1–200 screens. Must include `root`.
`nodes[].id`	string	Stable node id (≤ 64 chars), referenced by `root` and option `next`. Must be unique.
`nodes[].prompt`	string	Screen text (≤ 160 chars).
`nodes[].options`	array	Up to 12 branch options. Omit for a terminal screen.
`nodes[].options[].key`	string	Input token the subscriber types (digits, letters, `#` or `*`; ≤ 8 chars).
`nodes[].options[].label`	string	Label rendered next to the key.
`nodes[].options[].next`	string	Id of the node this option navigates to. Must resolve to an existing node.
`nodes[].final`	boolean	Force the node to end the session even if it has options.

On PUT /menu the tree is validated for unique node ids and that root plus every option next resolves to an existing node; the request is rejected otherwise. A successful write replaces any previously configured menu.

curl -X PUT https://api.orbit.devotel.io/api/v1/ussd/menu \
  -H "X-API-Key: dv_live_sk_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "serviceCode": "*384*1#",
    "root": "main",
    "nodes": [
      {
        "id": "main",
        "prompt": "Welcome to Acme",
        "options": [
          { "key": "1", "label": "Check balance", "next": "balance" },
          { "key": "2", "label": "Buy airtime", "next": "airtime" }
        ]
      },
      { "id": "balance", "prompt": "Your balance is 250.00" },
      { "id": "airtime", "prompt": "Airtime top-up is coming soon." }
    ]
  }'

The configured menu is returned under data.menu. GET /api/v1/ussd/menu returns the same shape, or data.menu: null when none has been configured yet.

Simulate a session step

Run the live engine against an input string without touching your aggregator — useful while building and testing menus. Pass an inline menu to preview an unsaved definition; omit it to use the tenant’s configured menu.

Field	Type	Notes
`text`	string	Accumulated input, `*`-joined (empty or omitted for the initial dial).
`menu`	object	Optional inline menu to preview instead of the saved one.

curl -X POST https://api.orbit.devotel.io/api/v1/ussd/simulate \
  -H "X-API-Key: dv_live_sk_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{ "text": "1" }'

{
  "data": {
    "action": "END",
    "message": "Your balance is 250.00",
    "node_id": "balance",
    "raw": "END Your balance is 250.00"
  },
  "meta": { "request_id": "req_…", "timestamp": "2026-06-18T00:00:00.000Z" }
}

raw is the exact plain-text body the callback would return for the same input. When no menu is configured the simulator returns an END screen rather than an error.

Aggregator callback

Configure this URL in your aggregator dashboard (for example Africa’s Talking). It is a public webhook: the {tenantId} path segment scopes the call to the tenant that owns the menu, so no API key is sent. The aggregator posts it on every step of a session. It accepts both JSON and application/x-www-form-urlencoded bodies with the fields below, and responds with a text/plain body beginning CON (continue) or END (terminate).

Field	Type	Notes
`sessionId`	string	Aggregator session id (logged for telemetry).
`phoneNumber`	string	Subscriber MSISDN.
`serviceCode`	string	Dial code the subscriber used.
`text`	string	Accumulated input string, `*`-joined.

curl -X POST https://api.orbit.devotel.io/api/v1/ussd/callback/tenant_abc123 \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "sessionId=ATUid_123&phoneNumber=%2B254700000000&serviceCode=*384*1%23&text=1"

END Your balance is 250.00

USSD has no “back” affordance, so an input that doesn’t match any option — or that arrives after a terminal screen — ends the session cleanly. A callback for a tenant with no configured menu ends the session with END Service is not available. rather than leaving the subscriber hanging.

Network-initiated (push) sessions

The endpoints above all answer a session the subscriber opened by dialling a short code. Push works in the opposite direction: your application asks your aggregator to open a USSD session on a subscriber’s handset — for balance prompts, mobile-money confirmations, and feature-phone OTP flows. Push has no company-wide provider. You register your own aggregator push endpoint per tenant, exactly like the inbound callback URL you set in your aggregator dashboard, and Orbit POSTs each push to it. The push URL must be an https:// URL and is re-validated and DNS-pinned against the SSRF guard on every send.

Configure the push provider

Set the aggregator endpoint your push sessions go out through with PUT /api/v1/ussd/push/config.

Field	Type	Notes
`pushUrl`	string	Required. Aggregator push endpoint. Must be an `https://` URL (≤ 2048 chars).
`serviceCode`	string	Optional default service / short code the push opens against (e.g. `3841#`).
`senderId`	string	Optional sender / channel id some aggregators require on push.
`authHeaderName`	string	Optional header name the provider authenticates with (e.g. `Authorization`, `apiKey`).
`authHeaderValue`	string	Optional credential for `authHeaderName`. Write-only — never returned on read.

curl -X PUT https://api.orbit.devotel.io/api/v1/ussd/push/config \
  -H "X-API-Key: dv_live_sk_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "pushUrl": "https://ussd.aggregator.example/push",
    "serviceCode": "*384*1#",
    "senderId": "ACME",
    "authHeaderName": "Authorization",
    "authHeaderValue": "Bearer agg_secret_token"
  }'

GET /api/v1/ussd/push/config returns the stored config under data.config, or data.config: null when none is set. The credential is never echoed back: instead of authHeaderValue, the read response carries authConfigured — a boolean reporting whether a credential is stored.

{
  "data": {
    "config": {
      "pushUrl": "https://ussd.aggregator.example/push",
      "serviceCode": "*384*1#",
      "senderId": "ACME",
      "authHeaderName": "Authorization",
      "authConfigured": true
    }
  },
  "meta": { "request_id": "req_…", "timestamp": "2026-06-18T00:00:00.000Z" }
}

Open a push session

POST /api/v1/ussd/push opens the session on the subscriber’s handset via the configured aggregator.

Field	Type	Notes
`phoneNumber`	string	Required. Destination handset in E.164 (e.g. `+234801234567`). A leading `+` is added if omitted.
`message`	string	Required. First screen text (1–182 chars).
`action`	string	`CON` keeps the session open for a reply; `END` shows a one-shot notice. Defaults to `CON`.
`serviceCode`	string	Optional override of the configured default service code for this push.
`clientRequestId`	string	Optional idempotency / correlation key, echoed to the aggregator.

curl -X POST https://api.orbit.devotel.io/api/v1/ussd/push \
  -H "X-API-Key: dv_live_sk_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "phoneNumber": "+234801234567",
    "message": "Your balance is 250.00. Reply 1 to top up.",
    "action": "CON",
    "clientRequestId": "bal-2026-06-29-001"
  }'

{
  "data": {
    "status": "accepted",
    "providerStatus": 200,
    "phoneNumber": "+234801234567"
  },
  "meta": { "request_id": "req_…", "timestamp": "2026-06-18T00:00:00.000Z" }
}

providerStatus is the HTTP status your aggregator returned (a 2xx). accepted means the aggregator took the session; the subscriber’s reply, if any, then arrives on your aggregator callback like any other step.

Error codes

Status	When
`409`	No push provider is configured yet — set one via `PUT /api/v1/ussd/push/config` first.
`422`	The request body is invalid, or the configured `pushUrl` was rejected by the SSRF guard.
`502`	The aggregator could not be reached, or returned a non-2xx response.

USSD sessions never originate outbound voice or SMS. The reply is returned synchronously to the aggregator inside the open session, so no termination path is involved.

API Reference

All Endpoints

USSD API

USSD API

How a session works

Endpoints

The menu definition

Create or replace a menu

Simulate a session step

Aggregator callback

Network-initiated (push) sessions

Configure the push provider

Open a push session

Error codes

See also

​USSD API

​How a session works

​Endpoints

​The menu definition

​Create or replace a menu

​Simulate a session step

​Aggregator callback

​Network-initiated (push) sessions

​Configure the push provider

​Open a push session

​Error codes

​See also

USSD API

How a session works

Endpoints

The menu definition

Create or replace a menu

Simulate a session step

Aggregator callback

Network-initiated (push) sessions

Configure the push provider

Open a push session

Error codes

See also