Verify API - Get started with Silent Verify

📘

NOTE:

Contact our sales team for availability of Silent Verify in your region. This product is available for full-service accounts only.

These steps walk you through using the Silent Verify verification method of the Telesign Verify API via the Telesign Android SDK. These instructions assume the use of a verification policy with:

• Silent Verify set as the primary verification method.
• SMS one-time passcode (OTP) set as the fallback verification method.

The steps assume a log in use case, but the same workflow also applies for other use cases. Two scenarios are covered: 1) silent verification succeeds and 2) silent verification times out and verification by SMS OTP succeeds.

Before you begin

Install the Telesign Verify Android SDK. Contact Telesign Customer Support or your Telesign contact to get access.

Setup

• Add the Telesign Verify Android SDK as a dependency in the Gradle project for your Android app.

• Add the following statements to the "proguard-rules.pro" file for the project:

  Kotlin

  -keep class com.telesign.verify.data.dto.** { *; }
  -keep class com.telesign.verify.api.models.** { *; }
  

  These statements exempt those two classes from being obfuscated by ProGuard, which is necessary for the Telesign SDK to function.

• Add the following permission to the "AndroidManifest.xml" file:

  Kotlin

  <uses-permission android:name="android.permission.CHANGE_NETWORK_STATE" />
  

  This enables the Telesign SDK to make use of the end user's mobile connection, even if they are configured to use Wi-Fi first.

🚧

CAUTION:

If connection to a mobile network cannot be established, you cannot use Silent Verify. The service fails over to using the backup delivery method (such as SMS OTP) in your verification policy, if one is defined.

Scenario 1: Silent Verify succeeds

1. USER attempts action (such as log in) on customer's mobile APP.
2. APP passes USER's phone number to customer's SERVER.
3. SERVER makes a request to the Telesign REST API to create a verification process.
4. REST API responds with a reference ID and mobile app token.
5. SERVER saves these values for later use and maps them to a new session ID.
6. SERVER sends the session ID and mobile app token to the APP.
7. APP subscribes to events sent by its local instance of the Telesign SDK using the TsVerify.observeEvents() method.
8. Telesign SDK responds with flow for these events.
9. APP passes mobile app token to the Telesign SDK using the TsVerify.activate() method.
10. Telesign SDK sends a request to Telesign REST API to begin silent verification.
11. Telesign REST API responds to Telesign SDK, confirming that silent verification is in progress.
12. APP displays to USER something like "silent verification in progress".
13. Telesign SDK gets verification payload from carrier and passes it to Telesign REST API to finalize.
14. Telesign REST API sends HTTP response to SDK indicating that silent verification succeeded.
15. Since the verification policy has been fully processed, Telesign SDK sends a TsVerifyEvent.Completed() event to APP. At this point the APP does not yet know that silent verification was successful.
16. APP asks SERVER for verification status.
17. SERVER makes a request to the Telesign REST API to retrieve a verification process.
18. REST API responds with the verification state.
19. If the verification state is VERIFIED, SERVER notifies APP that verification was successful.
20. APP allows USER to proceed with action.

Scenario 2: Silent Verify fails, SMS Verify succeeds

1. USER attempts action (such as log in) on customer's mobile APP.
2. APP passes USER's phone number to customer's SERVER.
3. SERVER makes a request to the Telesign REST API to create a verification process.
4. REST API responds with a reference ID and mobile app token.
5. SERVER saves these values for later use and maps them to a new session ID.
6. SERVER sends the session ID and mobile app token to the APP.
7. APP subscribes to events sent by its local instance of the Telesign SDK using the TsVerify.observeEvents() method.
8. Telesign SDK responds with flow for these events.
9. APP passes mobile app token to the Telesign SDK using the TsVerify.activate() method.
10. Telesign SDK sends a request to Telesign REST API to begin silent verification.
11. Telesign REST API responds to Telesign SDK, confirming that silent verification is in progress.
12. APP displays to USER something like "silent verification in progress".
13. Telesign SDK gets verification payload from carrier and passes it to Telesign REST API to finalize.
14. Telesign REST API sends HTTP response to SDK indicating that silent verification failed.
15. Telesign SDK fails over to next method in the verification policy and sends request to REST API to verify using SMS.
16. Telesign REST API tells Telesign SDK that it is in progress sending the SMS.
17. Telesign SDK sends a TsVerifyEvent.ExpectsOTP() event to APP, indicating that an SMS OTP is on its way to the USER.
18. APP updates UI with message saying something like "silent verification could not be completed" and displaying input field for asserted OTP from USER.
19. USER receives SMS OTP on their device.
20. USER enters asserted OTP in input field, before the time out window expires.
21. APP sends this asserted OTP to Telesign SDK using the TsVerify.finalizeWithOTP() method.
22. Telesign SDK sends this asserted OTP to Telesign to check against the original OTP sent.
23. Once the verification policy has been fully processed, Telesign SDK sends a TsVerifyEvent.Completed() event to APP. At this point the APP does not yet know that SMS verification was successful.
24. APP asks SERVER for verification status.
25. SERVER makes a request to the Telesign REST API to retrieve a verification process.
26. REST API responds with the verification state.
27. If the verification state is VERIFIED, SERVER notifies APP that verification was successful. Telesign determined that the asserted OTP matched the original OTP.
28. APP allows USER to proceed with action.