App Verify API - Review the app verification flow

This page describes the basic flow of an application using App Verify API. Links are provided to the endpoint you need to use for each part of the flow.

App verification flow

App Verify API sends an end user a phone call where the verification code is the last five digits of the caller ID.

There are two ways you can set up your application flow:

  • Frictionless app verification - To use the frictionless method, you must have permission from Google to access call logs.
  • Missed call verification - Instead of automatically retrieving the verification code from the caller ID, you have the end user manually review the phone number they missed a call from and enter the last five digits of the number as the verification code.

Reviewing the diagram, the part that will differ slightly is how the code is retrieved. For the arrow labeled Verify Code, with frictionless app verification the code is sent for the end user. With missed call verification, the end user must take the last five digits of the missed call, and enter them into the app.

A diagram of the basic flow of an application using App Verify.

The following table includes all of the essential parts necessary for an App Verify API transaction to be successful:

NameDescription
CustomerThe organization that develops the application and is responsible for the transaction.
HandsetA device such as a phone.
NumberThe phone number used on the handset.
ApplicationThe software that runs on the handset.
UserThe person who is using the handset.
Caller IDAn identification number generated by Telesign.
PrefixThe first digits of the caller ID.
Verify codeThe last five digits of the caller ID; randomly generated by Telesign.

Steps in the verification flow

  1. Run your application on the user's handset. This sets up the transaction and uses the network to call the customer’s network interface.
  2. Make an Initiate request to Telesign that includes the phone number used for the handset. Telesign then returns a prefix that you send to your application for screening calls. You can review the initiate endpoint parameters and responses on the POST /v1/verify/auto/voice/initiate page.
  3. Telesign calls the phone number using a voice call with a predefined caller ID, which includes a fixed prefix and five digits that are randomly generated. Other calls from different caller IDs that do not start with the Telesign prefix are likely to be real phone calls. Therefore, your application should allow the user to answer calls that don't normally have the specified prefix.
  4. If you are using the frictionless app verification method, your application identifies the call that starts with the prefix and extracts a verify code (the last five digits of the caller ID), which the application sends to your network interface. Otherwise, if you are using the missed call verification flow, your end user manually extracts the five digits from the end of the missed call and adds them to the app.
  5. This code is then sent with a Finalize request to Telesign. This request must include the reference ID for the transaction and the verify code that your application received. When you send the Finalize request, Telesign recommends that you also implement terminate the call on the handset. If you do not, as a back up, when Telesign receives the Finalize request, Telesign terminates the call. If Telesign does not receive a Finalize request, the call is canceled after a short period of time. Canceling the call as soon as you can safely do so alleviates potential problems caused by voicemail picking up the call as well as preventing unnecessary phone charges. You can review the finalize endpoint parameters and responses on the POST /v1/verify/auto/voice/finalize page.
  6. Telesign compares the verify code generated for the call with the verify code in the Finalize request to determine whether they match. The result indicates whether the transaction is successful or not ('success' or 'failed'). If the transaction is successful, you can verify that the handset is associated with the number provided. If the transaction is not successful you can send an unknown caller ID failure request to Telesign, and Telesign responds with failure details. You can review the endpoint for caller ID and its parameters and responses on the POST /v1/verify/auto/voice/finalize/callerid page. If there is an issue with a timeout, you can report it with the finalize timeout endpoint. You can review the finalize timeout endpoint and its parameters and responses on the POST /v1/verify/auto/voice/finalize/timeout page.
  7. You can find out the status of your request by using the get status endpoint. To read more about this endpoint refer to the GET /v1/verify/auto/voice/{reference_id} page.

📘

NOTE:

  • Only one Finalize request is allowed for any given transaction, as additional requests for the same transaction result in an error. Therefore, you should only finalize once. If you try to make two finalize requests for the same reference ID, the first will yield valid results (success or failure), and the second will return a finalize error (telesign.exceptions.TelesignError: Invalid AutoVerify API finalize) and the information associated with that reference ID will be invalidated.
  • Telesign can process multiple Get Status requests for checking the status of a transaction.
  • All information from the handset must go through REST API requests you send. It is your responsibility to ensure security at the application and API levels. In particular, you must not distribute Telesign credentials in the application, because anyone could disassemble the application to gain access. This would put both your company and Telesign at risk for a security breach.

WHAT'S NEXT

App Verify API - Review required permissions