API Documentation

Welcome to the Have I Been Ransomed API documentation. This API allows you to search through our database of ransomware breach data and infostealer logs to check if specific information has been compromised in known incidents.

The API provides three main endpoints: metadata search for basic information, full data search for detailed results, and full stealer search for infostealer data. All endpoints require proper authentication and follow rate limiting policies.

Base URL

https://haveibeenransom.com/api/

Authentication

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 OR buy a plan at BUY API KEY.

1.1 Total Breaches Count

Returns the total number of breaches in the database.

GET /breaches/total

Example Request

curl "https://haveibeenransom.com/breaches/total"

Example Response

{
  "total": 1113
}

1.2 Full Breaches List

Returns the complete list of all breaches sorted by discovery date (oldest to newest).

GET /breaches/full

Example Request

curl "https://haveibeenransom.com/breaches/full"

Example Response

{
  "breaches": [
    {
      "id": "11111",
      "id_source": "11111",
      "group_name": "ransomgang name",
      "post_title": "Example Company Breached",
      "post_url": "http://example3wh7hnmaiokchk7qoebupfgoik6rhaexample.onion/id=1234",
      "website": "example.com",
      "country": "US",
      "description": "United States",
      "discovered": "2024-12-16 21:07:57.040833",
      "indexed": "2025-07-11T00:33:13.072665",
      "Identities Found": 1872
    },
    {
      "id": "22222",
      "id_source": "22222",
      "group_name": "another_gang",
      "post_title": "Another Company Data Leak",
      "post_url": "http://example.onion/id=5678",
      "website": "anothercompany.com",
      "country": "GB",
      "description": "United Kingdom",
      "discovered": "2024-12-17 10:15:30.123456",
      "indexed": "2025-07-12T08:20:45.987654",
      "Identities Found": 3421
    }
  ]
}

Available Search Fields

Our database contains various types of data from ransomware breaches and infostealer logs. The following fields are available for searching and will be returned in the results:

🔒 Ransomware Breaches Fields

Search Field	Description
name	Full names and name-related information
phone	Phone numbers and contact information
email	Email addresses
username	Usernames and login identifiers
id	ID numbers and identification data
country	Country information
domain	Website domains/emails leaked
password	Passwords found in breaches

🕵️ Infostealer Logs Fields

Search Field	Description
email	Email addresses from stolen credentials
name	Names found in stolen data
phone	Phone numbers from compromised systems
username	Usernames from stolen credentials
id	ID numbers found in logs
country	Country of compromised systems
domain	Domains from stolen credentials
password	Passwords from stolen credentials
wallets	Cryptocurrency wallet addresses
steamid	Steam account IDs
steamuser	Steam usernames
teleid	Telegram user IDs
teleuser	Telegram usernames
telephone	Telegram phone numbers
telelink	Telegram group links
vpn	VPN domains or IP addresses
ftp	FTP domains or IP addresses
hwid	Hardware IDs (Computer IDs)

Important Notes:

Some fields map to multiple database columns for comprehensive searching
The email_context field contains various types of personal information associated with email addresses
Search queries are case-insensitive and support partial matching
Domain searches will return all records associated with that domain
Multi-field searches are supported by separating fields with commas (e.g., email,username)

1. Metadata Search (Ransomware Breaches)

Search 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

Parameters

Parameter	Type	Required	Description
field	string	Yes	Available fields: name, phone, email, username, id, country, domain, password
query	string	Yes	Search term
page	integer	No	Page number (default: 1)

⭐ Complete Mode (Enterprise Only)

The /complete endpoint returns ALL results without pagination. This feature is only available for Enterprise license holders due to the large volume of data returned.

Example Request Single Field

curl -H "Authorization: Bearer your-token-1234" \
    "https://haveibeenransom.com/api/metadata/domain/example.com"

Example Request Multiple Fields

curl curl -H "Authorization: Bearer your-token-1234" \
    "https://haveibeenransom.com/api/metadata/email,username/[email protected]"

Example Complete Request

curl -H "Authorization: Bearer your-token-1234" \
   "https://haveibeenransom.com/api/metadata/domain/example.com/complete" - ⭐ Enterprise Only

Example Response

{
  "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
  }
}

2. Full Data Search (Ransomware Breaches)

Search for detailed information about breaches affecting a specific email. This endpoint provides comprehensive data about the breach and affected records. Multi-field search available.

GET /api/fulldata/fields/query
GET /api/fulldata/fields/query/complete ⭐ Enterprise Only
GET /api/fulldata/fields/query?search_after=X/id_source
GET /api/fulldata/fields/query/id_source/complete ⭐ Enterprise Only

Parameters

Parameter	Type	Required	Description
fields	string	Yes	Available fields: email, phone, domain, id, country, name, username, password
query	string	Yes	Search term
search_after	integer	No	Number (default: 0)

⭐ Complete Mode (Enterprise Only)

The /complete endpoint returns ALL results without pagination. This feature is only available for Enterprise license holders due to the large volume of data returned.

Example Request Single Field

curl -H "Authorization: Bearer your-token-1234" \
     "https://haveibeenransom.com/api/fulldata/domain/example.com"

Example Request Multiple Fields

curl -H "Authorization: Bearer your-token-1234" \
     "https://haveibeenransom.com/api/fulldata/email,name/[email protected]"

Example Request Complete Mode (Enterprise Only)

curl -H "Authorization: Bearer your-token-1234" \
     "https://haveibeenransom.com/api/fulldata/email/[email protected]/complete"

Example Response

{
  "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": "Lorem ipsum......",
        "group_name": "play",
        "company_affected": "Company XYZ",
        "post_url": "http://example3wh7hnmaiokchk7qoebupfgoik6rhaexample.onion/id=1234",
        "website": "example.com"
      }
    }
  ],
  "has_next_page": true,
  "search_after": 253941,
  "total_hits": 325478
}

3. Full Stealer Search (Infostealer Logs)

Search for detailed information from infostealer logs. This endpoint provides comprehensive data about stolen credentials, crypto wallets, gaming accounts, and more. Multi-field search available.

GET /api/fullstealer/fields/term
GET /api/fullstealer/fields/term?search_after=X
GET /api/fullstealer/fields/term/complete ⭐ Enterprise Only

Parameters

Parameter	Type	Required	Description
fields	string	Yes	Available fields: email, name, phone, username, id, country, domain, password, wallets, steamid, steamuser, teleid, teleuser, telephone, telelink, vpn, ftp, hwid
term	string	Yes	Search term
search_after	integer	No	number (default: 0)
id_source	string	No	Filter by specific source ID

⭐ Complete Mode (Enterprise Only)

The /complete endpoint returns ALL results without pagination. This feature is only available for Enterprise license holders due to the large volume of data returned.

Example Request Single Field

curl -H "Authorization: Bearer your-token-1234" \
     "https://haveibeenransom.com/api/fullstealer/email/[email protected]"

Example Request Multiple Fields

curl -H "Authorization: Bearer your-token-1234" \
     "https://haveibeenransom.com/api/fullstealer/email,username/[email protected]"

Example Request with Offset

curl -H "Authorization: Bearer your-token-1234" \
     "https://haveibeenransom.com/api/fullstealer/steamid/76561198012345678/"

Example Request with Source Filter

curl -H "Authorization: Bearer your-token-1234" \
     "https://haveibeenransom.com/api/fullstealer/email/[email protected]/"

Example Request Complete Mode (Enterprise Only)

curl -H "Authorization: Bearer your-token-1234" \
     "https://haveibeenransom.com/api/fullstealer/domain/example.com/complete"

Example Request Complete Mode with Source (Enterprise Only)

curl -H "Authorization: Bearer your-token-1234" \
     "https://haveibeenransom.com/api/fullstealer/email/[email protected]/complete"

Example Response

{
  "success": true,
  "term": "example.com",
  "data": [
    {
      "email": "[email protected]",
      "password": "leaked_password",
      "domain": "example.com",
      "filename": HWID 012381932ADCASFDKALDLAD,
    }
  ],
  "has_next_page": true,
  "search_after": 2587,
  "total_hits": 14356
}

Example Response

{
  "success": true,
  "term": "HWID 012381932ADCASFDKALDLAD",
  "data": [
    {
      "email": "[email protected]",
      "password": "leaked_password",
      "domain": "example.com",
      "wallets": ["bc1q...", "0x1283921ASDK..."],
      "steam_id": "76561198012345678",
      "telegram_id": "123456789",
      "hwid": "HWID-ABC-123",
      "filename": "HWID ABC-123_analisys123",
      "source_metadata": {
        "malware_family": "RedLine",
        "infection_date": "2024-01-15",
        "country": "US",
        "ip_address": "192.168.1.1"
      }
    }
  ],
  "has_next_page": true,
  "search_after": 2587,
  "total_hits": 14356
}

4. Error Responses

The API returns standard HTTP status codes and error messages:

Common Error Codes

Status Code	Description
400	Bad Request - Invalid parameters
401	Unauthorized - Invalid API key
403	Forbidden - Enterprise feature requires upgrade
429	Too Many Requests - Rate limit exceeded
500	Internal Server Error

Error Response Example

{
  "success": false,
  "error": {
    "code": 403,
    "message": "Enterprise feature required",
    "details": "The /complete endpoint is only available for Enterprise license holders"
  }
}

5. Rate Limiting

API requests are subject to rate limiting to ensure fair usage:

Basic: 100 requests per day
Premium: 1000 requests per day
Enterprise: 10000 requests per day + Complete mode access

Rate limit headers are included in all responses to help you track your usage.

6. Frequently Asked Questions

Q: What's the difference between metadata and full data search?

Metadata search provides basic breach information without sensitive details, while full data search returns comprehensive information about the specific data compromised.

Q: What's the difference between fulldata and fullstealer endpoints?

The fulldata endpoint searches ransomware breach data, while fullstealer searches infostealer logs which contain stolen credentials, crypto wallets, gaming accounts, and other sensitive information from compromised systems.

Q: How often is the database updated?

Our database is continuously updated as new ransomware breaches and infostealer logs are discovered and verified. Updates typically occur within 24-48 hours of breach disclosure.

Q: Can I search for domains instead of specific emails?

Yes, all endpoints support domain queries (e.g., "example.com") to find all breaches or logs affecting that domain.

Q: What is Complete mode and how do I access it?

Complete mode returns all results without pagination, which is useful for comprehensive data exports. This feature is exclusively available for Enterprise license holders. Contact [email protected] to upgrade.

Q: How does pagination work?

Metadata search uses page numbers (up to 20 results per page), while fulldata and fullstealer use offset-based pagination (20 results per request). Use the next_offset value from the response to get the next batch of results.