API Documentation
Learn how to use our Abuse API with simple examples and detailed explanations.
Introduction
Our API allows you to interact with our service programmatically, you can fetch abuse insight data, validate users and customers, submit reports, manage resources and access your account details.
Use Cases
Most popular use-cases include:
- Validate users and e-mail addresses
- Check insight info on ip-addresses
- Get abuse info and evaluate users or customers
- Submit abuse reports
Authentication
To authenticate with our API, include your API-Key for every request in the HTTP request header as a Bearer token:
Authentication Example
curl https://api.abusereport.com \
-H "Authorization: Bearer {YOUR_API_KEY}"If you are logged in, we will automatically insert your API-Key into the placeholder {YOUR_API_KEY}.
You can always access your API-Key from the account page.
Account Information
You can retrieve your account information and current API usage with a simple GET request to our API:
Account Info
curl https://api.abusereport.com \
-H "Authorization: Bearer {YOUR_API_KEY}"Account Info Response
{
"success": true,
"username": "AbuseReport",
"email_address": "[email protected]",
"plan": "Business",
"requests_usage_limit": 50000,
"requests_usage": 431,
"requests_remaining": 49569
}Example Check Request
Here is an example of a simple GET request to our API using the Check endpoint for retrieving abuse insight info:
E-Mail Check Example
curl https://api.abusereport.com/check/[email protected] \
-H "Authorization: Bearer {YOUR_API_KEY}"E-Mail Check Result
{
"success": true,
"has_reports": false,
"risk_score": 20,
"inbox": "support",
"domain": "abusereport.com",
"tld": "com",
"reachable": true,
"disposable": false,
"mx": {
"record": true,
"values": [
{
"name": "abusereport.com",
"type": 15,
"TTL": 3600,
"data": "1 aspmx.l.google.com."
},
{
"name": "abusereport.com",
"type": 15,
"TTL": 3600,
"data": "10 alt3.aspmx.l.google.com."
},
{
"name": "abusereport.com",
"type": 15,
"TTL": 3600,
"data": "10 alt4.aspmx.l.google.com."
},
{
"name": "abusereport.com",
"type": 15,
"TTL": 3600,
"data": "5 alt1.aspmx.l.google.com."
},
{
"name": "abusereport.com",
"type": 15,
"TTL": 3600,
"data": "5 alt2.aspmx.l.google.com."
}
]
},
"spf": {
"record": true,
"value": "v=spf1 include:_spf.google.com -all"
},
"dmarc": {
"record": false,
"value": null
},
"reports": []
}IP Check Example
curl https://api.abusereport.com/check/8.8.8.8 \
-H "Authorization: Bearer {YOUR_API_KEY}"IP Check Result
{
"success": true,
"ip_address": "8.8.8.8",
"has_reports": false,
"risk_score": 40,
"country": "United States",
"country_code": "US",
"state": null,
"city": "Sunnyvale",
"zipcode": "95196",
"organisation": {
"name": "Google LLC",
"network": "8.8.8.0 - 8.8.8.255"
},
"asn": {
"name": "Google LLC",
"asn": 15169,
"domain": "www.google.com",
"route": "8.8.8.0/24"
},
"abuse_contact": {
"name": "Google LLC",
"address": "1600 Amphitheatre Parkway, Mountain View, CA, 94043, US",
"email": "[email protected]",
"phone": "+1-650-253-0000"
},
"proxy": false,
"hosting": true,
"timezone": "America/Los_Angeles",
"reports": []
}The Check endpoint accepts any type of email or ip-address and provides you with the latest details.
You don't need to specify the type of value you want to check, it will be automatically validated.
If you strictly want to check for a certain type, you can pass the ?type=email|ip_address as an optional argument.
Get Abuse Reports
To get a list of all your submitted abuse reports, you can send a GET request to the following API endpoint:
Get Reports Example
curl https://api.abusereport.com/reports \
-H "Authorization: Bearer {YOUR_API_KEY}"Submit Abuse Report
You can create a new abuse report by sending a POST request with the report details to our API:
Request Body
POST https://api.abusereport.com/reports
Authorization: Bearer {YOUR_API_KEY}
Content-Type: application/json
{
"report_value": "[email protected]",
"report_type": "email_address",
"report_abuse_type": "ddos",
"comment": "optional"
}Submit Report Example
curl -X POST https://api.abusereport.com/reports \
-H "Authorization: Bearer {YOUR_API_KEY}" \
-H "Content-Type: application/json" \
-d '{' \
-d ' "report_value": "[email protected]",' \
-d ' "report_type": "email_address",' \
-d ' "report_abuse_type": "ddos",' \
-d ' "comment": "optional"' \
-d '}'Submit Report Response
{
"success": true,
"report_id": "report_id"
}Delete Report
You can delete specific abuse reports by sending a DELETE request with the report ID to our API. This action cannot be undone:
Request Body
DELETE https://api.abusereport.com/reports
Authorization: Bearer {YOUR_API_KEY}
Content-Type: application/json
{
"id": "report_id"
}Delete Report Example
curl -X DELETE https://api.abusereport.com/reports \
-H "Authorization: Bearer {YOUR_API_KEY}" \
-H "Content-Type: application/json" \
-d '{"id": "report_id"}'Delete Report Response
{
"success": true,
"message": "Report successfully deleted",
"report_id": 123456
}Response
API responses are always returned in JSON format, depending on the value which was checked, the returned result details can differ. For example, the check result for an e-mail address won't contain any ip-address related info, such as geo-location or ASN. Below are examples for both requests:
HTTP Response Codes
Our API always returns the corresponding HTTP status code for the response, if there is an error, error details are additionally returned in the JSON response, here are some common HTTP response codes you may encounter:
- 200 OK: The request was successful.
- 400 Bad Request: The request was invalid or was missing required parameters.
- 429 Too Many Requests: You have reached your monthly request limit, you need to upgrade your plan.
- 403 Unauthorized: The provided API-Key is invalid or user does not have permissions for the desired action.
- 404 Not Found: The requested API endpoint could not be found.
- 500 Internal Server Error: An error occurred while processing your request on our end.
Limits
Your monthly request limit depends on your current plan, you can see your remaining requests on your account page.
The limit resets at the first day on the upcoming month, there are no additional rate-limits or pagination on our API.
Requests to none data or report related endpoints, for example, account details, won't count against your quota.