Provero Logo

Breach Detection

The Breach Detection API checks if an email, username, phone number, domain, or password has been compromised in known data breaches.
It provides information on the breach source and the type of data exposed.

Password lookups: when type is password, send the full SHA-1 hash of the password as the value. Do not send the plaintext password. The API uses a partial-hash lookup approach so only a small portion of the hash is used for the upstream search, with the full match confirmed server-side.

Endpoint

POST 
https://api.provero.io/api/fraud-check/breach

Headers

Authorization: Bearer REPLACE_WITH_API_TOKEN
Content-Type: application/json
Accept: application/json

Request Body

Field Type Required Description
type enum Yes Accepted values: email, username, phone, domain, password.
value string Yes The actual data item you want to check for breach exposure. For type=password, this must be the full 40-character SHA-1 hash of the password, for example 5BAA61E4C9B93F3F0682250B6CF8331B7EE68FD8.
Request Body example (JSON)
{
    "type": "string",
    "value": "string"
}

Code Examples

import requests
import hashlib

type = "email" # Replace with "email", "username", "phone", "domain", or "password"
raw_value = "support.provero.io" # Replace with the source value
value = raw_value

if type == "password":
    value = hashlib.sha1(raw_value.encode("utf-8")).hexdigest().upper()

url = "https://api.provero.io/api/fraud-check/breach"
headers = {
    "Authorization": "Bearer REPLACE_WITH_API_TOKEN",
    "Content-Type": "application/json"
}

response = requests.post(url, headers=headers, json={"type": type, "value": value})
print(response.status_code)
print(response.text)
<?php
$type = "email"; // Replace with "email", "username", "phone", "domain", or "password"
$rawValue = "support.provero.io"; // Replace with the source value
$value = $rawValue;

if ($type === "password") {
    $value = strtoupper(sha1($rawValue));
}

$curl = curl_init();
curl_setopt_array($curl, [
    CURLOPT_URL => "https://api.provero.io/api/fraud-check/breach",
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_POSTFIELDS => json_encode(['type' => $type, 'value' => $value]),
    CURLOPT_HTTPHEADER => [
        "Authorization: Bearer REPLACE_WITH_API_TOKEN",
        "Content-Type: application/json"
    ],
]);

$response = curl_exec($curl);
if (curl_errno($curl)) {
    echo 'Error:' . curl_error($curl);
}
curl_close($curl);
echo $response;
const type = "email"; // Replace with "email", "username", "phone", "domain", or "password"
const rawValue = "support.provero.io"; // Replace with the source value
const apiToken = "REPLACE_WITH_API_TOKEN";

async function sha1Hex(value) {
    if (!window.isSecureContext || !window.crypto || !window.crypto.subtle) {
        throw new Error("SHA-1 hashing requires a secure browser context (HTTPS) with Web Crypto support.");
    }

    const data = new TextEncoder().encode(value);
    const hashBuffer = await window.crypto.subtle.digest("SHA-1", data);

    return Array.from(new Uint8Array(hashBuffer))
        .map((byte) => byte.toString(16).padStart(2, "0"))
        .join("")
        .toUpperCase();
}

async function breachCheck(type, rawValue, apiToken) {
    const value = type === "password" ? await sha1Hex(rawValue) : rawValue;

    const response = await fetch("https://api.provero.io/api/fraud-check/breach", {
        method: "POST",
        headers: {
            "Authorization": `Bearer ${apiToken}`,
            "Content-Type": "application/json",
            "Accept": "application/json"
        },
        body: JSON.stringify({ type, value })
    });

    const payload = await response.json();

    if (!response.ok) {
        throw new Error(payload.message || "Breach detection request failed.");
    }

    return payload;
}

breachCheck(type, rawValue, apiToken)
    .then((result) => {
        console.log(result);
    })
    .catch((error) => {
        console.error(error);
    });
type="email" # Replace with "email", "username", "phone", "domain", or "password"
raw_value="support.provero.io" # Replace with the source value
value="$raw_value"

if [ "$type" = "password" ]; then
  value=$(printf '%s' "$raw_value" | shasum -a 1 | awk '{print toupper($1)}')
fi

curl -X POST https://api.provero.io/api/fraud-check/breach \
  -H "Authorization: Bearer REPLACE_WITH_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d "{\"type\": \"$type\", \"value\": \"$value\"}"

Response Examples

Success 
{
    "value": "requested_value",
    "type": "requested_type",
    "leaks": [
        {
            "name": "Adobe",
            "domain": "adobe.com",
            "breachDate": "2013-10-04",
            "description": "User profile and password hints were exposed."
        }
    ]
}
Application Error 
{
    "requestError": {
        "serviceException": {
            "messageId": "Error message",
            "code": "400"
        }
    }
}
Payment Required - Insufficient Balance 
{
    "message": "Insufficient balance for validation request.",
    "service": "breach-detection",
    "required_amount": "0.0060000000",
    "current_balance": "0.0000000000"
}
Validation Error - Type - Not Provided 
{
    "message": "Please provide a type.",
    "errors": {
        "email": [
            "Please provide a type."
        ]
    }
}
Validation Error - Type - Invalid Value 
{
    "message": "Type must be one of email, username, phone, domain, password.",
    "errors": {
        "type": [
            "Type must be one of email, username, phone, domain, password."
        ]
    }
}
Validation Error - Value - Not Provided 
{
    "message": "Please provide a value to search.",
    "errors": {
        "email": [
            "Please provide a value to search."
        ]
    }
}
Validation Error - Email - Invalid Value 
{
    "message": "The value field must be a valid email address.",
    "errors": {
        "type": [
            "The value field must be a valid email address."
        ]
    }
}
Validation Error - Phone - Invalid Value 
{
    "message": "The value should be a valid phone number.",
    "errors": {
        "value": [
            "The value should be a valid phone number."
        ]
    }
}
Validation Error - Domain - Invalid Value 
{
    "message": "The value must be a valid domain.",
    "errors": {
        "type": [
            "The value must be a valid domain."
        ]
    }
}
Validation Error - Password - Invalid Value 
{
    "message": "The value must be a valid 40-character SHA-1 hash.",
    "errors": {
        "value": [
            "The value must be a valid 40-character SHA-1 hash."
        ]
    }
}
Validation Error - Unsupported Type 
{
    "message": "Type must be one of email, username, phone, domain, password.",
    "errors": {
        "type": [
            "Type must be one of email, username, phone, domain, password."
        ]
    }
}

Response Body

Success structure

Field Name Type Example Always Present Description
type enum email Yes The type of data checked, matching the requests type parameter.
value string support.provero.io Yes The actual data that was checked for breaches.
leaks array [{"name":"Adobe","domain":"adobe.com","breachDate":"2013-10-04","description":"User profile and password hints were exposed."}] Yes An array of breach objects. Each object may include name, domain, breachDate, and description. Fields that are not available for a given breach type are returned as null.

Error structure

Field Name Type Example Always Present Description
message string The value field must be a valid IP address. No Top-level error message returned on validation failure, insufficient balance, or other request errors.
errors object {"type": ["The value field must be a valid IP address."]} No Validation error details.
requestError object {"serviceException": {"messageId": "Error message", "code": "400"}} No Application-level error response object.
service string breach-detection No Service alias returned with a 402 insufficient-balance response.
required_amount string 0.0060000000 No Credit amount required to process the validation request.
current_balance string 0.0000000000 No Current available balance at the time the request was rejected.