Skip to main content
The Finowl API is a small, predictable JSON API. Every endpoint takes a POST with a JSON body and returns JSON.

​
Base URL

All endpoints are versioned under /v1. HTTPS is required.

​
Endpoints

Check an email

POST /v1/breaches/email

Check a password

POST /v1/breaches/password

Predict from a name

POST /v1/gender/name

Predict from an email

POST /v1/gender/email

Predict from a username

POST /v1/gender/username

Predict in batch

POST /v1/gender/batch

​
Authentication

Send your API key as a bearer token on every request.
See Authentication for how to create, store and rotate keys.

​
Request format

  • Method: POST for every endpoint. Other methods return 405 method_not_allowed.
  • Header: Content-Type: application/json. Anything else returns 415 json_required.
  • Body: a single JSON object, at most 128 KB.
  • Unknown fields are rejected with 400 invalid_input. This catches typos such as contry before they cost you a credit.
  • null is not accepted for any field. Leave optional fields out instead.

​
Response format

Successful responses return the result object directly, with no envelope for breach checks and a data envelope for gender predictions. Errors always use the same shape:
The full list of codes is on the Errors page.

​
Conventions