Exposures 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 Exposures API allows you to lookup all of the credentials Exposures that have been found for a given username and obtain the detailed information about each Exposure. An example use case would be to monitor for new Exposures for a given group of users and send them notifications so that they may reset their credentials on the compromised site.

Available Calls

GET Exposures For User


https://api.passwordping.com/exposures

Returns all of the credentials Exposures that have been found for a given user.

See Using PasswordPing for general instructions on using the API.

Request

Parameter Type Description
username string The username or email address of the user OR a SHA256 hash of the username/email address (recommended)
includeExposureDetails int (Optional) If this parameter is specified and non-zero, the results will include the exposure details inline, rather than just the IDs. In this case the exposures array in the response will contain an array of ExposureDetails objects

Response

Response Description
200 The username was found and the associated Exposures are in the response body
404 The username was not found in PasswordPing’s database and has no Exposures associated with it.

Response Body

The response body contains an array of the Exposure IDs this user has associated with it. These IDs can be used with the Exposure Details API to get additional information about each Exposure.

Member Type Description
count integer The number of items in the exposures array
exposures string[] An array of Exposure IDs. Can be used with the Exposure Details call to retrieve additional info. If the includeExposureDetails parameter is used, it will instead contain an array of ExposureDetails objects.

Example

Request
curl --header "authorization: basic {your auth string}" "https://api.passwordping.com/exposures?username=sample@email.tst"
Response
{ 
  "count": 3,
  "exposures": [
      "57dc11964d6db21300991b78",
      "5805029914f33808dc802ff7",
      "57ffcf3c1395c80b30dd4429"
  ]
}

GET Exposures For Domain


https://api.passwordping.com/exposures

Returns all of the credentials Exposures that have been found for users with an email address on a given domain.

NOTE: Your API key must have permissions to make this call for a given domain. This generally requires verification you own the domain. Please Contact Us to have a domain added to your account.

See Using PasswordPing for general instructions on using the API.

Request

Parameter Type Description
domain string The domain to return exposures for (e.g. “passwordping.com”)
includeExposureDetails int (Optional) If this parameter is specified and non-zero, the results will include the exposure details inline, rather than just the IDs. In this case the exposures array in the response will contain an array of ExposureDetails objects

Response

Response Description
200 Exposures for the domain were found and the associated Exposures are in the response body
404 The domain was not found in PasswordPing’s database and has no Exposures associated with it.

Response Body

The response body contains an array of the Exposure IDs this domain has associated with it. These IDs can be used with the Exposure Details API to get additional information about each Exposure.

Member Type Description
count integer The number of items in the exposures array
exposures string[] An array of Exposure IDs. Can be used with the Exposure Details call to retrieve additional info. If the includeExposureDetails parameter is used, this will instead contain an array of ExposureDetails objects.

Example

Request
curl --header "authorization: basic {your auth string}" "https://api.passwordping.com/exposures?domain=email.tst"
Response
{ 
  "count": 4,
  "exposures": [
      "57ffcf3c1395c80b30dd4429",
      "5805029914f33808dc802ff7",
      "598e5b844eb6d82ea07c5783",
      "57dc11964d6db21300991b78"
  ]
}

GET Exposed Users For Domain


https://api.passwordping.com/exposures

Returns a paginated list of all of the users exposed on a given domain, along with the associated exposures for each user.

NOTE: Your API key must have permissions to make this call for a given domain. This generally requires verification you own the domain. Please Contact Us to have a domain added to your account.

See Using PasswordPing for general instructions on using the API.

Request

Parameter Type Description
accountDomain string The domain to return exposed users for (e.g. “passwordping.com”)
pageSize integer The number of results to return in a single call
pagingToken string For each call to the API, if there are additional 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 Exposed users for the domain were found and the requested page is in the response body
404 The domain was not found in PasswordPing’s database and has no exposed users associated with it.

Response Body

The response body contains a paginated array of the exposed users this domain has associated with it. Each user object has an array of Exposure IDs. These IDs can be used with the Exposure Details API to get additional information about each Exposure. It is recommended to cache the details of the Exposure after retrieval to minimize the number of API calls made.

Member Type Description
count integer The total number of exposed user records available.
users ExposedUser[] An array of ExposedUser objects containing the results for the current page.
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.

ExposedUser:
Member Type Description
username string The email address of the user who was exposed
exposures string[] An array of Exposure IDs. Can be used with the Exposure Details call to retrieve additional info.

Example

Request
curl --header "authorization: basic {your auth string}" "https://api.passwordping.com/exposures?accountDomain=email.tst&pageSize=2"
Response
{ 
  "count": 12,
  "users": [
    {
      "username": "sample@email.tst",
      "exposures": [
        "57dc11964d6db21300991b78",
        "5805029914f33808dc802ff7",
        "57ffcf3c1395c80b30dd4429",
        "598e5b844eb6d82ea07c5783",
        "59bbf691e5017d2dc8a96eab",
        "59bc2016e5017d2dc8bdc36a",
        "59bebae9e5017d2dc85fc2ab"
        "57ffcf3c1395c80b30dd4429",
        "5805029914f33808dc802ff7",
        "598e5b844eb6d82ea07c5783",
        "57dc11964d6db21300991b78"
      ]
    },
    {
      "username": "xxxxxxxxxx@email.tst",
      "exposures": [
        "5805029914f33808dc802ff7"
      ]
    }
  ],
  "pagingToken": "58055cd814f3380a94324adc"
}


GET Exposure Details


https://api.passwordping.com/exposures

Returns the detailed information for a credentials Exposure. The responses to this call can and should be cached
to limit the number of calls made. The Exposure details are not typically expected to change over time, so they
can be retained for relatively long periods of time, e.g. for up to 30 days.

See Using PasswordPing for general instructions on using the API.

Request

Parameter Type Description
id string The ID of the Exposure

Response

Response Description
200 The response body contains the details of the Exposure
404 The requested Exposure was not found

Response Body

Member Type Description
id string The ID of the Exposure
title string Title of the exposure – for breaches, the domain of the origin site
entries integer The number of credentials found in the exposure
date date The date the exposure occurred, as much as is known. The value is as follows:

  • null if the date is not known
  • Month and day set to December 31st, if only the year is known (e.g. “2015-12-31” if Exposure date was sometime in 2015)
  • Day set to the first of the month if only the month is known (e.g. “2015-06-01” if Exposure date was sometime in June 2015)
  • Otherwise, exact date if exact date is known, including time
category string A category for the origin website, if the exposure was a data breach.
passwordType string The format of the passwords in the Exposure, e.g. “Cleartext”, “MD5”, “BCrypt”, etc.
exposedData string[] The types of user data which were present in the Exposure, e.g. “Emails”, “Passwords”, “Physical Addresses”, “Phone Numbers”, etc.
dateAdded date The date the Exposure was found and added to the PasswordPing database.
sourceURLs string[] An array of URLs the data was found at. Only present for some types of Exposures, like when the source was a paste site.
domainsAffected integer The number of unique email address domains in this Exposure. So, for instance, if the Exposure only contained “gmail.com” and “yahoo.com” email addresses, this number would be 2.

Example

Request
curl --header "authorization: basic {your auth string}" "https://api.passwordping.com/exposures?id=57dc11964d6db21300991b78"
Response
{ 
  "id": "57dc11964d6db21300991b78",
  "title": "funsurveys.net",
  "entries": 5123,
  "date": "2015-05-01T00:00:00.000Z",
  "category": "Surveys",
  "passwordType": "Cleartext",
  "exposedData": [
      "Emails",
      "Passwords"
  ],
  "dateAdded": "2016-09-16T15:36:54.000Z"
  "sourceURLs": [],
  "domainsAffected": 683
}