Voice Verify - Verify with Telesign code

This page walks you step-by-step through how to use Telesign Voice Verify to send a voice message to an end-user with a verification code generated by Telesign. It also explains how to test if input from an end-user matches that code, so you can complete verification.

Keep the reference pages POST /v1/verify/call and GET /v1/verify/{reference_id} 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 to the Verify API. 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
templateText with a variable.Text that overrides the contents of the predefined message templates. Include the $$CODE$$ variable to have the verification code automatically inserted. See Voice Verify - Text-to-speech tips for guidance on writing the copy for your message.no

SMS Verify 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
&template=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 a randomly generated verification code.

Voice Verify response

HTTP/1.1 200 OK
Content-Type: application/json
{
  "reference_id": "0123456789ABCDEF0123456789ABCDEF",
  "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": ""
  },
  "additional_info": {
    "message_parts_count": 1
  }
}
  1. Save the value of the property reference_id from the response. You will need it to complete the verification flow.
  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 the status of the call, not delivery of the voice message all the way to the end-user.

Step 2: 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 a GET /verify/{reference_id} request.
    • Include the end-user's potential code in the verify_code query parameter.
    • Include the reference_id for the transaction in the reference_id path parameter.

Get status request

GET /v1/verify/0123456789ABCDEF0123456789ABCDEF?verify_code=57244 HTTP/1.1
Authorization: Basic 12345678-9ABC-DEF0-1234-56789ABCDEF0:Uak4fcLTTH/Tv8c/Q6QMwl5t4ck=
Host: rest-ww.telesign.com
  1. In the response, if the value of the verify.code_state property is VALID, the verification completed successfully.
  2. The status.code and status.description properties in the payload of this response indicate the delivery status all the way to the end-user.

Get status response

HTTP/1.1 200 OK
Content-Type: application/json
{
  "reference_id": "ABCDEF0123456789ABCDEF0123456789",
  "sub_resource": "call",
  "errors": [],
  "status": {
    "updated_on": "2015-04-17T22:26:43.784963Z",
    "code": 100,
    "description": "Call answered"
  },
  "verify": {
    "code_state": "VALID",
    "code_entered": ""
  },
  "additional_info": {
    "code_entered": null,
    "message_parts_count": 1
  }
}

Did this page help you?