Documentation for Product Version:
An Exposure refers to any unintended release of user credentials on the Internet. This could be due to a data breach at a site, malware that has captured user credentials, a phishing site which has been capturing user credentials, etc. An Exposure occurs when this stolen credential data is then posted or shared in some public or private venue. Enzoic (formerly PasswordPing) routinely scours the web looking for this data and catalogues it into its database. Every time a new list of credentials is found, this is added as a new Exposure in our database.
The Exposure Alerts Service API allows you to register email addresses with Enzoic so you can be notified about future exposures that involve them. The notifications will be made to a webhook URL you establish with Enzoic. See the Webhooks section for more details. For general information on webhooks, see webhooks.org.
https://api.enzoic.com/alert-subscriptions
Allows you to setup a new exposure alert subscription for one or more email addresses. For additional privacy and security, emails are submitted as SHA256 hashes.
See Using Enzoic for general instructions on using the API.
Request parameters should be passed as a JSON object in the request body.
| Parameter | Type | Description |
|---|---|---|
| usernameHashes | string or string[] | A single SHA256 hash or an array of SHA256 hashes containing the lowercase email addresses you wish to setup Exposure alerts for. |
| Response | Description |
|---|---|
| 201 | The call was successful. Your webhook will now be called whenever one of the submitted email addresses is involved in a new Exposure. |
| Member | Type | Description |
|---|---|---|
| added | integer | The number of new alert subscriptions created. |
| alreadyExisted | integer | The number of alert subscriptions which already existed. |
curl --header "authorization: basic {your auth string}" --header "content-type: application/json" --data '{ "usernameHashes": [ "e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855" ] }' https://api.enzoic.com/alert-subscriptions
{
"added": 1,
"alreadyExisted": 0
}
https://api.enzoic.com/alert-subscriptions
Allows you to delete Exposure alert subscriptions for one or more email addresses.
See Using Enzoic for general instructions on using the API.
Request parameters should be passed as a JSON object in the request body.
| Parameter | Type | Description |
|---|---|---|
| usernameHashes | string or string[] | A single SHA256 hash or an array of SHA256 hashes containing the lowercase email addresses you wish to remove Exposure alerts for. |
| Response | Description |
|---|---|
| 201 | The call was successful. You will no longer receive alerts for the provided email addresses. |
| Member | Type | Description |
|---|---|---|
| deleted | integer | The number of alert subscriptions deleted. |
| notFound | integer | The number of provided email hashes which were not found in the alert subscriptions table. |
curl -X "DELETE" --header "authorization: basic {your auth string}" --header "content-type: application/json" --data '{ "usernameHashes": [ "e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855" ] }' https://api.enzoic.com/alert-subscriptions
{
"deleted": 1,
"notFound": 0
}
https://api.enzoic.com/alert-subscriptions
Returns whether a alert subscription exists for a given email hash.
See Using Enzoic for general instructions on using the API.
| Parameter | Type | Description |
|---|---|---|
| usernameHash | string | A SHA256 hash of the lowercase email address to check. |
| Response | Description |
|---|---|
| 200 | An alert subscription exists for the provided email hash. |
| 404 | The alert subscription does not exist for the provided email hash. |
| Member | Type | Description |
|---|---|---|
| usernameHash | string | The email hash that is subscribed for alerts |
curl --header "authorization: basic {your auth string}" "https://api.enzoic.com/alert-subscriptions?usernameHash=e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855"
{
"usernameHash": "e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855"
}
https://api.enzoic.com/alert-subscriptions
Returns a paginated list of all user-level alert subscriptions for your account.
See Using Enzoic for general instructions on using the API.
| Parameter | Type | Description |
|---|---|---|
| pageSize | integer | The number of results to return in a single call |
| pagingToken | string | For each call to the API, if there are more pages of results available then a pagingToken will be returned. Pass the pagingToken in via this parameter to retrieve the subsequent page of results. Should be left off for the initial call to the API. |
| Response | Description |
|---|---|
| 200 | The response body contains the requested page of results. |
| Member | Type | Description |
|---|---|---|
| count | integer | The total number of user alert subscription records available. |
| usernameHashes | string[] | An array of SHA256 lowercase email address hashes which are currently subscribed for alerts. |
| pagingToken | string | Present when there are additional pages of results available. Pass this token in on a subsequent call to fetch the next page of results. |
curl --header "authorization: basic {your auth string}" "https://api.enzoic.com/alert-subscriptions?pageSize=2"
{
"count": 4,
"usernameHashes": [
"e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855",
"48ad38875d11ac5327167a79303f18ac85b878198f71434daa82a2884ee39e3a"
],
"pagingToken": "5854757a7750ac6c4230f656"
}
https://api.enzoic.com/alert-subscriptions
Allows you to setup a new exposure alert subscription for one or more email domains. Note that you must be pre-approved and verified to subscribe for the domain(s) you are registering. Please Contact Us for assistance.
See Using Enzoic for general instructions on using the API.
Request parameters should be passed as a JSON object in the request body.
| Parameter | Type | Description |
|---|---|---|
| domains | string or string[] | A single email domain or an array containing the domains you wish to setup Exposure alerts for. |
| Response | Description |
|---|---|
| 201 | The call was successful. Your webhook will now be called whenever an email address on the submitted domains is involved in a new Exposure. |
| Member | Type | Description |
|---|---|---|
| added | integer | The number of new alert subscriptions created. |
| alreadyExisted | integer | The number of alert subscriptions which already existed. |
curl --header "authorization: basic {your auth string}" --header "content-type: application/json" --data '{ "domains": [ "enzoic.com", "anotherdomain.co.uk" ] }' https://api.enzoic.com/alert-subscriptions
{
"added": 1,
"alreadyExisted": 0
}
https://api.enzoic.com/alert-subscriptions
Allows you to delete Exposure alert subscriptions for one or more email domains.
See Using Enzoic for general instructions on using the API.
Request parameters should be passed as a JSON object in the request body.
| Parameter | Type | Description |
|---|---|---|
| domains | string or string[] | A single email domain or an array containing the domains you wish to remove Exposure alerts for. |
| Response | Description |
|---|---|
| 201 | The call was successful. You will no longer receive alerts for the provided domains. |
| Member | Type | Description |
|---|---|---|
| deleted | integer | The number of alert subscriptions deleted. |
| notFound | integer | The number of provided domains which were not found in the alert subscriptions table. |
curl -X "DELETE" --header "authorization: basic {your auth string}" --header "content-type: application/json" --data '{ "domains": [ "enzoic.com", "anotherdomain.co.uk" ] }' https://api.enzoic.com/alert-subscriptions
{
"deleted": 1,
"notFound": 0
}
https://api.enzoic.com/alert-subscriptions
Returns whether an alert subscription exists for a given email domain.
See Using Enzoic for general instructions on using the API.
| Parameter | Type | Description |
|---|---|---|
| domain | string | The domain to check. |
| Response | Description |
|---|---|
| 200 | An alert subscription exists for the provided email hash. |
| 404 | The alert subscription does not exist for the provided email hash. |
| Member | Type | Description |
|---|---|---|
| usernameHash | string | The email hash that is subscribed for alerts |
curl --header "authorization: basic {your auth string}" "https://api.enzoic.com/alert-subscriptions?domain=enzoic.com"
{
"domain": "enzoic.com"
}
https://api.enzoic.com/alert-subscriptions
Returns a paginated list of all domain alert subscriptions for your account.
See Using Enzoic for general instructions on using the API.
| Parameter | Type | Description |
|---|---|---|
| domains | integer | Set to a non-zero value to return a list of domain alert subscriptions |
| pageSize | integer | The number of results to return in a single call |
| pagingToken | string | For each call to the API, if there are more pages of results available then a pagingToken will be returned. Pass the pagingToken in via this parameter to retrieve the subsequent page of results. Should be left off for the initial call to the API. |
| Response | Description |
|---|---|
| 200 | The response body contains the requested page of results. |
| Member | Type | Description |
|---|---|---|
| count | integer | The total number of domain alert subscription records available. |
| domains | string[] | An array of domains which are currently subscribed for alerts. |
| pagingToken | string | Present when there are additional pages of results available. Pass this token in on a subsequent call to fetch the next page of results. |
curl --header "authorization: basic {your auth string}" "https://api.enzoic.com/alert-subscriptions?domains=1&pageSize=2"
{
"count": 4,
"domains": [
"enzoic.com",
"anotherdomain.co.uk"
],
"pagingToken": "5854757a7750ac6c4230f656"
}
To use the Exposure Alerts Service API, it is necessary to setup your Webhook with Enzoic. You will need to specify a URL on your end that will be called with a POST whenever a notification is made. You will also receive a Webhook Key and Webhook Secret which will be passed to your endpoint via basic HTTP authentication.
NOTE: Webhook notifications will be sent from IP address: 52.42.159.171. You may need to update your firewall rules accordingly.
The content of the POST body for webhook notifications will be a JSON object with the members specified below:
| Member | Type | Description |
|---|---|---|
| date | date | The date/time (in GMT) that the Exposure was found |
| exposureID | string | The ID of the Exposure. This can subsequently be used with the GET Exposure Details API to retrieve additional information about the Exposure. |
| username | string | The username/email address which was exposed. |
| usernameHash | string | The SHA-256 hash of the username/email address exposed. |
An example POST body:
{
"username": "sample@email.tst",
"usernameHash": "de34a09f96a6677f8a4e0a17545a20e0b60a2f093879c82ed36cff75930d5814",
"date": "2017-01-17T04:51:05.1915231Z"
"exposureID": "583d32144d6db21a908faa11"
}
For security reasons, you should authenticate calls to your Webhook endpoint. To facilitate this, you will be provided with Webhook Key and a Webhook Secret when you configure your Webhook in Enzoic. These will be passed as a standard basic authentication HTTP header in a similar manner to how you construct authentication headers to call the Enzoic API: the Webhook Key is the username and the Webhook Secret is the password. As per the standard, the authentication header passed to your endpoint is constructed as follows:
authorization: basic Base64({Webhook Key}:{Webhook Secret})
Once you have your webhook up and publicly accessible, you can verify all is working using the Webhook Test REST Call below. This will make a POST to your URL with test data.
https://api.enzoic.com/webhook-test
This call will cause a test POST to be sent to the webhook URL registered to your account. This allows you to verify that your webhook URL is setup properly and able to receive Exposure Alerts from Enzoic.
See Using Enzoic for general instructions on using the API.
There are no request parameters required for this call.
| Response | Description |
|---|---|
| 200 | The call was successful. Your webhook should receive a test POST as a result. |
| 404 | No webhook URL is registered for your account. Contact support to have a URL added. |
curl --header "authorization: basic {your auth string}" --header "content-type: application/json" https://api.enzoic.com/webhook-test