PhoneCheck Integration Guide

Integration Guide
info

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

The tru.ID PhoneCheck API confirms the ownership of a mobile phone number by verifying the possession of an active SIM card with the same number. For this verification, a mobile data session is created to a unique Check URL. 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.

This guide will walk you through a common approach to integrating PhoneCheck into a client/server architecture to achieve a match result.

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 PhoneCheck to succeed.
  • Mobile Network Operator (MNO) is the mobile provider that provides your Customer's SIM card.

PhoneCheck Workflow Integration

The PhoneCheck workflow consists of three sections.

  1. Create a PhoneCheck - Initializing the PhoneCheck process.
  2. Process PhoneCheck - Accessing the PhoneCheck's check_url over a mobile data connection.
  3. Finalize PhoneCheck - Submitting the PhoneCheck's code and verifying the Check has been completed.

1) Create a PhoneCheck

Creating a PhoneCheck workflow is as follows:

  • Customer sends phone number to Backend Server.
  • Backend server sends a POST request to tru.ID PhoneCheck API.
  • tru.ID PhoneCheck 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 PhoneCheck. activate Device Device->>Server: Send phone number activate Server rect rgb(232, 231, 231) Server->>API: POST /token API-->>Server: Access Token Server->>API: POST /checks note left of Server: Create PhoneCheck note right of API: Create PhoneCheck<br/>"ACCEPTED" API-->>Server: PhoneCheck with URL end Server-->>Device: Return PhoneCheck URL to Device deactivate Server deactivate Device

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

2) Process the PhoneCheck

Processing a PhoneCheck 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 PhoneCheck. activate Device Device->>API: GET PhoneCheck check_url activate Device API-->>Device: Redirect to redirect_url API-->>Device: Redirect to MNO Device-->>MNO: Follows redirect to MNO MNO-->>Device: Redirect to tru.ID Device-->>API: Follow redirect to tru.ID API-->>Device: Response with code or error deactivate Device deactivate Device

3) Complete the PhoneCheck

Completing a PhoneCheck workflow is as follows:

  • Application passes code to the backend server.
  • Server makes a PATCH request to tru.ID with check_id and code.
  • Verification result returned to the application.
  • PhoneCheck 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 PhoneCheck. activate Device Device->>Server: Pass code received from tru.ID<br /> after final redirect Server->>API: PATCH PhoneCheck /checks/{id}<br /> with code API->>Server: Return PhoneCheck result from API Server->>Device: Verification complete, continue <br />user's journey or display error. deactivate Device

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.

Resources

Download our Developer Console mobile app
Made withacross the 🌍
© 2022 4Auth Limited. All rights reserved. tru.ID is the trading name of 4Auth Limited.