Overview

{
  "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}
      ]
    }]
}

"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
        }]
    }]
}

// 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 }] }
      ]
}

"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: /reference/server-api-get-event
    "signals": {
        // Nested Smart Signals can be used, compatible with the Server API response.
        "ipBlockList": 12,
          "vpn": {
          "publicVPN": 5
        },
        "proxy": 3
      }
  }
}

"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
}