App Verify API - Get Started

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 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 the handset owner noticing, 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

  • Base URL: rest-ww.telesign.com
  • 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

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

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 the Finalize CallerID Unknown 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 the Finalize Timeout 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 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. 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 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

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=

Did this page help you?