Review the App Verification Flow

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

The app verification flow is discussed in the following sections:

App Verification Flow

Below is a typical flow for using the App Verify API:

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

Name Description
Customer The organization that develops the application and is responsible for the transaction.
Handset A device such as a phone.
Number The phone number used on the handset.
Application The software that runs on the handset.
User The person who is using the handset.
Caller ID An identification number generated by TeleSign.
Prefix The first digits of the caller ID.
Verify Code The 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. 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.
  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.

Next Steps

This section offers some suggestions for next steps to take.