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:
  • Agent API (POST /api/lookup/email/password/breaches): the API-key endpoint documented on this page, for programmatic access (e.g. your sign-up backend).
  • Async jobs (POST /api/jobs/password): up to 1,000,000 passwords processed in the background.
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.

Request

Provide exactly one of sha1 (recommended) or password.
string
Upper-case hex SHA-1 of the password (40 hex chars). 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.
number
Credits charged for this request (always 1).
number
Duplicate of credits, included for usage tracking.
boolean
Always false; password checks are not cached.

Errors

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

Bulk (asynchronous)

To check a whole list, submit it as an async job instead of looping this endpoint. SHA-1 hash every password client-side first, so plaintext never reaches the server. One entrypoint handles every lookup - set type=password-breaches - and a webhook delivers the finished file when it’s done.
  • Up to 1,000,000 SHA-1 hashes per job, 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, status checks, and download options.

Cost

1 credit per unique password checked (single and async job). Duplicate passwords are de-duplicated and only charged once.