IP Reputation

Returns only the threat indicators for an IP address: proxy, VPN, Tor, bot, relay, hosting and blacklist status.

Overview#

lookup/ip/threats is the lightweight way to ask "is this address risky?". Unlike IP Lookup it skips geography, timezone and currency and returns just the ip and a threats object. That makes responses small and fast, which suits checks in the hot path of a login or checkout.

When to use it#

• A quick pass/fail screen before creating an account or starting a payment.
• Decisions that only depend on anonymization and automation signals.
• High-volume pipelines where location data is unnecessary.

Reading the result#

• threats.isProxy indicates anonymizing infrastructure and threats.proxyType names the kind. Many legitimate users use VPNs, so prefer a step-up check (a one-time code, for example) over an outright block.
• threats.isHosting suggests the traffic comes from a data center rather than a person. Together with threats.isBot it is a good reason to challenge or deny.
• threats.isTor marks exit nodes of the Tor network; threats.isRelay marks privacy relays, which are usually benign but hide the real location.
• threats.blacklisted is true when the address matches your own blacklists, and threats.custom_rules_applied lists the custom rules that fired.

A practical policy: allow when everything is false, step up when only isProxy or isRelay is true, and block or review when isTor, isBot or isHosting is combined with another risk signal.

Notes#

• Counts as one request. Test mode returns fake data, is free and raises no events.
• Included in every plan.
• Custom rules in the IP reputation group can test the proxy type, each flag and the country, and can blacklist or whitelist the address.
• A suspicious_ip event is raised when the risk reaches 50 out of 100 and goes to your webhooks.
• A missing or invalid address returns error 112 (invalid_ip) with HTTP 200.

Request#

• Authenticate with the key parameter or an Authorization: Bearer header.
• Counts as 1 request.
• Available on: Free trial Standard Premium Pay-as-you-go

Parameters#

Every method also accepts format, lang, mode, userID, callback. See Options.

Code samples#

curl -G "https://gurdx.cretip.com/api/lookup/ip/threats" \
  --data-urlencode "key=YOUR_API_KEY" \
  --data-urlencode "ip=1.1.1.1"

<?php

$response = file_get_contents('https://gurdx.cretip.com/api/lookup/ip/threats?'.http_build_query(['key' => 'YOUR_API_KEY', 'ip' => '1.1.1.1']));
$result = json_decode($response, true);

if ($result['status'] === 'success') {
    print_r($result['data']);
} else {
    echo $result['code'].': '.$result['description'];
}

const params = new URLSearchParams({"key":"YOUR_API_KEY","ip":"1.1.1.1"});
const res = await fetch(`https://gurdx.cretip.com/api/lookup/ip/threats?${params}`);
const result = await res.json();

if (result.status === 'success') {
  console.log(result.data);
} else {
  console.error(result.code, result.description);
}

import requests

res = requests.get("https://gurdx.cretip.com/api/lookup/ip/threats", params={"key": "YOUR_API_KEY", "ip": "1.1.1.1"})
result = res.json()

if result["status"] == "success":
    print(result["data"])
else:
    print(result["code"], result["description"])

Response#

Success#

{
    "status": "success",
    "data": {
        "ip": "12.12.12.12",
        "threats": {
            "isProxy": true,
            "proxyType": "Socks",
            "isTor": false,
            "isBot": false,
            "isRelay": false,
            "isHosting": true,
            "blacklisted": false
        },
        "custom_rules_applied": {
            "total": 0,
            "rules": []
        }
    },
    "executionTime": 90
}

Error#

Errors are delivered with HTTP 200 — always check the status field.

{
    "status": "error",
    "code": 101,
    "type": "invalid_key",
    "description": "The API Key is missing or invalid."
}

Response fields#