PhoneCheck 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:

• A tru.ID account
• The tru.ID CLI
• A tru.ID project with client_id and client_secret credentials

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

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

1. Get the User's Phone Number

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

2. Send the Phone Number to the Application Server

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.

3. Create a PhoneCheck using the PhoneCheck API

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.

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

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

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

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

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

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

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.

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.

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

• PhoneCheck API Reference
• OAuth2 API Reference