i p X a p i
Get Free API Key
Home
Blog
IP Blacklist API

IP Blacklist API

IP Blacklist API

Security teams and fraud engineers need a fast, deterministic way to decide whether an IP address has been reported to email, DNSBL, or abuse blacklists before allowing logins, sign-ups, or sensitive actions. By the end of this post you will be able to call a production IP blacklist endpoint, parse the response fields that drive access control, and ship a minimal decisioning layer that scales to your traffic without guessing fields or inventing data.

What the IP blacklist check does in a security workflow

The IP blacklist check returns whether a given IP is listed on any monitored blacklists. You can plug this into an allow/deny or step-up authentication flow at the edge, gateway, or application layer. Common outcomes:

Illustration: IP Blacklist API
  • is_listed = false: continue with normal risk checks.
  • is_listed = true and listed_count > 0: throttle, block, or force MFA before allowing sensitive actions.
  • timeout_count > 0: treat as indeterminate; combine with other telemetry (device fingerprint, velocity) or retry asynchronously.

This post focuses strictly on security use cases. We will not cover unrelated categories like marketing or analytics. All examples use the documented path and the fixture IP so you can copy and paste without surprises.

Endpoint, method, and authentication

Endpoint path and method:

  • HTTP method: GET
  • Path: /api/blacklist-check
  • Query parameter: ip (IPv4 or IPv6)

Base access:

  • Primary API base: https://ipxapi.com
  • Management control plane: MCP (for account-level controls and monitoring)

Authorization:

  • Header: Authorization: Bearer YOUR_API_KEY
  • Accept: application/json

Plans and access:

Run your first blacklist check (curl)

The following is the official, copy-pasteable curl and JSON fixture for the documented IP. Live flags can change; do not treat this as your current IP.

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

Official product-fixture JSON response for 8.8.8.8:

{
"ip": "8.8.8.8",
"is_listed": false,
"checked_blacklists": 100,
"listed_count": 0,
"ok_count": 100,
"timeout_count": 0,
"listed_blacklists": [],
"timeouts": []
}

Field usage in security decisions:

  • ip: The IP address that was checked.
  • is_listed: Boolean indicator to drive block/allow or step-up logic.
  • checked_blacklists: Total lists queried; helpful for completeness checks and monitoring.
  • listed_count: Number of lists that flagged the IP; use for severity tiers.
  • ok_count: Number of lists that responded and did not list the IP.
  • timeout_count: Number of list queries that timed out; treat >0 as partial coverage.
  • listed_blacklists: Array of blacklist names (empty in the fixture) for audit trails and analyst review.
  • timeouts: Array of list names that did not respond within the timeout budget.

Use the same endpoint from JavaScript

This minimal example shows how to query the endpoint, handle timeouts in the response, and transform the result into a structured decision. Replace YOUR_API_KEY with your token.

async function checkIpBlacklist(ip) {
const url = `https://ipxapi.com/api/blacklist-check?ip=${encodeURIComponent(ip)}`;
const res = await fetch(url, {
method: 'GET',
headers: {
'Accept': 'application/json',
'Authorization': 'Bearer YOUR_API_KEY'
},
// Keep the network timeout in your client modest; server-side timeouts are reflected in timeout_count.
});

if (!res.ok) {
// Do not map transport errors to "not listed".
throw new Error(`HTTP ${res.status}: ${await res.text()}`);
}

const data = await res.json();

// Derive a decision with minimal branching.
// Use timeout_count to mark results as partial when needed.
const decision = (() => {
if (data.is_listed === true) return 'deny_or_challenge';
if (data.timeout_count > 0) return 'indeterminate_retry_or_riskblend';
return 'allow';
})();

return {
decision,
evidence: {
ip: data.ip,
is_listed: data.is_listed,
listed_count: data.listed_count,
checked_blacklists: data.checked_blacklists,
ok_count: data.ok_count,
timeout_count: data.timeout_count,
listed_blacklists: data.listed_blacklists,
timeouts: data.timeouts
}
};
}

// Example usage:
checkIpBlacklist('8.8.8.8')
.then(result => {
console.log('Decision:', result.decision);
console.log('Evidence:', result.evidence);
})
.catch(err => {
console.error('Blacklist check failed:', err);
});

Interpreting responses and building decisions

Security decisions should be deterministic, documented, and debuggable. Start with a simple state machine based on the fields provided by the API:

  • Allow: is_listed = false AND timeout_count = 0
  • Allow with logging: is_listed = false AND timeout_count > 0
  • Step-up challenge: is_listed = true AND listed_count = 1
  • Deny or hard challenge: is_listed = true AND listed_count >= 2

Do not infer geo, ASN, or reputation scores from this endpoint. Only use the documented fields. If you need to combine with other signals (e.g., VPN detection), orchestrate that on your side and keep each integration isolated.

Repeatable, complete JSON examples you can test with

The following blocks are the same official fixture repeated so you can plug them into unit tests and parsers without inventing fields or values. They preserve the exact keys and structure and are safe for snapshot tests.

{
"ip": "8.8.8.8",
"is_listed": false,
"checked_blacklists": 100,
"listed_count": 0,
"ok_count": 100,
"timeout_count": 0,
"listed_blacklists": [],
"timeouts": []
}
{
"ip": "8.8.8.8",
"is_listed": false,
"checked_blacklists": 100,
"listed_count": 0,
"ok_count": 100,
"timeout_count": 0,
"listed_blacklists": [],
"timeouts": []
}
{
"ip": "8.8.8.8",
"is_listed": false,
"checked_blacklists": 100,
"listed_count": 0,
"ok_count": 100,
"timeout_count": 0,
"listed_blacklists": [],
"timeouts": []
}

Because live flags can change over time, treat these as product fixtures. Do not cache them as a permanent, real-world status for any IP. They are useful for schema validation, client integration tests, and edge configuration deployment checks.

Integration details that save time in production

Idempotent checks and deduplication

Calls to the blacklist-check endpoint are idempotent with the same ip parameter. In high-throughput gateways, coalesce duplicate checks for the same IP within a short time window using an in-memory key like ipxapi:blacklist:8.8.8.8 with a TTL (e.g., 300 seconds) to minimize fan-out and cost.

Client-side timeouts vs. timeout_count

timeout_count is returned by the service to indicate upstream list timeouts during the aggregation step. Your client network timeout should be set independently. If your client times out the HTTP call, you will not receive timeout_count and should treat the check as indeterminate and retry via a queue or background worker.

Caching and TTLs

Blacklist states can change. Use a short TTL (e.g., 5–15 minutes) for negative results (not listed) and consider a slightly longer TTL (e.g., 30–60 minutes) for positive results to minimize repeated risk events. Always refresh on suspicious behavior even within TTL windows. Do not hardcode a permanent status for any IP based on a single response.

Bulk processing pattern

For bursty sign-up or login waves, rate-limit calls per source IP at your edge, queue the blacklist tasks, and short-circuit to allow if a recent cached result with timeout_count = 0 exists. If timeout_count > 0, allow with step-up and schedule a retry. Avoid parallel duplicate checks for the same IP in the same second by using a lock or singleflight pattern.

Auditability

Persist the response subset you actually use for decisions: ip, is_listed, listed_count, timeout_count, and listed_blacklists (if present). Store a decision outcome, a rule version, and a timestamp alongside the raw fields for post-incident review.

Error handling

  • HTTP non-2xx: Do not assume not listed. Mark as indeterminate and apply your fallback policy (e.g., step-up challenge and retry).
  • JSON parse errors: Alert and quarantine the path; do not silently pass traffic as safe.
  • Partial results: timeout_count > 0 means only some lists responded; consider blending with additional signals.

Embedding the check in real security controls

Practical placements and what to log:

  • Reverse proxy or API gateway: Run the check before routing. Add headers like X-Blacklist-Listed: true|false and X-Blacklist-Count: N for downstream services.
  • Authentication: On password or OAuth token issuance, require MFA if is_listed = true or timeout_count > 0.
  • Abuse prevention: Block account creation when listed_count >= 1 and list namespace matches your high-severity list allowlist.
  • Mail pipeline: Defer or reject messages for listed senders; store listed_blacklists for deliverability analysts.

Security teams should keep the decision logic minimal, defensive, and well-commented. Tie each branch to a ticket or runbook entry so responses are repeatable and auditable.

Observability: metrics, logs, and alerts

Track the following metrics per minute and per route:

  • ipxapi.blacklist.requests: count of calls by outcome (2xx/4xx/5xx).
  • ipxapi.blacklist.is_listed_true: gauge or count to detect spikes in malicious sources.
  • ipxapi.blacklist.timeout_count_sum and rate: rising timeouts may indicate upstream issues or network trouble.
  • ipxapi.blacklist.latency_ms: client-observed latency by percentile.

In logs, include the correlation ID from your edge, the target IP, is_listed, listed_count, and timeout_count. Redact Authorization headers. Rotate and retain logs according to your security policy.

Operational runbook steps

When is_listed increases suddenly or timeout_count spikes:

  • Fail-open vs. fail-closed: Choose based on route criticality. For authentication, prefer fail-open with step-up. For admin endpoints, prefer fail-closed with manual override.
  • Toggle cache TTLs: Shorten for noisy traffic sources; lengthen for known benign segments during incidents.
  • Use the MCP to review account status and usage graphs, and validate that requests are succeeding across regions.

Compliance and data handling

Given that IP addresses may be considered personal data in some jurisdictions, ensure you have a lawful basis for processing. Apply your retention limits and data minimization principles: store only the fields you actually use for enforcement and audits.

Reference fixture for testing your parser

Use this official product-fixture JSON when writing schema validation tests or demonstrating results in your internal documentation. It exactly matches the schema referenced earlier.

{
"ip": "8.8.8.8",
"is_listed": false,
"checked_blacklists": 100,
"listed_count": 0,
"ok_count": 100,
"timeout_count": 0,
"listed_blacklists": [],
"timeouts": []
}

FAQ

Does the endpoint support both IPv4 and IPv6?
The ip parameter accepts an IP address. If you receive a 2xx with JSON, parse it normally. If you receive a non-2xx, handle it as an error and do not assume the IP is safe.

How should I handle timeout_count > 0?
Treat the result as partial. Blend with other risk signals, add step-up friction, and schedule a retry. Do not downgrade to “not listed.”

Can I cache results?
Yes. Use short TTLs and refresh on suspicious behavior. Never cache indefinitely. Store only the fields required for your decision and audits.

What authentication is required?
Use the Authorization: Bearer YOUR_API_KEY header and Accept: application/json. Do not send query string keys for auth unless your internal policy requires a proxy.

How do I get started and see the field definitions?
Create an account via Register and review the Documentation for parameters and response fields.

Next steps

Set up your API key, run the provided curl against the fixture IP to validate connectivity, then wire the JavaScript sample into your gateway or auth service. When you are ready, create your account at Register and keep the Documentation open while you integrate. For account controls and visibility, use the MCP.

Ready to use IpXapi?

Search

Recent Posts