---
title: "Create USSD OTP"
method: POST
path: "/v1/ussd-otps"
tags: ["USSD OTP"]
---

# Create USSD OTP

`POST /v1/ussd-otps`

Creates a new USSD OTP session for secure phone-bound verification.

## Headers

- `Idempotency-Key` string, required — This header is used to uniquely identify a logical request, ensuring that it is not processed more than once during retries.
- `Monime-Version` 'caph.2025-08-23' | 'caph.2025-06-20', nullable — Specifies which version of the Monime API will handle this request.
- `Monime-Space-Id` string, required — The value is the tenancy parameter that Monime uses to determine which space the request is intended for.

## Request body

- object — Creates a new USSD OTP session for secure phone-bound verification.
  - `authorizedPhoneNumber` string, required — Phone number (MSISDN) authorized to verify the OTP. Will be used to validate the incoming USSD request.
  - `verificationMessage` string, nullable — Message shown to the user after successful verification, typically rendered on the USSD interface.
  - `duration` string — How long the OTP code remains valid before expiring. Specified as a duration string (e.g., '30s', '2m').
  - `metadata` object, nullable — Optional metadata to associate additional context or tracking info with this OTP session.

## Response `200`

OK

- object
  - `success` boolean — Represents the status of the query operation, confirming if it was successful. This field is always true
  - `messages` unknown[] — Contains a list of messages providing relevant information or feedback related to the query or operation
    - unknown
  - `result` UssdOtp — A **USSD OTP** represents a **one-time passcode session** used to authenticate users through a USSD dial flow. It enables secure, **phone-bound verification**, ensuring that the person interacting via USSD is the legitimate account holder. In addition to generating and validating the OTP, the flow may include **user-facing feedback messages** that confirm the process. ---
    - `id` string — **Unique identifier** for this USSD OTP session.
    - `status` 'pending' | 'verified' | 'expired' — **Status** of the OTP session. One of: - pending: Awaiting verification. - verified: OTP was successfully confirmed. - expired: OTP expired before verification.
    - `dialCode` string — **USSD dial code** that the user should dial (e.g., \*715\*12345#) to initiate the OTP verification.
    - `authorizedPhoneNumber` string — **Authorized phone number** (MSISDN) associated with this OTP. May be masked for privacy.
    - `verificationMessage` string, nullable — **Message** shown to the user after successful verification, typically rendered on the USSD interface.
    - `createTime` string, date-time — Timestamp when this OTP session was created.
    - `expireTime` string, date-time — **Expiration time** after which the OTP becomes invalid.
    - `metadata` object, nullable — **Optional metadata** for attaching additional context or tracking info to this OTP session.

---

[API](https://skmtc.dev/monime/apis/monime-api.md) · [All operations](https://skmtc.dev/monime/apis/monime-api/llms.txt) · [OpenAPI document](https://skmtc-service-production.skmtc.workers.dev/v1/apis/monime/monime-api/revisions/bd7f875ea428/schema)