HEROIC Logo
API docs by Redocly

HEROIC Enterprise API (8.0.0)

Download OpenAPI specification:

URL: https://heroic.com Terms of Service

Introduction

The HEROIC Enterprise API gives you access to breach catalogs, breach search, credit card search, and account management. All endpoints are scoped under the v8 base path and require API key authentication.

Base URL

https://api.heroic.com/v8

Authentication

Every request must include your API key in the header:

Header Required Description
x-api-key Yes Your Enterprise API key
Obtaining an API key: Log into your HEROIC Enterprise account, go to API Key Management, then create or copy an API key. Use the Account summary endpoint to list your keys and their status.

Error handling

Code Meaning What to do
401 Unauthorized Missing or invalid API key, or key is inactive.
403 Forbidden API limit reached for the current month.
404 Not found Resource (e.g. breach UUID) does not exist.
422 Validation error Invalid or missing parameters; check the response body.
500 Server error Contact HEROIC support.

PII masking

Sensitive data in API responses is masked for privacy and compliance: Credit card numbers — first 6 and last 4 digits visible (e.g. 543210XXXXXX1234). SSNs — last 2 digits visible. Passwords — last 2 characters visible.

Support

For help: support@heroic.com

Breach catalog

List breaches and get breach metadata (site, date, counts, etc.).

List breaches

Returns all breaches in the catalog with metadata (site name, domain, date leaked, pwned count, etc.). Results are ordered by most recently updated first.

Authorizations:
ApiKey
query Parameters
number_of_records
integer

Optional limit on how many breaches to return.

header Parameters
x-api-key
required
string

Your Enterprise API key.

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Get breach details

Returns full details for a single breach by its UUID.

Authorizations:
ApiKey
path Parameters
hackSourceUuid
required
string <uuid>

UUID of the breach (from the breach catalog).

header Parameters
x-api-key
required
string

Your Enterprise API key.

Responses

Response samples

Content type
application/json
{
  • "uuid": "095be615-a8ad-4c33-8e9c-c7612fbf6c9f",
  • "source_name": "string",
  • "site_name": "string",
  • "site_domain": "string",
  • "site_logo": "http://example.com",
  • "date_leaked": "string",
  • "breach_type": "string",
  • "site_categories": "string",
  • "site_country": "string",
  • "site_language": "string",
  • "password_types": "string",
  • "leaked_data_types": "string",
  • "is_verified": "string",
  • "is_sensitive": "string",
  • "heroic_article_url": "string",
  • "description": "string",
  • "pwned_count": 0,
  • "created_at": "string",
  • "updated_at": "string"
}

Breach search

Search breach records. You must send at least one search field in the query string.

Allowed search fields

Parameter Description
email Exact email address.
email_domain Email domain (e.g. example.com).
ip_address Exact IP address.
ip_address_from IP range start (inclusive). Use with or without ip_address_to.
ip_address_to IP range end (inclusive). Use with or without ip_address_from.
phone_number Exact phone number.
social_security_number Exact social security number.
bitcoin_address Exact Bitcoin address.
password Exact password, or * to match any record where a password is present.

Searching with multiple attributes

You can combine several search fields in one request. All conditions are ANDed: only records that match every provided field are returned.

  • Exact match + exact match — e.g. a specific email and a specific password.
  • Exact match + “field present” — use the value * for a field to require that the field exists (e.g. “this email where a password is present”).

Examples

Single attribute (email, page 2, 50 per page):

GET /breach-search?email=user@example.com&page=2&number_of_records=50

Email and exact password (breaches where this email appears with this password):

GET /breach-search?email=user@example.com&password=MySecret123

Email where a password is present (any password; use * for “field exists”):

GET /breach-search?email=user@example.com&password=*

Email and phone number:

GET /breach-search?email=user@example.com&phone_number=%2B15551234567

Email domain and IP range:

GET /breach-search?email_domain=company.com&ip_address_from=192.168.1.0&ip_address_to=192.168.1.255

Pagination

  • page — Page number (default 1).
  • number_of_records — Page size; maximum 100 (default 20).
Authorizations:
ApiKey
query Parameters
page
integer >= 1
Default: 1
number_of_records
integer [ 1 .. 100 ]
Default: 20
email
string

Exact email address.

email_domain
string

Email domain (e.g. example.com).

ip_address
string

Exact IP address.

ip_address_from
string

IP range start (inclusive).

ip_address_to
string

IP range end (inclusive).

phone_number
string

Exact phone number.

social_security_number
string

Exact social security number.

bitcoin_address
string

Exact Bitcoin address.

password
string

Exact password, or * to match records where a password is present.

header Parameters
x-api-key
required
string

Your Enterprise API key.

Responses

Response samples

Content type
application/json
{
  • "records_found": 79,
  • "records_in_this_page": 10,
  • "next_page": 2,
  • "data": [
    ]
}

Credit card search

Search exposed credit card records. Supports query parameters for pagination and a query string with advanced syntax (e.g. by owner, bank, number pattern).

Query syntax (AND, OR, NOT)

  • number — Card number (masked: first 6 + last 4 visible).
  • owner — Cardholder name.
  • bank — Issuer bank.
  • cvv, expireDate, leakId, etc.

Examples

  • owner:"Alice Smith" AND bank:"Chase Bank"
  • number:411111*
Authorizations:
ApiKey
query Parameters
page
integer
Default: 0
size
integer
Default: 10
sort
string
Example: sort=createdAt,desc
query
string
Example: query=owner:Johnson AND bank:Citibank
header Parameters
x-api-key
required
string

Your Enterprise API key.

Responses

Response samples

Content type
application/json
{
  • "number": 0,
  • "size": 0,
  • "totalElements": 0,
  • "totalPages": 0,
  • "numberOfElements": 0,
  • "first": true,
  • "last": true,
  • "hasContent": true,
  • "content": [
    ]
}

Account

API keys, usage, and recent calls for your account.

Account summary

Returns your API keys (with status and last used), current month API usage, and the last 10 API calls. Use the API key from the x-api-key header to authenticate; the response lists all keys for your account.

Authorizations:
ApiKey
header Parameters
x-api-key
required
string

Your Enterprise API key.

Responses

Response samples

Content type
application/json
{
  • "keys": [
    ],
  • "current_month_consumption": {
    },
  • "recent_api_calls": [
    ]
}