Device Reachability

tru.ID Reachability is a new feature that enables applications to check whether the SIM card within a user’s device is on a network that tru.ID has connectivity to. The API request returns information about the mobile network that the device is on, and will produce any products that may be supported based on the IP address provided.

The API

The device with the SIM card will need a valid access token with the scope for coverage. This will need to only be coverage no other scope because the device will be using this token. To create an access token from your backend server with specific scopes please checkout the API docs.

An authenticated GET request with this new access token is made to the following URL: https://{data_residency}.api.tru.id/coverage/v0.1/device_ip.

On the device, the following is checked:

Is the IP address a cellular or landline IP address?
Is the Mobile Network Operator (MNO) supported?
Which products are supported?

For a successful phone/subscriber check, the device needs to be on a cellular IP address. The mobile SDKs force the device to make the request over cellular data rather than Wi-Fi.

If you are making the API request manually within the project, you will need to write functionality to force the request over cellular data, or request the person using the application to turn Wi-Fi off.

The SDKs that have support for this functionality are:

What information is returned?

If the IP address is a cellular IP address and is supported by the MNO, then the HTTP status code returned will be 200 along with the following JSON body:

{
  "country_code": "GB",
  "dialing_code": "44",
  "network_id": "23410",
  "network_name": "O2 UK",
  "network_aliases": [
    "23402",
    "23411"
  ],
  "products": [
    {
      "product_id": "PCK",
      "product_name": "Phone Check"
    },
    {
      "product_id": "SCK",
      "product_name": "Sim Check"
    },
    {
      "product_id": "SUK",
      "product_name": "Subscriber Check"
    }
  ],
  "mobile_data_ip": "127.0.0.1"
}

If the IP address is a cellular (3/4/5G) IP address but is not supported by the MNO, then the HTTP status code returned will be 400 along with the following JSON body:

{
  "type": "https://developer.tru.id/docs/reference/api-errors#mno_not_supported"
}

In this case, you should fall back to another method of verifying the phone number.

If the IP address is not on a cellular (3/4/5G) connection, then the reachability check will fail as it cannot verify whether the mobile network operator (MNO) for the device is supported. The HTTP status code returned will be 412 along with the following JSON body:

{
  "type": "https://developer.tru.id/docs/reference/api-errors#not_mobile_ip"
}

Note: If using any of the SDKs except for the web SDK, the application can force a PhoneCheck through cellular data. This means that even if this response is returned in a Reachability check, a PhoneCheck is still possible. If you’re making the reachability check while implementing Phone/Subscriber checks on a mobile website, you may want to use this error to trigger a notification to the user to turn off WiFi antenna on their device and retry the verification through tru.ID.

More information on the Reachability API can be found on the API Reference.