Docs

USSD Codes

Register and manage the short-code service strings your subscribers dial.

A USSD code is a short-code service string like *657# assigned to your team. Codes can be dedicated (yours exclusively) or shared, where you take an extension off a code owned by a partner. Every code goes through an approval workflow before it can go live. Requests require the ussd scope on your API token.

Approval required

A newly registered code starts in pending approval status. It only serves sessions once an admin sets it to approval_status: "approved" and status: "active".

List your USSD codes

GET/api/v1/ussd/codes

Returns every code your team owns, with approval and activation status.

curl -X GET "https://timisha-solutions-api.salamu.co.ke/api/v1/ussd/codes" \
  -H "Authorization: Bearer YOUR_API_TOKEN"
200: OK
{
  "success": true,
  "data": [
    {
      "uuid": "code-uuid",
      "code": "*657#",
      "is_shared": false,
      "networks": ["safaricom"],
      "approval_status": "approved",
      "status": "active",
      "mode": "menu"
    }
  ]
}

Shared (partner) codes

GET/api/v1/ussd/shared-codes

Lists all platform-wide shared codes you can request an extension on.

curl -X GET "https://timisha-solutions-api.salamu.co.ke/api/v1/ussd/shared-codes" \
  -H "Authorization: Bearer YOUR_API_TOKEN"
GET/api/v1/ussd/shared-codes/{uuid}/availability

Check which extension numbers are still free on a given shared code before requesting one.

curl -X GET "https://timisha-solutions-api.salamu.co.ke/api/v1/ussd/shared-codes/code-uuid/availability" \
  -H "Authorization: Bearer YOUR_API_TOKEN"

Register a USSD code

POST/api/v1/ussd/codesJSON or multipart/form-data

Send JSON for a text-only request, or multipart/form-data to attach supporting documents in the same call. You can also upload documents afterwards (see below).

Parameters
codereq
string

Requested USSD code (e.g. *657#)

networksreq
string[]

Networks: safaricom | airtel | telkom | equitel

quoted_price
number

Your quoted monthly price if known

business_registration
file

Business certificate (multipart only)

request_letter_{network}
file

Per-network request letter (multipart only)

JSON request (no documents):

curl -X POST "https://timisha-solutions-api.salamu.co.ke/api/v1/ussd/codes" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
  "code": "*657#",
  "networks": [
    "safaricom",
    "airtel"
  ]
}'

Multipart with documents, encode networks as a JSON array and attach each file with -F:

curl (multipart)
curl -X POST "$NEXT_PUBLIC_API_URL/api/v1/ussd/codes" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -F 'code=*657#' \
  -F 'networks=["safaricom"]' \
  -F 'business_registration=@cert.pdf' \
  -F 'request_letter_safaricom=@letter_safaricom.pdf'

Get a USSD code

GET/api/v1/ussd/codes/{uuid}

Fetch a single code by UUID, including current approval and activation status.

curl -X GET "https://timisha-solutions-api.salamu.co.ke/api/v1/ussd/codes/code-uuid" \
  -H "Authorization: Bearer YOUR_API_TOKEN"

Update a USSD code

PUT/api/v1/ussd/codes/{uuid}

Set how the code handles sessions. In menu mode it serves a menu tree; in callback mode it POSTs each session event to your server; in survey mode it routes to a survey.

Parameters
mode
string

menu | callback | survey, how the code handles sessions

callback_url
string

For callback mode: URL to POST session events to

survey_id
string

For survey mode: survey UUID to route sessions to

menu_id
string

For menu mode: menu UUID to serve

Set to menu mode and attach a menu:

curl -X PUT "https://timisha-solutions-api.salamu.co.ke/api/v1/ussd/codes/code-uuid" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
  "mode": "menu",
  "menu_id": "menu-uuid"
}'

Set to callback mode so raw session events POST to your own server:

curl -X PUT "https://timisha-solutions-api.salamu.co.ke/api/v1/ussd/codes/code-uuid" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
  "mode": "callback",
  "callback_url": "https://yourserver.com/ussd/handler"
}'

Delete a USSD code

DELETE/api/v1/ussd/codes/{uuid}

Removes a code your team owns.

curl -X DELETE "https://timisha-solutions-api.salamu.co.ke/api/v1/ussd/codes/code-uuid" \
  -H "Authorization: Bearer YOUR_API_TOKEN"

Upload supporting documents

POST/api/v1/ussd/codes/{uuid}/documentsmultipart/form-data

Attach or replace documents on an existing code. Use the same field names as registration, business_registration and request_letter_{network}.

curl (multipart)
curl -X POST "$NEXT_PUBLIC_API_URL/api/v1/ussd/codes/code-uuid/documents" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -F 'business_registration=@cert.pdf' \
  -F 'request_letter_safaricom=@letter_safaricom.pdf'

Next steps

Build the screens subscribers see under Menus & nodes, then test the whole flow without a handset via Simulation.