You're reading about v4 of the API which is presently the current version and contains breaking changes over previous versions for searching breaches via email address.
The most common use of the API is to return a list of all breaches a particular account has been involved in. The API takes a single parameter which is the account to be searched for. Account should be a valid email address or alphanumeric username. The account is not case sensitive. This is an unauthenticated API.
GET https://hackcheck.woventeams.com/api/v4/breachedaccount/{account}
Semantic HTTP response codes are used to indicate the result of the search:
| Code | Description |
| 200 | OK — everything worked and here's a JSON array of hacked sites for the account |
| 400 | Bad request — the account does not comply with an acceptable format (i.e. it's an empty string) |
| 404 | Not found — the account could not be found and has therefore not been hacked to our knowledge |
| 500 | Server error |
Each breach contains a number of attributes describing the incident. In the future, these attributes may expand without the API being versioned. The current attributes are:
| Attribute | Type | Description |
| Name | string | A Pascal-cased name representing the breach which is unique across all other breaches. This value never changes and may be used to name dependent assets (such as images) but should not be shown directly to end users (see the "Title" attribute instead). |
| Title | string | A descriptive title for the breach suitable for displaying to end users. It's unique across all breaches but individual values may change in the future (i.e. if another breach occurs against an organisation already in the system). If a stable value is required to reference the breach, refer to the "Name" attribute instead. |
| Domain | string | The domain of the primary website the breach occurred on. This may be used for identifying other assets external systems may have for the site. |
| BreachDate | date | The date (with no time) the breach originally occurred on in ISO 8601 format. This is not always accurate — frequently breaches are discovered and reported long after the original incident. Use this attribute as a guide only. |
| AddedDate | datetime | The date and time (precision to the minute) the breach was added to the system in ISO 8601 format. |
| ModifiedDate | datetime | The date and time (precision to the minute) the breach was modified in ISO 8601 format. This will only differ from the AddedDate attribute if other attributes represented here are changed or data in the breach itself is changed (i.e. additional data is identified and loaded). It is always either equal to or greater then the AddedDate attribute, never less than. |
| Description | string | Contains an overview of the breach represented in HTML markup. The description may include markup such as emphasis and strong tags as well as hyperlinks. |
| DataClasses | string[] | This attribute describes the nature of the data compromised in the breach and contains an alphabetically ordered string array of impacted data classes. |
| IsVerified | boolean | Indicates that the breach is considered unverified. An unverified breach may not have been hacked from the indicated website. An unverified breach is still loaded into Hack Check when there's sufficient confidence that a significant portion of the data is legitimate. |
| IsSensitive | boolean | Indicates if the breach is considered sensitive. |
All responses returns breach models either in a collection (breaches for account or all breaches in the system) or as a single item (retrieving a breach by name). When a collection is returned, it's sorted alphabetically by the title of the breach.
[
{
"Name": "Adobe",
"Title": "Adobe",
"Domain": "adobe.com",
"BreachDate": "2013-10-04",
"AddedDate": "2013-12-04T00:00Z",
"ModifiedDate": "2013-12-04T00:00Z",
"Description": "In October 2013, 153 million Adobe accounts were breached with each containing an internal ID, username, email ...",
"DataClasses": ["Email addresses","Password hints","Passwords","Usernames"],
"IsVerified": True,
"IsSensitive": False
},
{
"Name": "BattlefieldHeroes",
"Title": "Battlefield Heroes",
"Domain": "battlefieldheroes.com",
"BreachDate": "2011-06-26",
"AddedDate": "2014-01-23T13:10Z",
"ModifiedDate": "2014-01-23T13:10Z",
"Description": "In June 2011 as part of a final breached data dump, the hacker collective "LulzSec" obtained and usernames and ...",
"DataClasses": ["Passwords","Usernames"],
"IsVerified": True,
"IsSensitive": False
},
...
]
All API endpoints must be invoked over HTTPS. Any requests over HTTP will result in a 301 response with a redirect to the same path on the secure scheme. Only TLS versions 1.2 and 1.3 are supported; older versions of the protocol will not allow a connection to be made.
CORS is supported for non-authenticated APIs. When supported, it accepts all origins — you can hit the API from websites on any other domain.
Woven has used the pattern of the API and response values from haveibeenpwned.com as part of this work simulation API.