App Verify API - Get started

This page explains how to use Telesign App Verify API to verify devices through a voice call that includes a verification code in the caller ID.

The code received on the handset can be:

  • Manually retrieved by the handset user and entered into your app to complete verification. This is called Missed Call Verification.
  • Automatically retrieved and verified without any action by the end user, so long as you obtain permission from Google to access call logs.

In either case, the code received on the handset is checked against the code generated by Telesign. This ensures that the phone making the request matches the phone number that the end user provided.

General requirements

  • Resource: rest-ww.telesign.com/v1/verify/auto/voice
  • Protocols: https
  • Authentication: Basic (easiest to implement) or Digest
  • Encoding: Accepts only UTF-8 unicode characters as inputs.
  • Accepts: application/x-www-form-urlencoded
  • Responds with: application/json
  • Required headers: Content-Type - application/x-www-form-urlencoded

Using App Verify API requires requests to multiple endpoints to achieve verification.

Endpoints

Endpoint titleHTTP methodEndpoint URIEndpoint description
InitiatePOSThttps://rest-ww.telesign.com/v1/verify/auto/voice/initiateUse this to start the verification process for the number you provide. You use this to have Telesign make a voice call using a predefined caller ID containing a fixed prefix and five randomly generated digits.
FinalizePOSThttps://rest-ww.telesign.com/v1/verify/auto/voice/finalizeUse this to send Telesign the verification code sent to the handset in the caller ID and the reference ID for the associated transaction.
Finalize caller IDPOSThttps://rest-ww.telesign.com/v1/verify/auto/voice/finalize/calleridIf a call is unsuccessful, the device will not receive the call. If there is a prefix sent by Telesign in the initiate request and it cannot be matched to the CLI of the verification call, you can use use this endpoint to report the issue to Telesign for troubleshooting.
Finalize timeout requestPOSThttps://rest-ww.telesign.com/v1/verify/auto/voice/finalize/timeoutIf a mobile device verification call does not make it to the designated handset within the specified amount of time, you can use this endpoint to report the issue to Telesign.
Get call statusGEThttps://rest-ww.telesign.com/v1/verify/auto/voice/{reference_id}If you need to find out what the status of the voice call that was made is, you can use this end point to retrieve details about the transaction.

Review the App Verify API flow

Review the app verification process on the App Verify API - Review the app verification flow page.

Review required permissions

See what permissions are required to set up app verification on the App Verify API - Review required permissions page. You do not need to worry about these if you will be implementing using Missed Call Verification. You cannot do frictionless app verification if you do not have access to call logs. Google now restricts access to these in most cases.

Review app best practices

See what the best practices for the App Verify API application are on the App Verify API - Review app best practices page.

Endpoints

Use this endpoint to start the verification process for the number you provide. Telesign makes a voice call to the number you specify in your request using a predefined caller ID containing a fixed prefix and five randomly generated digits.

Example
Request

POST https://rest-ww.telesign.com/v1/verify/auto/voice/initiate HTTP/1.1
Content-Type: application/x-www-form-urlencoded; charset=utf-8
Authorization: Basic AAAAAAAA-BBBB-CCCC-DDDD-EEEEEEEEEEEE:n1oBUjEwVunkjfH9paeA9qHrjQw=
phone_number=13105551212

Response (body)

{
  "reference_id": "0123456789ABCDEF0123456789ABCDEF",
  "sub_resource": "auto_verify_initiate",
  "errors": [],
  "prefix": "4478830",
  "status": {
      "updated_on": "2015-10-30T17:21:31.141377Z",
      "code": 2400,
      "description": "Pending"
  },
}

Use this endpoint to send Telesign the verification code sent to the end user's device in the caller ID and the reference ID for the associated transaction.

Example
Request

POST https://rest-ww.telesign.com/v1/verify/auto/voice/finalize HTTP/1.1
Content-Type: application/x-www-form-urlencoded; charset=utf-8
Authorization: Basic AAAAAAAA-BBBB-CCCC-DDDD-EEEEEEEEEEEE:n1oBUjEwVunkjfH9paeA9qHrjQw=
reference_id=ABCDEF0123456789ABCDEF0123456789&verify_code=37760 

Response (body)

{
  "reference_id": "0123456789ABCDEF0123456789ABCDEF",
  "sub_resource": "auto_verify_finalize",
  "errors": [],
  "status": {
      "updated_on": "2015-10-30T17:21:41.342350Z",
      "code": 2401,
      "description": "Success"
  },
  "verify_code": "37760",
}

If a call is unsuccessful, the device will not receive the call. If there is a prefix sent by Telesign in the initiate request and it cannot be matched to the CLI of the verification call, you can use use this endpoint to report the issue to Telesign for troubleshooting.

Example
Request

POST https://rest-ww.telesign.com/v1/verify/auto/voice/finalize/callerid HTTP/1.1
Content-Type: application/x-www-form-urlencoded; charset=utf-8
Authorization: Basic AAAAAAAA-BBBB-CCCC-DDDD-EEEEEEEEEEEE:n1oBUjEwVunkjfH9paeA9qHrjQw=
customer_id=b4ef1f2b-842d-4f95-a7f2-4b3addd606b0&reference_id=ABCDEF0123456789ABCDEF0123456789&unknown_caller_id=4407873012345

Response (body)

{

	"reference_id": "0123456789ABCDEF0123456789ABCDEF",
	"sub_resource": "auto_verify_finalize",
	"errors": [],
	"status": {
		"updated_on": "2017-12-30T17:21:31.141377Z",
		"code": 2407,
		"description": "CallerID prefix did not match"
	},

}

If a mobile device verification call does not make it to the designated handset within the specified amount of time, you can use the Finalize Timeout endpoint to report the issue to TeleSign.

Example
Request

POST https://rest-ww.telesign.com/v1/verify/auto/voice/finalize/timeout HTTP/1.1
Content-Type: application/x-www-form-urlencoded; charset=utf-8
Authorization: Basic AAAAAAAA-BBBB-CCCC-DDDD-EEEEEEEEEEEE:n1oBUjEwVunkjfH9paeA9qHrjQw=
reference_id=ABCDEF0123456789ABCDEF0123456789

Use this endpoint to retrieve details about the status of the voice call transaction.

Request

GET https://rest-ww.telesign.com/v1/verify/auto/voice/{reference_id} HTTP/1.1
Content-Type: application/x-www-form-urlencoded; charset=utf-8
Authorization: Basic AAAAAAAA-BBBB-CCCC-DDDD-EEEEEEEEEEEE:n1oBUjEwVunkjfH9paeA9qHrjQw=

WHAT'S NEXT

App Verify API - Tutorial: App Verify sample app