SMS Verify API - Verify with your own code

This page walks you step-by-step through how to use Telesign SMS Verify API to send your own verification code to an end-user. It also explains how to complete verification and send us completion data to improve the service.

📘

NOTE:

Keep in mind that there are two options for generating the code: you can either generate it yourself or we can generate it for you. If you include the verify_code parameter in your request, your code is used. In case you provide an invalid value or its length is out of range, you will receive an error code. If you don't provide the verify_code parameter, Telesign generates a code for you.

Keep the reference pages POST /v1/verify/sms and PUT /v1/verify/completion/{referenceid} open in another window while you work on these steps.

Before you begin

• Upgrade your account: Upgrade to a paid account if you are using a trial account.
• "From" phone number: You must buy a “from” phone number from Telesign before sending OTPs to any number other than the one you registered your account with.
• Transaction Callback Service: Set up the Transaction Callback Service so you can get the delivery status of the SMS messages you send.
• (Optional) Contact our Customer Support Team to configure any of these optional features:
  • Validity period: A time duration in minutes after which a verification code expires.

Step 1: Send the SMS

1. Send a POST /verify/sms request to the SMS Verify API. Include the following param values:

* You can directly include the verification code in your custom template if you prefer, but this is not recommended. If you use the Telesign default template, the verify_code param is required.

SMS Verify API request

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
&verify_code=57244
&template=Your code is $$CODE$$

2. The service then sends an SMS message, replacing the $$CODE$$ variable in the message template with your verification code.

SMS Verify API response

HTTP/1.1 200 OK
Content-Type: application/json

{
   "reference_id": "0123456789ABCDEF0123456789ABCDEF",
   "sub_resource": "sms",
   "errors": [],
   "status": {
      "updated_on": "2022-10-03T14:51:28.709526Z",
      "code": 290,
      "description": "Message in progress"
    },
    "verify": {
       "code_state": "UNKNOWN",
       "code_entered": ""
    },
    "additional_info": {
      "message_parts_count" : 1
    }
}

3. Save the value of the property reference_id from the response to use later when getting delivery status.
4. The status.code and status.description properties in the response indicate the preliminary delivery status of the SMS.

📘

NOTE:

The status.code property gives you status of delivery to the destination carrier, not necessarily all the way to the end-user.

Step 2: Complete verification and report completion

1. Once your end-user has submitted a potential code through your application, compare it to the verification code you created. If the two codes match, the verification completed successfully.
2. (Optional) We recommend that you notify Telesign each time you successfully verify an end-user, by sending a PUT /verify/completion/{reference_id} request that includes the reference ID from the original SMS Verify API transaction.

Completion request

PUT https://rest-ww.telesign.com/v1/verify/completion/0123456789ABCDEF0123456789ABCDEF HTTP/1.1
Authorization: Basic 12345678-9ABC-DEF0-1234-56789ABCDEF0:Uak4fcLTTH/Tv8c/Q6QMwl5t4ck= 
Host: rest-ww.telesign.com

Completion Response

HTTP/1.1 200 OK
Content-Type: application/json
{
  "reference_id": "0123456789ABCDEF0123456789ABCDEF",
  "sub_resource": "sms",
  "errors": [],
  "status": {
    "code": 1900,
    "updated_on": "2022-10-14T18:07:26.078515Z",
    "description": "Verify completion successfully recorded"
  }
}

📘

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.