> ## Documentation Index
> Fetch the complete documentation index at: https://docs.monime.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Create USSD OTP

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



## OpenAPI

````yaml post /v1/ussd-otps
openapi: 3.0.3
info:
  title: Monime API
  description: Monime REST API. Please visit https://docs.momime.io/api for more details.
  termsOfService: https://monime.io/legal/terms-of-service
  contact:
    name: Monime Developers
    url: https://github.com/monimesl
    email: dev@monime.io
  version: v1
servers:
  - url: https://api.monime.io/
security:
  - bearerAuth: []
paths:
  /v1/ussd-otps:
    post:
      tags:
        - USSD OTP
      summary: Create USSD OTP
      description: Creates a new USSD OTP session for secure phone-bound verification.
      operationId: CreateUSSDOTP
      parameters:
        - name: Idempotency-Key
          in: header
          description: >-
            This header is used to uniquely identify a logical request, ensuring
            that it is not processed more than once during retries.
          required: true
          schema:
            maxLength: 64
            type: string
            description: >-
              This header is used to uniquely identify a logical request,
              ensuring that it is not processed more than once during retries.
        - name: Monime-Version
          in: header
          description: Specifies which version of the Monime API will handle this request.
          schema:
            enum:
              - caph.2025-08-23
              - caph.2025-06-20
            type: string
            description: >-
              Specifies which version of the Monime API will handle this
              request.
            nullable: true
        - name: Monime-Space-Id
          in: header
          description: >-
            The value is the tenancy parameter that Monime uses to determine
            which space the request is intended for.
          required: true
          schema:
            maxLength: 64
            pattern: ^spc-.*$
            type: string
            description: >-
              The value is the tenancy parameter that Monime uses to determine
              which space the request is intended for.
      requestBody:
        content:
          application/json:
            schema:
              title: CreateUSSDOTP
              required:
                - authorizedPhoneNumber
              type: object
              properties:
                authorizedPhoneNumber:
                  type: string
                  description: >-
                    Phone number (MSISDN) authorized to verify the OTP. Will be
                    used to validate the incoming USSD request.
                verificationMessage:
                  maxLength: 255
                  type: string
                  description: >-
                    Message shown to the user after successful verification,
                    typically rendered on the USSD interface.
                  nullable: true
                duration:
                  type: string
                  description: >-
                    How long the OTP code remains valid before expiring.
                    Specified as a duration string (e.g., '30s', '2m').
                  default: 5m
                  example: 5m
                metadata:
                  maxProperties: 64
                  type: object
                  additionalProperties:
                    maxLength: 100
                    type: string
                    description: >-
                      Metadata values are free-form strings up to 100
                      characters.
                  description: >-
                    Optional metadata to associate additional context or
                    tracking info with this OTP session.
                  nullable: true
              description: >-
                Creates a new USSD OTP session for secure phone-bound
                verification.
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                    description: >-
                      Represents the status of the query operation, confirming
                      if it was successful. This field is always true
                  messages:
                    type: array
                    items: {}
                    description: >-
                      Contains a list of messages providing relevant information
                      or feedback related to the query or operation
                  result:
                    $ref: '#/components/schemas/UssdOtp'
components:
  schemas:
    UssdOtp:
      title: USSD OTP
      type: object
      properties:
        id:
          type: string
          description: '**Unique identifier** for this USSD OTP session.'
        status:
          enum:
            - pending
            - verified
            - expired
          type: string
          description: |-
            **Status** of the OTP session. One of:
            - pending: Awaiting verification.
            - verified: OTP was successfully confirmed.
            - expired: OTP expired before verification.
        dialCode:
          type: string
          description: >-
            **USSD dial code** that the user should dial (e.g., \*715\*12345#)
            to initiate the OTP verification.
        authorizedPhoneNumber:
          type: string
          description: >-
            **Authorized phone number** (MSISDN) associated with this OTP. May
            be masked for privacy.
        verificationMessage:
          maxLength: 255
          type: string
          description: >-
            **Message** shown to the user after successful verification,
            typically rendered on the USSD interface.
          nullable: true
        createTime:
          type: string
          description: Timestamp when this OTP session was created.
          format: date-time
        expireTime:
          type: string
          description: '**Expiration time** after which the OTP becomes invalid.'
          format: date-time
        metadata:
          maxProperties: 64
          type: object
          additionalProperties:
            maxLength: 100
            type: string
            description: Metadata values are free-form strings up to 100 characters.
          description: >-
            **Optional metadata** for attaching additional context or tracking
            info to this OTP session.
          nullable: true
      description: >
        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.


        ---
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: auth-scheme
      description: >-
        Bearer HTTP authentication specified with the header Authorization:
        Bearer <access_token>

````