openapi: 3.0.3 info: title: Have I Been Pwned API v3 Breach Breachedaccount API description: Version 3 of the Have I Been Pwned API. Authenticated APIs for breaches by account, pastes, domain search, domain verification, stealer logs, and subscription status require both the hibp-api-key and user-agent headers. Availability varies by subscription tier and is noted per operation. The Pwned Passwords range API is free and does not require authentication. version: 3.0.0 license: name: Creative Commons Attribution 4.0 International url: https://creativecommons.org/licenses/by/4.0/ servers: - url: https://haveibeenpwned.com/api/v3 description: HIBP API v3 server - url: https://api.pwnedpasswords.com description: Pwned Passwords k-Anonymity API (no authentication required) tags: - name: Breachedaccount paths: /breachedaccount/{account}: servers: - url: https://haveibeenpwned.com/api/v3 get: summary: Get all breaches for an account description: Available on Core, Pro, and High RPM subscriptions. Returns the breaches for the supplied account (email address, username, or phone number). The account is not case-sensitive and is trimmed of leading or trailing whitespace. The account should always be URL encoded. This is an authenticated API requiring both the hibp-api-key and user-agent headers. Test API keys can be used to query test accounts on the hibp-integration-tests.com domain. parameters: - $ref: '#/components/parameters/UserAgent' - name: account in: path required: true schema: type: string description: URL-encoded account to search for (email address, username, or phone number) - name: truncateResponse in: query schema: type: boolean default: true description: Returns the full breach model when false. By default, only the name of the breach is returned rather than the complete breach data. - name: domain in: query schema: type: string description: Filters the result set to only breaches against the domain specified. It is possible that one site (and consequently domain), is compromised on multiple occasions. - name: includeUnverified in: query schema: type: boolean default: true description: Returns breaches that have been flagged as 'unverified'. By default, both verified and unverified breaches are returned when performing a search. security: - HibpApiKey: [] responses: '200': description: A list of breaches for the account. By default the response is truncated to only the breach name. Set truncateResponse=false to receive the full breach model. Sensitive and retired breaches are not returned by the public API. content: application/json: schema: oneOf: - type: array items: $ref: '#/components/schemas/TruncatedBreach' - type: array items: $ref: '#/components/schemas/Breach' '400': description: Bad request — the account does not comply with an acceptable format (i.e. it's an empty string) content: application/json: schema: $ref: '#/components/schemas/Error' '401': description: Unauthorized — the API key provided was not valid content: application/json: schema: $ref: '#/components/schemas/Error' examples: missing: value: statusCode: 401 message: Access denied due to missing hibp-api-key. malformed: value: statusCode: 401 message: Access denied due to improperly formed hibp-api-key. invalid: value: statusCode: 401 message: Access denied due to invalid hibp-api-key. '403': description: Forbidden — no user agent has been specified in the request. content: application/json: schema: $ref: '#/components/schemas/Error' '404': description: Not found — the account could not be found and has therefore not been pwned content: application/json: schema: $ref: '#/components/schemas/Error' '429': description: Too many requests — the rate limit has been exceeded headers: Retry-After: description: Seconds until retry (rounded up to the next whole second) schema: type: integer content: application/json: schema: $ref: '#/components/schemas/Error' example: statusCode: 429 message: Rate limit is exceeded. Try again in 2 seconds. '503': description: Service unavailable — usually returned by Cloudflare if the underlying service is not available content: application/json: schema: $ref: '#/components/schemas/Error' x-hibp-subscription-tiers: - Core - Pro - High RPM tags: - Breachedaccount /breachedaccount/range/{prefix}: servers: - url: https://haveibeenpwned.com/api/v3 get: summary: Get all breached account hashes for a range description: Available on Pro and High RPM subscriptions. Search breached accounts via k-anonymity by providing the first 6 characters of the SHA-1 hash of a normalised email address. The response contains matching hash suffixes and associated breach names after public filtering. Sensitive and retired breaches are not returned. Per the terms of use, any results that do not match the target account being searched must be discarded immediately and not stored or further processed. parameters: - $ref: '#/components/parameters/UserAgent' - name: prefix in: path required: true schema: type: string minLength: 6 maxLength: 6 pattern: ^[0-9A-Fa-f]{6}$ description: First 6 characters of the SHA-1 hash of the email address to search for (hexadecimal, not case-sensitive) security: - HibpApiKey: [] responses: '200': description: Hash suffixes and breach names for accounts in the requested range. Sensitive breaches are removed and any suffix with no remaining public breaches is omitted. content: application/json: schema: type: array items: $ref: '#/components/schemas/BreachedAccountRangeResult' example: - hashSuffix: D95E127BD0C0455D0CF3CEE15022BA020D websites: - Adobe '400': description: Bad request — the prefix was not a 6-character hexadecimal string. content: text/plain: schema: type: string example: Invalid hex prefix '401': description: Unauthorized — the API key provided was not valid content: application/json: schema: $ref: '#/components/schemas/Error' examples: missing: value: statusCode: 401 message: Access denied due to missing hibp-api-key. malformed: value: statusCode: 401 message: Access denied due to improperly formed hibp-api-key. invalid: value: statusCode: 401 message: Access denied due to invalid hibp-api-key. '403': description: Forbidden — no user agent has been specified in the request, or the current subscription does not include access to the breached-account k-anonymity API. content: text/plain: schema: type: string examples: missingUserAgent: value: API request must include a user agent insufficientTier: value: Your HIBP API key does not have access to this resource '404': description: Not found — no public breached-account hashes remain for the requested range after filtering. content: text/plain: schema: type: string example: There are no hashes beginning with that prefix '429': description: Too many requests — the rate limit has been exceeded headers: Retry-After: description: Seconds until retry (rounded up to the next whole second) schema: type: integer content: application/json: schema: $ref: '#/components/schemas/Error' example: statusCode: 429 message: Rate limit is exceeded. Try again in 2 seconds. '503': description: Service unavailable — usually returned by Cloudflare if the underlying service is not available content: application/json: schema: $ref: '#/components/schemas/Error' x-hibp-subscription-tiers: - Pro - High RPM tags: - Breachedaccount components: schemas: Breach: type: object properties: Name: type: string description: A Pascal-cased name representing the breach which is unique across all other breaches. This value never changes and may be used to name dependent assets (such as images) but should not be shown directly to end users (see the 'Title' attribute instead). Title: type: string description: A descriptive title for the breach suitable for displaying to end users. It's unique across all breaches but individual values may change in the future (i.e. if another breach occurs against an organisation already in the system). Domain: type: string description: The domain of the primary website the breach occurred on. This may be used for identifying other assets external systems may have for the site. BreachDate: type: string format: date description: The date (with no time) the breach originally occurred on in ISO 8601 format. This is not always accurate — frequently breaches are discovered and reported long after the original incident. Use this attribute as a guide only. AddedDate: type: string format: date-time description: The date and time (precision to the minute) the breach was added to the system in ISO 8601 format. ModifiedDate: type: string format: date-time description: The date and time (precision to the minute) the breach was modified in ISO 8601 format. This will only differ from the AddedDate attribute if other attributes represented here are changed or data in the breach itself is changed (i.e. additional data is identified and loaded). It is always either equal to or greater then the AddedDate attribute, never less than. PwnCount: type: integer description: The total number of accounts loaded into the system. This is usually less than the total number reported by the media due to duplication or other data integrity issues in the source data. Description: type: string description: Contains an overview of the breach represented in HTML markup. The description may include markup such as emphasis and strong tags as well as hyperlinks. DataClasses: type: array items: type: string description: This attribute describes the nature of the data compromised in the breach and contains an alphabetically ordered string array of impacted data classes. IsVerified: type: boolean description: Indicates that the breach is considered unverified. An unverified breach may not have been hacked from the indicated website. An unverified breach is still loaded into HIBP when there's sufficient confidence that a significant portion of the data is legitimate. IsFabricated: type: boolean description: Indicates that the breach is considered fabricated. A fabricated breach is unlikely to have been hacked from the indicated website and usually contains a large amount of manufactured data. However, it still contains legitimate email addresses and asserts that the account owners were compromised in the alleged breach. IsSensitive: type: boolean description: Indicates if the breach is considered sensitive. The public API will not return any accounts for a breach flagged as sensitive. IsRetired: type: boolean description: Indicates if the breach has been retired. This data has been permanently removed and will not be returned by the API. IsSpamList: type: boolean description: Indicates if the breach is considered a spam list. This flag has no impact on any other attributes but it means that the data has not come as a result of a security compromise. IsMalware: type: boolean description: Indicates if the breach is sourced from malware. This flag has no impact on any other attributes, it merely flags that the data was sourced from a malware campaign rather than a security compromise of an online service. IsSubscriptionFree: type: boolean description: Indicates if the breach is subscription-free. This flag has no impact on any other attributes, it is only used when running a domain search where a sufficiently sized subscription isn't present. IsStealerLog: type: boolean description: Indicates if the breach is sourced from stealer logs. A breach with this flag also has the domains that appear in the logs loaded against each email address. This data can be accessed via the stealer logs API. LogoPath: type: string format: uri description: A URI that specifies where a logo for the breached service can be found. Logos are always in PNG format. Attribution: type: string nullable: true description: Sometimes requested by the party that provides the data to HIBP. required: - Name - Title - Domain - BreachDate - AddedDate - ModifiedDate - PwnCount - Description - DataClasses - IsVerified - IsFabricated - IsSensitive - IsRetired - IsSpamList - IsMalware - IsSubscriptionFree - IsStealerLog - LogoPath BreachedAccountRangeResult: type: object properties: hashSuffix: type: string description: The remaining 34 hexadecimal characters of the breached account's SHA-1 hash. websites: type: array items: type: string description: The breach names associated with the hashed account suffix after public API filtering. Sensitive breaches are never returned. required: - hashSuffix - websites TruncatedBreach: type: object properties: Name: type: string description: The stable Pascal-cased breach name. This is the value returned by default from /breachedaccount and can be used to look up the full breach model via /breach/{name}. required: - Name Error: type: object properties: statusCode: type: integer message: type: string required: - statusCode - message description: Standard error response returned by most authenticated HIBP APIs. parameters: UserAgent: name: user-agent in: header required: true description: User agent string identifying the consuming application. Required on all documented requests, including unauthenticated endpoints; missing user agents may receive HTTP 403 responses. schema: type: string securitySchemes: HibpApiKey: type: apiKey in: header name: hibp-api-key description: HIBP API key passed in the hibp-api-key header. Paid APIs require a 32-character hexadecimal value. On supported test-only endpoints, any 32-character hexadecimal value can be used as a test key for the hibp-integration-tests.com domain. externalDocs: description: Full API documentation and acceptable use policy url: https://haveibeenpwned.com/API/v3