SubscriberCheck Integration Guide

info

The page you're currently viewing displays functionality for the SubscriberCheck API v0.2. If you want to see the functionality for the SubscriberCheck API v0.1, please click here

The tru.ID SubscriberCheck API confirms the ownership of a mobile phone number by verifying the possession of an active SIM card with the same number. It also provides a flag that indicates if the SIM card associated with the mobile phone number has changed within the last seven days.

SubscriberCheck combines the functionality offered by both PhoneCheck and SIMCheck into a single product. It works by creating a mobile data session to a unique Check URL for the purpose of phone number verification. tru.ID then resolves a match between the phone number that the mobile network operator identifies as the owner of the mobile data session and the phone number being verified. it also determines when the SIM card for the phone number was last changed for additional verification purposes.

This guide will walk you through a common approach to integrating SubscriberCheck workflow into a client/server architecture to achieve a match result, determine when SIM associated with the mobile phone number last changed and provide steps for integrating SubscriberCheck into your applications.

This guide will be using four different entities. These are:

Customer's device, the mobile device of the person attempting to verify they're the owner of that phone number.
Your Backend Server is the server the customer's device communicates with for the application to run.
tru.ID API is the API your integration needs to communicate with for the SubscriberCheck to succeed.
Mobile Network Operator (MNO) is the mobile provider that provides your Customer's SIM card.

SubscriberCheck Workflow Integration

The SubscriberCheck workflow consists of three sections.

Create the SubscriberCheck - Initializing the SubscriberCheck process.
Process the SubscriberCheck - Accessing the SubscriberCheck's check_url over a mobile data connection.
Complete the SubscriberCheck - Submitting the SubscriberCheck's code and verifying the Check has been completed.

1) Create a SubscriberCheck

Creating a SubscriberCheck workflow is as follows:

Customer sends phone number to Backend Server.
Backend server sends a POST request to tru.ID SubscriberCheck API.
tru.ID SubscriberCheck API returns a response with the check_id and a unique check_url.
Backend server returns the check_url to the application.

sequenceDiagram participant Device participant Server as Your Backend Server participant API as tru.ID participant MNO as Mobile Network Operator note over Device, MNO: Create the SubscriberCheck. activate Device Device->>Server: Send phone number activate Server rect rgb(232, 231, 231) Server->>API: POST /checks note left of Server: Create SubscriberCheck note right of API: Create SubscriberCheck<br/>"ACCEPTED" API-->>Server: SubscriberCheck with URL end Server-->>Device: Return SubscriberCheck URL to Device deactivate Server deactivate Device

Once the device application has received the user's phone number, send it to your backend server.

Device sends Phone Number to your Backend Server

Backend Server creates a SubscriberCheck with tru.ID's API

Backend Server returns the Check URL to the Device

2) Process the SubscriberCheck

Processing a SubscriberCheck workflow is as follows:

Customer application opens the tru.ID Check URL
Customer Device follows redirect URL to MNO
- 200 Response returned including code or an error message depending on the result.

sequenceDiagram participant Device participant Server as Your Backend Server participant API as tru.ID participant MNO as Mobile Network Operator note over Device, MNO: Process the SubscriberCheck. activate Device Device->>MNO: Open SubscriberCheck check_url MNO-->>Device: Response with code or error deactivate Device

Device opens the tru.ID Check URL

3) Complete the SubscriberCheck

Completing a SubscriberCheck workflow is as follows:

Device passes code to the backend server.
Server makes a PATCH request to tru.ID with check_id and code.
Verification result returned to the device, including SIM changed status.
SubscriberCheck is now complete.

sequenceDiagram participant Device participant Server as Your Backend Server participant API as tru.ID participant MNO as Mobile Network Operator note over Device, MNO: Complete the SubscriberCheck. activate Device Device->>Server: Pass code received from tru.ID<br /> after final redirect Server->>API: PATCH SubscriberCheck /checks/{id}<br /> with code API->>Server: Return SubscriberCheck result from API Server->>Device: Verification complete, continue <br />user's journey or display error. deactivate Device

Device passes 'code' to the Backend Server

Backend Server makes 'PATCH' request to tru.ID SubscriberCheck API

tru.ID SubscriberCheck API returns 'PATCH' result to Backend Server

Get Started with development

There are multiple SDKs created by tru.ID to help developers integrate the APIs into their mobile application and backend server with minimal effort. To support these SDKs, guides have been written on getting started with the mobile technology of your choosing, whether it be iOS, Android, Flutter, and many others.

To get started with the mobile technology of your choice, click on the getting started with link.