Skip to content
Pipevest Developers

Processes a customer's USSD request

POST
/process
curl --request POST \
  --url https://api.pipevest.com/v1/ussd/process \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --header 'x-client-id: <x-client-id>' \
  --data '{ "sessionId": "ussd_3278668b308502f3a562950fc8043028", "choice": "1" }'

Advances an existing session. The body is { sessionId, choice } — it does not take a customerId.

What the customer sees (example: the Stocks menu):

Select Stock:

1. AAPL
2. AMZN
7. Next Page
8. Search Stock
0. Back to Home

Authorizations

Section titled “Authorizations”

Request Bodyrequired

Section titled “Request Bodyrequired”

The session and the customer’s menu choice.

Media typeapplication/json
object
sessionId
required

Unique session identifier.

string
Example
ussd_3278668b308502f3a562950fc8043028
choice
required

The customer’s menu choice, always sent as a string. May be a numeric key like “1” or a free-text search term like “Tesla”. Alphanumeric, 1–10 characters.

string
Example
1

Responses

Section titled “Responses”

200

Section titled “200”

USSD request processed successfully

Media typeapplication/json
object
message
required
string
data
required
object
data
required

The USSD process request response data.

object
sessionId
required

Unique session identifier.

string
currentState
required
string
menu
required

The menu structure with state, text, options, and end state flag.

object
state
required
string
text
required
string
options
required
Array<object>

A menu option with key, label, optional next state, and optional data.

object
key
required

The option key (e.g. “1”, “2”, or a search term).

string
label
required

The display label for the option.

string
nextState

The next state to transition to (some options, like “Next Page”, omit this).

string
data

Optional additional data associated with the option (e.g. stock information).

object
stockId
string
symbol
string
name
string
isEndState
required
boolean
ussdText
required
string
expiresAt
required
string format: date-time
Examples
ExamplestocksMenu

Stocks menu response

{
  "message": "USSD request processed successfully",
  "data": {
    "sessionId": "ussd_3278668b308502f3a562950fc8043028",
    "currentState": "STOCKS",
    "menu": {
      "state": "STOCKS",
      "text": "Select Stock:",
      "options": [
        {
          "key": "1",
          "label": "AAPL",
          "nextState": "SELECT_STOCK",
          "data": {
            "stockId": "cmhkp4jkw0005zxfok9m0kiwg",
            "symbol": "AAPL",
            "name": "Apple Inc."
          }
        },
        {
          "key": "2",
          "label": "AMZN",
          "nextState": "SELECT_STOCK",
          "data": {
            "stockId": "cmhkp4kcp0008zxfohlxjtvd7",
            "symbol": "AMZN",
            "name": "Amazon.com Inc."
          }
        },
        {
          "key": "7",
          "label": "Next Page"
        },
        {
          "key": "8",
          "label": "Search Stock",
          "nextState": "SEARCH_STOCK"
        },
        {
          "key": "0",
          "label": "Back to Home",
          "nextState": "HOME"
        }
      ],
      "isEndState": false
    },
    "ussdText": "Select Stock:\n\n1. AAPL\n2. AMZN\n7. Next Page\n8. Search Stock\n0. Back to Home",
    "expiresAt": "2025-11-06T14:38:12.202Z"
  }
}

400

Section titled “400”

Request failed schema validation

Media typeapplication/json
object
error
string
details
Array<object>
object
field
string
message
string
Example
{
  "error": "Validation failed",
  "details": [
    {
      "field": "customerId",
      "message": "Invalid customer ID format"
    }
  ]
}

401

Section titled “401”

Unauthorized

Media typeapplication/json
object
error
required
string
message
required
string
Example
{
  "error": "Unauthorized",
  "message": "Organization authentication token is required"
}