Welcome to the Have I Been Ransomed API documentation. This API allows you to search through our database of ransomware breach data to check if specific email addresses or domains have been compromised in known incidents.
The API provides two main endpoints: metadata search for basic information and full data search for detailed results. All endpoints require proper authentication and follow rate limiting policies.
https://haveibeenransom.com/api/
All API requests require authentication using an API key. Include your API key in the request headers:
Authorization: Bearer YOUR_API_KEY
Contact [email protected] to obtain an API key.
Our database contains various types of data from ransomware breaches. The following fields are available for searching and will be returned in the results:
| Search Field | Description |
|---|---|
| name | Full names and name-related information |
| phone | Phone numbers and contact information |
| Email addresses | |
| username | Usernames and login identifiers |
| id | ID numbers and identification data |
| country | Country information |
| domain | website domains/emails leaked |
email_context field contains various types of personal information associated with email addressesSearch for basic information about breaches affecting a specific email or domain. This endpoint provides metadata about breaches without exposing sensitive details. Results are paginated with up to 20 unique results per page.
GET /api/metadata/field/query
| Parameter | Type | Required | Description |
|---|---|---|---|
| query | string | Yes | Availible fields |
| page | integer | No | Page number (default: 1) |
curl -H "Authorization: Bearer your-token-1234"
"https://haveibeenransom.com/api/metadata/domain/example.com curl -H "Authorization: Bearer your-token-1234"
"https://haveibeenransom.com/api/metadata/email,username/[email protected] {
"success": true,
"results": [
{
"Identities Found": 1872,
"country": "US",
"description": "United States",
"discovered": "2024-12-16 21:07:57.040833",
"group_name": "ransomgang name",
"id": "11111",
"id_source": "11111",
"indexed": "2025-07-11T00:33:13.072665",
"post_title": "Example Company Breached",
"post_url": "http://example3wh7hnmaiokchk7qoebupfgoik6rhaexample.onion/id=1234",
"website": "example.com"
}
],
"pagination": {
"current_page": 1,
"total_pages": 3,
"total_sources": 45,
"has_next": true,
"has_previous": false
}
}Search for detailed information about breaches affecting a specific email. This endpoint provides comprehensive data about the breach and affected records. Availible Multi-field search
GET /api/fulldata/fields/query
| Parameter | Type | Required | Description |
|---|---|---|---|
| Fields | string | Yes | email, phone, domain, id, country |
| offset | integer | No | offset number (default: 0) |
curl -H "Authorization: Bearer your-token-1234"
"https://haveibeenransom.com/api/fulldata/domain/example.com curl -H "Authorization: Bearer your-token-1234"
"https://haveibeenransom.com/api/fulldata/email,name/[email protected]{
"success": true,
"email": "[email protected]",
"data": [
{
"email": "[email protected]",
"email_context": "phone, name, etc",
"From archive": "This domain has been in PDF archive example.pdf"
"source_metadata": {
"country": US,
"description": "Lore ipsunm......",
"group_name": "play",
"company_affected": "Company XYZ",
"post_url": "http://example3wh7hnmaiokchk7qoebupfgoik6rhaexample.onion/id=1234",
"website": "example.com"
}
}
],
"next_offset": 21,
"offset": 0,
"total_hits": 3402
}The API returns standard HTTP status codes and error messages:
| Status Code | Description |
|---|---|
| 400 | Bad Request - Invalid parameters |
| 401 | Unauthorized - Invalid API key |
| 429 | Too Many Requests - Rate limit exceeded |
| 500 | Internal Server Error |
{
"success": false,
"error": {
"code": 400,
"message": "Invalid email format",
"details": "The provided email address is not in a valid format"
}
}API requests are subject to rate limiting to ensure fair usage:
Rate limit headers are included in all responses to help you track your usage.
Metadata search provides basic breach information without sensitive details, while full data search returns comprehensive information about the specific data compromised.
Our database is continuously updated as new ransomware breaches are discovered and verified. Updates typically occur within 24-48 hours of breach disclosure.
Yes, the metadata search endpoint supports domain queries (e.g., "example.com") to find all breaches affecting that domain.
Each page returns up to 20 unique results. Use the "page" parameter to navigate through results, and check the pagination object in the response for navigation information.