SMS Verify - Get started

This page explains the basic usage of Telesign SMS Verify and directs you to instructions for sending your first request.

📘

What is Telesign SMS Verify?

Telesign SMS Verify delivers phone-based verification and multi-factor authentication (MFA) using a limited duration, one-time passcode (OTP) sent over SMS. Telesign SMS Verify allows you to:

• Send an OTP to a user's phone number to complete a log-in process after they have entered their password.
• Send an OTP to a user's phone number to verify their identity.
• Send an OTP to a phone number provided by a user to verify their ownership of the number.
• Send an OTP to a user's phone number to validate critical interactions.

General requirements

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

Basic usage

With Telesign-generated OTP

1. Send a request to the SMS Verify resource of the Verify API that includes:
   • The recipient's phone number. Telesign attempts to send an SMS to the end user with a randomly generated OTP if the request is successful.
2. Save the reference ID included in the HTTP response if the request is successful.
3. Send the following in a request to the Transaction Status resource of the Verify API once your end-user has submitted a potential OTP match through your application:
   • The reference ID you saved.
   • The potential OTP match from the user.
4. Check the verification state in the HTTP response from Telesign. If the potential OTP and the OTP sent by Telesign match, the HTTP response from Telesign includes the VALID verification state; this indicates that the verification completed successfully.
5. Resolve the attempted user action accordingly.

With your own OTP

1. Send a request to the SMS Verify resource of the Verify API that includes:
   • The recipient's phone number.
   • Your randomly generated OTP. Telesign attempts to send an SMS to the end user with your OTP if the request is successful.
2. Save the reference ID included in the HTTP response if the request is successful.
3. Send the saved reference ID in a request to the Transaction Status resource of the Verify API to see the delivery status of your message.
4. Compare the potential OTP match that your end-user has submitted through your application to the OTP that you sent. If the two codes match, the verification was completed successfully.
5. Resolve the attempted user action accordingly.

Try it

• For everyone: For instructions on how to send your first SMS Verify request without code, see SMS Verify - Try it without code.
• For developers: For instructions on how to send your first SMS with code, see SMS Verify - Tutorial: Get started with the SDK.

Example

POST /v1/verify/sms HTTP/1.1
Authorization: Basic 12345678-9ABC-DEF0-1234-56789ABCDEF0:Uak4fcLTTH/Tv8c/Q6QMwl5t4ck=
Content-Type: application/x-www-form-urlencoded; charset=utf-8
Host: rest-ww.telesign.com
phone_number=15558675309

HTTP/1.1 200 OK
Content-Type: application/json
{
  "reference_id": "0123456789ABCDEF0123456789ABCDEF",
  "sub_resource": "sms",
  "errors": [],
  "status": {
    "updated_on": "2015-10-03T14:51:28.709526Z",
    "code": 290,
    "description": "Message in progress"
  },
  "verify": {
    "code_state": "UNKNOWN",
    "code_entered": ""
  }
}

Compliance

For SMS Verify compliance best practices, please refer to the articles in the Compliance section in our Support Center.