API Response

When one of the client libraries sends collected data to the DeviceAssure service it is analysed and a result is returned to the client and also optionally to a callback URL provided by the customer.

Response Content

The API can return the following fields. The fields returned depend on what is enabled for the licence:

Field	Description
`referenceId`	A unique ID for the response. Useful to match responses sent to the callback URL to replies sent directly back to the library.
`result`	Result of the validation. Can be one of: `Authentic`, `Non-Authentic`, `Non-Compliant`, `Inconsistent` or `Indeterminate`. See Classifications for definitions.
`resultCode`	A unique identifier encompassing the `result` and the `reason` fields. See Classifications for all result codes.
`reason`	A descriptive string describing the result. See Classifications for all reason values.
`deviceIdentifiedAsRooted`	Flag indicating whether the device is rooted.
`customRomIdentified`	Flag indicating whether the device is running a Custom ROM.
`desktopIdentified`	Flag indicating whether the device has been identified as a desktop.
`privateBrowsing`	Flag indicating whether the browser is in private mode (e.g. Incognito mode in Chrome).
`torExitNode`	Flag indicating whether the request was identified as originating from the Tor network, based on matching the client's IP address against an up-to-date list of known Tor exit nodes. See the note below.
`tacResult`	Contains information on the validity of the passed TAC. Populated if the licence type has TAC details enabled.
`measured`	List of measured properties of the device.
`resultDetails`	List of validation result details for each known variant of the device. See Result Details below.
`deviceAtlasProperties`	List of DeviceAtlas properties for the identifier which most closely matches the device under test. See DeviceAtlas Properties below.
`deviceCheck`	List of GSMA's properties for a given IMEI.
`meta`	Metadata related to the request. Only present when metadata exists, e.g. when custom tags are configured in the DeviceAssure web library.

Note: The Tor exit node list is updated regularly, but there is potential for the DeviceAssure API to be briefly out of sync with the latest list.

Result Details

The number of items in resultDetails depends on the classification of the device:

Zero blocks if no known variants exist for the device
One block if the device is classified as AUTHENTIC (the matching variant is returned) or one known variant exists
More than one block if the device is not classified as AUTHENTIC and more known variants exist

Each result detail block contains:

Field	Description
`failures`	Matrix of property failures against the examined variant. Empty if the device is classified as AUTHENTIC.
`expected`	List of expected properties for the examined variant.

DeviceAtlas Properties

The following properties are returned by default:

Field	Web	Android	Description
`id`	Yes	Yes	DeviceAtlas device ID
`standardisedFullName`	Yes	Yes	Standardised full name of the device (e.g. "Samsung Galaxy S9")
`model`		Yes	Device model identifier
`yearReleased`		Yes	Year the device was released

Additional DeviceAtlas properties (naming, hardware capabilities, OS, browser, connectivity, multimedia) can be enabled as part of the licence agreement. See Product Options for details.

Two further properties are dynamically generated by DeviceAssure and available upon request:

Field	Description
`measuredStorageCapacity`	Computed storage capacity in GB, rounded up to the nearest power of 2 from the measured `storage.maxInternalStorageMB` value (e.g. a measured value of 240,309 MB returns `256`).
`eSimCompatible`	Indicates whether the device is eSIM compatible. See values below.

eSimCompatible Values:

Value	Description
`Yes`	The device is eSIM compatible
`No`	The device is NOT eSIM compatible
`Unknown`	The device is a desktop or browser in desktop mode; iPad models with cellular variants cannot be distinguished; device not identified by DeviceAtlas; or browser does not provide device identifying properties (e.g. Firefox on Android)

Note: The eSimCompatible property ignores Chinese model variants which do not support eSIM as these are not distinguishable using JavaScript alone.

Sample Response

A sample response returned by the DeviceAssure service is structured as follows:

{
  "referenceId": "9b34be0f-c55e-480d-87f0-88fa60528615",
  "result": "NON-AUTHENTIC",
  "deviceIdentifiedAsRooted": true,
  "customRomIdentified": false,
  "privateBrowsing": false,
  "desktopIdentified": false,
  "torExitNode": false,
  "reason": "Properties don't match any reference devices",
  "resultCode": "503",
  "tacResult": "Unavailable",
  "measured": {
    "board": "universal8895",
    "hardware": "mt6580",
    "manufacturer": "samsung",
    "brand": "samsung",
    "model": "SM-G960U",
    "sdk": "22",
    "numCores": "4",
    "cpuMaxFreqKhz": "3000",
    "cpuHardware": null,
    "devicePixelRatio": null,
    "heightPixels": 1440,
    "widthPixels": 720,
    "renderer": "Mali-G71",
    "memTotal": "6144"
  },
  "resultDetails": [
    {
      "failures": ["memTotal", "numCores", "cpuHardware", "renderer"],
      "expected": {
        "board": "sdm845",
        "hardware": "qcom",
        "manufacturer": "samsung",
        "brand": "samsung",
        "model": "SM-G960U",
        "sdk": "26",
        "numCores": "8",
        "cpuMaxFreqKhz": "1766",
        "cpuHardware": "Qualcomm Technologies, Inc SDM845",
        "devicePixelRatio": null,
        "heightPixels": 2009,
        "widthPixels": 1080,
        "renderer": "Adreno (TM) 630",
        "memTotal": "3349"
      }
    }
  ],
  "deviceAtlasProperties": {
    "id": "30011290",
    "standardisedFullName": "Samsung Galaxy S9"
  }
}

Sample Response with GSMA DeviceCheck

A sample response including GSMA's DeviceCheck properties is provided below:

{
  "referenceId": "e19ee8ae-e5b0-4f83-8bfd-9b4dbbe77d61",
  "result": "AUTHENTIC",
  "reason": "Device has passed all verification checks",
  "resultCode": "101",
  "privateBrowsing": false,
  "desktopIdentified": false,
  "torExitNode": false,
  "measured": {
    "tac": "35560090",
    "board": null,
    "hardware": null,
    "manufacturer": null,
    "brand": "Linux armv8l",
    "model": null,
    "sdk": null,
    "numCores": "8",
    "cpuMaxFreqKhz": null,
    "cpuHardware": null,
    "devicePixelRatio": "1.75",
    "heightPixels": 915,
    "widthPixels": 412,
    "renderer": "Mali-G52",
    "memTotal": null
  },
  "resultDetails": [
    {
      "failures": [],
      "expected": {
        "board": "exynos850",
        "hardware": "exynos850",
        "manufacturer": "samsung",
        "brand": "samsung",
        "model": "SM-A217F",
        "sdk": "29",
        "numCores": "8",
        "cpuMaxFreqKhz": "2002000",
        "cpuHardware": null,
        "devicePixelRatio": "1.75",
        "heightPixels": 1600,
        "widthPixels": 720,
        "renderer": "Mali-G52",
        "memTotal": "2730"
      }
    }
  ],
  "deviceAtlasProperties": {
    "model": "SM-A217F",
    "marketingName": "Galaxy A21s",
    "standardisedFullName": "Samsung Galaxy A21s",
    "manufacturer": "Samsung",
    "yearReleased": 2020,
    "primaryHardwareType": "Mobile Phone"
  },
  "deviceCheck": {
    "modelname": "SM-A217F/DS",
    "WLAN": "Yes",
    "nfc": "Yes",
    "brandname": "Samsung",
    "devicetype": "Smartphone",
    "manufacturer": "Samsung Korea",
    "bluetooth": "Yes",
    "operatingsys": "Android",
    "marketingname": "Galaxy A21s",
    "blackliststatus": "No"
  }
}

Licence Key Usage

A valid licence key is required in order to be able to use the DeviceAssure service. DeviceAtlas provide the licence key and configure the quotas below according to partner requirements and infrastructure capacity.

A licence has the following usage quotas:

quota – maximum number of requests allowed
daily quota – maximum number of requests allowed per day
weekly quota – maximum number of requests allowed per week
monthly quota – maximum number of requests allowed per month

Callback URL

A licence can have a callback URL associated to it. If provided, the result of the validation is sent to the given url in the same format as the response sent back to the library. The purpose of this is to permit straightforward aggregation of results by the customer for analysis purposes, or to provide an input to a separate service.