| General Info | Before You Start | Check Emails / Domains | Monitor | Notifications |

Working with the Account

Most Breach Report API calls are only applicable to the email addresses and web domains that have been registered with the consumer's account.

This chapter describes the following API calls:

Add an email address to the account
Add a web domain to the account
Get the list of registered email addresses
Get the list of registered web domains
Remove an email address from the account
Remove a web domain from the account
Check a registered email address for data breach incidents
Check a registered web domain for compromised email addresses

Add an Email Address

Request URL: {BASE_URL}/api/v1/email/

Request method: POST

This API call accepts an email address and adds it to the Breach Report account. The BR account must be associated with the secret API key (needs to be included in the request header).

The API call returns a response code and a status message including the Email ID.

How to construct the request:

Include the API key in the request header.
Specify the email address in the request body.

Request parameters

Show the parameters.

Name	Type	Description
api-key	string	The key you can generate on the portal. Must be included in the request header.
email	string	Email address to be checked.

Code Examples

Shell command example.

curl --location --request POST '{{BASE_URL}}/api/v1/email' \
--header 'api-key: {{API_KEY}}' \
--header 'Content-Type: application/x-www-form-urlencoded' \
--data-urlencode 'email=me@vassily.pro'

JavaScript code example.

// Using fetch()
var myHeaders = new Headers();
myHeaders.append("api-key", "{{API_KEY}}");
myHeaders.append("Content-Type", "application/x-www-form-urlencoded");
var urlencoded = new URLSearchParams();
urlencoded.append("email", "test@test.com");
var requestOptions = {
  method: 'POST',
  headers: myHeaders,
  body: urlencoded,
  redirect: 'follow'
};

fetch("{{BASE_URL}}/api/v1/email", requestOptions)
  .then(response => response.text())
  .then(result => console.log(result))
  .catch(error => console.log('error', error));

Python code example.

# Using requests
import requests
url = "{{BASE_URL}}/api/v1/email"
payload = 'email=me@vassily.pro'
headers = {
  'api-key': '{{API_KEY}}',
  'Content-Type': 'application/x-www-form-urlencoded'
}
response = requests.request("POST", url, headers=headers, data = payload)
print(response.text.encode('utf8'))

Ruby code example.

require "uri"
require "net/http"

url = URI("{{BASE_URL}}/api/v1/email")

http = Net::HTTP.new(url.host, url.port);
request = Net::HTTP::Post.new(url)
request["api-key"] = "{{API_KEY}}"
request["Content-Type"] = "application/x-www-form-urlencoded"
request.body = "email=me@vassily.pro"

response = http.request(request)
puts response.read_body

Request Parameters

Show the parameters.

Name	Type	Description
api-key	string	An API key you can generate on the portal. Include this key in the request header.
email	string	Email you want to add to the account for monitoring.

Response Examples

Successfully registred an email address.

{
  "status": "success",
  "email": {
    "id": "5e550fafaab5935e61ce6ddc",
    "emailAddress": "john.smith@example.com"
  }
}

Name	Type	Description
id	string	ID of the requested email address in the Breach Report database.
emailAddress	string	The requested email address.

Cannot add a registered email address again.

{
  "status": "error",
  "message": "Email address already exists"
}

Add a Domain Name

Request URL: {BASE_URL}/api/v1/domain/

Request method: POST

This API request adds an web domain to the Breach Report account. The target Breach Report account must be identified by the API key from the request header. The API call returns a response code and a status message including the Domain ID.

Some popular internet domains (gmail.com, facebook.com and such) are included in the API stop list and cannot be added. However, if you represent one of the companies from the stop list and wish to use our service, please contact us at support@breachreport.com.

The request returns a response code and a status message.

How to construct the request:

Include the API key in the request header.
Specify the domain name in the request body.

Request Parameters

Show the parameters.

Name	Type	Description
api-key	string	The API key (generated on the portal). Must be included in the request header.
domain	string	Domain to register.

Code Examples

Shell command example.

curl --location --request POST '{{BASE_URL}}/api/v1/domain' \
--header 'api-key: {{API_KEY}}' \
--header 'Content-Type: application/x-www-form-urlencoded' \
--data-urlencode 'domain=vassily.pro'

JavaScript code example.

// Using fetch()
var myHeaders = new Headers();
myHeaders.append("api-key", "{{API_KEY}}");
myHeaders.append("Content-Type", "application/x-www-form-urlencoded");
var urlencoded = new URLSearchParams();
urlencoded.append("domain", "test.com");
var requestOptions = {
  method: 'POST',
  headers: myHeaders,
  body: urlencoded,
  redirect: 'follow'
};

fetch("{{BASE_URL}}/api/v1/domain", requestOptions)
  .then(response => response.text())
  .then(result => console.log(result))
  .catch(error => console.log('error', error));

Python code example.

# Using requests
import requests
url = "{{BASE_URL}}/api/v1/domain"
payload = 'domain=vassily.pro'
headers = {
  'api-key': '{{API_KEY}}',
  'Content-Type': 'application/x-www-form-urlencoded'
}
response = requests.request("POST", url, headers=headers, data = payload)
print(response.text.encode('utf8'))

Ruby code example.

require "uri"
require "net/http"
url = URI("{{BASE_URL}}/api/v1/domain")
http = Net::HTTP.new(url.host, url.port);
request = Net::HTTP::Post.new(url)
request["api-key"] = "{{API_KEY}}"
request["Content-Type"] = "application/x-www-form-urlencoded"
request.body = "domain=vassily.pro"
response = http.request(request)
puts response.read_body

Response Examples

Added the domain successfully.

{
  "status": "success",
  "domain": {
    "id": "5e751009aab5935e61ce6ddd",
    "domainName": "smith-example.com",
    "isVerified": false,
    "txtRecord": "brdomaincode=123542-2dfbd-5364-643535"
  }
}

Name	Type	Description
id	string	Identifier of the domain.
domainName	string	The domain name.
isVerified	boolean	Indicator of whether the domain is verified.
txtRecord	string	The verification code for your domain. [Add this code as a TXT record for your web site to validate the domain].(03-manage-emails-domains.md#verifying-a-domain).

Cannot register the same domain multiple times.

{
  "status": "error",
  "message": "Domain smith-example.com already exists."
}

Cannot register a domain that's on the stop list.

{
  "status": "error",
  "message": "You cannot add this domain to the watchlist."
}

Get the Email List

Request URL: {BASE_URL}/api/v1/email

Request method: GET

This call returns the list of email addresses previously registered under the API key owner's account.

To construct the request, include the API key in the request header.

Request Parameters

Show the parameters.

Name	Type	Description
api-key	string	An API key you can generate on the portal. Include this key in the request header.

Code Examples

Shell command example.

curl --location --request GET '{{BASE_URL}}/api/v1/email' \
--header 'api-key: {{API_KEY}}'

JavaScript code example.

// Using fetch()
var myHeaders = new Headers();
myHeaders.append("api-key", "{{API_KEY}}");
var requestOptions = {
  method: 'GET',
  headers: myHeaders,
  redirect: 'follow'
};

fetch("{{BASE_URL}}/api/v1/email", requestOptions)
  .then(response => response.text())
  .then(result => console.log(result))
  .catch(error => console.log('error', error));

Python code example.

# Using requests
import requests
url = "{{BASE_URL}}/api/v1/email"
payload = {}
headers = {
  'api-key': '{{API_KEY}}'
}
response = requests.request("GET", url, headers=headers, data = payload)
print(response.text.encode('utf8'))

Ruby code example.

require "uri"
require "net/http"
url = URI("{{BASE_URL}}/api/v1/email")
http = Net::HTTP.new(url.host, url.port);
request = Net::HTTP::Get.new(url)
request["api-key"] = "{{API_KEY}}"
response = http.request(request)
puts response.read_body

Response Examples

Returned the email list.

{
  "status": "success",
  "data": [
    {
      "id": "5e4e968511944f4cf3184eb3",
      "emailAddress": "test@test.com",
      "inWatchlist": true,
      "isAssignToDomain": false
    },
    {
      "id": "5e550fafaab5935e61ce6ddc",
      "emailAddress": "john.smith@example.com",
      "inWatchlist": false,
      "isAssignToDomain": false
    }
  ]
}

Name	Type	Description
status	string	Operation status - `success` or `error`.
data	nested object	List / array of email address items.
id	string	Email address ID.
emailAddress	integer	Plaintext email address.
inWatchlist	boolean	This logical value shows whether the email address is currently being monitored (`true` or `false`).
isAssignToDomain	boolean	This value shows whether the email address is currently assigned to a domain.

Get the Domain List

Request URL: {BASE_URL}/api/v1/domain

Request method: GET

This call returns the list of web domains attributed to the API key owner's account.

To construct the request, include the API key in the request header.

Request Parameters

Show the parameters.

Name	Type	Description
api-key	string	An API key you can generate on the portal. Must be included in the request header.

Code Examples

Shell command example.

curl --location --request GET '{{BASE_URL}}/api/v1/domain' \
--header 'api-key: {{API_KEY}}'

JavaScript code example.

// Using fetch()
var myHeaders = new Headers();
myHeaders.append("api-key", "{{API_KEY}}");

var requestOptions = {
  method: 'GET',
  headers: myHeaders,
  redirect: 'follow'
};

fetch("{{BASE_URL}}/api/v1/email", requestOptions)
  .then(response => response.text())
  .then(result => console.log(result))
  .catch(error => console.log('error', error));

Python code example.

# Using requests

Public
import requests
url = "{{BASE_URL}}/api/v1/domain"
payload = {}
headers = {
  'api-key': '{{API_KEY}}'
}
response = requests.request("GET", url, headers=headers, data = payload)
print(response.text.encode('utf8'))

Ruby code example.

require "uri"
require "net/http"

url = URI("{{BASE_URL}}/api/v1/domain")

http = Net::HTTP.new(url.host, url.port);
request = Net::HTTP::Get.new(url)
request["api-key"] = "{{API_KEY}}"

response = http.request(request)
puts response.read_body

Response Examples

Returned the domain list.

{
  "status": "success",
  "data": [
    {
      "id": "5e4e978211944f4cf3184eb4",
      "domainName": "vassily.pro",
      "inWatchlist": true,
      "emailList": [
        {
          "id": "5e4e9b0d11944f4cf3184eb7",
          "emailAddress": "me@vassily.pro"
        }
      ]
    },
    {
      "id": "5e551009aab5935e61ce6ddd",
      "domainName": "smith-example.com",
      "inWatchlist": false,
      "emailList": []
    }
  ]
}

Name	Type	Description
status	string	Operation status - success or error.
data	integer	List / array of registered web domains.
domainName	integer	Domain name.
id	string	The domain's unique identifier in the Breach Report database.
inWatchlist	boolean	Indicates whether the domain is in the watchlist (in other words, is currently monitored).
emailList	nested object	Related email addresses, if any.

Delete an Email Address

Request URL: {BASE_URL}/api/v1/email/{EMAIL_ID}

Request method: DEL

The API request accepts a previously added email address's ID from the Breach Report database and removes the associated email address from the account.

The request returns a response code and a status message.

How to construct the request:

Include the API key in the request header.
Specify the Email ID in the requested URL address.

Request Parameters

Show the parameters.

Name	Type	Description
api-key	string	An API key you can generate on the portal. Include this key in the request header.
EMAIL_ID	string	Identifier of the email address to be removed from the account.

Code Examples

Shell command example.

curl --location --request DELETE '{{BASE_URL}}/api/v1/email/5e4d65741eb6bb316c90fef2' \
--header 'api-key: {{API_KEY}}'

JavaScript code example.

// Using fetch()
var myHeaders = new Headers();
myHeaders.append("api-key", "{{API_KEY}}");
var requestOptions = {
  method: 'DELETE',
  headers: myHeaders,
  redirect: 'follow'
};

fetch("{{BASE_URL}}/api/v1/email/5e4d65741eb6bb316c90fef2", requestOptions)
  .then(response => response.text())
  .then(result => console.log(result))
  .catch(error => console.log('error', error));

Python code example.

# Using requests
import requests
url = "{{BASE_URL}}/api/v1/email/5e4d65741eb6bb316c90fef2"
payload = {}
headers = {
  'api-key': '{{API_KEY}}'
}
response = requests.request("DELETE", url, headers=headers, data = payload)
print(response.text.encode('utf8'))

Ruby code example.

require "uri"
require "net/http"
url = URI("{{BASE_URL}}/api/v1/email/5e4d65741eb6bb316c90fef2")
http = Net::HTTP.new(url.host, url.port);
request = Net::HTTP::Delete.new(url)
request["api-key"] = "{{API_KEY}}"
response = http.request(request)
puts response.read_body

Response Examples

Removed the email address successfully.

{
  "status": "success",
  "email": {
    "id": "5e4e923611944f4cf3184eb5",
    "emailAddress": "john.smith@example.com"
  }
}

Name	Type	Description
status	string	Operation result - `success` or `error`.
id	string	Email address ID in the Breach Report database.
emailAddress	boolean	Email is verified the user: True/False.

Cannot remove an email address that's not registered.

{
  "status": "error",
  "message": "Email with current id does not exist"
}

Delete a Domain

Request URL: {BASE_URL}/api/v1/domain/{DOMAIN_ID}

Request method: DEL

The API call accepts a Domain ID and removes the associated domain from the account.

The request returns a response code and a status message.

How to construct the request:

Include the API key in the request header.
Specify the domain ID in the requested URL address.

Request Parameters

Show the parameters.

Parameter	Type	Description
api-key	string	An API key you can generate on the portal. Include this key in the request header.
DOMAIN_ID	string	Identified of the domain to be deleted

Code Examples

Shell command example.

curl --location --request DELETE '{{BASE_URL}}/api/v1/domain/5e4d82332d313f32626f8481' \
--header 'api-key: {{API_KEY}}'

JavaScript code example.

// Using fetch()
var myHeaders = new Headers();
myHeaders.append("api-key", "{{API_KEY}}");
var requestOptions = {
  method: 'DELETE',
  headers: myHeaders,
  redirect: 'follow'
};

fetch("{{BASE_URL}}/api/v1/domain/5e4d82332d313f32626f8481", requestOptions)
  .then(response => response.text())
  .then(result => console.log(result))
  .catch(error => console.log('error', error));

Python code example.

# Using requests
import requests
url = "{{BASE_URL}}/api/v1/domain/5e4d82332d313f32626f8481"
payload = {}
headers = {
  'api-key': '{{API_KEY}}'
}
response = requests.request("DELETE", url, headers=headers, data = payload)
print(response.text.encode('utf8'))

Ruby code example.

require "uri"
require "net/http"
url = URI("{{BASE_URL}}/api/v1/domain/5e4d82332d313f32626f8481")
http = Net::HTTP.new(url.host, url.port);
request = Net::HTTP::Delete.new(url)
request["api-key"] = "{{API_KEY}}"
response = http.request(request)
puts response.read_body

Response Examples

Removed the domain successfully.

{
  "status": "success",
  "domain": {
    "id": "5e5643007450412325943862",
    "domainName": "test-user3.com"
  }
}

Name	Type	Description
status	string	Success or error.
id	string	Email address ID in the Breach Report database.
emailAddress	boolean	Email is verified the user: True/False.

Cannot remove a domain that's not registered.

{ "status": "error", "message": "Domain with current id does not exist" }

Check a Registered Email Address

Request URL: {BASE_URL}/api/v1/email/{EMAIL_ID}/check

Request method: GET

The request accepts an Email ID and returns information on related data breaches.

Alternatively, you may check any email address (previously added or a new one) using a hashed email address value (recommended method) or a plaintext email address.

This API call returns:

Incident count for unverified emails.
Incident count and the details for verified emails.

How to construct the request:

Include the API key in the request header.
Specify the email ID in the requested URL address.

Request Parameters

Show the parameters.

Name	Type	Description
api-key	string	An API key you can generate on the portal. Should be included in the request header.
EMAIL_ID	string	Identifier of the requested email address.

Code Examples

Shell command example.

curl --location --request POST '{{BASE_URL}}/api/v1/email/check' \
--header 'api-key: {{API_KEY}}' \
--header 'Content-Type: application/x-www-form-urlencoded' \
--data-urlencode 'email=test@test.com'

JavaScript code example.

// Using fetch()
var myHeaders = new Headers();
myHeaders.append("api-key", "{{API_KEY}}");

var requestOptions = {
  method: 'GET',
  headers: myHeaders,
  redirect: 'follow'
};

fetch("{{BASE_URL}}/api/v1/email/5e454bbb575c76a755085afe/check", requestOptions)
  .then(response => response.text())
  .then(result => console.log(result))
  .catch(error => console.log('error', error));

Python code example.

# Using requests
import requests
url = "{{BASE_URL}}/api/v1/email/check"
payload = 'email=test@test.com'
headers = {
  'api-key': '{{API_KEY}}',
  'Content-Type': 'application/x-www-form-urlencoded'
}
response = requests.request("POST", url, headers=headers, data = payload)
print(response.text.encode('utf8'))

Ruby code example.

require "uri"
require "net/http"
url = URI("{{BASE_URL}}/api/v1/email/check")
http = Net::HTTP.new(url.host, url.port);
request = Net::HTTP::Post.new(url)
request["api-key"] = "{{API_KEY}}"
request["Content-Type"] = "application/x-www-form-urlencoded"
request.body = "email=test@test.com"
response = http.request(request)
puts response.read_body

Response Examples

Found data breaches (verified email address).

{
  "email": "john.smith@example.com",
  "records": 36,
  "isAssigned": true,
  "inWatchlist": false,
  "breaches": [
    {
      "breachId": 7708,
      "title": "CouponMom.com",
      "createdAt": "2019-03-06T14:22:34.498Z",
      "compromisedAccounts": 11032696,
      "breachYear": 2014,
      "url": "https://www.couponmom.com/",
      "logo": "https://crm.breachreport.com/images/uploads/U3k2YeESa5BWQrCd.webp",
      "description": "In 2014, a file containing data from Coupon Mom website which was alegedly hacked was dumbed on the dark web. It includes 11M email addresses and plaintext passwords. Further investigation showed that the records correspond to the Armor Games breached database. The breach was announced as an exclusive leak to RaidForums website.",
      "breachDataTypes": [
        "email",
        "plaintext password"
      ]
    }
  ]
}

Found data breaches (unverified email address).

{
    "email": "test@example.com",
    "records": 34924,
    "isAssigned": false,
    "breaches": 3
}

Cannot find matches (incorrect Email ID).

{
  "status": "error",
  "message": "Email does not exist"
}

Check a Registered Domain

Request URL: {{BASE_URL}}/api/v1/domain/5e7b8b4b56274b330a50d55f/check?size={{PAGE_SIZE}}&page={{PAGE_NUM}}

Request method: GET

This API call has been updated to return information on compromised email addresses and to support output pagination.

The API call accepts:

API key
Domain ID
Page size (number of unique email addresses to include in the output)
Page number (position of the email addresses within the output)

The API call returns information on previous data breaches - including data breach information - for the domain.

How to construct the request:

Include the API key in the request header.
Specify the Domain ID, page size and page number in the requested URL.

Request Parameters

Show the parameters.

Name	Type	Description
api-key	string	An API key you can generate on the portal. Must be included in the request header.
DOMAIN_ID	string	ID of the domain to check. Must be included in the requested URL.
PAGE_SIZE	integer	Max number of email address items to output. Must be included in the requested URL.
PAGE_NUM	integer	Position of output items within the full results list. Must be included in the requested URL.

Code Examples

Shell command example.

curl --location --request GET '{{BASE_URL}}/api/v1/domain/5e580e0ad336535a8f8f66b8/check?size=10&page=1' \
--header 'api-key: {{API_KEY}}'

JavaScript code example.

// Using fetch()
var myHeaders = new Headers();
myHeaders.append("api-key", "{{API_KEY}}");
var requestOptions = {
  method: 'GET',
  headers: myHeaders,
  redirect: 'follow'
};

fetch("{{BASE_URL}}/api/enterprise/v1/domain/5e580e0ad336535a8f8f66b8/check?size=10&page=1", requestOptions)
  .then(response => response.text())
  .then(result => console.log(result))
  .catch(error => console.log('error', error));

Python code example.

# Using requests
import requests
url = "{{BASE_URL}}/api/enterprise/v1/domain/5e580e0ad336535a8f8f66b8/check?size=10&page=1"
payload = {}
headers = {
  'api-key': '{{API_KEY}}'
}
response = requests.request("GET", url, headers=headers, data = payload)
print(response.text.encode('utf8'))

Ruby code example.

require "uri"
require "net/http"
url = URI("{{BASE_URL}}/api/enterprise/v1/domain/5e580e0ad336535a8f8f66b8/check?size=10&page=1")
http = Net::HTTP.new(url.host, url.port);
request = Net::HTTP::Get.new(url)
request["api-key"] = "{{API_KEY}}"
response = http.request(request)
puts response.read_body

Response Examples

Providing data breach information for the domain.

{
  "domain": "qip.com",
  "emailsCount": 1071,
  "isAssigned": true,
  "emails": [
    {
      "emailAddress": "123qwe@qip.com",
      "breaches": [
        {
          "breachId": 11691,
          "title": "Xss.is Combolist",
          "createdAt": "2019-10-11T08:31:30.596Z",
          "compromisedAccounts": 3039418396,
          "url": "",
          "logo": "https://crm.breachreport.com/images/uploads/fvSKpyvOsgOtEejw.png",
          "description": "A stolen credentials collection surfaced on the dark web community xss.is. The largest publicly shared file to date discovered by Breach Report, containing over 3 billion user accounts. The file is comprised of pairs of users' email addresses and plaintext passwords, which were hacked from a large number of unidentified websites and then dumped together in this single database.",
          "breachDataTypes": [
            "email",
            "plaintext password"
          ]
        }
      ]
    },
    {
      "emailAddress": "-1902736@qip.com",
      "breaches": []
    }
  ],
  "size": 10,
  "page": 1
}

|Name|Type|Description|

Name	Type	Description
domain	path	string
emailsCount	int	How many known email addresses were compromised on the domain.
isAssigned	boolean	Whether an email is verified with the issuing account.
emails	list	Array / list of compromised email addresses with related data incident information.
size	int	Page size (number of email address items in the output).
page	int	Page number.
emailAddress	string	Breach update time.
breaches	DateTime	Breach added to DB time.
title	string	Breach title.
breachId	int	An ID of a breach.
createdAt	int	An ID of a breach.
compromisedAccounts	int	Number of compromised accounts in the data incident.
url	string	The link to breach news source.
description	string	Description of the breach
logo	string	Link to the breach logo on Breach Report's internal breach database.
breachDataTypes	list	List / array of compromised data / credential types (email address, hashed password and such).

Cannot find a domain with this ID.

{
  "status": "error",
  "message": "Domain does not exist"
}

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

03-manage-emails-domains.md

03-manage-emails-domains.md

| General Info | Before You Start | Check Emails / Domains | Monitor | Notifications |

Working with the Account

Add an Email Address

Request parameters

Code Examples

Request Parameters

Response Examples

Add a Domain Name

Request Parameters

Code Examples

Response Examples

Get the Email List

Request Parameters

Code Examples

Response Examples

Get the Domain List

Request Parameters

Code Examples

Response Examples

Delete an Email Address

Request Parameters

Code Examples

Response Examples

Delete a Domain

Request Parameters

Code Examples

Response Examples

Check a Registered Email Address

Request Parameters

Code Examples

Response Examples

Check a Registered Domain

Request Parameters

Code Examples

Response Examples

Files

03-manage-emails-domains.md

Latest commit

History

03-manage-emails-domains.md

File metadata and controls

| General Info | Before You Start | Check Emails / Domains | Monitor | Notifications |

Working with the Account

Add an Email Address

Request parameters

Code Examples

Request Parameters

Response Examples

Add a Domain Name

Request Parameters

Code Examples

Response Examples

Get the Email List

Request Parameters

Code Examples

Response Examples

Get the Domain List

Request Parameters

Code Examples

Response Examples

Delete an Email Address

Request Parameters

Code Examples

Response Examples

Delete a Domain

Request Parameters

Code Examples

Response Examples

Check a Registered Email Address

Request Parameters

Code Examples

Response Examples

Check a Registered Domain

Request Parameters

Code Examples

Response Examples