Skip to content
Pipevest Developers

Response Data Definitions

Each USSD endpoint returns a standardized response structure. Below are their definitions and usage.

Response Structure

Section titled “Response Structure”

All USSD endpoints return a response with the following top-level structure:

{
  "message": "USSD session created successfully",
  "data": {
    "sessionId": "ussd_3278668b308502f3a562950fc8043028",
    "currentState": "HOME",
    "menu": {
      "state": "HOME",
      "text": "Select an investment option:",
      "options": [
        {
          "key": "1",
          "label": "Stocks",
          "nextState": "STOCKS"
        },
        {
          "key": "2",
          "label": "My Portfolio",
          "nextState": "MY_PORTFOLIO"
        }
      ],
      "isEndState": false
    },
    "ussdText": "Select an investment option:\n\n1. Stocks\n2. My Portfolio",
    "expiresAt": "2025-11-06T14:38:12.202Z"
  }
}
What the customer sees
Select an investment option:

1. Stocks
2. My Portfolio

Top-level Data

Section titled “Top-level Data”
Key Definition Required
message A string message indicating the result of the operation Yes
data An object containing the session and menu information Yes

Data Object

Section titled “Data Object”

The data object contains the session information and menu structure:

Key Definition Required
sessionId Unique identifier for the USSD session Yes
currentState The current state of the session (e.g., “HOME”, “STOCKS”, “MY_PORTFOLIO”) Yes
menu An object containing the menu structure with options Yes
ussdText The formatted USSD text to display to the user Yes
expiresAt The expiration timestamp of the session (ISO 8601 format) Yes
Section titled “Menu Object”

The menu object contains the menu structure and available options:

Key Definition Required
state The current menu state (e.g., “HOME”, “STOCKS”) Yes
text The menu text to display to the user Yes
options An array of menu options available to the user Yes
isEndState A boolean indicating whether this is an end state (session terminates if true) Yes
Section titled “Menu Options”

Each option in the options array is a MenuOption object:

Key Definition Required
key The option key that the user can select (e.g., “1”, “2”, or “Tesla”, “Apple”) Yes
label The display label for the option Yes
nextState The next state to transition to when this option is selected (optional) No
data Optional additional data associated with the option (e.g., stock information) No
Section titled “MenuOption Examples”

Simple option with next state:

{
  "key": "1",
  "label": "Stocks",
  "nextState": "STOCKS"
}

Option without next state (e.g., “Next Page”):

{
  "key": "7",
  "label": "Next Page"
}

Option with additional data (stock information):

{
  "key": "1",
  "label": "AAPL",
  "nextState": "SELECT_STOCK",
  "data": {
    "stockId": "cmhkp4jkw0005zxfok9m0kiwg",
    "symbol": "AAPL",
    "name": "Apple Inc."
  }
}

Complete Example Response

Section titled “Complete Example Response”

Example: 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"
  }
}
What the customer sees
Select Stock:

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