SIMCheck Guide

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:

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).

sequenceDiagram participant Server participant API as tru.ID participant MNO Server->>API: POST /token activate Server Server->>API: POST /checks note right of API: Create SIMCheck API-->>API: MNO lookup note right of API: Determine the<br />registered MNO API->>MNO: Retrieve SIM info MNO-->>API: SIM info API-->>Server: SIM info note right of Server: Apply logic<br />based on no_sim_change

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

$ POST /oauth2/v1/token
Host: https://{data_residency}
Authorization: Basic {encoded_credentials}
Content-Type: application/x-www-form-urlencoded

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.


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 /sim_check/v0.1/checks
Host: https://{data_residency}
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",
"_links": {
"self": {
"href": "https://{data_residency}{check_id}"
"snapshot_balance": 100

Within the response payload the key attribute is:

  • 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.

The application server now has information about whether the SIM card associated with a phone number changed within the last seven days. 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.

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