App Verify API - Get started
This page explains how to use the Telesign App Verify API to verify devices through a flash 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. This is called Frictionless App Verification.
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.
NOTE:
The verification code length is set up by our Customer Support Team. Please contact them to configure this code. They will help you determine whether the code will be five or six digits.
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 randomly generated digits for the verification code. |
| 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, along with the reference ID for the associated transaction. This step helps confirm the success of the verification call, improves reporting accuracy and ensures smoother resolution if issues arise. |
| 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 the randomly generated digits for the verification code.
Example
Request
curl --location --request POST 'https://rest-la6.telesign.com/v1/verify/auto/voice/initiate' \
--header 'Accept: application/json' \
--header 'Content-Type: application/json' \
--header 'Authorization: Basic AAAAAAAA-BBBB-CCCC-DDDD-EEEEEEEEEEEE:n1oBUjEwVunkjfH9paeA9qHrjQw=' \
--form 'phone_number="your phone number"'
Response (body)
{
"resource_uri": "/v1/auto/voice/finalize",
"reference_id": "0123456789ABCDEF0123456789ABCDEF",
"sub_resource": "auto_verify_initiate",
"errors": [],
"status": {
"updated_on": "2025-03-05T21:47:07.962922Z",
"code": 2400,
"description": "Pending"
},
"prefix": "4478730",
"verify_code": "20085"
}
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
curl --location 'https://rest-la6.telesign.com/v1/verify/auto/voice/finalize' \
--header 'Authorization: Basic AAAAAAAA-BBBB-CCCC-DDDD-EEEEEEEEEEEE:n1oBUjEwVunkjfH9paeA9qHrjQw=' \
--header 'Content-Type: application/x-www-form-urlencoded' \
--data-urlencode 'reference_id=6656D5F06914025C91D5CDD7A398BFEE'
Response (body)
{
"resource_uri": "/v1/verify/6656E61D9674045C91D417A1EC38210A",
"reference_id": "0123456789ABCDEF0123456789ABCDEF",
"sub_resource": "auto_verify_finalize",
"errors": [],
"status": {
"updated_on": "2025-03-21T16:27:03.473939Z",
"code": 2401,
"description": "Success"
},
"verify_code": "69816"
}
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
curl --location 'https://rest-la6.telesign.com/v1/verify/auto/voice/finalize/callerid?reference_id=null&uknown_callerid=null' \
--header 'Authorization: Basic AAAAAAAA-BBBB-CCCC-DDDD-EEEEEEEEEEEE:n1oBUjEwVunkjfH9paeA9qHrjQw=' \
--header 'Content-Type: application/x-www-form-urlencoded' \
--data-urlencode 'reference_id=6657BA3BBCEC035C91D786B351C83A01' \
--data-urlencode 'unknown_caller_id=447873086363'
Response (body)
{
"resource_uri": "/v1/verify/665728003420025C91D5CDEF02F89BDF",
"reference_id": "0123456789ABCDEF0123456789ABCDEF",
"sub_resource": "auto_verify_finalize_unknown",
"errors": [],
"status": {
"updated_on": "2025-03-24T21:12:50.289628Z",
"code": 2407,
"description": "Caller ID 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
curl --location 'https://rest-la6.telesign.com/v1/verify/auto/voice/finalize/timeout' \
--header 'Authorization: Basic AAAAAAAA-BBBB-CCCC-DDDD-EEEEEEEEEEEE:n1oBUjEwVunkjfH9paeA9qHrjQw=' \
--header 'Content-Type: application/x-www-form-urlencoded' \
--data-urlencode 'reference_id=6657BA52AD580A5C91D7BDC064683C6C'
Response (body)
{
"resource_uri": "/v1/verify/2657270BF1AC075C91D69D9A76E8600C",
"reference_id": "0123456789ABCDEF0123456789ABCDEF",
"sub_resource": "auto_verify_finalize_timeout",
"errors": [],
"status": {
"updated_on": "2025-03-24T20:06:01.454168Z",
"code": 2409,
"description": "Verification call not received"
}
}
Use this endpoint to retrieve details about the status of the voice call transaction.
Request
curl --location 'https://rest-la6.telesign.com/v1/verify/auto/voice/6657BA8C49C8055C91D0EA25A6083C49' \
--header 'Authorization: Basic AAAAAAAA-BBBB-CCCC-DDDD-EEEEEEEEEEEE:n1oBUjEwVunkjfH9paeA9qHrjQw='
Response (body)
{
"reference_id": "0123456789ABCDEF0123456789ABCDEF",
"sub_resource": "app_verify_api",
"errors": [],
"status": {
"updated_on": "2025-03-28T21:19:42.406000Z",
"code": 2401,
"description": "Success"
}
}
Updated 8 days ago