SubscriberCheck Integration Guide

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:

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
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 SubscriberCheck note right of API: Create SubscriberCheck<br/>"ACCEPTED" API-->>Server: SubscriberCheck with URL end deactivate Server deactivate Device activate Device activate Server Server-->>Device: 4. Return SubscriberCheck URL to Device deactivate Server deactivate Device activate Device Device->>API: 5. GET SubscriberCheck 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 SubscriberCheck result<br />via Server deactivate Device activate Device Server->>API: 7. Get SubscriberCheck Result from API<br />GET /checks/check_id activate API API->>MNO:get match and<br />SIM changed result MNO-->>API: note right of API: SubscriberCheck<br/>"COMPLETED" API-->>Server: SubscriberCheck status deactivate API deactivate Device activate Device Server-->>Device: 8. Return SubscriberCheck 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 SubscriberCheck 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 SubscriberCheck using the SubscriberCheck 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 SubscriberCheck note right of API: Create SubscriberCheck<br/>"ACCEPTED" API-->>Server: SubscriberCheck 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=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.

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 /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

sequenceDiagram participant Device participant Server participant API as tru.ID participant MNO activate Device activate Server Server-->>Device: 4. Return SubscriberCheck 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/subscriber_check/v0.1/checks/c69bc0e6-a429-11ea-bb37-0242ac130002/redirect"
}

5. Request the SubscriberCheck 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 SubscriberCheck 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 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
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 SubscriberCheck via the application server.

6. Mobile Device requests SubscriberCheck Result via the Application Server

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

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

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

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

sequenceDiagram participant Device participant Server participant API as tru.ID participant MNO activate Device Server-->>Device: 8. Return SubscriberCheck Result to Device deactivate 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.

phone device wrapper

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.

Resources

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