Verify API - Get Started with voice

📘

NOTE:

To add this product to your account, contact a Telesign expert. This product is available for full-service accounts only.

This page walks you step-by-step through how to use the Telesign Verify API to send a voice call to an end user with a one-time passcode (OTP) in the language of your choice. It also explains how to complete the verification process, to confirm verification is successful based on matching of codes sent and entered.

Keep the reference pages Create a verification process and Update a verification process open in another window while you work on these steps.

Steps

📘

NOTE:

Updating a verification process using the procedure explained in Complete verification and get delivery status is a mandatory step when using Verify API. This step allows Telesign to know the real state of your verification as well as control all the features related to a verification process such as fallback, callback, and pricing. If your end user has verified themselves but the verification process is not updated, these features might not work as intended which can lead to extra costs or incorrect billing.

Send the request

1. Send a Create a verification process request to the Verify API. Include the following param values:

   Parameter	Value	Description	Required?
   recipient.phone_number	Digits without spaces or special characters, beginning with the country dialing code.	The recipient's phone number	No, but recommended in case your recipient cannot be reached by email.
   verification_policy[0].method	voice	One of the verification methods included in a verification policy.	Required only if email is not already defined as the primary verification method for this account's default verification policy.
   verification_policy[0].fallback_time	A time in seconds.	The time window in seconds that the service waits before abandoning the current verification method and then initiating verification using the next method.	No. In case you don’t specify the fallback time, default fallback time is used.
   verification_policy[1].method	sms	One of the verification methods included in a verification policy. This is your backup method.	No, but recommended in case your recipient cannot be reached by email.
   security_factor	A numeric code, formatted as a string.	The OTP to include in the message to the end user if you are generating your own OTP codes.	No but this parameter can be used if you wish to define your own OTP instead of allowing Telesign to generate an OTP.
   voice_lang	A code specifying the language the service will use when delivering the OTP message, formatted as a string.	A language code selected from the Voice - supported languages for text-to-speech language table	No, but if a code isn't provided, the default language which is English (en-US ) is used to deliver the OTP message.

   
   

Your request should look similar to this request example.

The parameter voice_lang defines the language used for the message. The default language if one isn't included in the request is en-US (English (US). Use a code for a support language from the Voice - supported languages for text-to-speech language table .

Request

POST /verification HTTP/1.1
Authorization: Basic 12345678-9ABC-DEF0-1234-56789ABCDEF0:Uak4fcLTTH/Tv8c/Q6QMwl5t4ck=
Content-Type: application/json; charset=utf-8
Host: verify.telesign.com
{
    "recipient": {
        "phone_number": "447975777666"
    },
    "verification_policy": [
        {
            "method": "voice"
        }
    ],
    "voice_lang": "en-GB"
}

2. The service then sends an calls your end user and plays a voice message, inserting a randomly generated OTP in the message. The message played is:
   
   

   Hello, thank you for using our phone verification system, your code is xxxxx. Once again, your code is xxxxx. Goodbye.

3. Save the value of the property reference_id from the response. You will need it to complete the verification flow.

4. The status.code and status.description properties in the response indicate the preliminary delivery status.

   Response

HTTP/1.1 200 OK
Content-Type: application/json
{
  "reference_id": "0123456789ABCDEF0123456789ABCDEF",
  "recipient": {
    "phone_number": "447975777666"
  },
  "state": "ONGOING",
  "verification_policy": [
    {
      "method": "voice",
      "fallback_time": 300
    }
  ],
  "status": {
    "code": 3901,
    "description": "Request in progress"
  }
}

📘

NOTE:

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

Complete verification and get delivery status

Once your end user has submitted a potential code through your application, complete the verification flow with a second API call.

1. Send an Update a verification process request to the Verify API. This is to provide Telesign with the asserted OTP from the end user.

   Parameter	Value	Description	Required?
   action	finalize	Specifies how you want to change the verification state for this verification process.	yes
   security_factor	A string consisting of a series of numeric digits.	The end user's asserted one-time passcode (OTP).	yes

Your request should look similar to this request example.

Request

PATCH /verification/0123456789ABCDEF0123456789ABCDEF/state HTTP/1.1
Authorization: Basic 12345678-9ABC-DEF0-1234-56789ABCDEF0:Uak4fcLTTH/Tv8c/Q6QMwl5t4ck=
Content-Type: application/json; charset=utf-8
Host: verify.telesign.com
{
  "action": "finalize",
  "security_factor": "5724433"
}

Response

HTTP/1.1 200 OK
Content-Type: application/json
{
  "status": {
    "code": 3900,
    "description": "Verified"
  }
}

2. If Telesign generated the OTP, and the value of the status.description property is Verified, the verification process completed successfully.