HEROIC Logo
API docs by Redocly

HEROIC API Reference (7.2.0)

Download OpenAPI specification:Download

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

Introduction

Welcome to HEROIC APIs reference documentation.

HEROIC enterprise APIs offers breach search APIs to it's clients which they can use for their own development requirements. The APIs provides following set of operations.

  • Get the list of data breaches HEROIC has discovered.
  • Search for company domain in data breaches.
  • Search breach details for an email address
  • Search breach details for an IP address
  • Search breach details for a phone number
  • Search breach details for a username
  • Search breach details for a password

HEROIC intelligently searches for your search queries in it's huge database with over 15 billion records to provide you with accurate result at high speeds.

Accessing the APIs

You are required to have an enterprise account with HEROIC to get access to these powerful APIs. Click here to sign up for an HEROIC Enterprise account.

You can access the APIs using the below endpoint:

https://api.heroic.com

Authentication

HEROIC APIs are protected by the unique API key. Follow the below steps to get an API key.

  • Login to your HEROIC Enterprise account.
  • Navigate to API key management.
  • Create an API key.
  • Make authenticated API calls using the API key generated in above step.

Request and Response

HTTP Request Body

Most of the parameters and data accompanying your requests will be contained in the body of the HTTP request.

HTTP Response Body

The HEROIC REST APIs returns output in JSON format.

Testing a Request

Use a third party client, such as curl, Postman, or Advanced REST Client, to test the HEROIC REST API.

Concurrent Request Limits

HEROIC enforces max 5 concurrent request in one second.

Timeout Limit

If a request does not complete within 60 seconds, the request times out and HEROIC returns a Gateway Timeout error.

Error Handling

If a request to HEROIC REST API fails, the response throw an error with status code, according to error type, with a corresponding error message to indicate the details of the error.

Code Error category Description Resolution
403 Authentication Failed Authentication fails due to invalid API authentication credentials. Ensure that a valid API credential is specified.
404 Path not found The given API path does not exist. Ensure that you have passed correct API route.
405 Invalid input Error occured due to invlid input. Ensure that you have entered correct input.
422 Validation Error Fails due validation throws an error. Read the message in api and try to send correct data according to message.
500 Internal server error Something went wrong or The server encounters an internal error. Contact HEROIC Enterprise support

Need help ?

We are happy to assist you whenever you need us. Just drop us an email with your queries to support@heroic.com and we'll get back to you.

Versioning

The HEROIC APIs are version controlled. Versioning ensures that changes made to the APIs are backward compatible. HEROIC uses a major and minor version nomenclature to manage changes. By specifying a version in a REST request, you can get expected responses regardless of future changes to the API.

Major version

The major version number of the REST API appears in the REST URL. Currently, HEROIC only supports the v7 major version. For example, GET https://api.heroic.com/v7.

Breach model

The data breach comprises several attributes that describes the breach, The attributes may potentially increase in the future without requiring versioning of the API. Presently, the attributes include:

Attribute Type Description
uuid UUID Unique identifier for each data breach.
sourceName String A distinctive title for the breach that can be shown to end users. It remains exclusive to each breach, although specific values may be subject to modification in the future (for instance, if another breach happens involving an organization already present in the system). If a constant value is needed to refer to the breach, please use the "uuid" attribute instead.
siteDomain String The domain associated with the main website where the breach took place. This information can be utilized to identify any other assets that external systems may have related to the website.
dateAdded String The date the breach was added to the system, specified in ISO 8601 format
dateLeaked String The date of the original breach occurrence (without specifying the time) in ISO 8601 format. Please note that this date may not always be entirely accurate, as breaches are often discovered and reported significantly later than the actual incident. Therefore, it is advisable to consider this attribute as a reference rather than a definitive value
category String[] Theme or the niche of website based on their content, purpose, or subject matter.
country String Geographic location or country associated with a particular website. It indicates the country in which the website is registered, hosted, or primarily operates from
language String Primary language used for the content and communication on a particular website. It denotes the language in which the website's text, labels, menus, and other textual elements are presented.
passwordType String The hashing algorithm used to store and authenticate passwords.
leakedDataTypes String[] Leaked data types refer to the various types of personal or sensitive information that can be exposed or compromised in a data breach or leak. Some common examples of leaked data types include Email address, Phone number, IP Address, Password, Credit card details etc.
isVerified Boolean False implies that the breach is classified as unverified. An unverified breach does not necessarily originate from the specified website and may not have been a result of hacking. However, unverified breaches are included in HEROIC when there is a reasonable level of confidence that a substantial portion of the data is genuine.
isSensitive Boolean A Breach that consists sensitive information such as passwords, locations, financial information. Such data breaches are not shared publicly to all.
description String Refers to a summary or explanation of a data breach that has occurred. It provides relevant details and information about the breach, typically including Nature of breach, Scope and impact, Data exposed, Recommendations, Announcements made by the target website company etc.
pwnedCount Integer Number of exposed in the data breach.
heroicArticle String A Link to an article or blog authored by HEROIC, intended to provide a concise summary and assist users in comprehending the details of the breach.

Data breaches

APIs for the Data breaches.

Get all breaches.

Returns an array of all the breaches HEROIC has discovered.

query Parameters
number_of_records
any
Example: number_of_records=12

Optional parameter to limit the number of breaches that needs to be returned. If you don't pass this parameter, All the breaches would be returned

Responses

Request samples 

curl -X GET "https://api.heroic.com/v7/breaches" \
  -H "Content-Type: application/json" \
  -H "api-key: YOUR_API_KEY"

Response samples

Content type
application/json
[
  • {
    }
]

Get breach details

Provides information associated with a breach. Requires UUID as a parameter.

path Parameters
uuid
any
Example: f5d77b03-44b4-11eb-9442-1d5c76d5a110

UUID of the data breach you wish to get the details for.

Responses

Request samples 

curl -X GET "https://api.heroic.com/v7/breaches/{uuid}" \
  -H "Content-Type: application/json" \
  -H "api-key: YOUR_API_KEY"

Response samples

Content type
application/json
{
  • "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 Addresss, Phone",
  • "heroic_article_url": null,
  • "description": "The hacker likely responsible for Ledger’s security breach in July recently dumped a large amount of data exposing the personal information of over 270,000 customers, including phone numbers and physical addresses. The leak also included 1 million emails of Ledger wallet owners and customers that were signed up to the company’s newsletter service.\nthe hacker presumably responsible for breaching the Ledger e-commerce database back in July dumped the personal information of thousands of affected users online. The company was blamed on social media for not providing better protection of user data and downplaying the extent of the initial breach. At the time, the hardware wallet maker declared that only 9,500 customers were affected by the security breach.\n",
  • "pwned_count": 1075382
}

Breach Search

Breach search API allows you to search for the breach details of an Email, IP Address, Phone number etc.

query Parameters
type
required
any
Example: type=email

Account Type Filter, Available values are one of these email , emaildomain , phonenumber , username , ipaddress.

account
required
any
Example: account=myemail@example.com

Account name as per selected account type.

paging_token
any

Optional Field Required For pagination, value will be received in first search response data.

header Parameters
api-key
required
any

key for Authentication API Token.

Responses

Request samples 

curl -X GET "https://api.heroic.com/v7/breach-search" \
  -H "Content-Type: application/json" \
  -H "api-key: YOUR_API_KEY"

Response samples

Content type
application/json
{
  • "records_found": 12,
  • "pagination_token": "0053001032e271c0ddeb11ed8a50195359d257484062633566646662383939636438356362623630343361663638656663353038393939333131346166633061393937306331626132643632623633623065383132f07ffffff5f07ffffff110",
  • "data": [
    ]
}