Overview

Fingerprint identifies millions of Android devices globally every month.

For each identified Android device, we generate and store a unique visitor ID and a collection of Smart Signals. When a device is identified again, additional Smart Signal data is added to the existing dataset. Often, when companies identify an Android device using our Android SDK, that device has already been recognized by other companies.

Since Fingerprint has a global database of Android device intelligence, we're offering it through our new Device Reputation Network (DRN) API. With this API, you can query our network using the visitor ID from a device you've identified. Unlike our event-based Server API , the DRN provides globally aggregated Smart Signals.

The DRN API is free to use, but is rate limited to prevent abuse. If you want to request a higher rate limit, contact us at [email protected].

👍

DRN API requests do not count toward your monthly plan and are not billed.

Before you use the DRN

To get started, you’ll need to use our Android SDK.

Please note, the iOS SDK and JavaScript agent SDK are not supported at this time.

After creating a Fingerprint account, integrate the Android SDK into your app to start identifying devices. For detailed instructions, refer to our Android integration guide. Once a device is identified, you can retrieve the visitor ID directly on the device, or if you're using our Zero Trust Mode and don't trust the devices, you can obtain it through a server-side API call.

With the Android device's visitor ID, you're ready to make an API call to the DRN.

Making your first DRN API call

Ensure you have your secret API key and visitorId, then make the following request:

GET https://drn-api.fpjs.io/drn/{visitor_id}?signals={signals}

Replace {visitor_id} with the visitorId and provide signals you want. We support one or more signals in the signals query parameter. Use a comma separated list for the signal list.

In version 2024-09-01, the DRN supports three global signals: regional_activity, suspect_score, and timestamps. More details about each signal are in the sections below.

If you want to request all three signals and your visitor ID is NSBNxrgR3h9hVkhR5mkc, the request will look like this:

curl --request GET \
  --url 'https://drn-api.fpjs.io/drn/NSBNxrgR3h9hVkhR5mkc?signals=regional_activity,suspect_score,timestamps' \
  --header 'Authorization: Bearer {secret-api-key}' \
  --header 'X-API-Version: 2024-09-01'

Make sure you provide your secret API key in the Authorization HTTP header. You can read all the details in our DRN API reference.

Global DRN signals

As of version 2024-09-01, DRN supports three global signals: regional_activity, suspect_score, and timestamps.

regional_activity

Represents a list of countries where the identified device was active in the last 30 days together with the level of activity in each country. Level of activity is a number between 0 and 1 and represents the percentage of activity in the country. For example if a device was active in a specific country 60% of the time, the level of activity will be 0.6. API reference . Note that the level of activity is scoped to a detector type.

We support two detector types: ip and origin. The ip detector detects a country code by the IP address at the moment of making an API call using the Android SDK. If a device is using a VPN, the ip detector will return the VPN exit node country.

The origin detector detects a real location of the device, utilizing our originCountry feature of the mobile SDK VPN detection, regardless of the IP address location or attempts to hide the location using VPN. The origin detector does not require geolocation permissions from the user.

Examples of different activityPercentage scenarios:

{
  "countries": [
    {
      "code": "US",
      "detectors": [
        {"type": "ip", "activityPercentage": 1.0},
        {"type": "origin", "activityPercentage": 1.0}
      ]
    }]
}

{
  "countries": [
    {
      "code": "US",
      "detectors": [
        {"type": "ip", "activityPercentage": 1.0},
        {"type": "origin", "activityPercentage": 1.0}
      ]
    }]
}

{
  "countries": [
    {
      "code": "US",
      "detectors": [
        {"type": "ip", "activityPercentage": 1.0}
      ]
    },
    {
      "code": "RU",
      "detectors": [
        {"type": "origin", "activityPercentage": 1.0}
      ]
    }]
}

{
  "countries": [
    {
      "code": "US",
      "detectors": [
        {"type": "ip", "activityPercentage": 0.6}
      ]
    },
    {
      "code": "CA",
      "detectors": [
        {"type": "ip", "activityPercentage": 0.4}
      ]
    },
    {
      "code": "RU",
      "detectors": [
        {"type": "origin", "activityPercentage": 1.0}
      ]
    }]
}

Regional activity gives a clear understanding where a device was physically located during the last 30 days and also where it wanted to appear to be located. Analyzing the detector types and the origin country helps prevent geo-related fraud.

Output format:

API reference available in this document.

"regionalActivity": [
  // RFC 3339 format, goes 30 days back from the time request received on the server in UTC
  "startDate": "2023-12-16T23:12:59Z",
  // The time the request was received on the server in UTC
  "endDate": "2024-01-16T23:12:59Z",
  // One country object per country of activity. 
  // One or two detectors are possible in each country.
  "countries": [
    {
      // Country codes are capitalized as defined in the ISO 3166-1 alpha 2 standard
      "code": "US" | "GB" | ...,
      "detectors": [
        {
          // Two detector types: "ip" and "origin"
          // "ip"-when the country is detected by IP address
          // "origin"-when the country is detected by "originCountry" feature of our VPN detection.
          // "origin" represents the country of real location
          "type": "ip" | "origin",
          // A number that's always > 0 and <= 1.
          "activityPercentage": Number
        }]
    }]
}

Output example:

// Device is physically based in Mexico and is also active in the US 20% of the time via VPN.
// Its response could look like this, 
// assuming the originCountry is available 
// (if the device is using the supported version of Android SDK).
// Note that one API call response can have both "origin" and "ip" at the same time, 
// because even when the originCountry is available, we should also use the IP country 
// (to capture the fact of the VPN usage).
"regionalActivity": {
  // Use RFC 3339 format, goes 30 days back from the time request received on the server.
  // UTC time zone
  "startDate": "2023-12-16T23:12:59Z",
    // The time the request was received on the server in UTC timezone
    "endDate": "2024-01-16T23:12:59Z",
    "countries": [
        // it's clear device is based in MX physically
        {
          "code": "MX",
          "detectors": [
            { "type": "origin", "activityPercentage": 1 },
            { "type": "ip", "activityPercentage": 0.8 }
          ]
        },
        // but 20% of the time makes VPN calls out of the US IP address
        { "code": "US", "detectors": [{ "type": "ip", "activityPercentage": 0.2 }] }
      ]
}

suspect_score

Suspect Score is a single value representing how many suspicious Smart Signals were in a particular request. You can read more in this Smart Signals Guide . The suspect score is calculated for each Fingerprint API request that your application makes with Android SDK.

The DRN version of the suspect_score is powerful, as it represents the minimum and maximum suspect scores we captured from the identified device in the last 30 days globally across the entire Fingerprint device network.

The maximum value contains a zero-excluded percentile, that makes it easy to see how suspicious that device was compared to other suspicious devices. For example if the percentile of the maximum suspect score is 0.95, it means that that device was more suspicious than 95% of other suspicious devices in the same 30-day time period.

Output format:

You can find the reference in this API reference document.

Output example:

"suspectScore": {
  // Time in RFC 3339 format, goes 30 days back from the time request received on the server in UTC
  "startDate": "2023-12-16T23:12:59Z",
  // The time the request was received on the server in UTC
  "endDate": "2024-01-16T23:12:59Z",
  // Minimum suspect score we captured globally for the identified Android device
  "minimum": {
    // Almost always will be zero, cannot be negative.
    // In rare cases will be > 0, 
    // when this device consistently generated a suspect score value greater than zero.
    // In this case, this device used a proxy all the time.
    "value": 3,
      // The signals object lists all the smart signals that contributed to the suspect score
      "signals": {
      "proxy": 3
    }
  },
  // Maximum suspect score we captured globally for the identified Android device
  "maximum": {
    // Most of the time will be 0, but sometimes will be > 0 for suspicious devices.
    // When you see a particularly high maximum value for a device, you need to review this device's activity
    "value": 20,
      // Zero-excluded percentile
      // E.g. a .75 value means the max suspect score is higher than 75% of
      // non-zero max suspect scores.
      // You can use this number to understand how high this max suspect score is
      // compared to other suspicious devices with non-zero maximum scores.
      // Can take four possible values: 0.25, 0.5, 0.75, and 0.95.
    "percentile": 0.75
      // The list of signals that contributed to the maximum captured suspect_score value.
      // Only the signal names with non-zero contribution will be used, together with their respective values.
      // Signal names and values are at the time of capturing the suspect score.
      // For a full reference for all possible values, see: https://dev.fingerprint.com/reference/getevent
    "signals": {
        // Nested smart signals can be used, compatible with the Server API response.
        "ipBlockList": 12,
          "vpn": {
          "publicVPN": 5
        },
        "proxy": 3
      }
  }
}

timestamps

Represents timestamps when we first and last saw this device on the Fingerprint device network. Knowing when a device was first seen can be useful as the devices that appeared recently (a few minutes ago) are suspicious. Output format is described in the API reference.

Output example:

"timestamps": {
  "firstSeenAt": "2023-12-29T23:12:00Z" // RFC3339 formatted UTC time with minute precision
  "lastSeenAt": "2023-12-29T23:12:00Z" // RFC3339 formatted UTC time with minute precision
}

Smart signal aggregation notes

When you use the DRN API, you will always use the device's visitorId value to query the network. Sometimes a device is only identified by Fingerprint through your workspace, and sometimes a device is identified by Fingerprint through multiple workspaces that belong to multiple companies.

Multiple companies

When multiple companies use Fingerprint API to identify a device, DRN will aggregate the data from multiple companies' data sets. For example, if Company A identified a device on 2023-01-01, and Company B identified the same device on 2024-01-01, the information from both smart signals will be available, but the aggregations will go only 30 days back.

Single company

If only one company identifies a device, the data will be aggregated only from that single company data set.