Voice Verify API - Verify with Telesign 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 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.

📘

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.

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

• Enable service: If Voice Verify API 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:

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

Voice Verify API 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
  }
}

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 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

2. In the response, if the value of the verify.code_state property is VALID, the verification completed successfully.
3. 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
  }
}