CM.com OTP API

openapi: 3.2.0
info:
  title: Cm Com OTP API
  version: '1.0'
  description: 'Operations tagged OTP across 3 of this provider''s published API definitions: cm-com-verification-otp-v1-openapi.yml, cm-com-verification-otp-v2-openapi.yml, cm-com-voice-voice-api-v2-openapi.yml. Each path carries the servers of the definition it was published in.'
servers:
- url: https://api.cm.com/v1.0/otp
- url: https://api.cm.com/otp/v2
- url: https://api.cm.com
tags:
- name: OTP
paths:
  /generate:
    post:
      operationId: create_otp
      summary: Generate code
      tags:
      - OTP
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/GenerateRequest'
      responses:
        '200':
          description: The code has been created.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GenerateResponse'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '500':
          $ref: '#/components/responses/UnknownError'
      security:
      - ProductToken: []
    servers:
    - url: https://api.cm.com/v1.0/otp
  /verify:
    post:
      operationId: verify_otp
      summary: Verify code
      tags:
      - OTP
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/VerifyRequest'
      responses:
        '200':
          description: Successful request.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/VerifyResponse'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '500':
          $ref: '#/components/responses/UnknownError'
      security:
      - ProductToken: []
    servers:
    - url: https://api.cm.com/v1.0/otp
  /otp:
    post:
      operationId: postOtp
      summary: Create code
      tags:
      - OTP
      requestBody:
        required: true
        content:
          application/json:
            schema:
              anyOf:
              - $ref: '#/components/schemas/CreateOtpSms'
              - $ref: '#/components/schemas/CreateOtpRcs'
              - $ref: '#/components/schemas/CreateOtpPush'
              - $ref: '#/components/schemas/CreateOtpVoice'
              - $ref: '#/components/schemas/CreateOtpEmail'
              - $ref: '#/components/schemas/CreateOtpWhatsApp'
      responses:
        '200':
          description: The code has been created.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/OtpResponse'
        '400':
          $ref: '#/components/responses/BadRequest_2'
        '401':
          $ref: '#/components/responses/Unauthorized_2'
        '500':
          $ref: '#/components/responses/UnknownError_2'
      security:
      - ProductToken: []
      x-operation-id-source: normalized
      x-operation-id-original: create_otp
    servers:
    - url: https://api.cm.com/otp/v2
  /otp/{id}/verify:
    parameters:
    - $ref: '#/components/parameters/id'
    post:
      operationId: postOtpByIdVerify
      summary: Verify code
      tags:
      - OTP
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/OtpVerify'
      responses:
        '200':
          description: Successful request.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/OtpResponse'
        '400':
          $ref: '#/components/responses/BadRequest_2'
        '401':
          $ref: '#/components/responses/Unauthorized_2'
        '500':
          $ref: '#/components/responses/UnknownError_2'
      security:
      - ProductToken: []
      x-operation-id-source: normalized
      x-operation-id-original: verify_otp
    servers:
    - url: https://api.cm.com/otp/v2
  /voiceapi/v2/otp:
    post:
      tags:
      - OTP
      summary: OTP
      description: Send out a Voice OTP (one time password). For more information, see the Voice OTP documentation.
      requestBody:
        description: Details of the OTP instruction.
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/OtpInstruction'
          text/json:
            schema:
              $ref: '#/components/schemas/OtpInstruction'
          application/*+json:
            schema:
              $ref: '#/components/schemas/OtpInstruction'
      responses:
        '200':
          description: Call is queued
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CallQueuedEvent'
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ExceptionEvent'
        '401':
          description: Unauthorized
      security:
      - X-CM-PRODUCTTOKEN: []
      operationId: postVoiceapiV2Otp
      x-operation-id-source: derived
    servers:
    - url: https://api.cm.com
components:
  schemas:
    VerifyRequest:
      type: object
      title: Verify request
      properties:
        id:
          type: string
          format: uuid
          description: The unique identifier for the code.
        code:
          type: string
          description: The code received via SMS/Push or Voice.
          examples:
          - '12345'
    GenerateRequest:
      type: object
      title: Generate request
      properties:
        recipient:
          type: string
          description: Phone number in international format without +.
          examples:
          - '0031601234567'
        sender:
          type: string
          description: 'The name or phone number of the sender. Please note that alphanumeric sender is not supported in all countries. If `allowVoice` is `true`, sender must be a phone number. For alphanumeric senders, the length should be between 3 and 11 characters.

            '
          examples:
          - My company
        length:
          type: integer
          description: The length of the code.
          minimum: 4
          maximum: 10
          default: 5
        expiry:
          type: integer
          description: The expiry in seconds.
          minimum: 10
          maximum: 3600
          default: 60
        allowVoice:
          type: boolean
          description: Send the code via a voice call.
        voiceLanguage:
          type: string
          description: Change the language of the voice call.
          enum:
          - de
          - en
          - es
          - fr
          - it
          - nl
          default: en
        allowPush:
          type: boolean
          description: Allow code to be send via push notification. When allowPush is set to `true`, a valid app key is required.
          default: false
        appKey:
          type: string
          description: The app key GUID.
          format: uuid
        message:
          type: string
          description: 'Set a custom message. You can use the placeholder {code} which will be replaced by the actual code. e.g. Your code is: {code}."

            '
      required:
      - recipient
      - sender
      examples:
      - recipient: '0031601234567'
        sender: My company
    GenerateResponse:
      type: object
      title: Generate response
      properties:
        id:
          type: string
          format: uuid
          description: The unique identifier for the code. Use this in combination with the received code to verify the code.
          readOnly: true
        createdAt:
          type: string
          description: The date the code was created.
          format: date-time
          readOnly: true
        expireAt:
          type: string
          description: The date the code will expire.
          format: date-time
          readOnly: true
    VerifyResponse:
      type: object
      title: Verify response
      properties:
        valid:
          type: boolean
          description: Indicates if the code was valid. Once a code has been successfully validated, it cannot be validated again.
          readOnly: true
    ErrorResponse:
      title: Error response
      type: object
      properties:
        status:
          type: integer
          format: int32
          description: Response status code, should match HTTP error code.
          examples:
          - 400
        message:
          type: string
          description: High level description of the error that occurred.
          examples:
          - The request is invalid
    CreateOtpBase:
      type: object
      properties:
        channel:
          type: string
          description: The channel to send the code.
        digits:
          type: integer
          description: The length of the code.
          minimum: 4
          maximum: 10
          default: 5
        expiry:
          type: integer
          description: The expiry of the code in seconds.
          minimum: 10
          maximum: 3600
          default: 60
      required:
      - channel
    CreateOtpMessage:
      type: object
      allOf:
      - $ref: '#/components/schemas/CreateOtpBase'
      properties:
        from:
          type: string
          description: The number or name of the sender. This must be a valid phone number in E.164 format or an alphanumeric string between 3 and 11 characters. Please note that alphanumeric senders are not supported in all countries.
          examples:
          - '+31601234567'
        to:
          type: string
          description: The receiver of the code. This must be a valid phone number in E.164 format.
          examples:
          - '+31602345678'
        message:
          type: string
          description: Set a custom message. You can use the placeholder {code}, this will be replaced by the actual code.
          maxLength: 160
          examples:
          - 'Your code is: {code}'
      required:
      - from
      - to
    CreateOtpWhatsApp:
      title: Create OTP (WhatsApp)
      type: object
      allOf:
      - $ref: '#/components/schemas/CreateOtpBase'
      properties:
        channel:
          examples:
          - whatsapp
          enum:
          - whatsapp
        from:
          type: string
          description: The number of the sender. This must be a valid phone number in E.164 format.
          examples:
          - '+31601234567'
        to:
          type: string
          description: The number of the receiver. This must be a valid phone number in E.164 format.
          examples:
          - '+31602345678'
        message:
          type: string
          description: Set a custom message. You can use the placeholder {code}, this will be replaced by the actual code.
          maxLength: 160
        locale:
          type: string
          description: The locale of the message. This must match with configured locales for the template.
      required:
      - from
      - to
    CreateOtpVoice:
      type: object
      title: Create OTP (Voice)
      allOf:
      - $ref: '#/components/schemas/CreateOtpBase'
      properties:
        channel:
          examples:
          - voice
          enum:
          - voice
        from:
          type: string
          description: The number of the sender. This must be a valid phone number in E.164 format.
          examples:
          - '+31601234567'
        to:
          type: string
          description: The number of the receiver. This must be a valid phone number in E.164 format.
          examples:
          - '+31602345678'
        locale:
          type: string
          description: Set the spoken language in the voice call.
          enum:
          - de-DE
          - en-AU
          - en-GB
          - en-IN
          - en-US
          - es-ES
          - fr-CA
          - fr-FR
          - it-IT
          - ja-JP
          - nl-NL
          default: en-GB
        anonymous:
          type: boolean
          description: Set whether the number of the caller (from) is hidden in the voice call.
          default: true
        message:
          type: string
          description: Set a custom message to be used in the voice call.
          maxLength: 500
        gender:
          type: string
          description: Set the gender of the text-to-speech voice used in the voice call.
          enum:
          - male
          - female
          default: female
        number:
          type: integer
          format: int32
          description: Set which text-to-speech voice to use in the voice call. For the list of numbers, see [TTS voices](https://developers.cm.com/voice/docs/supported-languages).
          minimum: 1
          maximum: 2147483647
        premium:
          type: boolean
          description: Set whether a premium text-to-speech voice is used in the voice call. Enabling this may incur additional cost.
          default: false
      required:
      - from
      - to
    CreateOtpSms:
      type: object
      title: Create OTP (SMS)
      allOf:
      - $ref: '#/components/schemas/CreateOtpMessage'
      properties:
        channel:
          examples:
          - sms
          enum:
          - sms
    CreateOtpEmail:
      title: Create OTP (Email)
      type: object
      allOf:
      - $ref: '#/components/schemas/CreateOtpBase'
      properties:
        channel:
          examples:
          - email
          enum:
          - email
        to:
          type: string
          description: The email address of the receiver.
          format: email
          examples:
          - example@example.com
        locale:
          type: string
          description: The locale for the email template.
        message:
          type: string
          description: Set a custom message to be used in the email message.
          maxLength: 500
      required:
      - to
    OtpResponse:
      type: object
      title: OTP Response
      properties:
        id:
          type: string
          format: uuid
          description: The identifier for the code. Use this in combination with the received code to verify the code.
          readOnly: true
        channel:
          type: string
          description: The channel used to send the code.
          enum:
          - email
          - push
          - rcs
          - sms
          - voice
          - whatsapp
          examples:
          - sms
        verified:
          type: boolean
          description: Indicates if the code is verified. Once a code has been successfully validated, it cannot be validated again.
          default: false
          readOnly: true
        createdAt:
          type: string
          description: The date the OTP was created.
          format: date-time
          readOnly: true
        expiresAt:
          type: string
          description: The date the OTP will expire.
          format: date-time
          readOnly: true
    CreateOtpRcs:
      type: object
      title: Create OTP (RCS)
      allOf:
      - $ref: '#/components/schemas/CreateOtpMessage'
      properties:
        channel:
          examples:
          - rcs
          enum:
          - rcs
    OtpVerify:
      type: object
      title: OTP Verification Request
      properties:
        code:
          type: string
          description: The code received via the specified channel.
          examples:
          - '12345'
      required:
      - code
    CreateOtpPush:
      type: object
      title: Create OTP (Push)
      allOf:
      - $ref: '#/components/schemas/CreateOtpMessage'
      properties:
        channel:
          examples:
          - push
          enum:
          - push
        pushAppKey:
          type: string
          description: The app key.
          format: uuid
      required:
      - pushAppKey
    ErrorResponse_2:
      title: Error response
      type: object
      properties:
        status:
          type: integer
          format: int32
          description: Response status code, should match HTTP error code.
          examples:
          - 400
        message:
          type: string
          description: High level description of the error that occurred.
          examples:
          - The request is invalid
        code:
          $ref: '#/components/schemas/ErrorCode'
    ErrorCode:
      type: integer
      description: "Error code description:\n\n * 1000 - Unknown error\n * 1001 - Invalid request\n * 2000 - Validation error\n * 2001 - Invalid `channel` field\n * 2002 - Invalid `from` field\n * 2003 - Invalid `to` field\n * 2004 - Invalid `message` field\n * 2005 - Invalid `digits` field\n * 2006 - Invalid `expiry` field\n * 2007 - Invalid `locale` field\n * 2008 - Invalid `pushAppKey` field\n * 2009 - Invalid `anonymous` field\n * 3001 - OTP was not found\n * 3002 - OTP has expired\n * 3003 - OTP is already verified\n * 3004 - Too many attempts\n * 3005 - Channel is not configured\n * 3006 - Subscription is required\n * 4001 - Failed to send message\n"
      enum:
      - 1000
      - 1001
      - 2000
      - 2001
      - 2002
      - 2003
      - 2004
      - 2005
      - 2006
      - 2007
      - 2008
      - 2009
      - 3001
      - 3002
      - 3003
      - 3004
      - 3005
      - 3006
      - 4001
      examples:
      - 1000
    Voice:
      title: Voice
      required:
      - gender
      - language
      - number
      type: object
      properties:
        language:
          maxLength: 6
          minLength: 5
          pattern: ^[a-zA-Z]{2,3}-[a-zA-Z]{2,3}$
          type: string
          description: 'The language (5 character locale) of the voice to use. Examples: en-US, en-GB, nl-NL. Defaults to en-GB'
          example: en-GB
        gender:
          $ref: '#/components/schemas/Gender'
        number:
          maximum: 2147483647
          minimum: 1
          type: integer
          description: 'Usually `1`, but if the selected language and gender support multiple voices, you can use this to make

            a selection between the different ones. To see the available voices, please see the

            <a href="/voice/tts/supported-languages">TTS voices documentation</a>.'
          format: int32
          example: 1
        volume:
          maximum: 4
          minimum: -4
          type: integer
          description: The volume level of the voice. Must be a value between -4 and 4. Defaults to 0.
          format: int32
          example: 2
        premium:
          type: boolean
          description: 'Whether to use a premium text-to-speech voice. Please be aware that additional costs will be charged for the

            use of premium voices. Defaults to `false`.'
          example: true
      additionalProperties: false
      description: The properties in this class are used to select the required TTS voice.
    ExceptionEvent:
      title: Exception Event
      type: object
      properties:
        type:
          type:
          - string
          - 'null'
          description: The Type of event.
          readOnly: true
        call-id:
          type: string
          description: The ID of the call this event belongs to.
          format: uuid
        instruction-id:
          type:
          - string
          - 'null'
          description: The ID of the instruction the event is a result of.
        queue-id:
          type:
          - string
          - 'null'
          description: The ID of the queue.
        code:
          $ref: '#/components/schemas/ExceptionEventCode'
        title:
          type:
          - string
          - 'null'
          description: The title of the exception.
          readOnly: true
        message:
          type:
          - string
          - 'null'
          description: Some explanatory text on the exception.
      additionalProperties: false
      description: And event containing an exception.
    Gender:
      title: Gender
      enum:
      - Male
      - Female
      type: string
      description: Genders supported by TTS.
    VoicemailResponse:
      title: Voicemail Response
      enum:
      - Ignore
      - Restart
      - Stop
      - Disconnect
      type: string
      description: The type that determines the flow of Voicemail detection.
    CodeType:
      title: Code Type
      enum:
      - Default
      - TTS
      - Custom
      type: string
      description: The type of the OTP code
    PromptType:
      title: Prompt Type
      enum:
      - File
      - TTS
      - TTS_SSML
      type: string
      description: The type of the prompt, to distinguish between a filename and a string that needs to be tts-ed.
    OtpInstruction:
      required:
      - caller
      - code
      type: object
      properties:
        instruction-id:
          maxLength: 64
          type:
          - string
          - 'null'
          description: 'Optional string that allows you to uniquely identify the placed outbound call. Its value is also included

            in the callback and Call Detail Records (CDRs).'
          example: mycustomid
        callee:
          maxLength: 24
          pattern: ^(\+|00)?[1-9]\d{6,14}$
          type:
          - string
          - 'null'
          description: 'The number to dial. When the number is invalid, the request will be rejected. Must be in valid international

            E.164 format.'
          example: '+31612345678'
        callees:
          pattern: ^(\+|00)?[1-9]\d{6,14}$
          maxItems: 100
          type:
          - array
          - 'null'
          items:
            type: string
          description: 'List of multiple numbers to dial. When the list contains one or more invalid numbers, the request will be

            rejected. Must be in valid international E.164 format.'
          example:
          - '+31612345678'
          - '+31612345679'
        caller:
          maxLength: 24
          minLength: 1
          pattern: ^(\+|00)?[1-9]\d{6,14}$
          type: string
          description: The caller ID to display on the recipient's phone. Must be in valid international E.164 format.
          example: '+31612345678'
        anonymous:
          type: boolean
          description: Indicates whether the caller ID should be hidden. Defaults to `false`.
          example: false
        callback-url:
          type:
          - string
          - 'null'
          description: 'URL that will be called when the call is finished. The body of this POST request will contain details about

            the call or calls.'
          format: uri
        max-ringing-timeout:
          maximum: 60
          minimum: 10
          type:
          - integer
          - 'null'
          description: 'Determines how long the Voice API will wait for the callee to answer the call. Cancels the ringing call

            after the timeout period exceeded. Defaults to `60`.'
          format: int32
          example: 60
        intro-prompt:
          maxLength: 500
          type:
          - string
          - 'null'
          description: 'Optional prompt to play when the call is first answered. This can be either TTS or SSML, or the path to an

            audio file in your Voice Audio Manager.'
          example: This is the CM.com OTP Service.
        intro-prompt-type:
          $ref: '#/components/schemas/PromptType'
        code-prompt:
          maxLength: 500
          type:
          - string
          - 'null'
          description: 'Optional prompt to play right before playing the actual OTP code. This can be either TTS or SSML, or the

            path to an audio file in your Voice Audio Manager. This prompt is also replayed when the code is replayed.'
          example: 'Your one time password is:'
        code-prompt-type:
          $ref: '#/components/schemas/PromptType'
        code:
          maxLength: 64
          minLength: 1
          type: string
          description: The code to read to the caller. Note that this code is read character per character, not as a word or number.
          example: 1234abc
        code-type:
          $ref: '#/components/schemas/CodeType'
        replay-prompt:
          maxLength: 500
          type:
          - string
          - 'null'
          description: 'Optional prompt instructing the callee to press 1 to replay the OTP. This can be either TTS or SSML, or the

            path to an audio file in your Voice Audio Manager.'
          example: Press 1 to replay the message.
        replay-prompt-type:
          $ref: '#/components/schemas/PromptType'
        outro-prompt:
          maxLength: 500
          type:
          - string
          - 'null'
          description: 'Optional prompt instructing the callee to press 1 to replay the Notification. This can be either TTS or

            SSML, or the path to an audio file in your Voice Audio Manager.'
          example: Press 1 to replay the message.
        outro-prompt-type:
          $ref: '#/components/schemas/PromptType'
        max-replays:
          maximum: 3
          minimum: 0
          type:
          - integer
          - 'null'
          description: The number of times the OTP can be replayed.
          format: int32
          example: 3
        auto-replay:
          type:
          - boolean
          - 'null'
          description: Whether to automatically replay the OTP. Defaults to `false`.
          example: false
        voice:
          $ref: '#/components/schemas/Voice'
        voicemail-response:
          $ref: '#/components/schemas/VoicemailResponse'
      additionalProperties: false
      description: Instruction to send an OTP (One Time Password) to the callee.
    ExceptionEventCode:
      title: Exception Event Code
      enum:
      - InvalidJson
      - SignatureError
      - FileNotFound
      - InvalidInstruction
      - InvalidParameter
      - InsufficientBalance
      - PremiumNotAllowed
      - CallLimitReached
      - TooManyNumbers
      type: string
      description: Enum of the different codes of exceptions.
    CallQueuedEvent:
      title: Call Queued Event
      type: object
      properties:
        type:
          type:
          - string
          - 'null'
          description: The Type of event.
          readOnly: true
        call-id:
          type: string
          description: The ID of the call this event belongs to.
          format: uuid
        instruction-id:
          type:
          - string
          - 'null'
          description: The ID of the instruction the event is a result of.
        queue-id:
          type:
          - string
          - 'null'
          description: The ID of the queue.
        caller:
          type:
          - string
          - 'null'
          description: The id (e.g. number) of the caller.
        callee:
          type:
          - string
          - 'null'
          description: The id (e.g. number) of the callee.
        success:
          type: boolean
          description: True if the PlaceCallInstruction was accepted.
        error:
          type:
          - string
          - 'null'
          description: True if the PlaceCallInstruction was accepted.
      additionalProperties: false
      description: 'Event that is a result (basically a direct response) to the PlaceCallInstruction.

        This one is generally used in the async versions of the calls.'
  responses:
    UnknownError:
      description: Unknown error
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
          example:
            status: 500
            message: An unknown error occurred.
    Unauthorized:
      description: Unauthorized
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
          example:
            status: 401
            message: Unauthorized
    BadRequest:
      description: Bad request
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
          example:
            status: 400
            message: The request is invalid
    UnknownError_2:
      description: Unknown error
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse_2'
          example:
            status: 500
            message: An unknown error occurred.
            code: 1000
    Unauthorized_2:
      description: Unauthorized
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse_2'
          example:
            status: 401
            message: Unauthorized
            code: 3006
    BadRequest_2:
      description: Bad request
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse_2'
          example:
            status: 400
            message: The request is invalid
            code: 2000
  parameters:
    id:
      name: id
      in: path
      schema:
        type: string
        format: uuid
      required: true
      description: The identifier of the OTP
      example: 5924b029-6ede-4cb9-a252-0440a85fd350
  securitySchemes:
    ProductToken:
      type: apiKey
      in: header
      name: X-CM-ProductToken
    X-CM-PRODUCTTOKEN:
      type: apiKey
      description: Your producttoken
      name: X-CM-PRODUCTTOKEN
      in: header
x-refined-from:
- cm-com-verification-otp-v1-openapi.yml
- cm-com-verification-otp-v2-openapi.yml
- cm-com-voice-voice-api-v2-openapi.yml