FinowlLanguage · Python
Use the Finowl API from Python with requests
Python is a comfortable home for Finowl because every call is a single JSON POST followed by a dictionary lookup. With requests you can add a breach check to a Django or Flask signup view, enrich a CSV of contacts inside a pandas notebook, or schedule a nightly job that rechecks customer emails. All three products share one base URL, one bearer token and one error shape, so a small helper module covers the whole API surface.
This guide uses requests because a Session gives you connection pooling, default headers and explicit timeouts in a few lines. The helper below reads FINOWL_API_KEY from the environment, raises a FinowlError that carries the status, the error code and any Retry-After value, and leaves the retry policy to you. Each API page then shows a complete script you can run with python3, along with notes on Celery workers, threading and keeping secrets out of tracebacks.
STEP 1
A reusable Python client
Keep your key in the FINOWL_API_KEY environment variable and route every call through one helper, so authentication, timeouts and error handling live in one place.
pip install requestsimport os
import requests
BASE_URL = "https://api.finowl.co"
class FinowlError(Exception):
"""Raised for any non-2xx response from the Finowl API."""
def __init__(self, status, code, retry_after=None):
super().__init__(f"Finowl API error {status}: {code}")
self.status = status
self.code = code
self.retry_after = retry_after
class FinowlClient:
def __init__(self, api_key=None, timeout=10):
key = api_key or os.environ["FINOWL_API_KEY"]
self.timeout = timeout
self.session = requests.Session()
self.session.headers.update({
"Authorization": f"Bearer {key}",
"Content-Type": "application/json",
})
def post(self, path, payload):
resp = self.session.post(BASE_URL + path, json=payload, timeout=self.timeout)
if resp.ok:
return resp.json()
try:
code = resp.json()["error"]["code"]
except (ValueError, KeyError, TypeError):
code = "unknown_error"
retry_after = resp.headers.get("Retry-After")
raise FinowlError(resp.status_code, code, int(retry_after) if retry_after else None)
# client = FinowlClient()
# client.post("/v1/breaches/email", {"email": "alex@example.com"})STEP 2
Call the API you need
Check email breaches in Python with requests
The email breach endpoint takes one address and returns a breached flag plus a list of breach records. In Python that list arrives as plain dictionaries, so you can loop over it, filter on IsVerified, or turn DataClasses into a set to see whether passwords or phone numbers were exposed. The script below is a command-line checker you can drop into a cron job or call from a management command.
Check breached passwords in Python at signup
NIST SP 800-63B recommends rejecting passwords that appear in lists of previously breached passwords. In Python the check fits neatly inside a form validator: post the candidate password, read breached and count, and raise a validation error if it has been seen before. Finowl hashes the password with SHA-1 and only uses a 5-character prefix for its range search, and it never logs or stores the value.
Predict gender from names in Python
The name endpoint returns a prediction object under data with result_status, gender, confidence and a source field that tells you whether the answer came from the dataset or the AI fallback. Passing a country code matters for names such as Andrea, Jean or Kim, which lean differently depending on where someone lives. Python makes it easy to compare the same name across countries, as the script below does.
A FEW GOOD QUESTIONS
Python questions
Other languages and frameworks
Ship with Python today
100 free credits every month. Try every request in the sandbox first.