API Documentation

Need Help? Just drop us an email with your queries to support@heroic.com and we'll get back to you.

Introduction

HEROIC offers a powerful suite of enterprise-grade APIs designed to detect and investigate exposed data across billions of breach records. With tens of billions of compromised records indexed, the HEROIC API allows you to search and retrieve breach data across multiple identity types and sources.

1. Access Requirements

To use the HEROIC API, you must have an active HEROIC Enterprise Account. Click here to sign up.

> Base URL

The Base URL for our APIs is:

https://api.heroic.com/v7

> Obtaining the API key

To obtain a key:

Log into your HEROIC Enterprise account.
Go to API Key Management.
Create or manage your API keys.

> Authentication

All requests must include an API key in the header:

x-api-key: YOUR_API_KEY

Your API key should be kept secure and never exposed in client-side code or public repositories.

> Rate Limiting

API requests are subject to rate limiting:

Standard Plan: 1,000 requests per hour
Enterprise Plan: 10,000 requests per hour
Bulk Operations: Contact support for higher limits

2. Data Privacy & Compliance

HEROIC is committed to data privacy and regulatory compliance:

> Data Handling

All PII is automatically masked in API responses
Data is encrypted in transit and at rest
Access logs are maintained for security auditing
Data retention follows GDPR and CCPA requirements

> Compliance Standards

GDPR: Full compliance with EU data protection regulations
CCPA: California Consumer Privacy Act compliance
SOC 2: Type II certified for security controls
ISO 27001: Information security management certified

3. API Operations

The HEROIC API supports multiple endpoints for breach data access and search capabilities.

https://api.heroic.com/v7/breaches
https://api.heroic.com/v7/breaches/{uuid}
https://api.heroic.com/v7/breach-search
https://api.heroic.com/v7/credit-card-search

3.1 GET /breaches

Returns metadata about breach sources including breach name, data types leaked, country of origin, and record counts. Useful for audit trails or breach intelligence overviews.

> Endpoint:

https://api.heroic.com/v7/breaches

> Query Parameters

Parameter	Required	Description
number_of_records	No	Limit the number of results returned

> Request Example:

GET /v7/breaches
x-api-key: YOUR_API_KEY

> Response Example:

{
  "uuid": "de4860a0-dddb-11e9-bc89-7d2ff98b46e3",
  "source_name": "XSS.IS Combolist",
  "site_domain": "xss.is",
  "date_leaked": "28-Feb-2019",
  "breach_type": "database",
  "site_categories": "Combo List",
  "site_country": "United States",
  "site_language": "English",
  "password_types": "Plaintext",
  "leaked_data_types": "Email Address, Username, Plaintext Password",
  "description": "Credential dump from XSS.IS, commonly shared among attackers",
  "heroic_article_url": null,
  "pwned_count": 2472611041
}

3.2. GET /breach-search

APIs for data breach search for accounts. Search for breach details by email, IP address, phone number, etc.

> Search Filters

In addition to the required type and account parameters, you can use any of the supported breach type values as additional filter parameters. These filters accept "yes" or "no" values to refine your search results.

> Example Usage

To search for an email address that also has a password exposed:

GET /breach-search?type=email&account=mohammad@gmail.com&password=yes

This will return all breach records for mohammad@gmail.com where a password was also exposed.

> Supported Filter Types

You can use any of these values as filter parameters:

email - Filter for records with email addresses
email_domain - Filter for records with email domains
phone_number - Filter for records with phone numbers
username - Filter for records with usernames
ip_address - Filter for records with IP addresses
social_security_number - Filter for records with SSNs
password - Filter for records with passwords
password_hash - Filter for records with password hashes
bitcoin_address - Filter for records with bitcoin addresses

> Filter Values

yes - Include only records that have this data type
no - Exclude records that have this data type

> Endpoint:

https://api.heroic.com/v7/breaches

> Query Parameters

Parameter	Required	Description
type	yes	The data type to search (e.g., email, ipaddress)
account	yes	The identity value (e.g., email address or phone number)
number_of_records	no	Limit the number of returned results
paging_token	no	Used for pagination across large result sets
password	no	Set to a specific value (e.g., tiger17) or yes/no to require any password
ip_address	no	Set to a specific IP (e.g., 192.168.1.1) or yes/no for any IP address
username	no	Set to a specific username or yes/no to require any username
phone_number	no	Set to a specific phone number or yes/no to require one
social_security_number	no	Set to a specific SSN or yes/no to require any SSN

> Parameter Chaining

You can combine filters using exact values or by setting fields to yes to indicate that the record must include any value for that field.

Request Examples:

GET/v7/breach-search?type=email&account=user@example.com&password=yes&ip_address=yes

GET/v7/breach-search?type=ipaddress&account=10.50.6.5&password=yes

GET/v7/breach-search?type=email&account=user@example.com&password=tiger17&username=admin

> Response Example:

{
  "records_found": 12,
  "pagination_token": "0053001032e271c0ddeb11ed8a50195359d257484062633566646662383939636438356362623630343361663638656663353038393939333131346166633061393937306331626132643632623633623065383132f07ffffff5f07ffffff110",
  "data": [
    {
      "breached_data": {
        "user_name": "kmatch7",
        "first_name": null,
        "last_name": null,
        "email": "kmatch7@yahoo.com",
        "email_domain": "yahoo.com",
        "phone_number": null,
        "ip_address": null,
        "bitcoin_address": null,
        "password": null,
        "password_hash": "71bb2e8e85702bc6dc8fe49bc2ca2664",
        "other_attributes": "{\"DATE_REG\": \"2012-01-31 03:50:51\"}"
      },
      "breach_details": {
        "uuid": "f5d77b03-44b4-11eb-9442-1d5c76d5a106",
        "site_name": "Ledger",
        "site_domain": "ledger.com",
        "site_logo": "https://breached-sites-logos.s3.us-west-2.amazonaws.com/ledger_logo.png",
        "date_leaked": "25-Jun-2020",
        "site_categories": "Crypto",
        "site_country": "United States",
        "site_language": "English",
        "password_types": "None",
        "leaked_data_types": "Email Address, Phone",
        "heroic_article_url": null,
        "description": "The hacker responsible for Ledger's security breach in July dumped a large amount of data exposing the personal information of over 270,000 customers, including phone numbers and physical addresses.",
        "pwned_count": 1075382
      }
    }
  ]
}

> Supported type Values:

Type	Description
email	Search for any data exposed for a specific email address
email_domain	Search for all identities tied to a specific domain (e.g., all @company.com accounts)
username	Find breaches tied to a specific username
phonenumber	Look up records exposed for a specific phone number
ipaddress	Search by IP address to detect exposed records
password	Find matching plaintext or hashed passwords from stealer logs or leaks

3.3 Credit Card Search

HEROIC's Credit Card Search API provides access to both legacy (free) and active (paid) stolen credit card data found across darknet markets and hacker forums. Free cards typically originate from older leaks and are useful for identifying previously compromised information, while paid cards are current, often functional, and marketed on underground platforms. HEROIC collects associated metadata such as BINs, expiration dates, issuing countries, prices, and seller reputations. Users can perform single BIN lookups, submit bulk queries, configure automated monitoring, and download results in formats including CSV, Excel, or JSON.

> Search Capabilities and Limitations

The API enables structured searches, including masked or SHA-256-hashed card numbers, owner names, CVV codes, and expiration dates. Users can apply advanced filters and syntax to refine results and maintain privacy. Monitoring options are available for ongoing updates. While powerful, the system is affected by common challenges—such as disappearing data, duplicate listings, low-quality or fake records, and the migration of card sales to newer platforms like Telegram and Discord. HEROIC continues to improve its scraping and detection capabilities, with regular updates and expanding coverage to adapt to the evolving threat landscape.

> What types of credit cards are indexed by HEROIC?

HEROIC tracks two primary categories of compromised credit card data uncovered across the deep and dark web:

Free Cards – These are stolen credit card records that have been made publicly available without cost on underground forums and leak sites. While HEROIC's systems have cataloged millions of such entries, the majority are from older breaches and are typically no longer valid for transactions. You can explore this data through the database search feature in the HEROIC Control Center.
Paid Cards – These are active, for-sale credit cards commonly listed on darknet marketplaces. Sold much like regular merchandise, these records are often fresh and functional, requiring a payment to access. HEROIC continuously scans and logs these listings to provide real-time intelligence on emerging threats.

> Advanced Search Syntax

This endpoint enables you to search for exposed credit card records discovered in data breaches and leaks. You can use query parameters to filter results by cardholder, issuing bank, or other criteria. The response includes masked card numbers, CVVs, expiration dates, issuing bank details, and breach-related metadata.

> Available Fields:

Field	Details
createdAt	Creation date & time.
number	Credit card number (default field), masked with X in the middle except first 6 and last 4 digits.
Hash	SHA-256 of a credit card number
expireDate	Expiration date
cvv	Card verification value
owner	Owner name
bank	Issuer bank name
leakId	Leak ID

> Operators:

AND, OR, NOT

> Examples:

Search cards starting with 411111: 411111*
Search cards starting with 400012 and ending with 7890, containing 16 digits: 400012XXXXXX7890
Search cards starting with 400012 and ending with 7890, containing any number of digits: 400012*7890
Search cards with Alice Smith as owner and Chase Bank as bank: owner:"Alice Smith" AND bank:"Chase Bank"
Search cards starting with 411111 and belonging to Bob Lee: number:411111* AND owner:"Bob Lee"
Search cards that have a CVV 555 and that expire on or after January 1, 2023: cvv:555 AND expireDate:[2023-01-01 TO *]

> Endpoint:

https://api.heroic.com/v7/credit-card-search

> Query Parameters

Parameter	Type	Required	Description
page	integer	No	Page number (zero-based). Example: page=0
size	integer	No	Number of records per page. Example: size=10
sort	string	No	Sort order (e.g., createdAt,desc). Example: sort=createdAt,desc
query	string	No	Search query (e.g., owner, bank, etc). Supports logical operators (AND, OR). Example: query=owner:Johnson AND bank:Citibank

> Response Example:

{
  "number": 0,
  "size": 10,
  "totalElements": 352,
  "totalPages": 36,
  "numberOfElements": 10,
  "first": true,
  "last": false,
  "hasContent": true,
  "content": [
    {
      "id": "70852ff0-fab3-3c49-87c7-9545fefcb02c",
      "createdAt": "2025-03-13 05:42:36",
      "bank": "FARMERS STATE BANK",
      "number": "424744XXXXXX0328",
      "owner": "Chad Wells",
      "cvv": "045",
      "expireDate": "2025-02-01",
      "cvssScore": 10,
      "leakId": "0f53e4b1-8c6a-3e38-96ac-c90909faf678",
      "leakName": "stealer log 11.02.2025",
      "leakPublishDate": "2025-02-11",
      "leakDiscoverDate": "2025-02-19",
      "leakSize": 59634800800,
      "leakTags": "password,log,credit-card,ip,email,hash,url,account,username"
    }
  ]
}

4. Request & Response Schema Details

Response structures are consistent across endpoints.
Always returned as JSON.
Fields include string, number, boolean, timestamp, or null.
Pagination tokens (when present) use paging_token.

> Response Format

All API responses follow a consistent structure:

Success responses: Return data directly or in a data field
Error responses: Include error and message fields
Pagination: Large result sets include paging_token for continuation
Rate limiting: Headers include X-RateLimit-Remaining and X-RateLimit-Reset

> Pagination

For endpoints returning large datasets:

Use paging_token parameter to continue from where you left off
Tokens are valid for 24 hours
Maximum 1000 records per request
Set number_of_records to limit results

5. Error Handling

Code	Error category	Description	Resolution
403	Authentication Failed	Invalid API credentials.	Ensure a valid API key is specified.
404	Path not found	The API path does not exist.	Check the API route.
405	Invalid input	Invalid input provided.	Check your input.
422	Validation Error	Validation failed.	Read the error message and correct your data.
500	Internal server error	Server error.	Contact HEROIC support.

6. HTTP Status Codes

Code	Description
200	OK – request succeeded
400	Bad Request – missing or invalid params
401	Unauthorized – missing or invalid API key
404	Not Found – no records found
429	Too Many Requests – rate limited
500+	Server errors – try again or contact support

6. PII Masking

HEROIC is committed to protecting sensitive personal information (PII) in all API responses. To ensure privacy and compliance, all PII fields such as credit card numbers, SSNs, and passwords are masked or redacted in the data returned by our APIs.

Credit card numbers: Randomly masked to show up to 6 digits (e.g., 543210XXXXXX1234).
SSNs: Only last 2 digits are visible (e.g., 123-456-78**).
Passwords: Only last 2 characters are visible (e.g., admin@12**).

This masking ensures that sensitive data cannot be reconstructed or misused, while still allowing for effective breach investigation and analysis. If you require access to unmasked data for legitimate security or compliance reasons, please contact HEROIC support for more information on our data access policies.

8. Data Dictionary

Breach Metadata

Field	Type	Description
uuid	string	Unique identifier for the breach
source_name	string	Name/title of the breach source
site_domain	string	Domain of the breached site
date_leaked	string	Date the data was leaked
breach_type	string	Type of breach (e.g., database)
site_categories	string	Tags/categories describing the site
site_country	string	Country where the breach originated
site_language	string	Primary language of the breached site
password_types	string	Type of password leaked (e.g., plaintext)
leaked_data_types	string	Types of data exposed in the breach
description	string	Summary of the breach
heroic_article_url	string	Link to HEROIC article (nullable)
pwned_count	integer	Number of identities exposed in the breach

Identity-Level Record

Field	Type	Description
email	string	Leaked email address
email_domain	string	Domain portion of the leaked email
username	string	Leaked username
password	string	Plaintext password if exposed
password_hash	string	Hashed password if exposed
phone_number	string	Leaked phone number
ip_address	string	Leaked IP address
social_security_number	string	Leaked social security number (if available)
hack_source_uuid	string	Corresponding breach UUID
severity	string	Risk severity (e.g., Low, Medium, High)

Enterprise Protection

Consumer Risk Protection

Data Partnerships

MSP/MSSP Support

Incident Response

Pricing

Get in touch with the HEROIC team

OUR SERVICES

SUPPORT

Healthcare

Financial Services

Retail

Technology

Education

Manufacturing

Legal

Government

CORE TECHNOLOGY

Darkhive

Cyberlytics

PLATFORM

Darkhive Catalog

Latest Blog Posts

HEROIC Cybersecurity Named Among Fastest-Growing U.S. Companies

FBI Warns of Scattered Spider’s Expanding Attacks on Airlines Using Social Engineering

16 Billion Passwords Exposed: The Biggest Credential Leak on Record?

Single Domain vs Full Domain Profile Scans: A New Frontier in Breached Identity Intelligence

Cybersecurity and It’s Impact on Startups: Keeping your Business Safe in the Digital Age

The Ledger Database Leak Exposes 272,854 User’s Personal Information

Latest News

Our Mission

HEROIC Labs

Partners

Careers

Contact Us

Branding Assets

Interested in learning more about HEROIC?

Introduction

1. Access Requirements

> Base URL

> Obtaining the API key

> Authentication

> Rate Limiting

2. Data Privacy & Compliance

> Data Handling

> Compliance Standards

3. API Operations

3.1 GET /breaches

> Endpoint:

> Query Parameters

> Request Example:

> Response Example:

3.2. GET /breach-search

> Search Filters

> Example Usage

> Supported Filter Types

> Filter Values

> Endpoint:

> Query Parameters

> Parameter Chaining

Request Examples:

> Response Example:

> Supported type Values:

3.3 Credit Card Search

> Search Capabilities and Limitations

> What types of credit cards are indexed by HEROIC?

> Advanced Search Syntax

> Available Fields:

> Operators:

> Examples:

> Endpoint:

> Query Parameters

> Response Example:

4. Request & Response Schema Details

> Response Format

> Pagination

5. Error Handling

6. HTTP Status Codes

6. PII Masking

8. Data Dictionary