App Verify Android SDK

The App Verify Android SDK integrates a frictionless user verification process into existing native Android applications. It allows mobile applications for Android to use TeleSign’s proprietary auto verification service to verify an end user’s device and phone number without embedding the authentication credentials in the application where they can be easily hacked and taken. The service securely sends a voice call or SMS to the end user’s device and automatically verifies the number.

Using the SDK, your mobile application can invoke the following types of verification:

  • Auto Voice verification, which sends a voice call
  • SMS Retriever, which sends an SMS message if the end user has GooglePlay installed (if this option is successful, you do not need to request permissions to send an SMS, making the end user experience smoother)
  • Auto SMS verification, which sends an SMS message

The App Verify Android SDK is discussed in the following sections:

NOTE:

A JSON Web Token (JWT) server is required in order to use App Verify. For details about how to create a JWT service, refer to Implement a JWT Service.

Supported Versions

The App Verify Android SDK supports Android API 16-25 (JellyBean to Nougat). Refer to the Android website for additional information.

How it Works

The following diagram illustrates the verification process flow between your mobile application, your server, and TeleSign’s server:

The app verification process as depicted in the diagram works like this:

  1. Open App & Input Phone Number - Open the application and input the phone number. (The end user must input a phone number in order for a JWT token to be fetched.)

  2. Start Verification with Phone Number & JWT - When an end user opens your application, after they enter their phone number, the application obtains a security token from your JWT service. Your application initializes verification by contacting the TeleSign server with the end user’s phone number and the security token.

  3. Voice call or SMS with code - TeleSign sends an SMS or voice call. The TeleSign server then texts or calls the end user’s phone with a short duration call. The verification call will vibrate the phone for a short pulse (if the vibrate permission is enabled), and the end user might see the caller ID briefly. The end user cannot respond to or cancel this call. The call has a predefined caller ID containing a randomly generated verification code.

NOTE:

The sample app waterfalls from AutoVoice to SMS Retriever to AutoSMS in order to showcase all available features. You may choose a different configuration depending on your needs.

  1. Auto Consume - In the Auto Consume step, the App Verify Android SDK automatically consumes and processes the incoming call or SMS to read the embedded verification code and verify the phone number. (If you are using SMS retriever, Google Play services receives an app hash that is reviewed to make sure the message is intended for your app and if so, it makes the message text available to your app through the SMS Retriever API.)

  2. Finalize Verification with Code - In the Finalize Verification with Code step, TeleSign compares the verification code that it generated for the call with the verification code that your application sent back to determine whether they match.

  3. Claim Verified - In the Claim Verified step, your application makes a claim to your network server that TeleSign verified the transaction.

  4. Confirm Verified - In the Confirm Verified step, your application obtains the verification status in either of the following ways. After your application confirms verification, your server can approve an end user’s transaction or create a user account. Using the Get Status approach, your application makes a request to the Get Status Service.

What’s in the App Verify Android Repository on GitHub?

The App Verify Android SDK repository is on GitHub here:

It contains the following components:

Requirements

Before using the App Verify Android SDK in an application, your application must meet the following requirements:

  • minSdkVersion of 16
  • appropriate permissions - See Required Permissions
  • Your TeleSign customer ID and API key (used for authentication)
  • JWT service - For instructions about how to set up your JWT service, refer to the JWT Service for App Verify page.
  • For SMS Retriever to work, you will need an Android device with Play services version 11 or newer.
NOTE:

Implementing a JWT Service is a critical step. Without a JWT Service, client applications cannot authenticate with TeleSign services used by the SDK.

Try the AppVerifySample Application

For a thorough walkthrough about how to configure and review the App Verify sample application, refer to the How it Works section of the Verify a Mobile Device with App Verify Android page.

Integrating the SDK

For a discussion and a code sample showing an integration of App Verify, refer to the Implementation Walkthrough section of the Verify a Mobile Device with App Verify Android page.

Obtaining Verification Status

This section describes the methods available to obtain verification status. For a complete walkthrough about obtaining verification, refer to the Final Verification with Get Status or Verify Transaction Callback section of the Verify a Mobile Device with App Verify page.

When you implement the verification process in your application, you must check the status of each transaction with TeleSign. There are two ways to do this, with the Verify Transaction Callback service, or with the Get Status service.

NOTE:

The Verify Transaction Callback and Get Status options are not App Verify SDK functionality in your application, but rather REST API requests made on the back end, between your server and the TeleSign server. For example, using Verify Transaction Callback, when the auto verification service determines a successful verification result, the TeleSign server sends a callback to your server to notify the client app of the verification transaction status.

Verify with the Get Status Service

In this scenario, you have the option to request verification results from TeleSign using the Get Status service. You can retrieve verification results within the 12-hour period following each instance of a verification request by sending a GET request to the URL noted in Get Status Service.

Verify with the Verify Transaction Callback Service

In this scenario, when TeleSign verifies your application’s user, it makes a callback request to a web service that you have set up. In order to use the callback service, you must first set up a web service and provide the URL to TeleSign support. Support then configures it in the TeleSign system. TeleSign then makes a server­-to-server callback to notify your service of the status of the verification transaction. For more information, see Verify Transaction Callback Service.

Get Status Service

TeleSign provides the option for you to retrieve verification status using the Get Status REST API.

Service Endpoint

The URL for issuing HTTP GET requests for the Get Status web service is:

https://rest-api.telesign.com/v1/mobile/verification/status/[xid]

After you make a verification request, retrieve the verification results by sending an HTTP request with an XID identifier for the original service request.

TeleSign’s web server processes REST API requests, then returns the results formatted as a JavaScript Object Notation (JSON) response in the entity-body of an HTTP response message.

Get Status by SDK

You can use a TeleSign SDK to perform Get Status requests, and Get Status code samples are available.

Choose your language:

The code sample for using Get Status looks like this:

var TeleSignSDK = require('telesignsdk');

const customerId = "FFFFFFFF-EEEE-DDDD-1234-AB1234567890"; // Todo: find in portal.telesign.com
const apiKey = "EXAMPLE----TE8sTgg45yusumoN6BYsBVkh+yRJ5czgsnCehZaOYldPJdmFh6NeX8kunZ2zU1YWaUw/0wV6xfw=="; // Todo: find in portal.telesign.com
const rest_endpoint = "https://rest-ww.telesign.com"; 
const timeout = 10*1000; // 10 secs
const EXTERNAL_ID = "external_id";

const client = new TeleSignSDK( customerId,
    apiKey,
    rest_endpoint,
    timeout // optional
    // userAgent
);

function statusCallback(error, responseBody) {
    if (error === null) {
        console.log(`App verify transaction for External ID: ${EXTERNAL_ID}` +
            ` => code: ${responseBody['status']['code']}` +
            `, description: ${responseBody['status']['description']}`);
    } else {
        console.error("Unable to perform status for the given externalID. " + error);
    }
}

console.log("## AppVerifyClient.status ##");

client.appverify.status(statusCallback, EXTERNAL_ID);

If you want to code everything yourself, you will need to handle authentication yourself. Refer to the section Authentication.

Sending a GET Request

After you make a verification request, retrieve the verification results by sending a GET request to the following URI with an XID identifier for the original service request:

GET /v1/mobile/verification/status/resource

The XID is the reference identifier that your JSON Web Token (JWT) service generates. This value uniquely identifies each token issued by the JWT service. For more information, see JWT Service for App Verify.

After the application completes the verification process on the server side, use the Get Status service with the xid parameter.

Sample GET Request

Request: https://rest-api.telesign.com/v1/mobile/verification/status/[xid]

Response (JSON):

Example Get Status Response
{
   "sub_resource" : "voice_auto",
   "status" : {
       "code":1800,
       "description":"Success"
      "updated_on" : "2015-04-15T18:40:54Z",
   },
   "mobile_verification" : {
      "phone_number" : "1-310-123-4567",
      "xid" : "4325217a-742e-11e4-b116-123b93f75cba ",
   },
}

The sub_resource value is the verification method type. The status code returns one of the following statuses: 1890 (Pending), 1800 (Success), or 1803 (Failure).

Transaction Get Status data is available for 12 hours. After that, the web service returns “Not Found.”

Status Codes

The following table includes status codes that can be generated by the Get Status API:

| Status Code | Description | | - - - - - - - - - - --| - - - - - - - - - - - — | | 1800 | Success | | 1803 | Failed | | 1805 | Not Supported | | 1807 | Caller ID unknown | | 1829 | Blocked by customer request | | 1830 | Blocked by TeleSign | | 1890 | Pending |

Verify Transaction Callback Service

TeleSign’s App Verify Android SDK offers the Verify Transaction Callback REST API to enable your application to receive verification results. The Verify Transaction Callback API makes a server­-to-server HTTP POST callback from the TeleSign server to your service endpoint to notify your web server of a successful verification transaction.

You can read any of the verification results without using your secret key, but to confirm that the results are genuinely from TeleSign, you must process the header and verify that the signature is from TeleSign. To read more about how to do that, see the section Authenticated Callbacks from TeleSign.

NOTE:

You must use standard ports in order for transaction callbacks to work properly. For HTTP, the default standard port would be 80, and for HTTPS (transport layer security (TLS)), the default standard port would be 443.

Service Setup

To use the Verify Transaction Callback service:

  1. Create a private URI on your web server for receiving callback notifications from TeleSign. Fields that will be sent back with the JSON formatted response include:
  • Custom Authorization header (refer to section Authenticate Callbacks from TeleSign below).
  • Reference ID
  • Sub-Resource
  • Errors
  • Status: Updated On
  • Status: Code
  • Status: Description
  • Verify: Code State
  • Verify: Code Entered
  • Verify: Code Submitted
  • Submit Timeline
NOTE:

For mission critical applications, TeleSign recommends that you provide redundancy by implementing two URIs instead of one.

  1. Provide TeleSign with your private URI.

  2. Allow 1 business day for setup to be completed.

  3. You will receive callback notifications after a verification transaction completes. You can check the transaction status codes you receive in the Transaction Status Codes for Get Status and Verify Transaction Callback section.

  4. If TeleSign is unable to deliver your callback notification on the first attempt, the TeleSign server waits 30 seconds, then tries again. If the second attempt fails, the server waits an additional 5 minutes and then makes a final attempt. After that, to obtain verification information, your application should resort to using the Get Status method, described above.

Authenticate Callbacks from TeleSign

If you need to set up authenticated callbacks, you must use digest authentication. You can read about digest authentication and authenticated callbacks in the Authenticated Callbacks with the Get Status / Verify Transaction API section on the Authentication page.

Callback Verification Results

TeleSign provides a JSON response to Verify Transaction Callbacks only in the case of a successful App Verify verification.

NOTE:

If start/initiate fails, TeleSign does not send a callback. However, if the verification process begins, TeleSign does send a callback.

The following is a sample JSON response from a POST callback request:

JSON
{
  "status": {
    "updated_on": "2014-10-30T22:57:43.984001Z",
    "code": 1800,
    "description": "Success"
  },
  "submit_timestamp": "2014-10-30T22:57:43.612000Z",
  "errors": [],
  "sub_resource": "voice_auto",
  "mobile_verification": {
    "phone_number": "13101234567",
    "xid": "4325217a-742e-11e4-b116-123b93f75cba"
  },
  "reference_id": "B149634764BC0144C833G7280C4403B8"
}

Transaction Status Codes for Get Status and Verify Transaction Callback

Code Description Detail
300 Transaction successfully completed The system was able to obtain all of the requested data for PhoneID.
301 Transaction partially completed The system was able to obtain some of the data for PhoneID, but not all of it.
500 Transaction not attempted No Call, SMS, or PhoneID request was attempted
501 Not authorized No permissions for this resource, or authorization failed.
599 Status not available The system is unable to provide status at this time.

General Best Practices

Prompt User to Enter Phone Number of Mobile Device

TeleSign recommends that you show a message prompting end users to enter the mobile phone number of the device on which the application is downloaded and installed, not the number of another device or landline. For example, the message might read:

“Please enter the mobile phone number of the device on which this application is installed and make sure that the cellular connection is on.”

You should attempt auto verification only on mobile devices capable of receiving a circuit-switched voice call or a SMS message. For example, if an end user downloads your app to a tablet that can perform only data traffic, auto verification will fail.

In cases where the end user does not want to provide a mobile number, you should design your application workflow appropriately to utilize other types of non-mobile verification (such as Voice Verify or SMS Verify) to provide the user with an option for an alternate form of verification, along with an appropriate message.

Enter Country and Phone Number Separately

Your application should display the country code (or country name) and the phone number in separate input text boxes. Recommended layouts are to position the fields vertically on different lines, or to position them horizontally with a gap between them. Often when end users enter the country code and phone number in the same field, it results in mistakes such as users adding a preceding ‘0’ or ‘+’, or inserting a ‘0’ between country code and phone number, as practiced in different countries.

Auto-Extraction

TeleSign recommends that your application not auto-extract phone numbers. Programmatic auto-extraction of phone numbers does not work consistently for various service providers and locales. If the auto-extraction support of phone number is provided, it is recommended that developers provide an option for the end users to edit the phone number.

The SDK includes methods that can help you auto extract your end user’s phone number from their phone. Auto extraction does not work well in every country, however, it can be a nice feature to offer in your application. Auto-extraction of a phone number works reliably (80% of the time or more) in the following countries:

  • Austria
  • Bahrain
  • Bosnia
  • Canada
  • Croatia
  • Finland
  • France
  • Herzegovina
  • Kuwait
  • Lebanon
  • Norway
  • Peru
  • Russia
  • Singapore
  • Switzerland
  • Taiwan
  • US
  • US Virgin Islands

For App Verify Voice, Notify the End User They Will Receive a Voice Call

Make sure your end user is aware that they will receive a voice call for verification purposes and that they should ignore it.

Tell Users to Omit Non-Numerals from Phone Numbers

You should instruct end users to enter their phone number without spaces, dashes, or special characters, because phone number formatting varies by country.

Best Practices for Phone Number Formatting

When you pass mobile phone numbers to the App Verify SDK, you must follow strict formatting rules in order for the TeleSign server to be able to verify the number. You must normalize the phone number prior to submitting it to the auto verification service.

The App Verify Android SDK accepts phone numbers in the E.164 format, which includes country codes, area codes, and phone number (number string with no spaces, dashes, and so on). For example:

  • 13101234567 is normalized from 1(310)123-4567 (United States)
  • 447981897555 is normalized from +44-7981-897555 (United Kingdom)

Allow the user to input the phone number.

You must normalize the phone number prior to submitting the SDK to process by doing the following:

  • Use regular expressions to strip characters.
  • Ensure that there are no characters, such as “,” and spaces.

For more information on phone number formatting for Android, see PhoneNumberUtils in the Android Developer Reference.

TeleSign recommends that developers allow end users to input the phone number directly in the application. This is because the App Verify Android SDK does not auto extract phone numbers from mobile devices. Developers can implement this feature directly, but with the caveat that it may not work consistently across carriers and devices worldwide.

NOTE:

All phone numbers for Domestic / International calling must include the country code.

Android Activity Lifecycle

Because the Android OS automatically reclaims resources, you as an application developer need to be aware of application lifecycle events. Background processes are the first resources to be reclaimed when the OS needs memory. The App Verify Android SDK runs auto voice and auto SMS verification asynchronously on a background thread, so a verification failure or a bad end user experience could occur if the running verification is associated with an activity that is moved to the background.

An activity can be paused, stopped, or destroyed. This discussion treats stopped as the same state as paused. Each state is defined as follows:

Paused/Stopped

An activity is paused when an end user moves it to the background. The current activity can pause, for example, when an end user changes activities or turns off the phone’s screen. The activity and associated threads continue to run, but can be reclaimed by the OS at any time, in which case they will be destroyed. When an activity calls onPause, you can leave Verification.startAsync running. The verification process can still call VerificationListener methods such as onStageFailure and onSuccess while the activity remains in the background. In other words, auto verification can complete successfully when an end user shuts off the screen or switches to another app. Being in a paused state poses some risk, because a paused activity can be destroyed, and a destroyed activity will lose its verification progress.

Destroyed

An activity is destroyed when an end user closes it or when it is reclaimed by the operating system. This is more likely to occur to an activity that is in the paused state. When an activity is destroyed, any references to it are destroyed as well, including the verification object. The application should call Verification.cancel in an activity’s onDestroy method, so that the SDK can perform cleanup on the object and the memory can be completely reclaimed by the OS. When the verification is cancelled or destroyed, the state of the verification will be lost. Even if the verification is given a chance to cancel (using the cancel method), an out-of-band voice call or SMS message can still arrive. In the case of auto voice verification, the incoming call would not be automatically terminated, since the verification thread is no longer running.

A best practice to mitigate the problems described for the pause and destroyed states would be to run the SDK from an Android Service, which is meant to be run in the background. The OS will avoid reclaiming all paused activities before it reclaims services. An activity could start a service, and the service can act as a buffer between the activity and the SDK. Even if the activity is paused or destroyed, it can reload the state from a running service when the app is reopened. This is essentially the Model/View/Presenter (MVP) design pattern: the activity (View) loads data from the service (Model), and the code to load data into the activity dynamically is the Presenter.

Handling Duplicate Verification Requests

Ensure that a duplicate verification request for the same number is not sent to TeleSign for verification when there is an on-going request. For example, the application should not call TeleSign API methods to trigger a duplicate verification process. The request should be either a success/failure/timeout which gets returned by the SDK to the application. You should disable or hide the button which is provided to the end user to trigger the Auto Verification process after the verification process is already triggered. This is to prevent duplicate verification requests originating from the application.

Handling Non-Verification Calls

This section provides details about how to handle non-verification calls. A non-verification call is any phone call that is not part of the verification process for your end user.

To correctly handle the calls, you need to be aware of three things:

  1. On a CDMA device with no wifi connection, when a phone call is in progress, the phone does not have internet access.
  • The customer’s registration process and App Verify fail, since they both need internet access.
  1. Two calls cannot simultaneously ring on a telephone. While one call is ringing, a second call that tries to ring is sent to voicemail or gets a busy signal, depending on whether voicemail is set up.
  • For the brief moment AutoVoiceVerification is ringing on the device, if another phone call comes in, it will get sent to voicemail. No call will get logged onto the device. The caller can either leave a voicemail or try again. AutoVoiceVerification will succeed normally.
  • If another phone call is ringing when the AutoVoiceVerification phone call tries to ring, the App Verify phone call will either get a busy signal or get sent to voicemail. If the call gets a busy signal, the TeleSign API will retry sending the voice call and the second call will come in a few seconds later while the phone is most likely not ringing. If the call is sent to voicemail, App Verify fails after waiting about 30 seconds for the call.
  1. On Android, if two calls are in progress, the API does not provide support for terminating one and only one of the calls. To avoid disrupting an ongoing call, TeleSign does not terminate calls if another call is in progress.
  • On a device with GSM or with both a CDMA and wifi connection, if the AutoVoice Verification call comes in while there is another phone call going on, TeleSign does not terminate either call. As a result, either the phone will ring until it gets sent to voicemail, or the phone is answered by the end user, and the call immediately hangs up and the end user is returned to their previous call. No matter which of these outcomes occurs, AutoVoiceVerification completes normally afterwards.

Required Permissions

Beginning with Marshmallow, you must explicitly request certain permissions you need for your application. This section displays all permissions you may potentially need.

  • android.permission.READ_PHONE_STATE - You must ask the end user to grant this permission.) Allows read only access to the phone’s state, and is used to determine the status of any ongoing calls. You need this permission so you can verify that your end user receives a phone call from TeleSign.

  • android.permission.CALL_PHONE - (When you ask the end user to grant the READ_PHONE_STATE permission, Android bundles this one in with it.) You need this permission so you can cancel phone calls from TeleSign.

  • android.permission.RECEIVE_SMS - (You must ask the end user to grant this permission if you want to use AutoSMS. If your end user has GooglePlay, you can use SMS retriever, and then you do not need to request this permission.) You need this so your application can receive SMS messages. You need this permission so you can read contents of SMS messages from TeleSign.

  • android.permission.WRITE_EXTERNAL_STORAGE - This permission is optional. You only need it to write encrypted logs to the SD card.

  • android.permission.INTERNET - Allows applications to open network sockets.

  • android.permission.ACCESS_NETWORK_STATE - Allows applications to access information about networks.

  • android.permission.VIBRATE - (Optional) Allows access to the vibrator. If this permission is enabled, a signal will be sent to alert the end user about an incoming call or SMS message.

Required Permissions for Android O

If you are targeting your application for Android O, the device must explicitly add android.permission.READ_PHONE_STATE and android.permission.CALL_PHONE in the manifest.xml in order for the App Verify SDK to read the verify code in the phone call and terminate the phone call. Previously, if you added android.permission.READ_PHONE_STATE in manifest.xml it would grant all permissions in the group (the group includes android.permission.READ_PHONE_STATE and android.permission.CALL_PHONE).

Error Codes

Verification Error Types

The App Verify Android SDK includes the Verification Listener, an interface to notify developers about events and errors in the verification flow, by way of callbacks. The Verification Listener includes the onStageFailure method, which enables developers to locate errors if the verification process fails. For more information on these errors, see the VerificationError.ErrorType enumeration in the Javadoc API Reference.

The following table describes the verification error codes that the App Verify Android SDK can generate:

Code Error Type Description Mitigation Steps
-1 MissingRequiredParameter A required App Verify parameter is missing. For example, the app version is not set. Contact TeleSign, it is possible an unsupported SDK version is in use.
-2 InvalidRequiredParameter The App Verify request parameter is invalid. For example, the customer_id is longer than 40 characters. Contact TeleSign.
-3 JWTInvalidSignature The JWT has an invalid signature. Please make sure your JWT server is returning valid token strings. 1. Review and follow JWT setup instructions in the developer portal. 2. Contact TeleSign for further assistance.
-4 JWTInvalidTimeRange The JWT has an invalid time range. (JWT parameter: now() < iat or now() > exp.) This is most likely due to setting the expiration window too short. TeleSign recommends 30 seconds. 1. Review and follow JWT setup instructions in the developer portal. 2. Contact TeleSign for further assistance.
-5 JWTInvalidISS The JWT ‘iss’ claims field does not match your Customer ID (customer_id). 1. Review and follow JWT setup instructions in the developer portal. 2. Contact TeleSign for further assistance.
-6 InvalidHashCash The generated HashCash stamp is invalid. If this occurs, please make sure you are using the latest version of the App Verify SDK. 1. If this occurs, make sure you are using the latest version of the App Verify SDK. 2. Display a message to you end user about syncing the device time to the mobile network time and retry verification. 3. If the problem persists, contact TeleSign for assistance.
-7 StageTimeout Data not found in database cache (initiate timeout) or the TeleSign backend is unable to get your API keys. 1. Verification process did not complete within required time. 2. Contact TeleSign for further assistance.
-8 VerificationMethodNotSupported Verification is attempted on a non-compatible device, for example on a tablet where a circuit switched voice call and SMS are not supported. A specific verification type is not supported in this region, for example, Auto Voice may not be available in specific countries. 1. Proceed to auto fail over to Auto SMS if supported or an alternate verification type if supported (Voice/Messaging).
-9 RateLimitExceeded Customer has hit the maximum limit for number of transactions allowed per second. 1. Auto fail over (if supported) if an error is encountered with voice or fallback to other verification methods. 2. You should have a workflow to waterfall to other verification methods.
-10 PhoneNumberBlockedByTelesign The phone number has been blocked by TeleSign. 1. Contact TeleSign, the phone number is in TeleSign’s block list. 2. Do not waterfall.
-11 PhoneNumberBlockedByCustomer The phone number is the block list of the customer and blocked by TeleSign due to customer request (blocking will be specific to a customer). 1. Contact TeleSign, the phone number is on TeleSign’s block list. 2. Do not waterfall.
-12 AuthenticationFailed Customer credentials are invalid or revoked. 1. Contact TeleSign.
-13 InvalidPhoneNumber The phone number may be incorrectly formatted or include invalid characters. 1. Display a message to the user on entering the mobile phone number. 2. Ensure that invalid characters, white spaces, or any other special characters are removed by the application before passing the phone number to the App Verify SDK’s method. 3. If the auto-extraction feature is used, ensure that it works well in the region where the device is being used or else disable the auto-extraction for that region. 4. Contact TeleSign.
-14 InvalidVerificationCode The verification code does not match to the one that was sent by TeleSign to the device. 1. Check the verification code that was sent to the device. 2. Contact TeleSign. 3. Disable the verify button after the end user presses it so they cannot initiate a duplicate verification. (This error is likely to occur if an end user requests verification more than once.)
-20 IPNotAllowed The source IP for the request is not in the list of allowed IPs configured for this account. 1. Contact TeleSign.
-21 MonthlyHardCapExceeded The monthly transaction cap has been exceeded for this account. 1. Contact TeleSign.
-22 DisabledForThisCountry This product is not enabled for this Country.
-23 MissingRequiredClaimInJWT JWT contains an invalid external ID.
-24 UnverifiedPhoneNumber There is an unverified phone number in the request.
-25 InsufficientFunds Insufficient funds in prepaid wallet for request.
-26 InvalidAppHash Invalid application hash setup.
0 Unknown An unknown error occurred. Contact TeleSign support.
1 JWTServerConnectionFailed Could not connect to the supplied JWT server. Either no internet connection is available or the supplied host name cannot be resolved. This condition might be caused if you provide malformed URLs or URLs that direct to non-existent servers, or if you do not pass a valid RequestTokenUrl.
2 MVServerConnectionFailed There was an error connecting to TeleSign’s backend. Check the phone’s internet connection or contact TeleSign support.
3 HashCashGenerationFailed An error occurred performing proof-of-work. Contact TeleSign support.
4 MVServerBadResponse The SDK received a malformed response from the TeleSign backend. Contact TeleSign support.
5 JWTServerBadResponse Received an unrecognizable response from the JWT server. Please make sure the URL you supplied points to a functional server, that the endpoint is working, and that the response is in the format specified in the documentation. If the server returns “Internal Server Error,” wraps the JWT in a dictionary, or does anything not matching the specification, then JWT retrieval will fail.
6 MissingRequiredPermission The user has not granted a runtime permission required to perform auto verification.
7 UnsupportedAndroidVersion The version of Android running on the phone is below the minimum version supported by the SDK. The current minimum is 16.
NOTE:

A phone number is required to use verification objects. Therefore, an error will occur on any device that doesn’t have a phone number associated with it.

System Unavailable

HTTP Code Error Code
503 -90001

Invalid Signature

HTTP Code Error Code
401 -30006

Rate Limit Exceeded

HTTP Code Error Code
429 -40007

XID Not Found or XID Does Not Belong to Customer

HTTP Code Error Code
400 -50059

Get Status by XID Codes

This section provides details about codes returned by App Verify when attempting to do a Get Status request using XID codes.

Transaction Status Code Reason
1800 : “Success” Client SDK code called / finalize with a successful resolution (i.e. not something like /finalize/unknown)
1803 : “Failed” Internal status code is not Success AND transaction is > 30 seconds old. The transaction timed out and failed.
1805: “Unsupported” Server side code logic considered the device data to be unsupported.
1806: “invalid_phone” Cleansing failed for the number given.
1807: “unknown” Voice call with unknown callerID received on device.
1808: “timeout” Client waited for the call but it did not occur.
1829: “blocked_by_customer” Customer feature was set to block this phone number.
1830: “blocked” TeleSign blocked this phone number.
1890 : “Pending” Internal status code is Pending AND transaction is <= 30 seconds old. The transaction did not time out yet.