SMS Verify API - Get started

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

📘

What is Telesign SMS Verify API?

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

• Send an OTP to a user's phone number to complete a sign 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

Verify with Telesign-generated OTP

1. USER initiates an action on your application, like trying to sign in.
2. YOU send a request to TELESIGN’s SMS Verify API resource that includes:

• USER’s phone number (PN)

3. TELESIGN sends an HTTP response to YOU confirming that the message send is in progress and including a Reference ID for the transaction.
4. YOU save this Reference ID.
5. TELESIGN generates an OTP and sends it via SMS to USER’s phone number.
6. USER asserts OTP on your application.
7. YOU send a request to TELESIGN’s Transaction Status resource that includes:

• This asserted OTP.
• The Reference ID for the original transaction that you saved earlier.

8. TELESIGN checks whether the codes match and sends an HTTP response to YOU with the verification status.
9. YOU check this HTTP response and resolve the initiated action based on the verification status. If the “VALID” status is returned, for example, you might sign the USER in.

Verify with own OTP

1. USER initiates an action on your application, like trying to sign in.
2. YOU send a request to TELESIGN’s SMS Verify API resource that includes:

• USER’s phone number (PN)
• An OTP that you’ve generated

3. TELESIGN sends an HTTP response to YOU confirming that the message send is in progress and including a Reference ID for the transaction.
4. TELESIGN sends your OTP via SMS to USER’s phone number.
5. USER asserts OTP on your application.
6. YOU compare this asserted OTP to the one you originally generated for this attempt.
7. (Optional) If the codes match, YOU send a request to TELESIGN’s Completions resource to report the successful completion.
8. (Optional) TELESIGN sends an HTTP response confirming the completion.
9. YOU resolve the initiated action based on the verification status. If verification was successful, for example, you might sign the USER in.

📘

NOTE:

Sending us completion data helps us identify and fix any issues with delivery, operators, and routes, which leads to a higher quality experience for you and your end-users.

Try it

• For everyone: For instructions on how to send your first OTP without code, see SMS Verify API - Try it without code.
• For developers: For instructions on how to send your first OTP with code, choose one of our SMS Verify API tutorials in your preferred programming language.

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=1234567890

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 API compliance best practices, please refer to the articles in the Compliance section in our Support Center.