PhoneCheck Integration Guide

Integration Guide

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. A mobile data session is created to a unique Check URL for the purpose of this 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.

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

Before you begin

In order to perform a PhoneCheck you'll need:

PhoneCheck Workflow Integration

The PhoneCheck workflow is as follows:

  1. Get the User's Phone Number on Mobile Device
  2. Send the Phone Number the Application Server
  3. Create a PhoneCheck using the PhoneCheck API
  4. Return the PhoneCheck URL to the Mobile Device
  5. Request the PhoneCheck URL on the Mobile Device over Mobile Data
  6. Mobile Device requests PhoneCheck Result via the Application Server
  7. Application Server gets PhoneCheck Result from PhoneCheck API
  8. Application Server returns the PhoneCheck Result to the Mobile Device
sequenceDiagram participant Device participant Server participant API as tru.ID participant MNO activate Device Device->>Device: 1. Get phone number deactivate Device activate Device Device->>Server: 2. Send phone number deactivate Device activate Device activate Server rect rgb(232, 231, 231) Server->>API: POST /token API-->>Server: Access Token Server->>API: POST /checks note left of Server: 3. Create PhoneCheck note right of API: Create PhoneCheck<br/>"ACCEPTED" API-->>Server: PhoneCheck with URL end deactivate Server deactivate Device activate Device activate Server Server-->>Device: 4. Return PhoneCheck URL to Device deactivate Server deactivate Device activate Device Device->>API: 5. GET PhoneCheck check_url activate Device API-->>Device: Redirect to MNO Device-->>MNO: Redirect to MNO MNO-->>Device: OK deactivate Device deactivate Device activate Device Device->>Server: 6. Request PhoneCheck result<br />via Server deactivate Device activate Device Server->>API: 7. Get PhoneCheck Result from API<br />GET /checks/check_id activate API API->>MNO:get match result MNO-->>API: note right of API: PhoneCheck<br/>"COMPLETED" API-->>Server: PhoneCheck status deactivate API deactivate Device activate Device Server-->>Device: 8. Return PhoneCheck Result to Device deactivate Device

The following sections provide detail for each step within the workflow:

1. Get the User's Phone Number

sequenceDiagram participant Device participant Server participant API as tru.ID participant MNO activate Device Device->>Device: 1. Get phone number deactivate Device

The first step within a PhoneCheck workflow is to capture the phone number to be verified by the user.

phone device wrapper

2. Send the Phone Number to the Application Server

sequenceDiagram participant Device participant Server participant API as tru.ID participant MNO activate Device Device->>Server: 2. Send phone number deactivate Device

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

POST the number to your application server and keep the HTTP connection from the mobile client to the server open.

$ POST /your_server_check_endpoint
Host: https://example.com
{
"phone_number": "447900123456"
}

At this point it is beneficial to provide the application user feedback that work is underway following their phone number submission. The common user experience in this scenario is to show an animated working screen.

info

It's important to be aware that the following steps may complete within tens of milliseconds and this should be managed within the mobile application user experience.

phone device wrapper

3. Create a PhoneCheck using the PhoneCheck API

sequenceDiagram participant Device participant Server participant API as tru.ID participant MNO activate Device activate Server rect rgb(232, 231, 231) Server->>API: POST /token API-->>Server: Access Token Server->>API: POST /checks note left of Server: 3. Create PhoneCheck note right of API: Create PhoneCheck<br/>"ACCEPTED" API-->>Server: PhoneCheck with URL end deactivate Server deactivate Device

Create a tru.ID Access Token using the tru.ID OAuth2 /token endpoint.

$ POST /oauth2/v1/token
Host: https://{data_residency}.api.tru.id
Authorization: Basic {encoded_credentials}
Content-Type: application/x-www-form-urlencoded
grant_type=client_credentials&scope=phone_check

In the example above:

  • The Authorization header identifies basic auth is being used. The value is your tru.ID project client_id and client_secret, found in the tru.json file, concatenated with a colon (:) and Base64 encoded. Identified as {encoded_credentials}, above
  • The Content-Type of the POST request is form URL encoded
  • The grant_type parameter is set to client_credentials. See Client Credentials in RFC 6749.
  • The scope instructs the tru.ID OAuth provider that the created Access Token should have permissions to use PhoneCheck resources

The response JSON has a property access_token with a value of the newly created Access Token.

For example:

{
"access_token": "2YotnFZFEjr1zCsicMWpAA",
"id_token": "eyJhbGciOiJSUzINiImtpZCI6InB1Ympx",
"expires_in": 3600,
"token_type": "bearer",
"scope": "phone_check"
}

For more information see the Create an Access Token section of the API Reference.

Next, create the PhoneCheck resource using the Access Token and an E.164 formatted phone number.

info

E.164 formatted phone numbers

The E.164 format contains the international country code, the phone number including area code excluding the leading 0.
CountryCountry CodePhone NumberE.164 Phone Number
UK4407700 900000447700900000
US1(415) 555-010014155550100
$ POST /phone_check/v0.1/checks
Host: https://{data_residency}.api.tru.id
Authorization: Bearer {access_token}
Content-Type: application/json
{
"phone_number": "447900123456"
}

The response to the POST request contains the newly created resource.

{
"check_id": "c69bc0e6-a429-11ea-bb37-0242ac130002",
"status": "ACCEPTED",
"charge_amount": 1,
"charge_currency": "API",
"created_at": "2020-06-01T16:43:30+00:00",
"ttl": 60,
"_links": {
"self": {
"href": "https://{data_residency}.api.tru.id/phone_check/v0.1/checks/c69bc0e6-a429-11ea-bb37-0242ac130002"
},
"check_url": {
"href": "https://{data_residency}.api.tru.id/phone_check/v0.1/checks/c69bc0e6-a429-11ea-bb37-0242ac130002/redirect"
}
},
"snapshot_balance": 100
}

Within the response payload there is a check_id to uniquely identify the newly created PhoneCheck and a _links.check_url.href (the PhoneCheck URL, which is a sub-resource /redirect of the PhoneCheck resource) for the next step of PhoneCheck workflow. For more information see the Create a PhoneCheck section of the API Reference.

4. Return the PhoneCheck URL to the Mobile Device

sequenceDiagram participant Device participant Server participant API as tru.ID participant MNO activate Device activate Server Server-->>Device: 4. Return PhoneCheck URL to Device deactivate Server deactivate Device

At this point you should return the check_id and _links.check_url.href to the mobile device and close the HTTP connection.

{
"check_id": "c69bc0e6-a429-11ea-bb37-0242ac130002",
"check_url": "https://{data_residency}.api.tru.id/phone_check/v0.1/checks/c69bc0e6-a429-11ea-bb37-0242ac130002/redirect"
}

5. Request the PhoneCheck URL on the Mobile Device over Mobile Data

sequenceDiagram participant Device participant Server participant API as tru.ID participant MNO activate Device Device->>API: 5. GET PhoneCheck check_url activate Device API-->>Device: Redirect to MNO Device-->>MNO: Redirect to MNO MNO-->>Device: OK deactivate Device deactivate Device

Now that the mobile device has the PhoneCheck URL it must request that URL. This enables the mobile network operator to identify the phone number associated with the mobile data session.

The mobile device must make a GET request to the provided PhoneCheck URL, check_url.

In order to do this, the following must happen:

  • The check_url HTTP GET request must be made using the mobile data connection
  • The HTTP request must follow all redirects
  • The HTTP request should be performed synchronously and no further action should be taken until it completes
info

We provide SDKs for Android, iOS, React Native and Mobile Web to aide making the GET check_url request. For Android, iOS and React Native the SDK forces the request to go over the mobile data connection. If you are developing for a platform where you cannot force the GET check_url request to be made over a mobile data connection you can instead prompt the user to turn off their WiFi before requesting the check_url.

The HTTP Once the check_url HTTP request completes the mobile device can query the result of the PhoneCheck via the application server.

6. Mobile Device requests PhoneCheck Result via the Application Server

sequenceDiagram participant Device participant Server participant API as tru.ID participant MNO activate Device Device->>Server: 6. Request PhoneCheck result<br />via Server deactivate Device

The tru.ID platform now knows whether the PhoneCheck Match has been performed. Your mobile application and the application server should now query the result. This will in turn trigger the tru.ID platform to fetch the PhoneCheck Match result from the MNO.

Make a request from the mobile application to your application server using the unique check_id.

GET /your_server_check_query_endpoint?check_id={check_id}
Host: https://example.com

It's important to authenticate the requests coming from the mobile client.

7. Application Server gets PhoneCheck Result from PhoneCheck API

sequenceDiagram participant Device participant Server participant API as tru.ID participant MNO activate Device Server->>API: 7. Get PhoneCheck Result from API<br />GET /checks/check_id activate API API->>MNO:get match result MNO-->>API: note right of API: PhoneCheck<br/>"COMPLETED" API-->>Server: PhoneCheck status deactivate API deactivate Device

Using the check_id provided to the server from the mobile device, query the PhoneCheck result on the tru.ID Platform using the Access Token created earlier to authenticate your API request.

GET /phone_check/v0.1/checks/{check_id}
Host: https://{data_residency}.api.tru.id
Authorization: Bearer {access_token}

The returned PhoneCheck resource will contain information including whether the PhoneCheck Match was a success.

{
"check_id": "c69bc0e6-a429-11ea-bb37-0242ac130002",
"status": "COMPLETED",
"match": true,
"charge_amount": 1,
"charge_currency": "API",
"created_at": "2020-06-01T16:43:30+00:00",
"ttl": 60,
"_links": {
"self": {
"href": "https://{data_residency}.api.tru.id/phone_check/v0.1/checks/c69bc0e6-a429-11ea-bb37-0242ac130002"
},
"check_url": {
"href": "https://{data_residency}.api.tru.id/phone_check/v0.1/checks/c69bc0e6-a429-11ea-bb37-0242ac130002/redirect"
}
}
}

8. Application Server returns the PhoneCheck Result to the Mobile Device

sequenceDiagram participant Device participant Server participant API as tru.ID participant MNO activate Device Server-->>Device: 8. Return PhoneCheck Result to Device deactivate Device

The server now knows if the PhoneCheck Match was successful. Finally, inform the mobile device by returning a response to the request opened in step 6.

{
"match": true
}

The mobile device and application now knows the user has been verified so this information can be passed on to the user and they can continue with their application user journey.

phone device wrapper

With the PhoneCheck workflow complete the server and client now know if the PhoneCheck Match was successful; the mobile device and application knows the user has been verified and the server knows future interactions from the device are from a valid user.

Resources

Made withacross the 🌍
© 2021 4Auth Limited. All rights reserved. tru.ID is the trading name of 4Auth Limited.