Getting started overview

Integrating with AbuseIPDB allows developers to programmatically check the reputation of IP addresses and report malicious activity. This guide focuses on the essential steps to get the API operational: account creation, API key generation, and executing a foundational request.

The AbuseIPDB API is a RESTful service, primarily communicating over HTTPS. Requests are typically made with standard HTTP methods (GET, POST) and responses are returned in JSON format. Authentication relies on an API key included in the request headers.

Here’s a quick reference for the setup process:

Step What to do Where
1. Sign up Create an AbuseIPDB account. AbuseIPDB registration page
2. Get API Key Generate your unique API key from the account dashboard. AbuseIPDB API page in dashboard
3. Make Request Use the API key to make an authenticated HTTP request. Your preferred development environment
4. Parse Response Process the JSON response from the API. Your application logic

Create an account and get keys

To begin using the AbuseIPDB API, you need an account and an associated API key. This key authenticates your requests and links them to your usage allowance.

1. Create an AbuseIPDB Account

Navigate to the official AbuseIPDB registration page. Provide the required information, typically an email address and a password, to create your account. Account creation is free and provides access to the free tier, which includes 5,000 requests per month.

2. Generate Your API Key

After successfully registering and logging in, go to your account dashboard. Locate the API section within your AbuseIPDB account settings. Here, you will find an option to generate a new API key. It's crucial to treat this key as sensitive information, similar to a password, as it grants access to your API quota.

API keys are typically long, alphanumeric strings. Once generated, copy your API key and store it securely. You will include this key in the headers of your API requests for authentication.

Your first request

With your API key in hand, you can make your first API call to check an IP address. The primary endpoint for checking an IP address is /api/v2/check. This example uses curl, a common command-line tool for making HTTP requests, and Python, leveraging the requests library.

Using cURL

The curl command below demonstrates how to query the /check endpoint. Replace YOUR_API_KEY with your actual API key and 1.2.3.4 with the IP address you wish to check. The Key header is used for authentication, and the Accept header specifies JSON as the desired response format.


curl -G https://api.abuseipdb.com/api/v2/check \
  --data-urlencode "ipAddress=1.2.3.4" \
  -d maxAgeInDays=90 \
  -H "Key: YOUR_API_KEY" \
  -H "Accept: application/json"

This command queries the reputation of 1.2.3.4, considering reports up to 90 days old. The response will be a JSON object containing details about the IP address, including its abuse score, country code, and any associated reports.

Using Python

For Python developers, the requests library simplifies HTTP interactions. Ensure you have it installed (pip install requests).


import requests

API_KEY = "YOUR_API_KEY"
IP_ADDRESS = "1.2.3.4"

url = "https://api.abuseipdb.com/api/v2/check"

headers = {
    'Accept': 'application/json',
    'Key': API_KEY
}

params = {
    'ipAddress': IP_ADDRESS,
    'maxAgeInDays': '90'
}

response = requests.get(url, headers=headers, params=params)

if response.status_code == 200:
    data = response.json()
    print(data)
else:
    print(f"Error: {response.status_code} - {response.text}")

This Python script performs the same check as the curl example. It constructs the necessary headers and parameters, then sends a GET request. The response is parsed as JSON and printed to the console.

Expected Response Structure

A successful response (HTTP status 200) will typically return a JSON object similar to this (truncated for brevity):


{
    "data": {
        "ipAddress": "1.2.3.4",
        "isPublic": true,
        "abuseConfidenceScore": 100,
        "countryCode": "US",
        "usageType": "Data Center/Web Hosting/Transit",
        "isp": "Example ISP",
        "domain": "example.com",
        "hostnames": [],
        "totalReports": 1234,
        "numDistinctUsers": 567,
        "lastReportedAt": "2026-05-28T10:30:00+00:00"
    }
}

The abuseConfidenceScore is a key indicator, ranging from 0 (no reports) to 100 (high confidence of malicious activity). The totalReports and numDistinctUsers fields provide additional context on the reporting volume.

Common next steps

After successfully making your first request, consider these common next steps to further integrate AbuseIPDB:

  • Explore other endpoints: The AbuseIPDB API reference details other endpoints, such as /report for submitting new abuse reports, /blacklist for retrieving a list of reported IPs, and /check-block for checking an entire CIDR block.
  • Implement error handling: Integrate robust error handling for various HTTP status codes (e.g., 400 for bad requests, 401 for unauthorized, 429 for rate limiting) to make your application resilient.
  • Manage rate limits: Understand and implement strategies to handle API rate limits. AbuseIPDB clearly defines rate limits based on your subscription tier. Consider using exponential backoff for retries.
  • Secure your API key: Avoid hardcoding your API key directly in your application code. Use environment variables or a secure configuration management system. According to the AWS documentation on access key best practices, storing credentials securely is a fundamental security measure.
  • Integrate with security tools: Consider integrating AbuseIPDB data into existing security information and event management (SIEM) systems, firewalls, or intrusion detection systems to automate threat response.
  • Upgrade your plan: If your usage exceeds the free tier, review the AbuseIPDB pricing page and upgrade to a paid plan to accommodate higher request volumes. Paid plans start at $15/month for 250,000 requests.

Troubleshooting the first call

Encountering issues during your first API call is common. Here are some troubleshooting tips:

  • Check API Key: Double-check that your API key is correct and included in the Key header. An incorrect or missing key will result in a 401 Unauthorized error.
  • Verify IP Address Format: Ensure the ipAddress parameter is a valid IPv4 or IPv6 address. Invalid formats may lead to a 400 Bad Request error.
  • Review Headers: Confirm that both the Key and Accept: application/json headers are correctly set.
  • Inspect Status Code: Always check the HTTP status code of the response. Refer to the AbuseIPDB API reference for error codes.
  • Examine Response Body: If an error occurs, the API often returns a JSON response with an errors array detailing the problem. Parse this for specific error messages. For example, a 429 Too Many Requests error indicates you've hit your rate limit.
  • Network Connectivity: Ensure your development environment has outbound internet access to api.abuseipdb.com. Proxy or firewall settings might block the connection.
  • Consult Documentation: The official AbuseIPDB documentation is the most comprehensive resource for specific endpoint details, parameters, and error responses.