BreachAlarm API

BreachAlarm offers an Application Programming Interface (API) accessible via Secure HTTP, which enables third parties to check the breach status of email addresses and/or domain names. Optionally, API users may also obtain a history of past breaches in which a given email address or domain name was involved.

The BreachAlarm API is a paid service. For pricing, please contact support@breachalarm.com.

This page provides detailed technical API documentation, to enable potential consumers to evaluate the service, and as a reference for developers integrating their application with the API.

Contents


Accessing the API

The BreachAlarm API (v1) may be accessed by sending Secure HTTP GET requests to URLs in the following format:

https://breachalarm.com/api/v1/<resource>/<identifier>

For example, to check the breach status of the email address example@example.com, you would send the following request:

GET https://breachalarm.com/api/v1/breachedemails/example%40example.com

Note: If you require the ability to specify the API version (v1) without including it in the URL (i.e. via an Accept or Accept-Version header, or ?apiver URL parameter), please contact us.

API Keys

As the API is a paid service, all requests must be accompanied by a valid API key. You must supply this key in a Api-Key HTTP header with your request:

GET https://breachalarm.com/api/v1/<resource>/<identifier>
Api-Key: <your key>

Requests without an API key, or with an invalid API key will receive an HTTP 401 Unauthorized response.

If you require a limited API key for use in development, please contact us.


API Endpoints

Breached Emails

You may check the breach status of a particular email address. The response will indicate the number of times the address has been included in a breach, and the date of the most recent breach that included the address.

GET https://breachalarm.com/api/v1/breachedemails/<email>

The email address must be URL-encoded (in particular, the @ character must be escaped as %40). For example, to check the breach status of example@example.com:

GET https://breachalarm.com/api/v1/breachedemails/example%40example.com

If you prefer not to send the actual email address to BreachAlarm, you can send the SHA1 hash of the email address you wish to check instead. Again, for example@example.com:

GET https://breachalarm.com/api/v1/breachedemails/914fec35ce8bfa1a067581032f26b053591ee38a

Important: Make sure the email address is trimmed of whitespace and converted to lowercase before you hash it.

Note: BreachAlarm is unable to verify that a given SHA1 hash corresponds to a valid email address; therefore, it is your responsibility to validate the input to the hash. Checking the hash of an invalid email address will simply return a result indicating the address is not compromised. Such requests will count against your API usage.

Parameters

If you wish, you can request that the response include the detailed breach history for the email address.

Parameter Example Description
history ?history=true Response includes detailed breach history.

Response

The response to a successful request will be a JSON-formatted Result.


Breached Domains

You may check the breach status of a particular domain name. The response will indicate the number of times that any email address with that domain name has been included in a breach, and the date of the most recent breach that included an address address with that domain.

GET https://breachalarm.com/api/v1/breacheddomains/<domain>

The domain name must be URL-encoded (although, it is unusual for domain names to include characters that require escaping). For example, to check the breach status of example.com:

GET https://breachalarm.com/api/v1/breacheddomains/example.com

If you prefer not to send the actual domain name to BreachAlarm, you can send the SHA1 hash of the domain you wish to check instead. Again, for example.com:

GET https://breachalarm.com/api/v1/breacheddomains/0caaf24ab1a0c33440c06afe99df986365b0781f

Important: Make sure the domain name is trimmed of whitespace and converted to lowercase before you hash it.

Note: BreachAlarm is unable to verify that a given SHA1 hash corresponds to a valid domain name; therefore, it is your responsibility to validate the input to the hash. Checking the hash of an invalid domain name will simply return a result indicating the domain is not compromised. Such requests will count against your API usage.

Parameters

If you wish, you can request that the response include the detailed breach history for the domain name.

Parameter Example Description
history ?history=true Response includes detailed breach history.

Response

The response to a successful request will be a JSON-formatted Result.


Data Models

Result model

Successful requests to the Breached Emails and Breached Domains API endpoints will return a JSON-formatted result, containing the following attributes:

Attribute Type Description
count integer The number of breaches in which the requested credential has appeared.
last_seen string (If count > 0.) The date (YYYY-MM-DD) of the most recent breach in which the requested credential has appeared.
breach_history array (If requested.) Details of the breaches in which the requested credential has appeared. Each entry in the array is presented using the History model.

Note: Breach history may include fewer breaches than indicated by the count attribute. This is because BreachAlarm has only tracked detailed breach history since late 2014. Breaches before this time do not appear in breach history, but are reflected in count.

Important: Additional attributes may be added to this model in the current API version. Clients should therefore handle unexpected attributes without error.

Examples

When the requested credential has not appeared in any breaches, the following Result is returned:

{"count": 0}

If the requested credential has appeared in five breaches, most recently on April 1st, 2015, the following Result is returned:

{"count": 5, "last_seen": "2015-04-01"}

If requested, a response may include detailed breach history (see History):

{
  "count": 5,
  "last_seen": "2015-04-01",
  "breach_history": [
    {
      "id": "123",
      "source": "Adobe",
      "hacker": "LulzSec",
      "date": "2015-04-01",
      "count": 4
    },
    {
      "id": "456",
      "source": "eHarmony",
      "hacker": "Unknown",
      "date": "2014-01-01",
      "count": 1
    }
  ]
}

History model

When requested, the Result model may contain detailed breach history, which is represented by an array of breaches in this format:

Attribute Type Description
id string A unique and permanent identifier for the breach.

Note: Currently this is an integer presented as a string, but this is likely to change to something more descriptive for newly-added breaches in the future.
source string The name of the website or company from which the breached data were stolen.
hacker string The name of the hacker or group believed to be responsible for the breach.
date string The date (YYYY-MM-DD) that the breach data was released online.
count integer The number of times the requested credential appeared in this breach.

Important: Additional attributes may be added to this model in the current API version. Clients should therefore handle unexpected attributes without error.

Examples

See examples for the Result model.


Additional Information

Response Status Codes

Successful API requests will usually return a 200 Success response status. The API will return other status codes under various circumstances. In general, the response will also include a message with more information.

This table provides a summary of the HTTP status codes you may expect to receive from the API:

Code Meaning Description
200 Success The request was successful and the response body will contain the requested data.
400 Bad request The supplied email address, domain name, or SHA1 hash was not in a valid format. Check that the value was URL-encoded (e.g. @ must be represented as %40 in a URL).
401 Unauthorized No API key was supplied with the request, or the supplied API key is invalid or expired.
403 Forbidden The supplied API key is not allowed to perform the request (e.g. your account may not be authorized to perform domain checks, or to obtain detailed breach history). Contact us if you’d like to upgrade your account.
404 Not Found You requested a resource not supported by this API. Check the spelling of your URL.
500 Internal Server Error (We hope you never get this.) The API failed with an unexpected error. BreachAlarm staff is notified of any such failure and will look into it, but please contact us if you want to be notified of our progress correcting a specific error.
501 Bad Gateway (We really hope you never get this.) The BreachAlarm API (and likely the BreachAlarm website too) is down. Rest assured, we’re working on it!

Cross-Origin Resource Sharing (CORS)

We do not anticipate the BreachAlarm API to be used for in-browser applications; therefore, CORS (which would allow client JavaScript running in a browser on another domain to issue requests to the BreachAlarm API) is not currently supported.

We are happy to implement this if the scenario is reasonable. If you require CORS support for your application, please contact us with the details.