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.

🧠 First, how infostealer data is organized

When a computer is infected, the stealer dumps everything it finds into 5 separate buckets (indexes):

  • Credential → saved logins (URL / user / password)
  • Cookies → browser cookies / sessions
  • Info → system info (Country, OS, HWID, log date…)
  • plus → extras: crypto wallets, VPN, FTP, Steam, Telegram…
  • Filelist → list of files grabbed from the machine

Every one of those documents shares the same Filename — a unique ID for the infected machine, e.g. HWID E32F8AFB9CF347BA22FCCF354C9E9B5C_analysis14951. Think of Filename as the "victim machine ID" that glues all the pieces together.

📦 The response has 3 possible shapes — always check "mode" first

The field you search by decides how the answer is shaped. Read the top-level "mode" value and parse accordingly:

mode Triggered when you search by… What you get
fragments email, username, phone, id, domain, password, domain_employees A flat list in "matches", one item per matching credential: {URL, USER, PASS, Filename}.
documents wallets, steamid, steamuser, teleid, teleuser, telephone, telelink, vpn, ftp, hwid Raw documents in "data", each as {_index, _source}.
stealers 🆕 country Results grouped per infected machine in "data". Each group bundles ALL its documents from the 5 indexes. See below.

🆕 What changed: searching by country now returns the full profile

Before: /api/fullstealer/country/AU only returned the single document where the Country field lives (the logs_info one) — so you saw the machine existed, but none of its actual loot.

Now: for each match we grab its Filename and pull everything tied to that machine across all 5 indexes — credentials, cookies, system info, wallets, file list — and return it grouped per machine. One search → the complete victim profile.

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 by Country (returns full stealer profiles 🆕)

Country must be a 2-letter code (e.g. US, AU, ES). Responds with "mode": "stealers".

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

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 A — mode: "fragments"

Returned when you search by email, username, phone, id, domain or password. Each item in matches is a single matching login. Filename tells you which machine it came from. 

{
  "mode": "fragments",
  "matches": [
    {
      "URL": "https://login.example.com",
      "USER": "[email protected]",
      "PASS": "leaked_password_123",
      "Filename": "HWID E32F8AFB9CF347BA22FCCF354C9E9B5C_analysis14951"
    }
  ],
  "count": 1,
  "total_docs": 14356,
  "search_term": "example.com",
  "fields": ["domain"],
  "search_after": 2587,
  "has_next_page": true
}

Example Response B — mode: "documents"

Returned when you search by wallets, steamid, steamuser, telegram fields, vpn, ftp or hwid. Each entry in data is a raw document; the real content lives inside _source, and _index tells you which bucket it came from. 

{
  "mode": "documents",
  "data": [
    {
      "_id": "kJ3l9ZcBxq",
      "_index": "logs_plus",
      "_score": null,
      "_source": {
        "Filename": "HWID E32F8AFB9CF347BA22FCCF354C9E9B5C_analysis14951",
        "HWID": "E32F8AFB9CF347BA22FCCF354C9E9B5C",
        "Country": "AU",
        "Wallets Cracked": ["bc1qxy2k...", "0x1283921ASDK..."]
      }
    }
  ],
  "count": 1,
  "total_hits": 320,
  "search_term": "76561198012345678",
  "fields": ["steamid"],
  "has_next_page": false
}

Example Response C — mode: "stealers" (country search 🆕)

Returned only when you search by country. data is a list of infected machines. Each machine has its filename, a count of how many documents belong to it, and a documents array bundling everything found for that machine across the 5 indexes. 

{
  "mode": "stealers",
  "data": [
    {
      "filename": "HWID E32F8AFB9CF347BA22FCCF354C9E9B5C_analysis14951",
      "count": 4,
      "documents": [
        {
          "_index": "logs_info",
          "_source": {
            "Filename": "HWID E32F8AFB...analysis14951",
            "Country": "AU",
            "HWID": "E32F8AFB9CF347BA22FCCF354C9E9B5C",
            "LogDate": "2024-11-02"
          }
        },
        {
          "_index": "logs_credential",
          "_source": {
            "Filename": "HWID E32F8AFB...analysis14951",
            "Credentials": [
              {
                "URL": "https://mail.example.com",
                "USER": "[email protected]",
                "PASS": "hunter2"
              }
            ]
          }
        },
        {
          "_index": "logs_plus",
          "_source": {
            "Filename": "HWID E32F8AFB...analysis14951",
            "Wallets Cracked": ["bc1qxy2k...", "0x9aF3..."],
            "VPN info": "nordvpn.com"
          }
        },
        {
          "_index": "logs_filelist",
          "_source": {
            "Filename": "HWID E32F8AFB...analysis14951",
            "Files": ["C:\\Users\\victim\\Desktop\\passwords.txt"]
          }
        }
      ]
    }
  ],
  "count": 1,
  "total_hits": 5821,
  "search_term": "AU",
  "fields": ["country"],
  "search_after": 1024,
  "has_next_page": true
}

How to read it:

  • count (top level) → number of machines returned on this page.
  • total_hits → total country matches available across all pages.
  • data[].count → how many documents that single machine has.
  • Use search_after + has_next_page to page through more machines.

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 cursor-based pagination via search_after (20 results per request). Take the search_after value from the response and pass it as a query parameter to fetch the next batch: ?search_after=2587. When has_next_page is false, you've reached the end.

Q: Why does a country search on fullstealer look different from other searches?

Because country search now returns "mode": "stealers" — results grouped per infected machine. Instead of a single isolated row, each machine comes with all of its documents (credentials, cookies, system info, wallets, file list) bundled together under its Filename. This gives you the complete profile of every victim machine in that country in one call. All other fields keep their previous fragments/documents shapes.

Q: How do I know which response shape to expect from fullstealer?

Always read the top-level "mode" field. fragments → look in matches (flat list of {URL, USER, PASS, Filename}). documents → look in data (raw docs, real content inside _source). stealers → look in data (one entry per machine, documents bundled inside).