Quickstart

Create an account

Create an API key

Open API Keys in the dashboard and select Create key. Give it a label you will recognize later, such as production-backend.

The full key is shown only once. Copy it into your secret manager or .env file before closing the dialog.

Store the key as an environment variable

export FINOWL_API_KEY="finowl_..."

Keep the key on your server. Never put it in frontend code, a mobile app or a public repository.

Make your first request

Check whether a common password has been breached:

curl https://api.finowl.co/v1/breaches/password \
  -H "Authorization: Bearer $FINOWL_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"password": "P@ssw0rd"}'

const response = await fetch("https://api.finowl.co/v1/breaches/password", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.FINOWL_API_KEY}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({ password: "P@ssw0rd" }),
});

console.log(await response.json());

import os
import requests

response = requests.post(
    "https://api.finowl.co/v1/breaches/password",
    headers={"Authorization": f"Bearer {os.environ['FINOWL_API_KEY']}"},
    json={"password": "P@ssw0rd"},
    timeout=40,
)
print(response.json())

package main

import (
    "fmt"
    "io"
    "net/http"
    "os"
    "strings"
    "time"
)

func main() {
    body := strings.NewReader(`{"password": "P@ssw0rd"}`)
    request, _ := http.NewRequest("POST", "https://api.finowl.co/v1/breaches/password", body)
    request.Header.Set("Authorization", "Bearer "+os.Getenv("FINOWL_API_KEY"))
    request.Header.Set("Content-Type", "application/json")

    client := &http.Client{Timeout: 40 * time.Second}
    response, err := client.Do(request)
    if err != nil {
        panic(err)
    }
    defer response.Body.Close()
    result, _ := io.ReadAll(response.Body)
    fmt.Println(string(result))
}

<?php
$request = curl_init('https://api.finowl.co/v1/breaches/password');
curl_setopt_array($request, [
    CURLOPT_POST => true,
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_TIMEOUT => 40,
    CURLOPT_HTTPHEADER => [
        'Authorization: Bearer ' . getenv('FINOWL_API_KEY'),
        'Content-Type: application/json',
    ],
    CURLOPT_POSTFIELDS => json_encode(['password' => 'P@ssw0rd']),
]);
echo curl_exec($request);

require "net/http"
require "json"

uri = URI("https://api.finowl.co/v1/breaches/password")
request = Net::HTTP::Post.new(uri)
request["Authorization"] = "Bearer #{ENV.fetch('FINOWL_API_KEY')}"
request["Content-Type"] = "application/json"
request.body = { password: "P@ssw0rd" }.to_json

response = Net::HTTP.start(uri.host, uri.port, use_ssl: true, read_timeout: 40) do |http|
  http.request(request)
end
puts response.body

You should see:

{ "breached": true, "count": 133211 }

The exact count changes as new breaches are added.

Try a gender prediction

curl https://api.finowl.co/v1/gender/name \
  -H "Authorization: Bearer $FINOWL_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name": "James Smith", "country": "US"}'

{
  "data": {
    "result_status": "identified",
    "gender": "male",
    "confidence": 0.99,
    "country": "US"
  }
}

Check your usage

Open the dashboard overview to see both requests, the credits they used and your remaining balance.

Next steps

Handle errors

Learn which errors to fix, which to wait out and which never to retry.

Understand credits

How credits are counted, when you are charged and how to top up.

Block breached passwords

A production-ready sign-up integration.

Enrich contacts in batch

Process thousands of records safely.

Get started

Core concepts

Guides

Next steps

Handle errors

Understand credits

Block breached passwords

Enrich contacts in batch

​Next steps

Handle errors

Understand credits

Block breached passwords

Enrich contacts in batch

Next steps