Telesign Messages API

openapi: 3.2.0
info:
  title: SMS Verify Messages API
  version: '1.0'
  description: Use the Telesign SMS Verify API to send an SMS with a one-time passcode (OTP) 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: Messages
paths:
  /v1/verify/sms:
    parameters: []
    post:
      summary: Send SMS verification code
      responses:
        '200':
          $ref: '#/components/responses/200Response'
        '400':
          $ref: '#/components/responses/400Response'
        '401':
          description: '**Unauthorized.** The request requires user authentication. Code against the Telesign status or error codes from the `status.code` and `errors.code` properties in the response payload, rather than the HTTP status code of the response.


            | Status code | Status description   | Error code | Description   |

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

            | 500 | Transaction not attempted | -10009     | Invalid source IP address |

            | 500 | Transaction not attempted | -10033     | {phone_number} has not been verified for this trial account. |

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

            | 501 | Not authorized            | -30000     | Invalid Customer ID. |

            | 501 | Not authorized            | -30001     | Customer ID Account Suspended. |

            | 501 | Not authorized            | -30004     | Missing required ''Authorization'' header |

            | 501 | Not authorized            | -30005     | Required ''Authorization'' header is not in the correct format|

            | 501 | Not authorized            | -30006     | Invalid Signature |

            | 501 | Not authorized            | -30007     | Missing required ''Date'' or ''x-ts-date'' header    |

            | 500 | Transaction not attempted | -30008     | Invalid ''x-ts-auth-method'' header.|

            | 501 | Not authorized            | -30009     | ''Date'' or ''x-ts-date'' header is not RFC822 compliant  |

            | 501 | Not authorized            | -30010     | ''Date'' or ''x-ts-date'' header is not within tolerable range |

            | 501 | Not authorized            | -30011     | ''x-ts-nonce'' header value is either too long or too short |

            | 501 | Not authorized            | -30012     | ''x-ts-nonce'' header value has been used recently |

            | 501 | Not authorized            | -30015     | Invalid API Key.  |'
          content:
            application/json:
              schema:
                allOf:
                - $ref: '#/components/schemas/sharedResponseSchema'
                - $ref: '#/components/schemas/401ResponseSchema'
                - type: object
                  properties:
                    signature_string:
                      type: string
                      description: Returned when request signature is not valid. Signature from failed authorization requests - doesn’t contain all required data (like x-ts-auth-method), or it’s not ordered properly.
                      example: 'POST\napplication/x-www-form-urlencoded\n\nx-ts-auth-method: HMAC-SHA256\nx-ts-date:Tue, 31 Jan 2024 11:36:42 GMT\nx-ts-nonce:ab$CDef/gh123+II4jk\nphone_number=11234567890\n/v1/verify/sms'
              examples:
                Unauthorized:
                  value:
                    reference_id: 0123456789ABCDEF0123456789ABCDEF
                    sub_resource: sms
                    errors:
                    - code: -10009
                      description: Invalid source IP address
                    status:
                      updated_on: '2020-08-27T17:28:49.559307Z'
                      code: 500
                      description: Transaction not attempted
        '429':
          $ref: '#/components/responses/429Response'
        '500':
          $ref: '#/components/responses/500Response'
      x-readme:
        code-samples:
        - name: C#
          language: csharp
          code: 'using RestSharp;


            var client = new RestClient("https://rest-ww.telesign.com/v1/messaging");

            var request = new RestRequest("POST");


            request.AddHeader("accept", "application/json");

            request.AddHeader("content-type", "application/x-www-form-urlencoded");

            request.AddHeader("authorization", "Basic [REDACTED]");

            request.AddParameter("application/x-www-form-urlencoded", "is_primary=true&phone_number=8184823381&message=hello&message_type=ARN&account_lifecycle_event=1&external_id=88888", ParameterType.RequestBody);


            RestResponse response = client.Execute(request);'
      operationId: sendSMSVerifyCode
      description: 'Use this action to send an SMS with a verification code to a recipient phone number.


        ## General requirements

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

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

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

        * **Responds with:** `application/json`

        * **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:
                  type: string
                  description: The end user's phone number you want to send a message to, as digits without spaces or special characters, beginning with the country dialing code.
                  example: '15558675309'
                ucid:
                  type: string
                  description: 'A code specifying the use case you are making the request for. 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 details to request information about a potential purchase (like a loan, real estate, or attending a school), and you want to check if they are legitimate.

                    * `OTHR` - For 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 you want to confirm they will show up.

                    * `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 for identity theft purposes.

                    * `TRVF` - For use when you are transferring money and want to check if the transfer is approved by sending a text message to your end user. This is similar to `CHBK`, but is specifically for a money transaction.

                    * `UNKN` - For a situation not addressed by other tags (same as `OTHR`).'
                originating_ip:
                  type: string
                  description: Your end user's IP address (do not send your own IP address). This is used to help Telesign improve our services. 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>.
                language:
                  type: string
                  description: A code specifying the language of the predefined template you wish to use. For a complete list of codes, see [SMS Verify API - Supported languages](/enterprise/docs/sms-verify-api-supported-languages). If you provide overriding message text in the `template` parameter, this field is not used.
                verify_code:
                  type: string
                  description: 'The verification code used for the code challenge. By defauls, Telesign randomly generates a seven-digit numeric value for you. You can override the default behavior by including your own numeric code for this parameter, with a value between `000` and `9999999`. Only numeric characters are supported. Either way, the verification code replaces the variable `$$CODE$$` in the message template. '
                  example: '57244'
                  minLength: 3
                  maxLength: 7
                template:
                  type: string
                  description: Text that overrides the contents of the predefined message templates. Include the `$$CODE$$` variable to have the verification code automatically inserted. For payment transactions, include the `$$AMOUNT$$` and `$$PAYEE$$` variables to have those payment details from your other params automatically inserted. By default, the maximum length of this field is 160 characters. Telesign recommends that you keep your messages brief if possible, but if you want to send longer messages contact our Customer Support Team to have the maximum increased. A long message may be up to 1600 characters.
                  example: Your code is $$CODE$$
                sender_id:
                  type: string
                  description: Specifies the sender ID to be displayed to the end user on the SMS message. Before using this, give any sender IDs you might want to use to our Customer Support Team, so we can add them to our allow list. If the sender ID in this field is not on this list, it is not used. We do not guarantee that the sender ID you specify will be used; Telesign may override this value to improve delivery quality or to follow the SMS regulations of particular countries. We recommend limiting values to 0-9 and A-Z, as support for other ASCII characters varies by carrier.
                  maxLength: 20
                is_primary:
                  type: string
                  description: Whether you are using this service as your primary provider to send this message (`”true”`) or"as a backup after your primary provider failed (`”false”`). We use this data to optimize message routing.
                  default: 'true'
                dlt_template_id:
                  type: string
                  maxLength: 40
                  description: '**(India-local traffic only)**. The ID of the DLT template used for this message. See [India DLT Update](https://support.telesign.com/s/article/India-DLT-Update) for more details on the relevant regulations.'
                dlt_entity_id:
                  type: string
                  maxLength: 40
                  description: '**(India-local traffic only)**. The ID of the entity sending this message. See [India DLT Update](https://support.telesign.com/s/article/India-DLT-Update) for more details on the relevant regulations.'
                transaction_amount:
                  type: string
                  description: '**(Payment-transactions only)**  Replaces the `$$AMOUNT$$` variable in the message template. Specifies the currency and amount for the payment that the end user is approving. This parameter is required if `transaction_payee` is included in the request.'
                  maxLength: 40
                transaction_payee:
                  type: string
                  description: '**(Payment-transactions only)** Replaces the `$$PAYEE$$` variable in the message template. Specifies the entity that the end user is approving a payment to.

                    This parameter is required if `transaction_amount` is included in the request.'
                  maxLength: 40
                sim_swap_check:
                  type: string
                  description: Set a value of `"true"` to screen this transaction using a Telesign SIM Swap check. This only has an effect if we have enabled SIM Swap for your account and configured it to be toggled using this parameter. If your account is configured to perform the check on every transaction, set a value of `"false"` to suppress the check. Contact our [Customer Support Team](mailto:support@telesign.com) to turn on this feature.
                  maxLength: 40
                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:
      - Messages
components:
  schemas:
    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.
    SMSVerifySuccessResponse:
      title: SMSVerifySuccessResponse
      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.
      - $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'
    401ResponseSchema:
      title: 401ResponseSchema
      type: object
      properties:
        errors:
          type: array
          items:
            type: object
            properties:
              code:
                type: integer
                example: -10009
              description:
                type: string
                example: Invalid source IP address
        status:
          type: object
          properties:
            code:
              type: integer
              example: 500
            description:
              type: string
              example: Transaction not attempted
    sharedResponseSchema:
      title: sharedResponseSchema
      type: object
      description: ''
      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 delivery status of the SMS.
              example: 290
            description:
              type: string
              description: Text describing the delivery status of the SMS.
              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'
        risk:
          $ref: '#/components/schemas/ScoreRisk'
    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'
  responses:
    400Response:
      description: '**Bad request.** The request could not be understood by the server due to malformed syntax. Code against the Telesign status or error codes from the `status.code` and `errors.code` properties in the response payload, rather than the HTTP status code of the response.



        | Status code | Status description   | Error code | Description   |

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

        | 500 | Transaction not attempted | -10001     | Invalid Request: {parameter name} Parameter: {parameter value} |

        | 500 | Transaction not attempted | -10001     | Invalid Request: Missing Parameter: {parameter name} |

        | 500 | Transaction not attempted | -10001     | Invalid Request: {parameter name} Parameter                 |

        | 500 | Transaction not attempted | -10001     | Not Allowed Host: IP/Hostname Parameter: {host_ip_address}/{host_name} |

        | 500 | Transaction not attempted | -40006     | Bad request              |'
      content:
        application/json:
          schema:
            allOf:
            - $ref: '#/components/schemas/sharedResponseSchema'
          examples:
            Example:
              value:
                reference_id: 0123456789ABCDEF0123456789ABCDEF
                sub_resource: sms
                errors:
                - code: -10001
                  description: 'Invalid Request: PhoneNumber Parameter'
                status:
                  updated_on: '2020-08-27T17:28:49.559307Z'
                  code: 500
                  description: Transaction not attempted
    429Response:
      description: '**Too many requests.** The user sent too many requests in a given amount of time. Code against the Telesign status or error codes from the `status.code` and `errors.code` properties in the response payload, rather than the HTTP status code of the response.


        | Status code | Status description   | Error code | Description   |

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

        | 500 | Transaction not attempted | -40007     | Rate Limit Exceeded   |

        | 500 | Transaction not attempted | -40008     | Verify SMS exceeded transaction hard cap. Request denied.         |'
      content:
        application/json:
          schema:
            allOf:
            - $ref: '#/components/schemas/sharedResponseSchema'
            - type: object
              properties:
                errors:
                  type: array
                  items:
                    type: object
                    properties:
                      code:
                        type: integer
                        example: -40008
                      description:
                        type: string
                        example: 'SMS Verify exceeded transaction hard cap. Request denied. '
                status:
                  type: object
                  properties:
                    code:
                      type: integer
                    description:
                      type: string
          examples:
            Example:
              value:
                reference_id: 0123456789ABCDEF0123456789ABCDEF
                sub_resource: sms
                errors:
                - code: -40008
                  description: 'SMS Verify exceeded transaction hard cap. Request denied. '
                status:
                  updated_on: '2020-08-27T17:28:49.559307Z'
                  code: 500
                  description: Transaction not attempted
    500Response:
      description: '**Service unavailable.** The system is unavailable, try again. Code against the Telesign status or error codes from the `status.code` and `errors.code` properties in the response payload, rather than the HTTP status code of the response.


        | Status code | Status description   | Error code | Description   |

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

        | 500 | Transaction not attempted | -90001  | System Unavailable, please try again later.  |'
      content:
        application/json:
          schema:
            allOf:
            - $ref: '#/components/schemas/sharedResponseSchema'
            - type: object
              properties:
                errors:
                  type: array
                  items:
                    type: object
                    properties:
                      code:
                        type: integer
                        example: -10004
                      description:
                        type: string
                        example: Reference ID expired
                status:
                  type: object
                  properties:
                    code:
                      type: integer
                    description:
                      type: string
                signature_string:
                  type: string
                  description: Returned when request signature is not valid. Signature from failed authorization requests - doesn’t contain all required data (like x-ts-auth-method), or it’s not ordered properly.
                  example: 'POST\napplication/x-www-form-urlencoded\n\nx-ts-auth-method: HMAC-SHA256\nx-ts-date:Tue, 31 Jan 2024 11:36:42 GMT\nx-ts-nonce:ab$CDef/gh123+II4jk\nphone_number=11234567890\n/v1/verify/sms'
          examples:
            Example:
              value:
                reference_id: 0123456789ABCDEF0123456789ABCDEF
                sub_resource: sms
                errors:
                - code: -10004
                  description: Reference ID expired
                status:
                  updated_on: '2020-08-27T17:28:49.559307Z'
                  code: 500
                  description: Transaction not attempted
    200Response:
      description: "**Success.** Your request was fulfilled and resulted in a message being sent. Code against the Telesign status or error codes from the `status.code` and `errors.code` properties in the response payload, rather than the HTTP status code of the response.\n \n | Status code | Associated text string | Description                                      |\n |-------------|------------------------|--------------------------------------------------|\n | 290         | Message in progress    | The message is being sent to the SMS gateway.    |\n"
      content:
        application/json:
          schema:
            allOf:
            - $ref: '#/components/schemas/sharedResponseSchema'
            - $ref: '#/components/schemas/SMSVerifySuccessResponse'
          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
                verify:
                  code_state: UNKNOWN
                  code_entered: ''
  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