SubscriberCheck Integration Guide

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.

Before you begin

In order to perform a SubscriberCheck you'll need:

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

SubscriberCheck Workflow Integration

The SubscriberCheck 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 SubscriberCheck using the SubscriberCheck API
4. Return the SubscriberCheck URL to the Mobile Device
5. Request the SubscriberCheck URL on the Mobile Device over Mobile Data
6. Mobile Device requests SubscriberCheck Result via the Application Server
7. Application Server gets SubscriberCheck Result from SubscriberCheck API
8. Application Server returns the SubscriberCheck Result, including SIM changed status, 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 SubscriberCheck 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 SubscriberCheck using the SubscriberCheck 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=subscriber_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 SubscriberCheck 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": "subscriber_check"
}

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

Next, create the SubscriberCheck resource using the Access Token and a E.164 formatted phone number.

POST /subscriber_check/v0.1/checks
Host: https://{data_residency}.api.tru.id
Authorization: Bearer {access_token}
Content-Type: application/json

{
	"phone_number": "447900123456"
}

1.5. 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/subscriber_check/v0.1/checks/c69bc0e6-a429-11ea-bb37-0242ac130002"
    },
    "check_url": {
      "href": "https://{data_residency}.api.tru.id/subscriber_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 SubscriberCheck and a _links.check_url.href (the Check URL, which is a sub-resource /redirect of the SubscriberCheck resource) for the next step of SubscriberCheck workflow. For more information see the Create a SubscriberCheck section of the API Reference.

4. Return the SubscriberCheck 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/subscriber_check/v0.1/checks/c69bc0e6-a429-11ea-bb37-0242ac130002/redirect"
}

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

Now that the mobile device has the SubscriberCheck 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 SubscriberCheck 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 SubscriberCheck via the application server.

6. Mobile Device requests SubscriberCheck Result via the Application Server

The tru.ID platform now knows whether the SubscriberCheck 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 SubscriberCheck 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 SubscriberCheck Result from SubscriberCheck API

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

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

The returned SubscriberCheck resource will contain information including whether the match was a success and if the SIM changed within the last seven days. If match is true the mobile phone number has been verified and if no_sim_change is true the SIM has not changed within the past seven days.

{
  "check_id": "c69bc0e6-a429-11ea-bb37-0242ac130002",
  "status": "COMPLETED",
  "match": true,
  "no_sim_change": 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/subscriber_check/v0.1/checks/c69bc0e6-a429-11ea-bb37-0242ac130002"
    },
    "check_url": {
      "href": "https://{data_residency}.api.tru.id/subscriber_check/v0.1/checks/c69bc0e6-a429-11ea-bb37-0242ac130002/redirect"
    }
  }
}

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

The server now knows if the check was successful and when the SIM card was last changed. Using that information the server can determine whether the user can be verified.

Finally, inform the mobile device by returning a response to the request opened in step 3.1.

{
  "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 SubscriberCheck workflow complete the server and client now know if the match was successful and when the SIM card was last changed; 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

• SubscriberCheck API Reference
• OAuth2 API Reference