API Access

Accessing your data through the innerworks API

The Innerworks API allows you to programmatically access detection results, including fingerprinting and VPN status, using a request ID obtained from the frontend SDK. You can query the API with your API key and optionally specify the response format (simple or detailed). The simple format returns basic fingerprint and VPN detection results, while the detailed format includes enriched metadata such as browser, OS, user ID, detection reasoning, and geolocation.

curl --request GET \
--url https://api.prod.innerworks.me/api/v1/innerworks/inference?request_id={REQUEST_ID}&format={FORMAT} \
--header "x-api-key: {API_KEY}"

The request ID will be found in the payload response from the frontend SDK request.

The "format" field is optional, and defaults to "simple", but if "detailed" is passed then extra information is added to the response.

Here we return a single field `fingerprint`

{
  "fingerprinting" : {
    "fingerprint": "...."
  }
}

Here we return `vpnIsEnabled` which indicates whether the request to your application was made by a user utilising a VPN 'trueGeoLocationName' which shows the true location of the requesting user, and 'trueGeoLocationCode which is the geolocation code of that user

{
  "geolocation": {
    "vpnIsEnabled": false,
    "trueGeoLocationName": "United Kingdom",
    "trueGeoLocationCode": "GB"
  }
}

Here we return a series of key-value pairs indicating the users browser, deviceOS, the socialID you provided, and then fingerprint.

{
  "fingerprinting" : {
    "fingerprint": "....",
    "browser": "....",
    "deviceOs": "....",
    "socialId": "USER_ID" // this is the same id sent with innerworksMetrics.send()
  }
}

Here we return a series of key-value pairs indicating if the user used a VPN, what the true location of the user is, and if in use, how we detected the use of a VPN.

{
  "geolocation": {
    "vpnIsEnabled": false,
    "vpnDetectionReasons": "None",
    "trueGeoLocationName": "United Kingdom",
    "trueGeoLocationCode": "GB",
    "vpnProvider": "...",
    "vpnLocationCode": "...",
    "stateUS": "...",
    "trueUserIpAddress": "...",
    "requestIpAddress": "..."
  }
}