PhoneCheck 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 IDlayr 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. IDlayr 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.
IDlayr 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.

Create a PhoneCheck - Initializing the PhoneCheck process.
Process PhoneCheck - Accessing the PhoneCheck's check_url over a mobile data connection.
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 IDlayr PhoneCheck API.
IDlayr 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 IDlayr 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 /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.

Device sends Phone Number to your Backend Server

Backend Server creates a PhoneCheck with IDlayr's API

Backend Server returns the Check URL to the Device

2) Process the PhoneCheck

Processing a PhoneCheck workflow is as follows:

Customer application opens the IDlayr 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 IDlayr participant MNO as Mobile Network Operator note over Device, MNO: Process the PhoneCheck. activate Device Device->>MNO: Open PhoneCheck check_url MNO-->>Device: Response with code or error deactivate Device

Device opens the IDlayr Check URL

3) Complete the PhoneCheck

Completing a PhoneCheck workflow is as follows:

Application passes code to the backend server.
Server makes a PATCH request to IDlayr 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 IDlayr participant MNO as Mobile Network Operator note over Device, MNO: Complete the PhoneCheck. activate Device Device->>Server: Pass code received from IDlayr<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

Device passes `code` to the Backend Server

Backend Server makes `PATCH` request to IDlayr PhoneCheck API

IDlayr PhoneCheck API returns `PATCH` result to Backend Server

Get Started with development

There are multiple SDKs created by IDlayr 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.