tru.ID logo

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:

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

$ POST /sim_check/v0.1/checks
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": "{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.

tru.ID logo




Keep current with industry news and updates from tru.ID.

Follow us on:

Made with ❤️ across the 🌍

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