Build with explainable IP intelligence.

Turn directly observed hostile behavior into explainable allow, challenge, and block decisions. Start with ACE v2 for one IP, then add bulk evaluation, customer policy, live telemetry, and security automation as your integration grows.

ACE v1 remains supported and documented for customers with existing integrations. Those APIs continue to provide the familiar risk levels, legacy threat labels, reputation lookups, bulk workflows, and downloadable intelligence that production systems rely on today.

ACE v2 is FraudGuard's current engine and the future of the platform. It is where we are concentrating new detection logic, richer evidence, explainable recommendations, forecasting, and live capabilities such as Attack Stream. New integrations should begin with ACE v2; existing ACE v1 customers can continue operating normally and adopt ACE v2 as they modernize their enforcement workflows.

In this reference, ACE v2 IP Intelligence contains the recommended decision APIs and ACE v2-powered live telemetry. IP intelligence contains ACE v1 compatibility APIs plus specialized lookup and downloadable-data endpoints.

ACE v1 versus ACE v2

Both engines use FraudGuard threat intelligence, but they expose different decision models and are not schema-compatible.

Integration essentials

• Create credentials. Start a trial or open API keys in the FraudGuard dashboard to get your API username and password.
• Base URL: https://api.fraudguard.io
• Authentication: HTTP Basic Authentication with your FraudGuard API username and password. Send credentials only over HTTPS and store them in a secrets manager or server-side environment variables.
• Request format: Send Content-Type: application/json for JSON request bodies and Accept: application/json when you expect JSON.
• Rate limits: Limits vary by plan and product. Retry a 429 only when the response identifies a temporary rate limit, and honor Retry-After when present. A plan or access-gate 429 requires an account change and will not recover through retries.
• Reliability: Set a request timeout. Retry retryable rate-limit 429, 500, and 503 responses with exponential backoff and jitter; automatically retry only idempotent requests unless your workflow prevents duplicate writes.
• Caching: When ACE v2 returns cache_ttl_seconds, reuse the decision for that period unless your policy requires a fresher lookup.
• Errors: Check the HTTP status before parsing success data. Log the status, sanitized error code/message, and any request identifier returned by the endpoint. Never log credentials, tokens, full query strings, or response bodies containing personal or customer data.

ACE v2 IP Intelligence

ACE v2 IP Intelligence is FraudGuard's next-generation IP reputation API. It is designed for real-time allow, challenge, and block decisions using verified FraudGuard honeypot observations, attack behavior, infrastructure enrichment, network context, geography, and account-specific customer controls.

Unlike static IP lists, ACE v2 explains why a recommendation was made. A response can show the observed attack families, attack volume over 24-hour, 7-day, and 30-day windows, targeted services, protocols and ports, current infrastructure classification, customer whitelist/blacklist/geoblock matches, confidence factors, and human-readable reasons.

Plan Availability

HTTP Request

POST https://api.fraudguard.io/ace/v2/ip/check

Authentication

Basic Authentication is required for every request.

Headers

Request Body

{
  "ip": "8.216.12.173"
}

CIDR ranges are not accepted by this endpoint. Submit one normalized IP address or hostname per request.

If you submit a hostname, FraudGuard resolves it to one IP address and runs the normal ACE v2 IP lookup against that resolved IP. If DNS returns multiple IP addresses, one resolved address is used for the lookup. The response ip field contains the resolved IP address, and the response includes a hostname field containing the original submitted hostname.

curl -u "username:password" \
  -H "Content-Type: application/json" \
  -X POST "https://api.fraudguard.io/ace/v2/ip/check" \
  -d '{"ip":"8.216.12.173"}'

require 'json'
require 'net/http'

uri = URI('https://api.fraudguard.io/ace/v2/ip/check')
request = Net::HTTP::Post.new(uri)
request.basic_auth('username', 'password')
request['Content-Type'] = 'application/json'
request.body = JSON.generate({ ip: '8.216.12.173' })

response = Net::HTTP.start(uri.hostname, uri.port, use_ssl: true) do |http|
  http.request(request)
end

puts response.body

import requests
from requests.auth import HTTPBasicAuth

response = requests.post(
    'https://api.fraudguard.io/ace/v2/ip/check',
    json={'ip': '8.216.12.173'},
    auth=HTTPBasicAuth('username', 'password'),
    timeout=30
)

print(response.text)

const response = await fetch('https://api.fraudguard.io/ace/v2/ip/check', {
  method: 'POST',
  headers: {
    'Authorization': 'Basic ' + Buffer.from('username:password').toString('base64'),
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({ ip: '8.216.12.173' })
});

console.log(await response.json());

<?php
$ch = curl_init('https://api.fraudguard.io/ace/v2/ip/check');
curl_setopt_array($ch, [
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_POST => true,
  CURLOPT_HTTPAUTH => CURLAUTH_BASIC,
  CURLOPT_USERPWD => 'username:password',
  CURLOPT_HTTPHEADER => ['Content-Type: application/json'],
  CURLOPT_POSTFIELDS => json_encode(['ip' => '8.216.12.173']),
]);
$result = curl_exec($ch);
curl_close($ch);
echo $result;

$user = 'username'
$pass = 'password'
$pair = "$($user):$($pass)"
$encodedCreds = [System.Convert]::ToBase64String([System.Text.Encoding]::ASCII.GetBytes($pair))
$basicAuthValue = "Basic $encodedCreds"

$Headers = @{
    Authorization = $basicAuthValue
}

$body = @{
    ip = '8.216.12.173'
} | ConvertTo-Json

Invoke-WebRequest `
    -Uri 'https://api.fraudguard.io/ace/v2/ip/check' `
    -Headers $Headers `
    -Method Post `
    -ContentType 'application/json' `
    -Body $body

Example Response

{
  "ip": "8.216.12.173",
  "recommendation": {
    "action": "block",
    "evidence_summary": "This IP was observed performing 3 total attack events across 2 FraudGuard honeypots in the last 7 days, including 2 Jenkins probing events and 1 HTTP/WAF probing event, most recently on May 26, 2026 at 19:31 UTC.",
    "cache_ttl_seconds": 14400
  },
  "classification": {
    "primary": "web_scanner",
    "secondary": [
      "multi_service_scanner",
      "honeypot_attacker",
      "ai_automation",
      "hosting_provider"
    ]
  },
  "risk": {
    "level": 5,
    "label": "critical",
    "confidence": 85,
    "confidence_factors": [
      "recent_activity",
      "repeated_activity",
      "multi_honeypot_reach",
      "specific_attack_signature",
      "multiple_attack_types",
      "multiple_target_services"
    ]
  },
  "observed_activity": {
    "observed": true,
    "attack_families": [
      "web_probe"
    ],
    "activity": {
      "pattern": "burst",
      "trend": "burst",
      "attack_events_24h": 3,
      "attack_events_7d": 3,
      "attack_events_30d": 3,
      "distinct_attack_types_30d": 2,
      "distinct_target_services_30d": 2,
      "distinct_target_ports_30d": 2,
      "first_seen": "2026-05-26T15:45:54+00:00",
      "last_seen": "2026-05-26T19:31:59+00:00"
    },
    "attacks": [
      {
        "type": "jenkins_login_page_probe",
        "service": "jenkins",
        "protocol": "http",
        "destination_port": 8080,
        "attack_events_24h": 2,
        "attack_events_7d": 2,
        "attack_events_30d": 2,
        "honeypots_reached_24h": 1,
        "honeypots_reached_7d": 1,
        "honeypots_reached_30d": 1,
        "first_seen": "2026-05-26T15:45:54+00:00",
        "last_seen": "2026-05-26T15:45:57+00:00"
      },
      {
        "type": "waf_attack",
        "service": "http",
        "protocol": "http",
        "destination_port": 80,
        "attack_events_24h": 1,
        "attack_events_7d": 1,
        "attack_events_30d": 1,
        "honeypots_reached_24h": 1,
        "honeypots_reached_7d": 1,
        "honeypots_reached_30d": 1,
        "first_seen": "2026-05-26T19:31:59+00:00",
        "last_seen": "2026-05-26T19:31:59+00:00"
      }
    ],
    "last_observed_attack": {
      "event_type": "waf_attack",
      "service": "http",
      "protocol": "http",
      "destination_port": 80,
      "observed_at": "2026-05-26T19:31:59+00:00"
    }
  },
  "attributes": {
    "ai_automation_suspected": {
      "detected": true
    }
  },
  "reasons": [
    {
      "code": "abusive_activity_observed",
      "message": "Abusive activity observed by FraudGuard ACE",
      "severity": "high"
    },
    {
      "code": "scanner_activity_observed",
      "message": "Scanner or probing activity observed",
      "severity": "medium"
    },
    {
      "code": "honeypot_interaction_observed",
      "message": "Interaction observed across FraudGuard honeypot infrastructure",
      "severity": "high"
    },
    {
      "code": "waf_attack_activity_observed",
      "message": "HTTP/WAF attack activity observed",
      "severity": "high"
    },
    {
      "code": "activity_within_7_days",
      "message": "Activity observed within the last 7 days",
      "severity": "high"
    }
  ],
  "customer": {
    "ip_in_whitelist": false,
    "ip_in_blacklist": false,
    "ip_in_geoblock": false
  },
  "infrastructure": {
    "type": "hosting_provider",
    "provider": "Alibaba Cloud",
    "is_tor_exit": false,
    "is_public_proxy": false,
    "is_vpn": false,
    "is_hosting_provider": true,
    "is_residential_proxy": false,
    "is_mobile_network": false,
    "is_satellite_network": false,
    "is_shared_exit": false,
    "is_ai_agent": false,
    "first_seen": "2026-05-18T02:44:12+00:00",
    "last_seen": "2026-05-18T15:07:09+00:00",
    "updated_at": "2026-05-18T15:07:09+00:00"
  },
  "network": {
    "asn": 45102,
    "asn_org": "Alibaba US Technology Co., Ltd.",
    "isp": "Alibaba",
    "organization": "Alibaba",
    "prefix": "8.216.12.0/24",
    "connection_type": "Corporate"
  },
  "geography": {
    "country": "Japan",
    "isocode": "JP",
    "state": "Tokyo",
    "city": "Tokyo",
    "postal_code": "102-0082",
    "timezone": "Asia/Tokyo",
    "latitude": 35.6893,
    "longitude": 139.6899
  },
  "metadata": {
    "request_id": "acev2_example_single_lookup",
    "generated_at": "2026-05-27T00:47:35+00:00",
    "schema_version": "2.0.0",
    "api_version": "2.0.0",
    "engine": "ace_v2"
  }
}

Response Fields

Schema stability and dynamic values: the response schema is stable for this API version, while classification and signal values are intentionally dynamic. FraudGuard may add new detections, services, attack signatures, infrastructure categories, behavior models, confidence factors, reason codes, attributes, attack families, attack types, and infrastructure types over time. Integrations should parse known fields but tolerate new values in classification, confidence_factors, attack_families, attacks[].type, reasons[].code, attributes, and infrastructure.type.

recommendation

Recommended action values:

Cache guidance: use cache_ttl_seconds as FraudGuard's recommended cache duration for your own cache layer. ACE v2 may return different TTLs based on risk level, signal freshness, observed activity, infrastructure context, and how quickly the underlying evidence may change.

classification

Current public classification values include:

risk

Risk levels:

ACE v2 no longer uses the legacy threat taxonomy from earlier FraudGuard APIs. Use classification, reasons, attributes, and observed_activity for behavioral context, and use the returned recommendation—not the numeric risk alone—as the default enforcement input.

Current public confidence factors include:

observed_activity

The observed_activity.activity object contains:

Supported activity.pattern values:

Supported activity.trend values:

Current public attack_families include:

Each object in observed_activity.attacks contains:

When present, observed_activity.last_observed_attack contains:

attributes

attributes is an intentionally dynamic signal map. Keys are public signal names and values currently contain detected: true.

Common example attribute groups include:

reasons

Each reason contains:

Current public ACE v2 reason codes include:

Note: anonymized_network_behavior_observed can come from observed behavior, such as AI/API/proxy-style probing, and is not limited to current infrastructure flags. More specific current infrastructure reasons are emitted separately, such as public_proxy_infrastructure_observed or tor_exit_infrastructure_observed.

customer

The customer object is account-specific and is evaluated for the authenticated API user.

These fields are provided for customers who use FraudGuard custom whitelist, blacklist, or geoblock features. ACE v2 does not use these account-specific customer lists to change recommendation.action, risk, or classification; if your integration depends on whitelist, blacklist, or geoblock enforcement, check these values in your own application logic.

infrastructure

Current public infrastructure.type values include:

unknown, ai_agent, residential_proxy, vpn, tor_exit, public_proxy, hosting_provider, mobile_network, satellite_network, shared_exit.

network

geography

metadata

ACE v2 Bulk IP Intelligence

ACE v2 Bulk IP Intelligence runs the same ACE v2 analysis as the single-IP endpoint for multiple IPs in one request. Use this endpoint when you need to evaluate batches efficiently while receiving the same per-IP recommendation, classification, risk, activity, customer, infrastructure, network, and geography fields.

The result object for each IP follows the ACE v2 IP Intelligence schema. This section documents only the differences for bulk requests and responses.

Plan Availability

HTTP Request

POST https://api.fraudguard.io/ace/v2/ip/check/bulk

Authentication

Basic Authentication is required for every request.

Headers

Request Body

{
  "ips": [
    "8.8.8.8",
    "8.216.12.173",
    "app.fraudguard.io"
  ]
}

Bulk request behavior:

• Maximum accepted unique resolved IP lookups per request: 100.
• Duplicate resolved IPs are de-duplicated before lookup.
• Empty string values are ignored.
• CIDR ranges are not accepted.
• Hostnames are resolved to one IP address and then looked up like normal ACE v2 IPs. If DNS returns multiple IP addresses, one resolved address is used for the lookup.
• Results are keyed by unique resolved IP, not by request-array position. If multiple hostnames—or a hostname and a literal IP—resolve to the same address, they collapse into one result and its hostname field cannot represent every original input. Resolve DNS client-side or avoid colliding inputs when one-to-one attribution matters.
• If any non-empty submitted value is not a valid IPv4 address, IPv6 address, or resolvable hostname, the entire request returns an error instead of a partial result.
• Billing and monthly usage counters are incremented by the number of accepted unique resolved IP lookups, not by one per HTTP request.

curl -u "username:password" \
  -H "Content-Type: application/json" \
  -X POST "https://api.fraudguard.io/ace/v2/ip/check/bulk" \
  -d '{"ips":["8.8.8.8","8.216.12.173","app.fraudguard.io"]}'

require 'json'
require 'net/http'

uri = URI('https://api.fraudguard.io/ace/v2/ip/check/bulk')
request = Net::HTTP::Post.new(uri)
request.basic_auth('username', 'password')
request['Content-Type'] = 'application/json'
request.body = JSON.generate({
  ips: ['8.8.8.8', '8.216.12.173', 'app.fraudguard.io']
})

response = Net::HTTP.start(uri.hostname, uri.port, use_ssl: true) do |http|
  http.request(request)
end

puts response.body

import requests
from requests.auth import HTTPBasicAuth

response = requests.post(
    'https://api.fraudguard.io/ace/v2/ip/check/bulk',
    json={'ips': ['8.8.8.8', '8.216.12.173', 'app.fraudguard.io']},
    auth=HTTPBasicAuth('username', 'password'),
    timeout=30
)

print(response.text)

const response = await fetch('https://api.fraudguard.io/ace/v2/ip/check/bulk', {
  method: 'POST',
  headers: {
    'Authorization': 'Basic ' + Buffer.from('username:password').toString('base64'),
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    ips: ['8.8.8.8', '8.216.12.173', 'app.fraudguard.io']
  })
});

console.log(await response.json());

<?php
$ch = curl_init('https://api.fraudguard.io/ace/v2/ip/check/bulk');
curl_setopt_array($ch, [
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_POST => true,
  CURLOPT_HTTPAUTH => CURLAUTH_BASIC,
  CURLOPT_USERPWD => 'username:password',
  CURLOPT_HTTPHEADER => ['Content-Type: application/json'],
  CURLOPT_POSTFIELDS => json_encode([
    'ips' => ['8.8.8.8', '8.216.12.173', 'app.fraudguard.io'],
  ]),
]);
$result = curl_exec($ch);
curl_close($ch);
echo $result;

$user = 'username'
$pass = 'password'
$pair = "$($user):$($pass)"
$encodedCreds = [System.Convert]::ToBase64String([System.Text.Encoding]::ASCII.GetBytes($pair))
$basicAuthValue = "Basic $encodedCreds"

$Headers = @{
    Authorization = $basicAuthValue
}

$body = @{
    ips = @('8.8.8.8', '8.216.12.173', 'app.fraudguard.io')
} | ConvertTo-Json

Invoke-WebRequest `
    -Uri 'https://api.fraudguard.io/ace/v2/ip/check/bulk' `
    -Headers $Headers `
    -Method Post `
    -ContentType 'application/json' `
    -Body $body

Example Response

The bulk example response below is shortened to one result object. A real bulk response returns one result object per accepted unique resolved IP, and each result follows the ACE v2 IP Intelligence schema.

When a hostname resolves to a unique result IP, that result includes hostname with the submitted hostname and ip with the resolved address used for the lookup. See the duplicate-resolution caveat above when inputs collapse to the same IP.

{
  "results": [
    {
      "ip": "8.8.8.8",
      "recommendation": {
        "action": "allow",
        "evidence_summary": "No active FraudGuard ACE v2 threat signals were observed for this IP.",
        "cache_ttl_seconds": 28800
      },
      "classification": {
        "primary": "clean",
        "secondary": []
      },
      "risk": {
        "level": 1,
        "label": "minimal",
        "confidence": 100,
        "confidence_factors": [
          "no_active_threat_signals"
        ]
      },
      "observed_activity": {
        "observed": false,
        "attack_families": [],
        "activity": {
          "pattern": "none",
          "trend": "inactive",
          "attack_events_24h": 0,
          "attack_events_7d": 0,
          "attack_events_30d": 0,
          "distinct_attack_types_30d": 0,
          "distinct_target_services_30d": 0,
          "distinct_target_ports_30d": 0,
          "first_seen": null,
          "last_seen": null
        },
        "attacks": [],
        "last_observed_attack": null
      },
      "attributes": {},
      "reasons": [
        {
          "code": "no_active_ace_v2_signals",
          "message": "No active FraudGuard ACE v2 signals observed",
          "severity": "info"
        }
      ],
      "customer": {
        "ip_in_whitelist": false,
        "ip_in_blacklist": false,
        "ip_in_geoblock": false
      },
      "infrastructure": {
        "type": "unknown",
        "provider": null,
        "is_tor_exit": false,
        "is_public_proxy": false,
        "is_vpn": false,
        "is_hosting_provider": false,
        "is_residential_proxy": false,
        "is_mobile_network": false,
        "is_satellite_network": false,
        "is_shared_exit": false,
        "is_ai_agent": false,
        "first_seen": null,
        "last_seen": null,
        "updated_at": null
      },
      "network": {
        "asn": 15169,
        "asn_org": "GOOGLE",
        "isp": "Google",
        "organization": "Google",
        "prefix": null,
        "connection_type": "Corporate"
      },
      "geography": {
        "country": "United States",
        "isocode": "US",
        "state": null,
        "city": null,
        "postal_code": null,
        "timezone": "America/Chicago",
        "latitude": 37.751,
        "longitude": -97.822
      }
    }
  ],
  "count": 1,
  "metadata": {
    "request_id": "acev2_example_bulk_lookup",
    "generated_at": "2026-05-27T14:35:53+00:00",
    "schema_version": "2.0.0",
    "api_version": "2.0.0",
    "engine": "ace_v2"
  }
}

Bulk Response Fields

Differences From Single-IP ACE v2

• Single-IP endpoint request body uses ip; bulk request body uses ips.
• Single-IP response contains one result object with metadata inside that object.
• Bulk response contains results, count, and top-level metadata.
• Each bulk results[] object uses the same fields as a single-IP response, but does not include per-result metadata.
• Bulk requests are billed by accepted unique resolved IP lookup count.
• Bulk validation is all-or-nothing for invalid non-empty IP or hostname values.

ACE v2 IP Forecast

ACE v2 IP Forecast is FraudGuard's predictive risk API for a single IP address. It uses the ACE v2 engine to compare the IP's current risk state with a near-term forecast based on direct IP activity, historical risk snapshots, active ACE signals, and correlated activity in nearby network space.

This endpoint is intentionally predictive. current_risk and current_action describe the IP's current ACE v2 assessment at the time of the request. forecast_risk and forecast_action describe the model's projected near-term risk and recommended treatment over the returned forecast_horizon. A higher forecast does not always mean the exact IP has already performed malicious activity; inspect signals, nearby_activity, and why to understand whether the forecast is driven by direct observations, related prefix activity, or both.

Use this API when you need forward-looking enforcement guidance, such as adding friction before abuse is directly observed from the exact IP, monitoring IPs from risky prefixes more closely, or deciding whether a currently allowed IP should be challenged on sensitive workflows.

HTTP Request

POST https://api.fraudguard.io/ace/v2/ip/forecast

Authentication

Basic Authentication is required for every request.

Headers

Request Body

{
  "ip": "94.243.8.249"
}

CIDR ranges, hostnames, and arrays of IPs are not accepted by this endpoint. Submit one normalized IP address per request.

curl -u "username:password" \
  -H "Content-Type: application/json" \
  -X POST "https://api.fraudguard.io/ace/v2/ip/forecast" \
  -d '{"ip":"94.243.8.249"}'

require 'json'
require 'net/http'

uri = URI('https://api.fraudguard.io/ace/v2/ip/forecast')
request = Net::HTTP::Post.new(uri)
request.basic_auth('username', 'password')
request['Content-Type'] = 'application/json'
request.body = JSON.generate({ ip: '94.243.8.249' })

response = Net::HTTP.start(uri.hostname, uri.port, use_ssl: true) do |http|
  http.request(request)
end

puts response.body

import requests
from requests.auth import HTTPBasicAuth

response = requests.post(
    'https://api.fraudguard.io/ace/v2/ip/forecast',
    json={'ip': '94.243.8.249'},
    auth=HTTPBasicAuth('username', 'password'),
    timeout=30
)

print(response.text)

const response = await fetch('https://api.fraudguard.io/ace/v2/ip/forecast', {
  method: 'POST',
  headers: {
    'Authorization': 'Basic ' + Buffer.from('username:password').toString('base64'),
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({ ip: '94.243.8.249' })
});

console.log(await response.json());

<?php
$ch = curl_init('https://api.fraudguard.io/ace/v2/ip/forecast');
curl_setopt_array($ch, [
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_POST => true,
  CURLOPT_HTTPAUTH => CURLAUTH_BASIC,
  CURLOPT_USERPWD => 'username:password',
  CURLOPT_HTTPHEADER => ['Content-Type: application/json'],
  CURLOPT_POSTFIELDS => json_encode(['ip' => '94.243.8.249']),
]);
$result = curl_exec($ch);
curl_close($ch);
echo $result;

$user = 'username'
$pass = 'password'
$pair = "$($user):$($pass)"
$encodedCreds = [System.Convert]::ToBase64String([System.Text.Encoding]::ASCII.GetBytes($pair))
$basicAuthValue = "Basic $encodedCreds"

$Headers = @{
    Authorization = $basicAuthValue
}

$body = @{
    ip = '94.243.8.249'
} | ConvertTo-Json

Invoke-WebRequest `
    -Uri 'https://api.fraudguard.io/ace/v2/ip/forecast' `
    -Headers $Headers `
    -Method Post `
    -ContentType 'application/json' `
    -Body $body

Example Response

{
  "ip": "94.243.8.249",
  "current_risk": 1,
  "forecast_risk": 4,
  "current_action": "allow",
  "forecast_action": "challenge",
  "outlook": "worsening",
  "confidence": 90,
  "trend": "rising",
  "time_window": "30d",
  "forecast_horizon": {
    "period": "near_term",
    "days": 7
  },
  "signals": {
    "events_24h": 0,
    "events_7d": 0,
    "events_30d": 0,
    "risk_24h_ago": null,
    "risk_7d_ago": null,
    "risk_30d_ago": null,
    "active_trackers": [],
    "active_attributes": [],
    "max_severity_30d": null,
    "distinct_sources_30d": 0
  },
  "nearby_activity": {
    "prefix": "94.243.8.0/24",
    "events_24h": 30,
    "events_7d": 96,
    "events_30d": 111,
    "distinct_ips_24h": 2,
    "distinct_ips_7d": 10,
    "distinct_ips_30d": 12,
    "active_trackers": [
      "scanner_tracker",
      "abuse_tracker"
    ],
    "active_attributes": [
      "remote_access_probe",
      "persistent_touch_pattern",
      "dense_scan_cluster",
      "command_execution_probe",
      "shell_or_downloader_artifact",
      "suspicious_command_indicator",
      "legacy_shell_probe",
      "scan_retry_pattern",
      "credential_attack_pattern",
      "login_bruteforce_behavior",
      "credential_field_submitted",
      "credential_stuffing_probe",
      "repeated_probe_pattern",
      "sustained_probe_stream",
      "telnet_login_surface_scan",
      "multi_attempt_sequence",
      "high_volume_honeypot_activity",
      "web_route_scan",
      "authentication_surface_scan",
      "known_exploit_path_scan",
      "admin_surface_probe",
      "scripted_request_pattern",
      "recently_active"
    ],
    "max_severity_30d": 4
  },
  "why": [
    "No direct malicious activity observed for this IP",
    "Recent malicious activity observed in the same prefix",
    "Prefix contains scanner or probing activity",
    "Prefix contains abuse activity"
  ],
  "recommendation": "Apply additional scrutiny; nearby ACE activity indicates elevated prefix risk."
}

Forecast Response Fields

Schema stability and dynamic values: the top-level response schema is stable for this API version, while tracker names, attribute names, trend values, outlook values, and why messages are intentionally dynamic. FraudGuard may add new ACE v2 signals, trackers, attributes, trend labels, outlook labels, and explanation text over time. Integrations should parse known fields but tolerate new string values in outlook, trend, active_trackers, active_attributes, and why.

Forecast Interpretation

current_* fields are for the IP's current ACE v2 state. forecast_* fields are for the predicted near-term state. These can differ significantly. In the example above, the IP is currently allowed with current_risk 1, but the forecast is worsening because ACE v2 observed recent scanner and abuse activity in the same prefix. The recommended predictive action is therefore challenge.

Do not derive actions from risk numbers yourself. Use current_action for current enforcement and forecast_action for predictive enforcement. The forecast action can be softer or different from what a static risk-to-action mapping might suggest because it represents forward-looking control guidance, not only a current observed-abuse verdict.

Use signals to determine whether the exact IP has direct activity. Use nearby_activity to determine whether the forecast is being influenced by related prefix behavior. A forecast driven only by nearby_activity is still useful for additional scrutiny, but it should not be presented as evidence that the exact IP already performed the nearby activity.

Risk and Action Values

Risk levels use the ACE v2 1 through 5 scale, where 1 is the lowest risk and 5 is the highest risk. The forecast endpoint returns numeric risk only, so use the returned action fields for enforcement decisions.

Outlook values describe the relationship between current and forecast risk:

forecast_horizon

Read forecast_horizon.days from every response instead of assuming a fixed horizon. The example response forecasts the next 7 days.

signals

signals describes activity and risk history for the exact queried IP.

When signals.events_30d is 0, no direct malicious activity was observed for the exact IP during the returned time_window. The forecast can still rise when nearby network behavior indicates elevated risk.

nearby_activity

nearby_activity describes correlated ACE v2 activity in nearby network space. For IPv4, this is commonly a related prefix such as a /24; for other address families or future models, use the returned prefix value rather than assuming a fixed prefix size.

Nearby activity helps ACE v2 forecast risk before the exact IP has produced direct evidence. It is especially useful for detecting emerging scanning, abuse, credential attacks, and exploit probing moving through adjacent infrastructure.

Integration Guidance

• Use current_action when you only need the immediate ACE v2 decision for the exact IP.
• Use forecast_action when you want predictive controls for sensitive flows, such as login, signup, checkout, password reset, account changes, scraping-prone pages, and high-cost API endpoints.
• Treat challenge as a step-up control, not necessarily as a hard deny. Common challenge actions include BotGuard, CAPTCHA, MFA, rate limiting, device checks, queueing, or manual review.
• Do not describe forecast-only risk as confirmed direct abuse. The signals object is always present; when signals.events_30d is 0 and nearby_activity is elevated, explain that the forecast is based on related network activity.
• Log current_risk, forecast_risk, current_action, forecast_action, outlook, confidence, time_window, forecast_horizon, and why for review and tuning.
• Cache conservatively. This endpoint does not return cache_ttl_seconds, and forecasts can change as ACE v2 receives new telemetry.
• Re-query before durable account actions, permanent blocks, or support decisions that depend on the latest forecast.

Get Specific IP Reputation v1

This legacy endpoint returns the original FraudGuard IP reputation schema for one IP address. It remains available for compatibility; use ACE v2 for new integrations, explainable decisions, and the current intelligence model.

Response Fields

• isocode: The two-letter ISO 3166-1 alpha-2 country code representing the country associated with the IP address. Example: "KR" for the Republic of Korea.

• country: The full name of the country where the IP address is located. Example: "Republic of Korea".

• state: The state or region within the country associated with the IP address. Example: "Seoul".

• city: The city associated with the IP address. Example: "Seoul".

• discover_date: The date and time when the IP address was first identified or reported for suspicious activity, formatted as "YYYY-MM-DD HH:MM:SS". Example: "2018-12-11 07:00:45".

• threat: The category of threat detected for the IP address, as determined by FraudGuard.io’s Attack Correlation Engine (ACE). This field highlights specific behaviors or associations flagged for the IP:

  • "abuse_tracker": Indicates involvement in abusive activities, such as unauthorized access attempts or exploitation.
  • "honeypot_tracker": Associated with honeypot traps, suggesting the IP has been caught in decoy systems designed to detect malicious behavior.
  • "botnet_tracker": Part of a botnet network, indicating the IP is likely compromised and under the control of malicious actors.
  • "spam_tracker": Linked to spamming activities, including the distribution of unsolicited emails or messages.
  • "anonymous_tracker": Associated with anonymization services like proxies or TOR, which can be used to mask the true origin of traffic.
  • "vpn_tracker": Represents IP addresses associated with VPN servers, used primarily for anonymizing user traffic.
  • "unknown": No specific threat detected.

• risk_level: A numeric value representing the assessed threat level of the IP address, as determined by FraudGuard.io’s Attack Correlation Engine (ACE). The risk_level reflects not just the nature of malicious activities but also factors in time and recurrence:

  • Older incidents, especially from IPs that have not repeated their behavior, may have a lower risk level due to the lack of recent activity.
  • Recurring offenders or IPs flagged for multiple recent events are assigned a higher risk level. The scale typically ranges from 1 to 5, with higher numbers indicating greater risk:
  • Level 1 (Low Risk): Minimal or negligible threat. Likely a benign IP with a clean reputation.
  • Level 2: Some indicators of suspicious behavior but not considered actively dangerous.
  • Level 3: Moderate risk with signs of suspicious or harmful activity.
  • Level 4: High risk with significant evidence of malicious behavior, often repeated or recent.
  • Level 5 (Critical Risk): Severe threats, actively engaged in malicious activities and requiring immediate attention. Example: 5 (indicating a critical-risk IP).

curl -X GET -u "username:password" "https://api.fraudguard.io/ip/1.221.157.205"

require 'net/http'
require 'net/https'

def get_ip(server,path,username,password)
http = Net::HTTP.new(server,443)
req = Net::HTTP::Get.new(path)
http.use_ssl = true
req.basic_auth username, password
response = http.request(req)
return response.body
end

puts get_ip('api.fraudguard.io','/ip/1.221.157.205','username','password')

import requests
from requests.auth import HTTPBasicAuth
ip=requests.get('https://api.fraudguard.io/ip/1.221.157.205', verify=True, auth=HTTPBasicAuth('username', 'password'))
print (ip.text)

var options = {
   host: 'api.fraudguard.io',
   port: 443,
   path: '/ip/1.221.157.205',
   headers: {
      'Authorization': 'Basic ' + new Buffer(username + ':' + password).toString('base64')
   }
};

request = https.get(options, function(res){
   var body = "";
   res.on('data', function(data) {
      body += data;
   });
   res.on('end', function() {
      console.log(body);
   })
   res.on('error', function(e) {
     console.log("Got error: " + e.message);
   });
    });

}

<?php
$login = 'username';
$password = 'password';
$url = 'https://api.fraudguard.io/ip/1.221.157.205';
$ch = curl_init();
curl_setopt($ch, CURLOPT_URL,$url);
curl_setopt($ch, CURLOPT_RETURNTRANSFER,1);
curl_setopt($ch, CURLOPT_HTTPAUTH, CURLAUTH_BASIC);
curl_setopt($ch, CURLOPT_USERPWD, "$login:$password");
$result = curl_exec($ch);
curl_close($ch);
echo $result;

$user = 'username'
$pass = 'password'
$pair = "$($user):$($pass)"
$encodedCreds = [System.Convert]::ToBase64String([System.Text.Encoding]::ASCII.GetBytes($pair))
$basicAuthValue = "Basic $encodedCreds"

$Headers = @{
    Authorization = $basicAuthValue
}

Invoke-WebRequest -Uri 'https://api.fraudguard.io/ip/1.221.157.205' -Headers $Headers

Example response:

{
    "isocode": "KR",
    "country": "Republic of Korea",
    "state": "Seoul",
    "city": "Seoul",
    "discover_date": "2018-12-11 07:00:45",
    "threat": "honeypot_tracker",
    "risk_level": "5"
}

HTTP Request

GET https://api.fraudguard.io/ip/<IP>

URL Parameters

Get Specific IP Reputation v2

This legacy endpoint returns the v2 FraudGuard reputation schema for one IP address. It remains available for compatibility; use ACE v2 for new integrations.

Response Fields

• isocode: The two-letter ISO 3166-1 alpha-2 country code representing the country associated with the IP address. Example: "US" for the United States.

• country: The full name of the country where the IP address is located. Example: "United States".

• state_code: The abbreviated code for the state or region within the country. Example: "CA" for California.

• state: The full name of the state or region corresponding to the state_code. Example: "California".

• city: The city associated with the IP address. Example: "Pomona".

• postal_code: The postal or ZIP code for the location. Example: "91768".

• latitude: The geographic latitude of the IP address's location. Example: 34.0662.

• longitude: The geographic longitude of the IP address's location. Example: -117.7763.

• timezone: The IANA time zone identifier for the location. Example: "America/Los_Angeles".

• connection_type: The type of internet connection used. Possible values include: "Corporate", "Cable/DSL", "Mobile". Example: "Corporate".

• asn: The Autonomous System Number associated with the IP address. Example: 7018.

• asn_organization: The organization that owns the ASN. Example: "AT&T Services, Inc.".

• isp: The Internet Service Provider providing connectivity for the IP address. Example: "AT&T Services".

• organization: The specific organization associated with the IP address, which may differ from the ISP. Example: "AT&T Services".

• discover_date: The date and time when the IP address was first identified or reported for suspicious activity, formatted as "YYYY-MM-DD HH:MM:SS". Example: "2018-12-13 03:03:15".

• threat: The category of threat detected for the IP address, as determined by FraudGuard.io’s Attack Correlation Engine (ACE). This field highlights specific behaviors or associations flagged for the IP:

  • "abuse_tracker": Indicates involvement in abusive activities, such as unauthorized access attempts or exploitation.
  • "honeypot_tracker": Associated with honeypot traps, suggesting the IP has been caught in decoy systems designed to detect malicious behavior.
  • "botnet_tracker": Part of a botnet network, indicating the IP is likely compromised and under the control of malicious actors.
  • "spam_tracker": Linked to spamming activities, including the distribution of unsolicited emails or messages.
  • "anonymous_tracker": Associated with anonymization services like proxies or TOR, which can be used to mask the true origin of traffic.
  • "vpn_tracker": Represents IP addresses associated with VPN servers, used primarily for anonymizing user traffic.
  • "unknown": No specific threat detected.

• risk_level: A numeric value representing the assessed threat level of the IP address, as determined by FraudGuard.io’s Attack Correlation Engine (ACE). The risk_level reflects not just the nature of malicious activities but also factors in time and recurrence:

  • Older incidents, especially from IPs that have not repeated their behavior, may have a lower risk level due to the lack of recent activity.
  • Recurring offenders or IPs flagged for multiple recent events are assigned a higher risk level. The scale typically ranges from 1 to 5, with higher numbers indicating greater risk:
  • Level 1 (Low Risk): Minimal or negligible threat. Likely a benign IP with a clean reputation.
  • Level 2: Some indicators of suspicious behavior but not considered actively dangerous.
  • Level 3: Moderate risk with signs of suspicious or harmful activity.
  • Level 4: High risk with significant evidence of malicious behavior, often repeated or recent.
  • Level 5 (Critical Risk): Severe threats, actively engaged in malicious activities and requiring immediate attention. Example: 4 (indicating a high-risk IP).

curl -X GET -u "username:password" "https://api.fraudguard.io/v2/ip/12.167.53.202"

require 'net/http'
require 'net/https'

def get_ip(server,path,username,password)
http = Net::HTTP.new(server,443)
req = Net::HTTP::Get.new(path)
http.use_ssl = true
req.basic_auth username, password
response = http.request(req)
return response.body
end

puts get_ip('api.fraudguard.io','/v2/ip/12.167.53.202','username','password')

import requests
from requests.auth import HTTPBasicAuth
ip=requests.get('https://api.fraudguard.io/v2/ip/12.167.53.202', verify=True, auth=HTTPBasicAuth('username', 'password'))
print (ip.text)

var options = {
   host: 'api.fraudguard.io',
   port: 443,
   path: '/v2/ip/12.167.53.202',
   headers: {
      'Authorization': 'Basic ' + new Buffer(username + ':' + password).toString('base64')
   }
};

request = https.get(options, function(res){
   var body = "";
   res.on('data', function(data) {
      body += data;
   });
   res.on('end', function() {
      console.log(body);
   })
   res.on('error', function(e) {
     console.log("Got error: " + e.message);
   });
    });

}

<?php
$login = 'username';
$password = 'password';
$url = 'https://api.fraudguard.io/v2/ip/12.167.53.202';
$ch = curl_init();
curl_setopt($ch, CURLOPT_URL,$url);
curl_setopt($ch, CURLOPT_RETURNTRANSFER,1);
curl_setopt($ch, CURLOPT_HTTPAUTH, CURLAUTH_BASIC);
curl_setopt($ch, CURLOPT_USERPWD, "$login:$password");
$result = curl_exec($ch);
curl_close($ch);
echo $result;

$user = 'username'
$pass = 'password'
$pair = "$($user):$($pass)"
$encodedCreds = [System.Convert]::ToBase64String([System.Text.Encoding]::ASCII.GetBytes($pair))
$basicAuthValue = "Basic $encodedCreds"

$Headers = @{
    Authorization = $basicAuthValue
}

Invoke-WebRequest -Uri 'https://api.fraudguard.io/v2/ip/12.167.53.202' -Headers $Headers

Example response:

{
    "isocode": "US",
    "country": "United States",
    "state_code": "CA",
    "state": "California",
    "city": "Pomona",
    "postal_code": "91768",
    "latitude": 34.0662,
    "longitude": -117.7763,
    "timezone": "America/Los_Angeles",
    "connection_type": "Corporate",
    "asn": 7018,
    "asn_organization": "AT&T Services, Inc.",
    "isp": "AT&T Services",
    "organization": "AT&T Services",
    "discover_date": "2018-12-13 03:03:15",
    "threat": "abuse_tracker",
    "risk_level": "4"
}

HTTP Request

GET https://api.fraudguard.io/v2/ip/<IP>

URL Parameters

Get Specific IP v2 Geographic, ISP and Organizational Lookup Only

Returns geography, ISP, and organization data for one IP without running a full reputation lookup. Use it when network context—not a security decision—is the only required output.

Response Fields

• isocode: The two-letter country code representing the country associated with the IP address. Example: "US" for the United States.

• country: The full name of the country where the IP address is located. Example: "United States".

• state_code: The abbreviated code for the state or region within the country. Example: "MN" for Minnesota.

• state: The full name of the state or region corresponding to the state_code. Example: "Minnesota".

• city: The city associated with the IP address. Example: "Winona".

• postal_code: The postal or ZIP code for the location. Example: "55987".

• latitude: The geographic latitude of the IP address's location. Example: 44.03.

• longitude: The geographic longitude of the IP address's location. Example: -91.7009.

• timezone: The time zone identifier for the location. Example: "America/Chicago".

• connection_type: The type of internet connection used. Possible values include: "Corporate", "Cable/DSL", "Mobile". Example: "Cable/DSL".

• asn: The Autonomous System Number associated with the IP address. Example: 14828.

• asn_organization: The organization that owns the ASN. Example: "Hiawatha Broadband Communications, Inc".

• isp: The Internet Service Provider providing connectivity for the IP address. Example: "Hiawatha Broadband Communications".

• organization: The specific organization associated with the IP address, which may differ from the ISP. Example: "Hiawatha Broadband Communications".

curl -X GET -u "username:password" "https://api.fraudguard.io/v2/ip/geolookup/23.235.13.99"

require 'net/http'
require 'net/https'

def get_ip(server,path,username,password)
http = Net::HTTP.new(server,443)
req = Net::HTTP::Get.new(path)
http.use_ssl = true
req.basic_auth username, password
response = http.request(req)
return response.body
end

puts get_ip('api.fraudguard.io','/v2/ip/geolookup/23.235.13.99','username','password')

import requests
from requests.auth import HTTPBasicAuth
ip=requests.get('https://api.fraudguard.io/v2/ip/geolookup/23.235.13.99', verify=True, auth=HTTPBasicAuth('username', 'password'))
print (ip.text)

var options = {
   host: 'api.fraudguard.io',
   port: 443,
   path: '/v2/ip/geolookup/23.235.13.99',
   headers: {
      'Authorization': 'Basic ' + new Buffer(username + ':' + password).toString('base64')
   }
};

request = https.get(options, function(res){
   var body = "";
   res.on('data', function(data) {
      body += data;
   });
   res.on('end', function() {
      console.log(body);
   })
   res.on('error', function(e) {
     console.log("Got error: " + e.message);
   });
    });

}

<?php
$login = 'username';
$password = 'password';
$url = 'https://api.fraudguard.io/v2/ip/geolookup/23.235.13.99';
$ch = curl_init();
curl_setopt($ch, CURLOPT_URL,$url);
curl_setopt($ch, CURLOPT_RETURNTRANSFER,1);
curl_setopt($ch, CURLOPT_HTTPAUTH, CURLAUTH_BASIC);
curl_setopt($ch, CURLOPT_USERPWD, "$login:$password");
$result = curl_exec($ch);
curl_close($ch);
echo $result;

$user = 'username'
$pass = 'password'
$pair = "$($user):$($pass)"
$encodedCreds = [System.Convert]::ToBase64String([System.Text.Encoding]::ASCII.GetBytes($pair))
$basicAuthValue = "Basic $encodedCreds"

$Headers = @{
    Authorization = $basicAuthValue
}

Invoke-WebRequest -Uri 'https://api.fraudguard.io/v2/ip/geolookup/23.235.13.99' -Headers $Headers

Example response:

{
    "isocode": "US",
    "country": "United States",
    "state_code": "MN",
    "state": "Minnesota",
    "city": "Winona",
    "postal_code": "55987",
    "latitude": 44.03,
    "longitude": -91.7009,
    "timezone": "America/Chicago",
    "connection_type": "Cable/DSL",
    "asn": 14828,
    "asn_organization": "Hiawatha Broadband Communications, Inc",
    "isp": "Hiawatha Broadband Communications",
    "organization": "Hiawatha Broadband Communications"
}

HTTP Request

GET https://api.fraudguard.io/v2/ip/geolookup/<IP>

URL Parameters

Get Specific Hostname Reputation v2

The Get Specific Hostname Reputation v2 API resolves the hostname to one IPv4 address and performs a standard reputation lookup for that address. It does not evaluate every A record or any AAAA record; resolve DNS in your application and submit each address separately when complete coverage matters.

This endpoint is useful for quickly evaluating the current IP reputation associated with a hostname at the time of the request.

Response Fields

• isocode: The two-letter country code representing the country associated with the IP address of the hostname. Example: "US" for the United States.

• country: The full name of the country where the IP address of the hostname is located. Example: "United States".

• state_code: The abbreviated code for the state or region within the country. Example: "MD" for Maryland.

• state: The full name of the state or region corresponding to the state_code. Example: "Maryland".

• city: The city associated with the IP address of the hostname. Example: "Chestertown".

• postal_code: The postal or ZIP code for the location. Example: "21620".

• latitude: The geographic latitude of the IP address's location. Example: 39.2125.

• longitude: The geographic longitude of the IP address's location. Example: -76.0802.

• timezone: The time zone identifier for the location. Example: "America/New_York".

• connection_type: The type of internet connection used. Possible values include: "Corporate", "Cable/DSL", "Mobile". Example: "Corporate".

• asn: The Autonomous System Number associated with the IP address. Example: 29802.

• asn_organization: The organization that owns the ASN. Example: "HIVELOCITY VENTURES CORP".

• isp: The Internet Service Provider providing connectivity for the IP address. Example: "NOC4Hosts".

• organization: The specific organization associated with the IP address, which may differ from the ISP. Example: "Hivelocity Ventures Corp".

• discover_date: The date and time when the hostname was first identified or reported for suspicious activity, formatted as "YYYY-MM-DD HH:MM:SS". Example: "2020-06-02 03:35:23".

• threat: The category of threat detected for the hostname, as determined by FraudGuard.io’s Attack Correlation Engine (ACE). This field highlights specific behaviors or associations flagged for the hostname:

  • "abuse_tracker": Indicates involvement in abusive activities, such as unauthorized access attempts or exploitation.
  • "honeypot_tracker": Associated with honeypot traps, suggesting the hostname has been caught in decoy systems designed to detect malicious behavior.
  • "botnet_tracker": Part of a botnet network, indicating the hostname is likely compromised and under the control of malicious actors.
  • "spam_tracker": Linked to spamming activities, including the distribution of unsolicited emails or messages.
  • "anonymous_tracker": Associated with anonymization services like proxies or TOR, which can be used to mask the true origin of traffic.
  • "vpn_tracker": Represents IP addresses associated with VPN servers, used primarily for anonymizing user traffic.
  • "unknown": No specific threat detected.

• risk_level: A numeric value representing the assessed threat level of the hostname, as determined by FraudGuard.io’s Attack Correlation Engine (ACE). The risk_level reflects not just the nature of malicious activities but also factors in time and recurrence:

  • Older incidents, especially from hostnames that have not repeated their behavior, may have a lower risk level due to the lack of recent activity.
  • Recurring offenders or hostnames flagged for multiple recent events are assigned a higher risk level. The scale typically ranges from 1 to 5, with higher numbers indicating greater risk:
  • Level 1 (Low Risk): Minimal or negligible threat. Likely a benign hostname with a clean reputation.
  • Level 2: Some indicators of suspicious behavior but not considered actively dangerous.
  • Level 3: Moderate risk with signs of suspicious or harmful activity.
  • Level 4: High risk with significant evidence of malicious behavior, often repeated or recent.
  • Level 5 (Critical Risk): Severe threats, actively engaged in malicious activities and requiring immediate attention. Example: 1 (indicating a low-risk hostname).

curl -X GET -u "username:password" "https://api.fraudguard.io/v2/hostname/fraudguard.io"

require 'net/http'
require 'net/https'

def get_hostname(server,path,username,password)
http = Net::HTTP.new(server,443)
req = Net::HTTP::Get.new(path)
http.use_ssl = true
req.basic_auth username, password
response = http.request(req)
return response.body
end

puts get_hostname('api.fraudguard.io','/v2/hostname/fraudguard.io','username','password')

import requests
from requests.auth import HTTPBasicAuth
hostname=requests.get('https://api.fraudguard.io/v2/hostname/fraudguard.io', verify=True, auth=HTTPBasicAuth('username', 'password'))
print (hostname.text)

var options = {
   host: 'api.fraudguard.io',
   port: 443,
   path: '/v2/hostname/fraudguard.io',
   headers: {
      'Authorization': 'Basic ' + new Buffer(username + ':' + password).toString('base64')
   }
};

request = https.get(options, function(res){
   var body = "";
   res.on('data', function(data) {
      body += data;
   });
   res.on('end', function() {
      console.log(body);
   })
   res.on('error', function(e) {
     console.log("Got error: " + e.message);
   });
    });

}

<?php
$login = 'username';
$password = 'password';
$url = 'https://api.fraudguard.io/v2/hostname/fraudguard.io';
$ch = curl_init();
curl_setopt($ch, CURLOPT_URL,$url);
curl_setopt($ch, CURLOPT_RETURNTRANSFER,1);
curl_setopt($ch, CURLOPT_HTTPAUTH, CURLAUTH_BASIC);
curl_setopt($ch, CURLOPT_USERPWD, "$login:$password");
$result = curl_exec($ch);
curl_close($ch);
echo $result;

$user = 'username'
$pass = 'password'
$pair = "$($user):$($pass)"
$encodedCreds = [System.Convert]::ToBase64String([System.Text.Encoding]::ASCII.GetBytes($pair))
$basicAuthValue = "Basic $encodedCreds"

$Headers = @{
    Authorization = $basicAuthValue
}

Invoke-WebRequest -Uri 'https://api.fraudguard.io/v2/hostname/fraudguard.io' -Headers $Headers

Example response:

{
  "isocode":"US",
  "country":"United States",
  "state_code":"MD",
  "state":"Maryland",
  "city":"Chestertown",
  "postal_code":"21620",
  "latitude":39.2125,
  "longitude":-76.0802,
  "timezone":"America/New_York",
  "connection_type":"Corporate",
  "asn":29802,
  "asn_organization":"HIVELOCITY VENTURES CORP",
  "isp":"NOC4Hosts",
  "organization":"Hivelocity Ventures Corp",
  "discover_date":"2020-06-02 03:35:23",
  "threat":"unknown",
  "risk_level":"1"
}

HTTP Request

GET https://api.fraudguard.io/v2/hostname/<hostname>

URL Parameters

Get Specific IP Reputation v3 by Threat

Returns the legacy v3 reputation schema for one IP, grouped by threat type. Use ACE v2 for new integrations.

Response Fields

• isocode: The two-letter country code representing the country associated with the IP address. Example: "NL" for the Netherlands.

• country: The full name of the country where the IP address is located. Example: "Netherlands".

• state_code: The abbreviated code for the state or region within the country. Example: "NH" for North Holland.

• state: The full name of the state or region corresponding to the state_code. Example: "North Holland".

• city: The city associated with the IP address. Example: "Amsterdam".

• postal_code: The postal or ZIP code for the location. Example: "1012".

• latitude: The geographic latitude of the IP address's location. Example: 52.3759.

• longitude: The geographic longitude of the IP address's location. Example: 4.8975.

• timezone: The time zone identifier for the location. Example: "Europe/Amsterdam".

• connection_type: The type of internet connection used. Possible values include: "Corporate", "Cable/DSL", "Mobile". Example: "Corporate".

• asn: The Autonomous System Number associated with the IP address. Example: 202425.

• asn_organization: The organization that owns the ASN. Example: "IP Volume inc".

• isp: The Internet Service Provider providing connectivity for the IP address. Example: "IP Volume inc".

• organization: The specific organization associated with the IP address, which may differ from the ISP. Example: "IP Volume inc".

  • anonymous_tracker: Indicates whether the IP address is associated with anonymization services like proxies or TOR.
  • listed: Boolean value (true or false) indicating if the IP is flagged.
  • discover_date: The date and time when this association was first identified, formatted as "YYYY-MM-DD HH:MM:SS". Example: "listed": false, "discover_date": "2024-04-23 01:49:38".

• vpn_tracker: Indicates whether the IP address is associated with anonymization services like VPNs.

  • listed: Boolean value (true or false) indicating if the IP is flagged.
  • discover_date: The date and time when this association was first identified, formatted as "YYYY-MM-DD HH:MM:SS". Example: "listed": false, "discover_date": "2024-04-23 01:49:38".

• botnet_tracker: Indicates whether the IP address is part of a botnet network.

  • listed: Boolean value indicating if the IP is flagged.
  • discover_date: The date and time when this association was first identified. Example: "listed": true, "discover_date": "2024-04-22 03:00:23".

• honeypot_tracker: Indicates whether the IP address has interacted with honeypot traps, suggesting malicious behavior.

  • listed: Boolean value indicating if the IP is flagged.
  • discover_date: The date and time when this association was first identified. Example: "listed": false, "discover_date": "2024-04-23 01:49:38".

• abuse_tracker: Indicates whether the IP address has been involved in abusive activities, such as unauthorized access attempts.

  • listed: Boolean value indicating if the IP is flagged.
  • discover_date: The date and time when this association was first identified. Example: "listed": false, "discover_date": "2024-04-23 01:49:38".

• spam_tracker: Indicates whether the IP address is linked to spamming activities, including the distribution of unsolicited emails.

  • listed: Boolean value indicating if the IP is flagged.
  • discover_date: The date and time when this association was first identified. Example: "listed": false, "discover_date": "2024-04-23 01:49:38".

curl -X GET -u "username:password" "https://api.fraudguard.io/v3/ip-all-threats/89.248.165.0"

require 'net/http'
require 'net/https'

def get_ip(server,path,username,password)
http = Net::HTTP.new(server,443)
req = Net::HTTP::Get.new(path)
http.use_ssl = true
req.basic_auth username, password
response = http.request(req)
return response.body
end

puts get_ip('api.fraudguard.io','/v3/ip-all-threats/89.248.165.0','username','password')

import requests
from requests.auth import HTTPBasicAuth
ip=requests.get('https://api.fraudguard.io/v3/ip-all-threats/89.248.165.0', verify=True, auth=HTTPBasicAuth('username', 'password'))
print (ip.text)

var options = {
   host: 'api.fraudguard.io',
   port: 443,
   path: '/v3/ip-all-threats/89.248.165.0',
   headers: {
      'Authorization': 'Basic ' + new Buffer(username + ':' + password).toString('base64')
   }
};

request = https.get(options, function(res){
   var body = "";
   res.on('data', function(data) {
      body += data;
   });
   res.on('end', function() {
      console.log(body);
   })
   res.on('error', function(e) {
     console.log("Got error: " + e.message);
   });
    });

}

<?php
$login = 'username';
$password = 'password';
$url = 'https://api.fraudguard.io/v3/ip-all-threats/89.248.165.0';
$ch = curl_init();
curl_setopt($ch, CURLOPT_URL,$url);
curl_setopt($ch, CURLOPT_RETURNTRANSFER,1);
curl_setopt($ch, CURLOPT_HTTPAUTH, CURLAUTH_BASIC);
curl_setopt($ch, CURLOPT_USERPWD, "$login:$password");
$result = curl_exec($ch);
curl_close($ch);
echo $result;

$user = 'username'
$pass = 'password'
$pair = "$($user):$($pass)"
$encodedCreds = [System.Convert]::ToBase64String([System.Text.Encoding]::ASCII.GetBytes($pair))
$basicAuthValue = "Basic $encodedCreds"

$Headers = @{
    Authorization = $basicAuthValue
}

Invoke-WebRequest -Uri 'https://api.fraudguard.io/v3/ip-all-threats/89.248.165.0' -Headers $Headers

Example response:

{
    "isocode": "NL",
    "country": "Netherlands",
    "state_code": "NH",
    "state": "North Holland",
    "city": "Amsterdam",
    "postal_code": "1012",
    "latitude": 52.3759,
    "longitude": 4.8975,
    "timezone": "Europe/Amsterdam",
    "connection_type": "Corporate",
    "asn": 202425,
    "asn_organization": "IP Volume inc",
    "isp": "IP Volume inc",
    "organization": "IP Volume inc",
    "anonymous_tracker": {
        "listed": false,
        "discover_date": "2024-04-23 01:49:38"
    },
    "botnet_tracker": {
        "listed": true,
        "discover_date": "2024-04-22 03:00:23"
    },
    "honeypot_tracker": {
        "listed": false,
        "discover_date": "2024-04-23 01:49:38"
    },
    "abuse_tracker": {
        "listed": false,
        "discover_date": "2024-04-23 01:49:38"
    },
    "spam_tracker": {
        "listed": false,
        "discover_date": "2024-04-23 01:49:38"
    }
}

HTTP Request

GET https://api.fraudguard.io/v3/ip-all-threats/<IP>

URL Parameters

Get Specific IP Reputation v4

Returns the legacy v4 reputation schema with account-specific blacklist and whitelist context. Use ACE v2 for new integrations.

Response Fields

• isocode: The two-letter country code representing the country associated with the IP address. Example: "RU" for Russia.

• country: The full name of the country where the IP address is located. Example: "Russia".

• state_code: The abbreviated code for the state or region within the country. Example: "STA" for Stavropol Kray.

• state: The full name of the state or region corresponding to the state_code. Example: "Stavropol Kray".

• city: The city associated with the IP address. Example: "Pyatigorsk".

• postal_code: The postal or ZIP code for the location. Example: "357500".

• latitude: The geographic latitude of the IP address's location. Example: 44.0562.

• longitude: The geographic longitude of the IP address's location. Example: 43.0707.

• timezone: The time zone identifier for the location. Example: "Europe/Moscow".

• connection_type: The type of internet connection used. Possible values include: "Corporate", "Cable/DSL", "Mobile". Example: "Cable/DSL".

• asn: The Autonomous System Number associated with the IP address. Example: 44963.

• asn_organization: The organization that owns the ASN. Example: "Stavtelecom LLC".

• isp: The Internet Service Provider providing connectivity for the IP address. Example: "Stavtelecom LLC".

• organization: The specific organization associated with the IP address, which may differ from the ISP. Example: "Stavtelecom LLC".

• discover_date: The date and time when the IP address was first identified or reported for suspicious activity, formatted as "YYYY-MM-DD HH:MM:SS". Example: "2024-11-12 23:37:45".

• threat: The category of threat detected for the IP address, as determined by FraudGuard.io’s Attack Correlation Engine (ACE). This field highlights specific behaviors or associations flagged for the IP:

  • "abuse_tracker": Indicates involvement in abusive activities, such as unauthorized access attempts or exploitation.
  • "honeypot_tracker": Associated with honeypot traps, suggesting the IP has been caught in decoy systems designed to detect malicious behavior.
  • "botnet_tracker": Part of a botnet network, indicating the IP is likely compromised and under the control of malicious actors.
  • "spam_tracker": Linked to spamming activities, including the distribution of unsolicited emails or messages.
  • "anonymous_tracker": Associated with anonymization services like proxies or TOR, which can be used to mask the true origin of traffic.
  • "vpn_tracker": Represents IP addresses associated with VPN servers, used primarily for anonymizing user traffic.
  • "unknown": No specific threat detected.

• risk_level: A numeric value representing the assessed threat level of the IP address, as determined by FraudGuard.io’s Attack Correlation Engine (ACE). The risk_level reflects not just the nature of malicious activities but also factors in time and recurrence:

  • Older incidents, especially from IPs that have not repeated their behavior, may have a lower risk level due to the lack of recent activity.
  • Recurring offenders or IPs flagged for multiple recent events are assigned a higher risk level. The scale typically ranges from 1 to 5, with higher numbers indicating greater risk:
  • Level 1 (Low Risk): Minimal or negligible threat. Likely a benign IP with a clean reputation.
  • Level 2: Some indicators of suspicious behavior but not considered actively dangerous.
  • Level 3: Moderate risk with signs of suspicious or harmful activity.
  • Level 4: High risk with significant evidence of malicious behavior, often repeated or recent.
  • Level 5 (Critical Risk): Severe threats, actively engaged in malicious activities and requiring immediate attention. Example: 3 (indicating a moderate-risk IP).

• ip_in_whitelist: Indicates whether the IP address is present in a custom whitelist. Example: "false".

• ip_in_blacklist: Indicates whether the IP address is present in a custom blacklist. Example: "true".

curl -X GET -u "username:password" "https://api.fraudguard.io/v4/ip/92.42.8.20"

require 'net/http'
require 'net/https'

def get_ip(server,path,username,password)
http = Net::HTTP.new(server,443)
req = Net::HTTP::Get.new(path)
http.use_ssl = true
req.basic_auth username, password
response = http.request(req)
return response.body
end

puts get_ip('api.fraudguard.io','/v4/ip/92.42.8.20','username','password')

import requests
from requests.auth import HTTPBasicAuth
ip=requests.get('https://api.fraudguard.io/v4/ip/92.42.8.20', verify=True, auth=HTTPBasicAuth('username', 'password'))
print (ip.text)

var options = {
   host: 'api.fraudguard.io',
   port: 443,
   path: '/v4/ip/92.42.8.20',
   headers: {
      'Authorization': 'Basic ' + new Buffer(username + ':' + password).toString('base64')
   }
};

request = https.get(options, function(res){
   var body = "";
   res.on('data', function(data) {
      body += data;
   });
   res.on('end', function() {
      console.log(body);
   })
   res.on('error', function(e) {
     console.log("Got error: " + e.message);
   });
    });

}

<?php
$login = 'username';
$password = 'password';
$url = 'https://api.fraudguard.io/v4/ip/92.42.8.20';
$ch = curl_init();
curl_setopt($ch, CURLOPT_URL,$url);
curl_setopt($ch, CURLOPT_RETURNTRANSFER,1);
curl_setopt($ch, CURLOPT_HTTPAUTH, CURLAUTH_BASIC);
curl_setopt($ch, CURLOPT_USERPWD, "$login:$password");
$result = curl_exec($ch);
curl_close($ch);
echo $result;

$user = 'username'
$pass = 'password'
$pair = "$($user):$($pass)"
$encodedCreds = [System.Convert]::ToBase64String([System.Text.Encoding]::ASCII.GetBytes($pair))
$basicAuthValue = "Basic $encodedCreds"

$Headers = @{
    Authorization = $basicAuthValue
}

Invoke-WebRequest -Uri 'https://api.fraudguard.io/v4/ip/92.42.8.20' -Headers $Headers

Example response:

{
    "isocode": "RU",
    "country": "Russia",
    "state_code": "STA",
    "state": "Stavropol Kray",
    "city": "Pyatigorsk",
    "postal_code": "357500",
    "latitude": 44.0562,
    "longitude": 43.0707,
    "timezone": "Europe/Moscow",
    "connection_type": "Cable/DSL",
    "asn": 44963,
    "asn_organization": "Stavtelecom LLC",
    "isp": "Stavtelecom LLC",
    "organization": "Stavtelecom LLC",
    "discover_date": "2024-11-12 23:37:45",
    "threat": "anonymous_tracker",
    "risk_level": "3",
    "ip_in_whitelist": "false",
    "ip_in_blacklist": "true"
}

HTTP Request

GET https://api.fraudguard.io/v4/ip/<IP>

URL Parameters

Get Specific IP Reputation v5

Returns the legacy v5 reputation schema with account-specific blacklist, whitelist, and geoblock context. Use ACE v2 for new integrations.

Response Fields

• isocode: The two-letter country code representing the country associated with the IP address. Example: "VN" for Vietnam.

• country: The full name of the country where the IP address is located. Example: "Vietnam".

• state_code: The abbreviated code for the state or region within the country. Example: "HN" for Hanoi.

• state: The full name of the state or region corresponding to the state_code. Example: "Hanoi".

• city: The city associated with the IP address. Example: "Hanoi".

• postal_code: The postal or ZIP code for the location. Example: "unknown".

• latitude: The geographic latitude of the IP address's location. Example: 21.0292.

• longitude: The geographic longitude of the IP address's location. Example: 105.8526.

• timezone: The time zone identifier for the location. Example: "Asia/Bangkok".

• connection_type: The type of internet connection used. Possible values include: "Corporate", "Cable/DSL", "Mobile". Example: "Cable/DSL".

• asn: The Autonomous System Number associated with the IP address. Example: 18403.

• asn_organization: The organization that owns the ASN. Example: "The Corporation for Financing & Promoting Technology".

• isp: The Internet Service Provider providing connectivity for the IP address. Example: "FPT Telecom".

• organization: The specific organization associated with the IP address, which may differ from the ISP. Example: "FPT Telecom".

• ip_in_whitelist: Indicates whether the IP address is present in a custom whitelist. Example: "false".

• ip_in_blacklist: Indicates whether the IP address is present in a custom blacklist. Example: "true".

• ip_in_geoblock: Indicates whether the IP address is blocked based on its geographic location. Example: "true".

• discover_date: The date and time when the IP address was first identified or reported for suspicious activity, formatted as "YYYY-MM-DD HH:MM:SS". Example: "2024-11-13 04:00:08".

• threat: The category of threat detected for the IP address, as determined by FraudGuard.io’s Attack Correlation Engine (ACE). This field highlights specific behaviors or associations flagged for the IP:

  • "abuse_tracker": Indicates involvement in abusive activities, such as unauthorized access attempts or exploitation.
  • "honeypot_tracker": Associated with honeypot traps, suggesting the IP has been caught in decoy systems designed to detect malicious behavior.
  • "botnet_tracker": Part of a botnet network, indicating the IP is likely compromised and under the control of malicious actors.
  • "spam_tracker": Linked to spamming activities, including the distribution of unsolicited emails or messages.
  • "anonymous_tracker": Associated with anonymization services like proxies or TOR, which can be used to mask the true origin of traffic.
  • "vpn_tracker": Represents IP addresses associated with VPN servers, used primarily for anonymizing user traffic.
  • "unknown": No specific threat detected.

• risk_level: A numeric value representing the assessed threat level of the IP address, as determined by FraudGuard.io’s Attack Correlation Engine (ACE). The risk_level reflects not just the nature of malicious activities but also factors in time and recurrence:

  • Older incidents, especially from IPs that have not repeated their behavior, may have a lower risk level due to the lack of recent activity.
  • Recurring offenders or IPs flagged for multiple recent events are assigned a higher risk level. The scale typically ranges from 1 to 5, with higher numbers indicating greater risk:
  • Level 1 (Low Risk): Minimal or negligible threat. Likely a benign IP with a clean reputation.
  • Level 2: Some indicators of suspicious behavior but not considered actively dangerous.
  • Level 3: Moderate risk with signs of suspicious or harmful activity.
  • Level 4: High risk with significant evidence of malicious behavior, often repeated or recent.
  • Level 5 (Critical Risk): Severe threats, actively engaged in malicious activities and requiring immediate attention. Example: 5 (indicating a critical-risk IP).

curl -X GET -u "username:password" "https://api.fraudguard.io/v5/ip/1.52.122.126"

require 'net/http'
require 'net/https'

def get_ip(server,path,username,password)
http = Net::HTTP.new(server,443)
req = Net::HTTP::Get.new(path)
http.use_ssl = true
req.basic_auth username, password
response = http.request(req)
return response.body
end

puts get_ip('api.fraudguard.io','/v5/ip/1.52.122.126','username','password')

import requests
from requests.auth import HTTPBasicAuth
ip=requests.get('https://api.fraudguard.io/v5/ip/1.52.122.126', verify=True, auth=HTTPBasicAuth('username', 'password'))
print (ip.text)