IP Reputation API

Security teams need a fast, consistent way to check whether an IP address has a recent history of abuse before letting it touch login flows, payment endpoints, or admin tools. By the end of this guide, you’ll be able to call a dedicated IP reputation endpoint, parse the response fields that matter, and wire the results into allow/deny, step-up authentication, or manual review decisions.

What the IP reputation check does and when to use it

The IP reputation lookup returns concise signals about whether an address has been reported for abusive behavior. It’s designed for inline security decisions where milliseconds matter and the outcome has to be deterministic. Common integrations include:

• Login protection: deny or challenge logins from IPs with a recent abuse history.
• Signup hardening: gate account creation from risky network sources.
• Payment flows: add step-up verification if a card attempt originates from a reported IP.
• Admin and internal tools: block direct access from known-bad hosts.

All examples below use Authorization: Bearer YOUR_KEY, the documented abuse-check path, and the fixture IP for demonstration. Treat the fixture as an example only; live checks will differ per IP.

Endpoint, method, and authentication

The abuse reputation check is a simple GET request with a single query parameter:

• Method: GET
• Path: /api/abuse-check
• Query parameter: ip (IPv4 or IPv6 string)
• Auth: HTTP header Authorization: Bearer YOUR_KEY
• Accept: application/json

Pricing: the Basic plan is $29.99/mo. A trial is available for 7 days or 50 requests. For limits, field definitions, and service behavior, see the Documentation. To get an API key, Register.

Official cURL and JSON example

Below is the official, copy-pasteable request and response using the documented fixture IP 8.8.8.8. This is a product fixture for demonstration; live values will change over time.

curl "https://ipxapi.com/api/abuse-check?ip=8.8.8.8" -H "Accept: application/json" -H "Authorization: Bearer YOUR_KEY"

{
"ip": "8.8.8.8",
"is_listed": false,
"confidence_of_abuse": 0,
"total_reports": 14,
"distinct_reporters": 8,
"first_reported_at": "2026-01-15",
"last_reported_at": "2026-01-22",
"is_whitelisted": true,
"isp": "Google LLC",
"hostname": "dns.google"
}

How to read these fields for security decisions:

• ip: the address you requested.
• is_listed: boolean indicator of whether the IP currently appears on an abuse list.
• confidence_of_abuse: an integer score (range defined in docs) indicating the confidence that the IP is abusive. Use thresholds appropriate to your risk tolerance.
• total_reports and distinct_reporters: volume and uniqueness of reports. High counts can justify stronger friction.
• first_reported_at and last_reported_at: date-only ISO 8601 timestamps (YYYY-MM-DD). Useful for recency windows.
• is_whitelisted: boolean signal for special handling paths.
• isp and hostname: network context that can feed allowlists, audit logs, and analytics.

Fast integration checklist

1. Obtain your API key from the Register flow.
2. Build a GET request to /api/abuse-check with the ip query parameter and Bearer auth.
3. Parse is_listed, confidence_of_abuse, total_reports, distinct_reporters, and last_reported_at.
4. Implement a decision function: allow, step-up (e.g., MFA, CAPTCHA), or deny.
5. Log ip, decision, and key fields to your security data lake or SIEM.

JavaScript example: request, parse, and act

This snippet calls the same endpoint as the cURL above, reads the critical fields, and shows a minimal decision function. Replace targetIp with the value you want to evaluate at runtime.

async function checkIpReputation(targetIp) {
const url = `https://ipxapi.com/api/abuse-check?ip=${encodeURIComponent(targetIp)}`;
const res = await fetch(url, {
method: 'GET',
headers: {
'Accept': 'application/json',
'Authorization': 'Bearer YOUR_KEY'
}
});

// Handle non-JSON or unexpected responses gracefully
const text = await res.text();
let data;
try {
data = JSON.parse(text);
} catch (e) {
throw new Error(`Unexpected response format: ${text.slice(0, 200)}`);
}

// Extract the fields you will actually use
const {
ip,
is_listed,
confidence_of_abuse,
total_reports,
distinct_reporters,
first_reported_at,
last_reported_at,
is_whitelisted,
isp,
hostname
} = data;

// Minimal decision logic (tune thresholds in your environment)
// Use both a boolean list flag and a score-based threshold.
const deny =
is_listed === true ||
(typeof confidence_of_abuse === 'number' && confidence_of_abuse >= 80);

const stepUp =
!deny && (
(typeof confidence_of_abuse === 'number' && confidence_of_abuse >= 30) ||
(typeof total_reports === 'number' && total_reports >= 5) ||
(typeof distinct_reporters === 'number' && distinct_reporters >= 3)
);

const decision = deny ? 'deny' : (stepUp ? 'step-up' : 'allow');

// Return a compact object for your auth gateway / risk engine
return {
decision,
ip,
is_listed,
confidence_of_abuse,
total_reports,
distinct_reporters,
first_reported_at,
last_reported_at,
is_whitelisted,
isp,
hostname
};
}

// Example usage:
// checkIpReputation('8.8.8.8').then(console.log).catch(console.error);

Decision design: combining reputation with your controls

Keep the decision logic separate from the network call so it can evolve without redeploying gateway components. A common approach is to define three tiers per environment:

• Allow: no friction. Log a compact record including ip, is_listed, and confidence_of_abuse.
• Step-up: trigger CAPTCHA, email link, WebAuthn, or MFA only for higher-risk interactions.
• Deny: block clearly abusive origins outright for critical actions.

If you maintain an allowlist for operational vendors or monitoring services, check is_whitelisted to bypass friction when appropriate. Log these bypasses for audit.

Interpreting timestamps, caching, and stability

Timestamps first_reported_at and last_reported_at are date-only ISO 8601 strings (YYYY-MM-DD). When you apply recency windows (e.g., deny if last_reported_at is within N days), compute against UTC and store normalized dates to avoid timezone skew in your logs.

Reputation changes over time. To avoid repetitive remote calls in hot paths, cache results locally for a short period that matches your risk tolerance. If you cache, include is_listed, confidence_of_abuse, and last_reported_at in the cache key or metadata so you can invalidate entries when your thresholds change. Always respect the fact that live flags can change; do not treat the fixture response as your own IP or as a static truth.

Operational tips for secure rollouts

• Least-privilege secrets: store YOUR_KEY in a vault and inject it via runtime env variables.
• Timeouts and fallbacks: if the call fails, choose a safe default. Many teams apply step-up instead of deny on transient failures.
• Observability: log the request duration and decision outcome. Redact the token.
• Idempotence: for multi-attempt flows (e.g., retries), reuse the reputation result within a short window to limit duplicate checks.
• Change management: roll out new thresholds gradually and monitor false-positive rates.

Testing with the managed control plane

If you need to validate connectivity and surface-level availability outside of your application network, you can reference the dedicated control-plane host: MCP. Use it for environment checks alongside your standard monitoring. For all production lookups, call the abuse-check endpoint described above.

Security policy patterns: where to insert the check

Insert the reputation lookup in places where a single IP can influence high-risk outcomes:

• Before authentication: evaluate at the start of the login flow to save compute on known-bad origins.
• Risk-scored actions: run checks before password reset, 2FA reset, payment submission, or API key creation.
• Edge enforcement: in CDNs or API gateways that can cache benign results briefly and short-circuit abusive requests.

Minimize user friction by applying step-up challenges only where the confidence_of_abuse or report counts justify it. Record both the raw values and your final decision so incident responders can retrace the path that led to a deny or a challenge.

Error handling without leaking signals

Do not relay raw upstream error details to clients. On failure to retrieve a reputation response, log the event internally with context, then apply a conservative default. Avoid exposing whether an IP is “under review” or “blocked by reputation” in public messaging; return neutral error text to prevent reputation probing.

Rollout guide: from dry run to enforcement

1. Dry run: call the endpoint and log recommended decisions without enforcing them for 1–2 weeks.
2. Analyze logs: segment by product surface and country, and review deny/step-up rates.
3. Tune thresholds: adjust by action sensitivity (e.g., stricter for password reset, lighter for newsletter signup).
4. Progressive enforcement: enable step-up first, then block on the highest-confidence tier.
5. Periodic review: reassess thresholds each release cycle based on false-positive feedback.

Security data model: what to store

For incident response and anomaly detection, persist a compact record with these fields per evaluated event:

• ip (string)
• is_listed (boolean)
• confidence_of_abuse (number)
• total_reports, distinct_reporters (numbers)
• first_reported_at, last_reported_at (dates)
• decision (allow, step-up, deny)
• isp, hostname (strings for context)

Index ip and last_reported_at for fast queries during investigations, and set retention according to your security policy and regulatory obligations.

Frequently asked questions

How do I authenticate requests?
Send Authorization: Bearer YOUR_KEY and Accept: application/json on every request.

What endpoint do I call?
Use GET /api/abuse-check with the ip query parameter. The example in this guide uses the documented fixture IP 8.8.8.8.

Can I use this for inline decisions?
Yes. Parse is_listed, confidence_of_abuse, total_reports, distinct_reporters, and last_reported_at to drive allow, step-up, or deny policies.

What do the timestamps represent?
first_reported_at and last_reported_at are date-only ISO 8601 values. Treat them as UTC-aligned dates in your policy logic and storage.

Is there a trial?
Yes, the trial is 7 days or 50 requests. For plan details beyond the Basic $29.99/mo summary here, see the Documentation.

Get started

Provision your key and ship a guarded integration in minutes. Create an account now at Register, then use the cURL and JavaScript samples above to plug the abuse-check into your auth, payments, and admin surfaces.