Exposure Alerts Service API


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. 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 PasswordPing so you can be notified about future exposures that involve them. The notifications will be made to a webhook URL you establish with PasswordPing. See the Webhooks section for more details. For general information on webhooks, see webhooks.org.

Available Calls

POST Alert Subscriptions for Users


https://api.passwordping.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 PasswordPing for general instructions on using the API.

Request

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 email addresses you wish to setup Exposure alerts for.

Response

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.

Response Body

Member Type Description
added integer The number of new alert subscriptions created.
alreadyExisted integer The number of alert subscriptions which already existed.

Example

Request
curl --header "authorization: basic {your auth string}" --header "content-type: application/json" --data '{ "usernameHashes": [ "e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855" ] }' https://api.passwordping.com/alert-subscriptions
Response
{ 
  "added": 1,
  "alreadyExisted": 0
}

DELETE Alert Subscriptions for Users


https://api.passwordping.com/alert-subscriptions

Allows you to delete Exposure alert subscriptions for one or more email addresses.

See Using PasswordPing for general instructions on using the API.

Request

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 email addresses you wish to remove Exposure alerts for.

Response

Response Description
201 The call was successful. You will no longer receive alerts for the provided email addresses.

Response Body

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.

Example

Request
curl -X "DELETE" --header "authorization: basic {your auth string}" --header "content-type: application/json" --data '{ "usernameHashes": [ "e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855" ] }' https://api.passwordping.com/alert-subscriptions
Response
{ 
  "deleted": 1,
  "notFound": 0
}

GET Exposure Alert Subscription for Users


https://api.passwordping.com/alert-subscriptions

Returns whether a alert subscription exists for a given email hash.

See Using PasswordPing for general instructions on using the API.

Request

Parameter Type Description
usernameHash string A SHA256 hash of the email address to check.

Response

Response Description
200 An alert subscription exists for the provided email hash.
404 The alert subscription does not exist for the provided email hash.

Response Body

Member Type Description
usernameHash string The email hash that is subscribed for alerts

Example

Request
curl --header "authorization: basic {your auth string}" "https://api.passwordping.com/alert-subscriptions?usernameHash=e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855"
Response
{ 
  "usernameHash": "e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855"
}

GET All Exposure Alert Subscriptions for Users


https://api.passwordping.com/alert-subscriptions

Returns a paginated list of all user-level alert subscriptions for your account.

See Using PasswordPing for general instructions on using the API.

Request

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

Response Description
200 The response body contains the requested page of results.

Response Body

Member Type Description
count integer The total number of user alert subscription records available.
usernameHashes string[] An array of SHA256 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.

Example

Request
curl --header "authorization: basic {your auth string}" "https://api.passwordping.com/alert-subscriptions?pageSize=2"
Response
{ 
  "count": 4,
  "usernameHashes": [
      "e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855",
      "48ad38875d11ac5327167a79303f18ac85b878198f71434daa82a2884ee39e3a"
  ],
  "pagingToken": "5854757a7750ac6c4230f656"
}

POST Alert Subscriptions for Domains


https://api.passwordping.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 PasswordPing for general instructions on using the API.

Request

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

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.

Response Body

Member Type Description
added integer The number of new alert subscriptions created.
alreadyExisted integer The number of alert subscriptions which already existed.

Example

Request
curl --header "authorization: basic {your auth string}" --header "content-type: application/json" --data '{ "domains": [ "passwordping.com", "anotherdomain.co.uk" ] }' https://api.passwordping.com/alert-subscriptions
Response
{ 
  "added": 1,
  "alreadyExisted": 0
}

DELETE Alert Subscriptions for Domains


https://api.passwordping.com/alert-subscriptions

Allows you to delete Exposure alert subscriptions for one or more email domains.

See Using PasswordPing for general instructions on using the API.

Request

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

Response Description
201 The call was successful. You will no longer receive alerts for the provided domains.

Response Body

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.

Example

Request
curl -X "DELETE" --header "authorization: basic {your auth string}" --header "content-type: application/json" --data '{ "domains": [ "passwordping.com", "anotherdomain.co.uk" ] }' https://api.passwordping.com/alert-subscriptions
Response
{ 
  "deleted": 1,
  "notFound": 0
}

GET Exposure Alert Subscription for Domains


https://api.passwordping.com/alert-subscriptions

Returns whether an alert subscription exists for a given email domain.

See Using PasswordPing for general instructions on using the API.

Request

Parameter Type Description
domain string The domain to check.

Response

Response Description
200 An alert subscription exists for the provided email hash.
404 The alert subscription does not exist for the provided email hash.

Response Body

Member Type Description
usernameHash string The email hash that is subscribed for alerts

Example

Request
curl --header "authorization: basic {your auth string}" "https://api.passwordping.com/alert-subscriptions?domain=passwordping.com"
Response
{ 
  "domain": "passwordping.com"
}

GET All Exposure Alert Subscriptions for Domains


https://api.passwordping.com/alert-subscriptions

Returns a paginated list of all domain alert subscriptions for your account.

See Using PasswordPing for general instructions on using the API.

Request

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

Response Description
200 The response body contains the requested page of results.

Response Body

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.

Example

Request
curl --header "authorization: basic {your auth string}" "https://api.passwordping.com/alert-subscriptions?domains=1&pageSize=2"
Response
{ 
  "count": 4,
  "domains": [
      "passwordping.com",
      "anotherdomain.co.uk"
  ],
  "pagingToken": "5854757a7750ac6c4230f656"
}

Webhooks


To use the Exposure Alerts Service API, it is necessary to setup your Webhook with PasswordPing. 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&nbsp Webhook Secret which will be passed to your endpoint via basic HTTP authentication.

Webhook POST Body

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"
}

Webhook Authentication

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 PasswordPing. These will be passed as a standard basic authentication HTTP header in a similar manner to how you construct authentication headers to call the PasswordPing 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})

Testing Your Implementation

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.

GET Webhook Test


https://api.passwordping.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 PasswordPing.

See Using PasswordPing for general instructions on using the API.

Request

There are no request parameters required for this call.

Response

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.

Example

curl --header "authorization: basic {your auth string}" --header "content-type: application/json" https://api.passwordping.com/webhook-test