Skip to main content
POST
Password Breaches

Overview

Password Breaches tells you whether a password has appeared in known data breaches, and how many times, without ever transmitting or storing the plaintext password. It’s built for a sign-up / password-reset guard: warn a user when the password they chose has already leaked and prompt them to pick a different one. It uses the k-anonymity model on top of Have I Been Pwned’s Pwned Passwords corpus: the password is SHA-1 hashed and only the first 5 hex characters of the hash are ever sent to the upstream service. There are two ways to run it:
  • Single check (POST /api/lookup/email/password/breaches): the API-key endpoint documented on this page, for programmatic access (e.g. your sign-up backend).
  • Batches (POST /api/jobs/bulk with type=password-breaches): a background job for up to 1,000,000 SHA-1 hashes. See Check many passwords.
The plaintext password is never stored. History records only a masked label (a dotted mask plus the 5-char hash prefix), never the password or its full hash.

Authentication

Requires an API key in the Authorization header.

Request

Send sha1 (recommended) or password. If you send both, sha1 wins and password is ignored.
string
Upper-case hex SHA-1 of the password. Must be exactly 40 hex characters; surrounding whitespace is trimmed and lowercase hex is upper-cased for you. Preferred: the plaintext never leaves the caller. Only the first 5 hex chars are sent upstream.
string
The raw password to check. Hashed server-side (SHA-1) immediately and never stored; only the 5-char hash prefix leaves the server. Prefer sha1 in production.

Example request

Response

string
The 5-char SHA-1 hash prefix used for the k-anonymity query.
boolean
Whether the password appears in any known breach.
number
How many times the password has been seen across breaches.
string
Human-readable summary of the verdict.
number
Credits charged for this request. 1 on the first check, or 0 when you already checked this password during the 6-month free-repeat window.

Errors

Errors return a JSON body of the form {"error": "<message>", "code": "<code>"} with the matching HTTP status code.

Check many passwords

To check many passwords, upload SHA-1 hashes with POST /api/jobs/bulk (type=password-breaches) and download the result with kind=password. POST /api/jobs/bulk runs in the background and handles up to 1,000,000 hashes. SHA-1 hash every password client-side first, so plaintext never reaches the server. A webhook delivers the finished file.
  • Charged 1 credit per unique password.
  • download_link=true returns a download_url in the bulk.completed webhook; fetch it with your API key.
  • Export filters: all, breached. Only the masked hash prefix and breach count are stored - never the password or full hash.
See the Bulk Operations guide for the webhook payload and download options.

Cost

1 credit per unique password checked. Repeat single lookups are free during the 6-month free-repeat window.