SIMCheck Guide

The tru.ID SIMCheck API provides information on when a SIM card associated with a mobile phone number was last changed. This can be used when augmenting existing 2FA or anti-fraud workflows.

See SubscriberCheck for a solution that offers both phone number verification and SIM checking.

Before you begin

In order to perform a SIMCheck you'll need:

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

You're now ready to make your first SIMCheck API call.

Making a SIMCheck API call

Making the SIMCheck API request involves two steps.

1. Create an access token
2. Create a SIMCheck resources

The sequence diagram shows how SIMCheck works between your application server, the tru.ID API platform and the MNO (Mobile Network Operator).

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

POST /oauth2/v1/token
Host: https://eu.api.tru.id
Authorization: Basic {encoded_credentials}
Content-Type: application/x-www-form-urlencoded

grant_type=client_credentials&scope=sim_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 SIMCheck resources as indicated by sim_check.

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": "sim_check"
}

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

1.2 Create the SIMCheck resource

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

POST /sim_check/v0.1/checks
Host: https://eu.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": "COMPLETED",
  "no_sim_change": true,
  "charge_amount": 1,
  "charge_currency": "API",
  "created_at": "2020-06-01T16:43:30+00:00",
  "last_sim_change_at": "2020-05-20T12:35:00+00:00",
  "_links": {
    "self": {
      "href": "https://eu.api.4auth.io/subscriber_checks/v0.1/checks/{check_id}"
    }
  },
  "snapshot_balance": 100
}

Within the response payload there are two key attributes:

• no_sim_change - to ensure the SIM card has not changed within the past seven (7) days. true if the SIM has not changed. false indicates that the SIM has changed.
• last_sim_change_at - identifying when the SIM did last change. This property will only be returned if the data is available.

The application server now has information about when the SIM card associated with a phone number last changed. This information can be used within logic to determine whether a 2FA flow should proceed or flag a transaction as fraudulent.

For more information see the Create a SIMCheck section of the API Reference.