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 Internet Protocol. For IPv6, the value must be in the format defined by the IETF in the Internet-Draft document titled IP Version 6 Addressing Architecture.
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