Telesign Calls API

openapi: 3.2.0
info:
  title: Voice Verify Calls API
  version: '1.0'
  description: Use the Telesign Voice Verify API to send a one-time passcode (OTP) in a voice call to a recipient phone number.
  contact:
    name: Telesign Customer Support Team
    email: support@telesign.com
servers:
- url: https://rest-ww.telesign.com
security:
- Basic: []
tags:
- name: Calls
paths:
  /v1/verify/call:
    post:
      summary: Send a voice verification code
      operationId: sendVoiceVerifyCode
      responses:
        '200':
          description: "**Success.** Your request was fulfilled and resulted in a new resource being created. If you want to code against a response, you should retrieve the status or error code and use that rather than the HTTP status response.          \n\n| Status Code | Associated Text String | Description                                           |\n|-------------|------------------------|-------------------------------------------------------|\n| 100         | Call answered          | The call was answered.                                |\n| 101         | Not answered           | The call was not answered.                            |\n| 103         | Call in progress       | Telesign is either making the call or playing the voice message.                                        |\n| 105         | Call not handled yet   | The verification call has not yet been attempted.     |\n| 106         | Call failed            | An error occurred. No further attempt to call will be made.                                                 |\n| 107         | Line busy              | The line is busy.                                     |\n| 108         | Call canceled by Telesign      | Call canceled by Telesign.              |\n| 129         | Call blocked by your request  | Telesign blocked the call before it was placed. This is due to your prior submitted request to blocklist this phone number.                                    |\n| 130         | Call blocked by Telesign       | Telesign blocked the phone call. This can happen if the message contains inappropriate material, or if Telesign believes the client is abusing the service.  |\n| 500         | Transaction not attempted   | No request was attempted with this product.       |\n| 501         | Not authorized         | No permissions for this resource, or authorization failed.                                               |\n| 599         | Status not available   | The system is unable to provide status at this time.  |\n"
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/sendVoiceCodeResponse'
              examples:
                Example:
                  value:
                    reference_id: 0123456789ABCDEF0123456789ABCDEF
                    sub_resource: call
                    errors: []
                    status:
                      code: 103
                      description: Call in progress
                      updated_on: '2024-03-11T21:09:19.378673Z'
                    verify:
                      code_state: UNKNOWN
                      code_entered: ''
                    voice:
                      caller_id: '+11234567891'
        '400':
          description: 'Bad request, the request could not be understood by the server due to malformed syntax. If you want to code against a response, you should retrieve the status or error code and use that rather than the HTTP status response.


            | Error Code | Associated Text String   |

            |------------|--------------------------|

            | -10001     | Not Allowed Host (indicates that the IP address you are connecting from is not authorized to access the service)                 |

            | -40006     | Bad Request              |

            | -40007     | No Data Submitted        |

            '
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/failState'
              examples:
                Example:
                  value:
                    reference_id: 0123456789ABCDEF0123456789ABCDEF
                    sub_resource: call
                    errors:
                    - code: -40006
                      description: Bad Request
                    status:
                      code: 500
                      description: Transaction not attempted
                      updated_on: '2024-03-11T21:09:19.378673Z'
        '401':
          description: '**Unauthorized.** The request requires user authentication. If you want to code against a response, you should retrieve the status or error code and use that rather than the HTTP status response.


            | Error Code | Description   |

            |------------|--------------------------|

            | -10009     | Invalid source IP address|

            | -20002     | This product is not enabled for this Customer ID.                      |

            | -20003     | This feature is not enabled for this Customer ID.                      |

            |-20,004|This product is not enabled for this country.|

            | -30000     | Invalid Customer ID.     |

            | -30001     | Customer ID Account Suspended.               |

            | -30002     | Customer ID Account Not Activated.               |

            | -30003     | Customer ID new account limit reached.           |

            | -40002     | Not Authorized           |

            '
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/failState'
              examples:
                Example:
                  value:
                    reference_id: 0123456789ABCDEF0123456789ABCDEF
                    sub_resource: call
                    errors:
                    - code: -30000
                      description: Invalid Customer ID.
                    status:
                      code: 500
                      description: Transaction not attempted
                      updated_on: '2024-03-11T21:09:19.378673Z'
        '404':
          description: '**Not Found.** The server has not found anything matching the Request-URI. If you want to code against a response, you should retrieve the status or error code and use that rather than the HTTP status response.


            | Error Code | Associated Text String   |

            |------------|--------------------------|

            | -10001     | CustomerID/ReferenceID not found (returned when the reference ID given does not exist)          |

            | -10004     | Reference ID expired     |

            | -40004     | Resource Not Found       |

            '
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/failState'
              examples:
                Example:
                  value:
                    reference_id: 0123456789ABCDEF0123456789ABCDEF
                    sub_resource: call
                    errors:
                    - code: -40004
                      description: Resource Not Found
                    status:
                      code: 500
                      description: Transaction not attempted
                      updated_on: '2024-03-11T21:09:19.378673Z'
        '405':
          description: '**Method not allowed.** The request method is known by the server but has been disabled and cannot be used.


            | Error Code | Associated Text String   |

            |------------|--------------------------|

            | -40005     | Method Not Allowed       |

            '
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/failState'
              examples:
                Example:
                  value:
                    reference_id: 0123456789ABCDEF0123456789ABCDEF
                    sub_resource: call
                    errors:
                    - code: -40005
                      description: Method Not Allowed
                    status:
                      code: 500
                      description: Transaction not attempted
                      updated_on: '2024-03-11T21:09:19.378673Z'
        '429':
          description: '**Too Many Requests.**


            | Error Code | Associated Text String   |

            |------------|--------------------------|

            | -40008     | {product} exceeded transaction hard cap. Request denied.          |

            '
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/failState'
              examples:
                Example:
                  value:
                    reference_id: 0123456789ABCDEF0123456789ABCDEF
                    sub_resource: call
                    errors:
                    - code: -40008
                      description: VoiceVerify exceeded transaction hard cap. Request denied.
                    status:
                      code: 500
                      description: Transaction not attempted
                      updated_on: '2024-03-11T21:09:19.378673Z'
        '503':
          description: '**Service Unavailable.** The system is unavailable, try again.


            | Error Code | Associated Text String   |

            |------------|--------------------------|

            | -90001     | System Unavailable, please try again later.  |'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/failState'
              examples:
                Example:
                  value:
                    reference_id: 0123456789ABCDEF0123456789ABCDEF
                    sub_resource: call
                    errors:
                    - code: -90001
                      description: System Unavailable, please try again later.
                    status:
                      code: 500
                      description: Transaction not attempted
                      updated_on: '2024-03-11T21:09:19.378673Z'
      description: 'Use this action to send a voice message with a one-time passcode (OTP) to a recipient phone number.


        To add this product to your account, contact a Telesign expert. This product is available for full-service accounts only.


        ## General requirements

        * **Authentication:** Basic (easiest to implement) and Digest

        * **Encoding:** Accepts only UTF-8 encoded unicode characters as inputs

        * **Accepts:** `application/x-www-form-urlencoded`

        * **Required headers:** `Content-Type - application/x-www-form-urlencoded`

        * **Rate limit:** Default rate limits by product'
      requestBody:
        content:
          application/x-www-form-urlencoded:
            schema:
              type: object
              properties:
                phone_number:
                  description: The end user's phone number, as a string of digits without spaces or punctuation, beginning with the country dialing code (for example, "1" for North America).
                  type: string
                ucid:
                  description: 'A string specifying a use case code. Choices include -

                    * ATCK - for use in a 2FA situation like updating an account or logging in

                    * BACF - for creating an account where the service may be vulnerable to bulk attacks and fraudsters

                    * BACS - for creating an account where the service may be vulnerable to bulk attacks or individual spammers

                    * CHBK - for use when someone is trying to buy something expensive or unusual and you want to verify it is really them

                    * CLDR - calendar event

                    * LEAD - for use in a situation where you require a person to enter personal information in order to obtain information about something like a loan or realty or school, and you want to check if the person is bogus or not

                    * OTHR - if you have a situation not addressed by other tags

                    * PWRT - for use in a situation where a password reset is required

                    * RESV - for use when you have end users making reservations and not showing up, and you want to be able to include phone verification in the loop

                    * RXPF - for use when you are trying to prevent prescription fraud

                    * SHIP - for use when you are sending a shipping notification

                    * THEF - for use when you are trying to prevent an end user from deactivating or redirecting a phone number in order to take over someone else''s identity

                    * TRVF - for use when you are transferring money and you want to check to see if it is approved by sending a text message or phone call to your end user. This is similar to CHBK, but is specifically for a money transaction

                    * UNKN - if you have a situation not addressed by other tags (same as OTHR)

                    '
                  type: string
                originating_ip:
                  description: 'Your end user''s IP address (do not send your own IP address). IPv4 and IPv6 are supported. For IPv4, the value must be in the format defined by the Internet Engineering Task Force (IETF) in the Internet-Draft document titled <a href="https://tools.ietf.org/html/rfc791">Internet Protocol</a>. For IPv6, the value must be in the format defined by the IETF in the Internet-Draft document titled <a href="https://tools.ietf.org/html/rfc4291#section-2.2">IP Version 6 Addressing Architecture</a>.

                    '
                  type: string
                language:
                  type: string
                  default: en-US
                  example: en-GB
                  description: A code specifying the language of the predefined template you wish to use. For a complete list of codes, see [Voice Verify API - Supported languages for audio templates](/enterprise/docs/voice-verify-api-supported-languages-for-audio-templates). If you also include the `tts_message` parameter in this request, a different set of language codes is supported by the service; for a complete list of those codes, see [Voice - Supported languages for text-to-speech](/enterprise/docs/voice-supported-languages-for-text-to-speech). If the language you want to use is not supported, you may be able to add a custom audio template to your account, contact our [Customer Support Team](mailto:support@telesign.com) for more details.
                verify_code:
                  description: By default, the verification code used for the code challenge is a randomly generated five-digit number assigned by Telesign. If you prefer to use your own verification code, you can override the default behavior by including a three- to five-digit numeric value between 100 and 99999 as the value for this parameter.
                  type: string
                prompt_message:
                  description: This message is to be used in conjunction with `prompt_digit`. You provide a message to play, it is converted to text-to-speech and sent in a call and played for the end user. You are limited to 2000 code points. The message should contain the digit you want to press. For example, you might have the message - Press 7 to continue. Make sure the digit in your message matches the digit you send for `prompt_digit`. If the end user presses the correct digit, then the message you have for the `message` parameter plays. If the end user does not press the correct digit, the follow up message does not play, they hear the regular message repeated again. This can happen up to three times. If an end user presses incorrect digits on the third play through, the call hangs up. If the end user does not press any digits in the allotted time, the message repeats. If the end user does not press any digits a second time in a row, the call hangs up. All messages use the same `language` tag if you choose to include one.
                  type: string
                prompt_digit:
                  description: This digit is to be used in conjunction with `prompt_message`. Provide a single digit 0-9 that you want the end user to press. After playing the prompt message, the system will wait and give the end user two chances to press the correct digit. If they do, the message in the `message` parameter plays. All messages use the same `language` tag if you choose to include one.
                  type: string
                caller_id:
                  description: This parameter allows you to set a phone number as caller ID for a Voice Verify API call sent to your end users. In order to use a specific caller ID, you must purchase a phone number from Telesign. This can be done by contacting our Customer Support Team and asking to buy one or more numbers. Be aware that 100% preservation of a caller ID value is not guaranteed. Telesign or a terminating operator may override the caller ID value that your end user will receive in order to improve delivery quality or follow local Telecom regulations in particular countries.
                  type: string
                tts_message:
                  type: string
                  description: Provides a custom text-to-speech (TTS) message containing the verification one-time passcode (OTP) to play to the end user; this overrides the default template for the specified language. You must specify the message's language in the `language` parameter and the variable `$$CODE$$` in the message text. See [Voice Verify API - Text-to-speech tips](/enterprise/docs/voice-verify-api-text-to-speech-tips) for more details about this feature.
                  example: Hello. Thank you for using our phone verification system. Your code is $$CODE$$. Once again, your code is $$CODE$$. Goodbye.
                pressx:
                  description: 'PressX is a feature that allows you to send an end user a message that asks them to press a digit in order to hear their verification code. The message is in English, and as follows: Hello. Thank you for using the phone verification system. Please press *digit* to hear your code. The *digit* is randomly selected by Telesign, and the end user gets two tries to get the correct digit. If the end user presses the correct digit, they will receive a message containing their verification code. Please note that this feature is only available in English, so you cannot use a language tag for other languages with it. To use this feature, you would put `pressx=1` in the body of your request. You cannot use this feature with TTS.'
                  type: string
                extension_type:
                  description: 'It is not an issue when a user’s phone number belongs to a modern Private Branch Exchange (PBX) because outside numbers are usually assigned to individual extensions. Older PBX systems on the other hand, require extra call processing because incoming calls require either a live switchboard operator or an automated attendant to request the number of the user’s extension before completing the call. By default, Telesign does not support older PBX systems, but you can enable support for either live or automated switchboard scenarios by including the extension_type parameter. When you use this parameter, you must also use extension_template.

                    '
                  type: string
                extension_template:
                  description: A numerical string that specifies the extension used in the call, as described above. If the user must be reached at an extension, then use this parameter to specify the extension number. The extension string is composed of digits. You may use a maximum of 28 characters to specify your extension. For the extension_type=1 (DTMF digits are dialed), you can include commas in the extension number string, where each comma represents a one second pause in the dialing sequence.
                  type: string
                callback_url:
                  type: string
                  description: A URL where you want delivery reports to be sent related to your request. This overrides any default callback URL that you've previously set. The override only lasts for this request.
              required:
              - phone_number
      tags:
      - Calls
components:
  schemas:
    failState:
      title: failState
      allOf:
      - $ref: '#/components/schemas/sharedResSchema'
      - type: object
        properties:
          status:
            type: object
            properties:
              code:
                type: integer
                example: 500
              description:
                type: string
                example: Transaction not attempted
    errorObject:
      title: errorObject
      type: object
      properties:
        code:
          type: integer
          example: -10001
          description: A numeric code specifying which error occurred.
        description:
          type: string
          example: 'Invalid Request: PhoneNumber Parameter'
          description: Text describing the error that occurred.
      description: Contains properties related to an error that occurred during processing of the request.
    verifyDetails:
      title: verifyDetails
      type: object
      description: Contains properties about the status of the verification attempt by the end user (if any).
      properties:
        code_state:
          type: string
          example: UNKNOWN
          enum:
          - VALID
          - INVALID
          - UNKNOWN
          - EXPIRED
          - MAX_ATTEMPTS_EXCEEDED
          description: "Indicates whether the verification code you provided in your request matches that sent by Telesign to the end-user. Possible values are: \n* `VALID` - The codes match. \n* `INVALID` - The codes do not match.\n* `EXPIRED` - The match was attempted after the end of the validity period for the code.\n* `MAX_ATTEMPTS_EXCEEDED` - The match was attempted after the end user already had made the maximum allowed number of attempts for the code.\n* `UNKNOWN` - Any other state."
        code_entered:
          type: string
          description: If the end user entered a code, what they entered is provided here.
          example: '12345'
      required:
      - code_state
      - code_entered
    sharedResSchema:
      title: sharedResSchema
      type: object
      properties:
        reference_id:
          type: string
          example: 0123456789ABCDEF0123456789ABCDEF
          description: A unique, randomly generated hex value that identifies your web service request.
        sub_resource:
          type: string
          example: call
          description: The sub-resource in the URI path from your original request to initiate this transaction. Indicates which form of verification you used.
        errors:
          type: array
          description: Contains an object for each error condition that resulted from the request.
          items:
            $ref: '#/components/schemas/errorObject'
        status:
          $ref: '#/components/schemas/status'
    sendVoiceCodeResponse:
      title: sendVoiceCodeResponse
      allOf:
      - $ref: '#/components/schemas/sharedResSchema'
      - type: object
        properties:
          verify:
            $ref: '#/components/schemas/verifyDetails'
          voice:
            $ref: '#/components/schemas/voiceDetails'
    voiceDetails:
      title: voiceDetails
      type: object
      properties:
        caller_id:
          type: string
          example: '+11234567890'
          description: The [sender ID](https://support.telesign.com/s/article/What-is-a-Sender-ID) used for the call.
    status:
      title: status
      type: object
      description: Contains details about the request status.
      properties:
        code:
          type: integer
          description: A numeric code indicating the processing status of this request.
          example: 103
        description:
          type: string
          description: A text description of the status code.
          example: Call in progress
        updated_on:
          type: string
          description: 'An [RFC 3339](http://www.ietf.org/rfc/rfc3339.txt) timestamp indicating when the request status was updated. '
          example: '2024-03-11T21:09:19.378673Z'
      required:
      - code
      - description
      - updated_on
  securitySchemes:
    Basic:
      type: http
      scheme: basic