Get Started with the App Verify API

The TeleSign App Verify web service enables customers to verify devices through a voice call by a verification code provided in the caller ID.

It is a simplified REST API version of the App Verify SDK intended for customers who prefer to do their own implementation. It provides the ability to verify an end user by using a voice call and a code contained in the caller ID. 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.

NOTE:

The App Verify API is for Android only. TeleSign offers an app verification solution for iOS using the SMS API. You can read about that solution on the App Verify iOS Sample App page.

General Information

All requests submitted for the App Verify API:

  • Can be authenticated with Basic (easiest to implement) and Digest
  • Accept only UTF-8 encoded unicode characters as inputs
  • Use Content-Type application/x-www-form-urlencoded in request headers

The App Verify API uses multiple endpoints to achieve verification. These endpoints are described in the chart:

Endpoint Title HTTP Method Endpoint URI Endpoint Description
Initiate POST https://rest-ww.telesign.com/v1/verify/auto/voice/initiate Use 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.
Finalize POST https://rest-ww.telesign.com/v1/verify/auto/voice/finalize Use 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 ID POST https://rest-ww.telesign.com/v1/verify/auto/voice/finalize/callerid 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 the Finalize CallerID Unknown endpoint to report the issue to TeleSign for troubleshooting.
Finalize Timeout Request POST https://rest-ww.telesign.com/v1/verify/auto/voice/finalize/timeout 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.
Get Call Status GET https://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 Verification Flow

Review the app verification process on the Review the App Verification Flow page.

Review Required Permissions

See what permissions are required to set up app verification on the *Review Required Permissions page.

Review App Best Practices

See what the best practices for the App Verify application are on the Review App Best Practices page.

App Verify API Examples

This section provides examples of requests and responses for the different endpoints in the App Verify API.

POST Initiate

Use the /initiate endpoint 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. A POST initiate request looks like this:

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

The body of the response to a POST initiate request looks like this:

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

POST Finalize

Use this to send TeleSign the verification code sent to the handset in the caller ID and the reference ID for the associated transaction.

A POST finalize request looks like this:

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

The body of the response to a POST finalize request looks like this:

Response for POST Finalize Request
{
  "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",
}

POST Finalize CallerID

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 the Finalize CallerID Unknown endpoint to report the issue to TeleSign for troubleshooting.

A POST finalize caller ID unknown request looks like this:

POST Finalize Caller ID
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
POST Finalize CallerID Response
{

	"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"
	},

}

POST Finalize Timeout

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.

A POST finalize timeout request looks like this:

POST Finalize Timeout
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

Get Status

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.

A GET request for the status of a voice call looks like this:

GET Status Request
POST 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=