Voice Verify API - Verify with your own code

📘

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 Telesign Voice 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.

Before you begin, set up the Transaction Callback Service so you can get the delivery status of the voice messages you send.

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

Before you begin

• Enable service: If Voice Verify is not yet enabled for your account, ask Telesign Customer Support to grant you access.

Step 1: Send the voice message

1. Send a POST /verify/call request. 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.

Voice Verify API request

POST /v1/verify/call 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
&verify_code=57244
&tts_message=Your code is $$CODE$$

2. The service then makes a call; after that call is answered it plays a voice message, replacing the $$CODE$$ variable in the message template with your verification code.

Voice Verify API response

HTTP/1.1 200 OK
Content-Type: application/json
{
  "reference_id": "ABCDEF0123456789ABCDEF0123456789",
  "submit_timestamp": "Wed, 06 Nov 2015 13:36:07 -0800",
  "sub_resource": "call",
  "errors": [],
  "status": {
    "updated_on": "2015-10-03T14:51:28.709526Z",
    "code": 103,
    "description": "Call in progress"
  },
  "verify": {
    "code_state": "UNKNOWN",
    "code_entered": ""
  }
}

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 voice message.

📘

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 Voice Verify 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": "call",
  "errors": [],
  "status": {
    "code": 1900,
    "updated_on": "2014-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.