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