Creates a customer session

POST

/session

curl --request POST \
  --url https://api.pipevest.com/v1/ussd/session \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --header 'x-client-id: <x-client-id>' \
  --data '{ "customerId": "clx0a1b2c3d4e5f6g7h8i9j0k" }'

• Production
• Sandbox (UAT)

Opens a USSD session for a customer and returns the HOME menu.

What the customer sees:

Select an investment option:

1. Stocks
2. My Portfolio

Authorizations

• BearerAuth
• ClientId

Request Body^required

The customer to open a USSD session for.

Media typeapplication/json

object

customerId

required

Unique customer identifier (CUID string).

string

Example

clx0a1b2c3d4e5f6g7h8i9j0k

Responses

201

Customer session created successfully

Media typeapplication/json

object

message

required

string

data

required

object

data

required

The USSD session response data (HOME menu).

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

Example

{
  "message": "Success",
  "data": {
    "sessionId": "ussd_3278668b308502f3a562950fc8043028",
    "currentState": "HOME",
    "menu": {
      "state": "HOME",
      "text": "Select an investment option:",
      "options": [
        {
          "key": "1",
          "label": "Stocks",
          "nextState": "STOCKS",
          "data": {
            "stockId": "cmhkp4jkw0005zxfok9m0kiwg",
            "symbol": "AAPL",
            "name": "Apple Inc."
          }
        }
      ],
      "isEndState": false
    },
    "ussdText": "Select an investment option:\n\n1. Stocks\n2. My Portfolio",
    "expiresAt": "2025-11-06T14:38:12.202Z"
  }
}

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

Unauthorized

Media typeapplication/json

object

error

required

string

message

required

string

Example

{
  "error": "Unauthorized",
  "message": "Organization authentication token is required"
}