openapi: 3.2.0
info:
  title: Smart Verify One-time passcodes API
  version: '1.0'
  description: The Telesign Smart Verify API decides whether it is most effective to send a one-time passcode in an SMS or in a voice message.
  contact:
    name: Telesign Customer Support Team
    email: support@telesign.com
servers:
- url: https://rest-ww.telesign.com
security:
- Basic: []
tags:
- name: One-time passcodes
paths:
  /v1/verify/smart:
    post:
      summary: Send smart verify code
      operationId: sendSmartVerifyCode
      responses:
        '200':
          description: Your request was fulfilled and resulted in a new resource being created. Code against the status or error code and use that rather than the HTTP status response.
          content:
            application/json:
              schema:
                allOf:
                - $ref: '#/components/schemas/sharedResponseSchema'
                - type: object
                  properties:
                    sub_resource:
                      type: string
                      description: The channel that the service used to send this message.
                      example: sms
                      enum:
                      - sms
                      - voice
                    numbering:
                      $ref: '#/components/schemas/ScoreNumbering'
                    phone_type:
                      $ref: '#/components/schemas/ScorePhoneType'
                    carrier:
                      $ref: '#/components/schemas/Carrier'
              examples:
                Example:
                  value:
                    reference_id: 0123456789ABCDEF0123456789ABCDEF
                    sub_resource: sms
                    errors: []
                    status:
                      updated_on: '2020-08-27T17:28:49.559307Z'
                      code: 290
                      description: Message in progress
                    numbering:
                      original:
                        phone_number: '7833012348'
                        complete_phone_number: '17833012348'
                        country_code: '1'
                      cleansing:
                        call:
                          cleansed_code: 100
                          country_code: '1'
                          max_length: 10
                          min_length: 10
                          phone_number: '7833012348'
                        sms:
                          cleansed_code: 100
                          country_code: '1'
                          max_length: 10
                          min_length: 10
                          phone_number: '7833012348'
                    phone_type:
                      code: '2'
                      description: MOBILE
                    carrier:
                      carrier_id: string
                      name: Verizon
        '400':
          description: Bad request, the request could not be understood by the server due to malformed syntax. Code against the status or error code and use that rather than the HTTP status response.
          content:
            application/json:
              schema:
                allOf:
                - $ref: '#/components/schemas/sharedResponseSchema'
                - $ref: '#/components/schemas/SmartVerifyShared'
              examples: {}
        '401':
          description: Unauthorized, the request requires user authentication. Code against the status or error code and use that rather than the HTTP status response.
          content:
            application/json:
              schema:
                allOf:
                - $ref: '#/components/schemas/sharedResponseSchema'
                - $ref: '#/components/schemas/SmartVerifyShared'
        '404':
          description: Not Found, the server has not found anything matching the Request-URI. Code against the status or error code and use that rather than the HTTP status response.
          content:
            application/json:
              schema:
                allOf:
                - $ref: '#/components/schemas/sharedResponseSchema'
                - $ref: '#/components/schemas/SmartVerifyShared'
        '405':
          description: Responses are based on the subresource used. Code against the status or error code and use that rather than the HTTP status response.
          content:
            application/json:
              schema:
                allOf:
                - $ref: '#/components/schemas/sharedResponseSchema'
                - $ref: '#/components/schemas/SmartVerifyShared'
        '429':
          description: Too Many Requests, the user sent too many requests in a given amount of time. Code against the status or error code and use that rather than the HTTP status response.
          content:
            application/json:
              schema:
                allOf:
                - $ref: '#/components/schemas/sharedResponseSchema'
                - $ref: '#/components/schemas/SMSVerifySuccessResponse'
        '503':
          description: Service Unavailable, system unavailable, try again. Code against the status or error code and use that rather than the HTTP status response.
          content:
            application/json:
              schema:
                allOf:
                - $ref: '#/components/schemas/sharedResponseSchema'
                - $ref: '#/components/schemas/SMSVerifySuccessResponse'
      description: 'Use this action to send a one-time passcode (OTP) to your end user with the Telesign Smart Verify API. The service decides whether it is most effective to send the code in an SMS or in a voice message.


        ## General requirements

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

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

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

        * **Responds with:** `application/json`'
      parameters:
      - schema:
          type: string
        in: header
        name: Content-Type
        description: application/x-www-form-urlencoded
        required: true
      requestBody:
        content:
          application/x-www-form-urlencoded:
            schema:
              type: object
              properties:
                phone_number:
                  type: string
                  description: The end user's phone number you want to send a message to, including the country code, as a string of digits without spaces or special characters, beginning with the country dialing code.
                ucid:
                  type: string
                  description: 'An abbreviation specifying a use case. Valid options are:

                    * 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 passwor 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 shippingnotification

                    * 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 moneyand 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).

                    '
                tts_message:
                  type: string
                  description: If you choose to pass a custom message, you use this parameter to indicate what the custom message would be for text to speech (TTS). You MUST set the language parameter if you use this parameter. If a language is not supported, Telesign may choose a default for you. If you do not set the language tag, United States English is assumed. Make sure to use $$CODE$$ in your message string, as this will generate and insert a random string with appropriate length as part of your TTS message.
                language:
                  type: string
                  description: If you use the tts_message parameter you must set the language. Choose from the list of [supported languages](/enterprise/docs/voice-verify-supported-languages-for-text-to-speech) also used by the Telesign Voice Verify API.
                sms_message:
                  type: string
                  description: If you choose to pass a custom message, you use this parameter to indicate what the custom message would be if an SMS is sent.
                preference:
                  type: string
                  description: Overrides the service's automatic method selection (SMS falling back on voice call), and attempts to force it to use your specified method. You can specify either `Voice Verify` (use call) or `SMS Verify` (use SMS) as the recommended method to attempt. Telesign uses the override method whenever possible. Telesign may ignore this specified method if the destination device does not support it.
                  enum:
                  - SMS Verify
                  - Voice Verify
                ignore_risk:
                  type: boolean
                  description: Overrides the service's automatic method selection (SMS falling back on voice call), and attempts to force it to use your specified method. You can specify either `Voice Verify` (use call) or `SMS Verify` (use SMS) as the recommended method to attempt. Telesign uses the override method whenever possible. Telesign may ignore this specified method if the destination device does not support it.
              required:
              - phone_number
        description: ''
      deprecated: true
      tags:
      - One-time passcodes
components:
  schemas:
    Carrier:
      title: Carrier
      type: object
      description: Contains details about the company that provides telecommunications services for this phone number.
      properties:
        carrier_id:
          type: string
          description: An ID specifying this carrier. Contact our [Customer Support Team](mailto:support@telesign.com) to include this property in your response.
        name:
          type: string
          description: The name of this carrier.
          example: Verizon
    ScoreRisk:
      title: ScoreRisk
      type: object
      description: Contains properties related to the risk score for the specified phone number. Only returned when this feature has been enabled by the [Telesign Customer Support Team](mailto:support@telesign.com).
      properties:
        level:
          type: string
          example: low
          description: The severity of the risk. [Score Scales](/enterprise/docs/intelligence-get-started#score-scales) provides a table with risk levels.
        recommendation:
          type: string
          description: The action that Telesign recommends that you take based on the risk score.
          example: allow
          enum:
          - allow
          - flag
          - block
        score:
          type: integer
          description: The risk score for this phone number.
    SIMSwapResponse:
      type: object
      title: SIMSwapResponse
      description: Properties related to the SIM Swap check for this transaction. This is only included if enabled by our [Customer Support Team](mailto:support@telesign.com).
      properties:
        swap_date:
          type: string
          description: 'The date of the SIM swap, if one is detected. '
          example: '2018-09-05'
        swap_time:
          type: string
          description: 'The time of the SIM swap, if one is detected. '
          example: '22:00:00'
        risk_indicator:
          type: string
          description: "Indicates the likelihood that a SIM swap occured for this number. The response ranges between `1` and `4`.\n* `1` - **(very low)** Swap did not occur or it occurred 15+ days ago. \n* `2` - **(low)** Swap occurred between 3 and 14 days ago. \n* `3` - **(medium)** Swap occurred in the last 72 hours. \n* `4` - **(high)** Swap occurred in the last 24 hours."
          example: '1'
        status:
          type: object
          description: Contains properties related to the status of the SIM Swap check.
          properties:
            code:
              type: integer
              description: 'A code indicating the status of your request. '
              example: 2800
            description:
              type: string
              description: Description of the status of your request.
              example: Request successfully completed
    SMSVerifySuccessResponse:
      title: SMSVerifySuccessResponse
      description: ''
      allOf:
      - type: object
        properties:
          verify:
            type: object
            description: Contains properties related to the verification status.
            properties:
              code_state:
                type: string
                description: Indicates whether the verification code you provided in your request matches that sent by Telesign to the end-user. At this point in the verification process, the status is always `UNKNOWN`.
                enum:
                - UNKNOWN
                example: UNKNOWN
              code_entered:
                type: string
                description: Always set to an empty string. There is no code entered by the end user at this point in the verification process.
          additional_info:
            type: object
            description: Properties related to optional features you have enabled through our Customer Support Team.
            properties:
              mcc:
                type: string
                description: Mobile country code (MCC) of the destination number.
              mnc:
                type: string
                description: Mobile network code (MNC) of the destination number.
              price:
                type: string
                description: The price of the message you are sending.
      - $ref: '#/components/schemas/VerifyPlusResPackages'
      x-examples: {}
    ScorePhoneType:
      title: ScorePhoneType
      type: object
      description: This object is only included if enabled by the [Telesign Customer Support Team](mailto:support@telesign.com).
      properties:
        code:
          type: string
          description: One of the [phone type codes](/enterprise/docs/codes-languages-and-time-zones#phone-type-codes).
          example: '2'
        description:
          type: string
          description: Text describing the phone type.
          example: MOBILE
    errorObject:
      type: object
      title: errorObject
      description: Contains properties related to an error that occurred during processing of the request.
      properties:
        code:
          type: integer
          description: A numeric code specifying which error occurred.
          example: -10001
        description:
          type: string
          description: Text describing the error that occurred.
          example: 'Invalid Request: PhoneNumber Parameter'
    sharedResponseSchema:
      title: sharedResponseSchema
      type: object
      properties:
        reference_id:
          type: string
          description: A unique, randomly generated hex value that identifies your web service request.
          example: 0123456789ABCDEF0123456789ABCDEF
          minLength: 32
          maxLength: 32
        sub_resource:
          type: string
          example: sms
          description: The subresource in the URL accessed by this request.
        errors:
          type: array
          description: Contains an object specifying each error that occurred. If no errors occurred, the array is empty.
          items:
            $ref: '#/components/schemas/errorObject'
        status:
          type: object
          description: Contains properties describing the preliminary delivery status of the SMS you sent.
          properties:
            updated_on:
              type: string
              description: 'An RFC 3339 timestamp indicating when the delivery status was last updated. '
              example: '2020-08-27T17:28:49.559307Z'
            code:
              type: integer
              description: A numeric code indicating the transaction status.
              example: 290
            description:
              type: string
              description: Text describing the transaction status.
              example: Message in progress
          required:
          - updated_on
          - code
          - description
    VerifyPlusResPackages:
      title: VerifyPlusResPackages
      type: object
      properties:
        phone_type:
          $ref: '#/components/schemas/ScorePhoneType'
        numbering:
          $ref: '#/components/schemas/ScoreNumbering'
        sim_swap:
          $ref: '#/components/schemas/SIMSwapResponse'
        risk:
          $ref: '#/components/schemas/ScoreRisk'
    SmartVerifyShared:
      title: SmartVerifyShared
      type: object
      properties:
        sub_resource:
          type: string
          description: The service that sent this response.
          enum:
          - smart
          example: smart
    ScoreNumbering:
      title: ScoreNumbering
      type: object
      description: Contains properties related to the numbering attributes of the specified phone number. This object is only included if enabled by the [Telesign Customer Support Team](mailto:support@telesign.com).
      properties:
        original:
          type: object
          description: Contains details about the original phone number included in the request.
          properties:
            phone_number:
              type: string
              description: The base phone number without the [country dialing code](/enterprise/docs/codes-languages-and-time-zones#country-codes-and-dialing-codes).
              example: '7833012348'
            complete_phone_number:
              type: string
              description: The base phone number prefixed with the [country dialing code](/enterprise/docs/codes-languages-and-time-zones#country-codes-and-dialing-codes).
              example: '17833012348'
            country_code:
              type: string
              description: The 1, 2, or 3-digit [country dialing code](/enterprise/docs/codes-languages-and-time-zones#country-codes-and-dialing-codes). For example, the country dialing code for both the U.S.A. and Canada is `1`, and the country dialing code for the United Kingdom is `44`.
              example: '1'
        cleansing:
          type: object
          description: Contains details about how the phone number was cleansed. Phone cleansing corrects common formatting issues in submitted phone numbers.
          properties:
            call:
              type: object
              description: Contains cleansing details for the phone number if it is enabled to receive voice calls.
              properties:
                cleansed_code:
                  type: integer
                  description: One of the [phone number cleansing codes](/enterprise/docs/codes-languages-and-time-zones#phone-number-cleansing-codes) specifying the cleansing operation performed on the phone number.
                  example: 100
                country_code:
                  type: string
                  description: The 1, 2, or 3-digit [country dialing code](/enterprise/docs/codes-languages-and-time-zones#country-codes-and-dialing-codes). For example, the country dialing code for both the U.S.A. and Canada is `1`, and the country dialing code for United Kingdom is `44`.
                  example: '1'
                max_length:
                  type: integer
                  description: The maximum number of digits allowed for phone numbers with this country dialing code.
                  example: 10
                min_length:
                  type: integer
                  description: The minimum number of digits allowed for phone numbers with this country dialing code.
                  example: 10
                phone_number:
                  type: string
                  description: The base phone number without the [country dialing code](/enterprise/docs/codes-languages-and-time-zones#country-codes-and-dialing-codes).
                  example: '7833012348'
            sms:
              type: object
              description: Contains cleansing details for the phone number if it is enabled to receive SMS.
              properties:
                cleansed_code:
                  type: integer
                  description: One of the [phone number cleansing codes](/enterprise/docs/codes-languages-and-time-zones#phone-number-cleansing-codes) specifying the cleansing operation performed on the phone number.
                  example: 100
                country_code:
                  type: string
                  description: The 1, 2, or 3-digit [country dialing code](/enterprise/docs/codes-languages-and-time-zones#country-codes-and-dialing-codes). For example, the country dialing code for both the U.S.A. and Canada is `1`, and the country dialing code for United Kingdom is `44`.
                  example: '1'
                max_length:
                  type: integer
                  description: The maximum number of digits allowed for phone numbers with this country dialing code.
                  example: 10
                min_length:
                  type: integer
                  description: The minimum number of digits allowed for phone numbers with this country dialing code.
                  example: 10
                phone_number:
                  type: string
                  description: The base phone number without the [country dialing code](/enterprise/docs/codes-languages-and-time-zones#country-codes-and-dialing-codes).
                  example: '7833012348'
  securitySchemes:
    Basic:
      type: http
      scheme: basic
      description: Easiest to implement. See [Basic Authentication](/api-reference/authentication#basic-authentication) for more details.
    Digest:
      name: Authorization
      type: apiKey
      in: header
      description: See [Digest Authentication](/api-reference/authentication#digest-authentication) for more details.
x-readme:
  explorer-enabled: true
  proxy-enabled: true
  samples-enabled: true