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.

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

Step 1: Send the voice message

  1. Send a POST /verify/call request. Include the following param values:
ParameterValueDescriptionRequired?
phone_numberDigits without spaces or special characters.The end user’s phone number you want to send a message to, beginning with the country/dialing code.yes
verify_codeA numeric code as a string, between 000 and 9999999.The verification code used for the code challenge. By default, Telesign randomly generates a seven-digit numeric value for you. You can override the default behavior by including your own numeric code as a value for this parameter. Either way, the verification code replaces the variable $$CODE$$ in the message template.yes*
tts_messageText with a variable.Text that overrides the contents of the predefined message templates. Include the $$CODE$$ variable to have the verification code automatically inserted. This text is converted to speech in the call to the end-user. See Voice Verify API - Text-to-speech tips for guidance on writing the copy for your message.no

*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$$
  1. 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": ""
  }
}
  1. Save the value of the property reference_id from the response to use later when getting delivery status.
  2. 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.