post

/v1/verify/sms

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
  • Endpoint: https://rest-ww.telesign.com/v1/verify/sms
  • 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

Request Body

Form data (application/x-www-form-urlencoded)
phone_number
string

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.

required
ucid
string

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
string

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
string

A code specifying the language of the predefined template you wish to use. For a complete list of codes, see the section Supported Languages. If you provide overriding message text in the template parameter, this field is not used.

verify_code
string

The verification code used for the code challenge. By default, 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. Either way, the verification code replaces the variable $$CODE$$ in the message template.

template
string

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.

sender_id
string

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.

maxLength: 20
is_primary
string

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
string

(India-local traffic only). The ID of the DLT template used for this message. See India DLT Update for more details on the relevant regulations.

maxLength: 40
dlt_entity_id
string

(India-local traffic only). The ID of the entity sending this message. See India DLT Update for more details on the relevant regulations.

maxLength: 40
transaction_amount
string

(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
string

(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
string

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 to turn on this feature.

maxLength: 40

Responses

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.

Status Code Associated Text String Description
200 Delivered to handset The SMS was delivered to the end user’s phone. (Final)
203 Delivered to gateway The SMS was delivered to the gateway. If the gateway responds with further information (including successful delivery to handset or delivery failure), the status is updated. (Intermediate)
207 Error delivering SMS to handset (reason unknown) The SMS could not be delivered to the end user’s handset for an unknown reason. (Final)
210 Temporary phone error The SMS could not be delivered to the handset due to a temporary error with the phone. Examples - phone is turned off, not enough memory to store the message. (Final)
211 Permanent phone error The SMS could not be delivered to the handset due to a permanent error with the phone. For example, the phone is incompatible with SMS, or illegally registered on the network. This can happen when a phone number is blacklisted, or is incorrectly provisioned. (Final)
220 Gateway/network cannot route message The network cannot route the message to the handset. (Final)
221 Message expired before delivery The message was queued by the mobile provider and timed out before it could be delivered to the handset. (Final)
222 SMS not supported SMS is not supported by this phone, carrier, plan, or user.
229 Message blocked by your request TeleSign blocked the SMS before it was sent. This is due to your prior submitted request to blocklist this phone number.
230 Message blocked by TeleSign TeleSign blocks a message if it is being sent to a phone number that is on a global blocklist.
231 Invalid/unsupported The content of the message is not supported.
233 Message blocked due to high risk score. It was determined that the risk score for the destination number is higher than configured Maximum Risk Score. For that reason TeleSign did not send the SMS.
250 Final status unknown The final status of the SMS cannot be determined.
251 Message successfully sent out for delivery, however final confirmation of delivery to handset was not received. This message was successfully delivered to the gateway, but TeleSign cannot confirm delivery to the handset because TeleSign does not receive the final handset DLR in this region. NOTE: There is a high probability that this message was successfully delivered to the handset.
290 Message in progress The message is being sent to the SMS gateway.
291 Queued by TeleSign TeleSign is experiencing unusually high volume and has queued the SMS message.
292 Queued by gateway The SMS gateway has queued the message.
295 Status delayed The status of the SMS is temporarily unavailable.
500 Transaction not attempted No SMS request was attempted.
501 Not authorized No permissions for this resource, or authorization failed.
502 Campaign error This error can be generated if there is a problem with the short code used.
503 Carrier rejected - temporary problem This error is generated if there is an error on the carrier or operator side that is temporary and the message can be retried.
504 Carrier rejected - permanent error This error is generated if there is an error on the carrier or operator side that is permanent and the message should not be retried.
505 Error on gateway - temporary error This error is generated if there is an error on TeleSign’s partner side that is considered temporary and the message can be retried.
506 Error on gateway - permanent error This error is generated if there is an error on TeleSign’s partner side that is considered permanent and the message should not be retried.
507 Invalid destination address There is a problem with the destination address used. Either the format is not valid, or the number is not associated with any carrier, or if MSC is used it does not know about this MSISDN.
508 Invalid source address The message requires a source address. Verify that one is provided and correct.
509 Parameters problem One or more parameters used in the request is not supported.
510 Message blocked by subscriber action or request The end user has blocked receiving SMS with their carrier plan or by request or from the particular short code used.
511 Subscriber low on credit The end user exceeded their spending limits and cannot receive SMS.
512 Roaming error End user cannot receive SMS because their device that receives the messages is roaming.
513 Mobile number portability error SMS failed because ported combinations are unreachable.
514 Subscriber absent The operator/carrier is temporarily unable to reach the end user.
515 Suspected spam This message is considered to be spam by carrier or operator.
517 Selected DLT details for India not supported The DLT template ID or entity ID in the request cannot be found by the end operator.
518 Message blocked due to high risk SIM swap indicator. The service determined that the SIM swap risk indicator for the destination number is higher than the maximum value configured for your account. For that reason TeleSign did not send the SMS.
519 Message not sent - requested SIM swap check could not be performed. The service could not perform the SIM swap check. This is because either the number is out of SIM swap coverage or information about the potential SIM swap event is missing.
599 Status not available The system is unable to provide status at this time.
Schema
object
reference_id
string

A 32-digit hex value used to identify the web service request. The value is unique to each request and is randomly-generated by TeleSign.

required
resource_uri
string

The URL path of your request.

1 validation + required
sub_resource
string

The subresource in the URI path that you made this request to.

1 validation + required
errors
array[object]

Contains an object for each error condition that resulted from the request.

required
status
object

Contains properties describing the preliminary delivery status of the SMS you sent.

required
verify
object

Contains properties related to the verification status.

additional_info
object

Properties related to optional features you have enabled through our Customer Support Team.

Send a Test Request

Send requests directly from the browser (CORS must be enabled)
$$.env
1 variable not set
host