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_KEYYour 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-search3.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=yesThis 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 addressesemail_domain- Filter for records with email domainsphone_number- Filter for records with phone numbersusername- Filter for records with usernamesip_address- Filter for records with IP addressessocial_security_number- Filter for records with SSNspassword- Filter for records with passwordspassword_hash- Filter for records with password hashesbitcoin_address- Filter for records with bitcoin addresses
> Filter Values
yes- Include only records that have this data typeno- 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 |
|---|---|
| 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
datafield - Error responses: Include
errorandmessagefields - Pagination: Large result sets include
paging_tokenfor continuation - Rate limiting: Headers include
X-RateLimit-RemainingandX-RateLimit-Reset
> Pagination
For endpoints returning large datasets:
- Use
paging_tokenparameter to continue from where you left off - Tokens are valid for 24 hours
- Maximum 1000 records per request
- Set
number_of_recordsto 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 |
|---|---|---|
| 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) |
/includes/qr-code.png)