Do I need Composer to use Finowl in PHP?

No. The examples rely only on the cURL and JSON extensions bundled with most PHP 8 installs. If you already use Composer and Guzzle, you can swap in a Guzzle client with no change to the payloads.

How do I use Guzzle instead of cURL?

Create a Guzzle client with base_uri https://api.finowl.co, a timeout and the Authorization header, then call post with the json option. Set http_errors to false and read getStatusCode and getHeaderLine('Retry-After').

Which PHP version is required?

PHP 8.0 or newer for match expressions, constructor property promotion and nullsafe syntax. The client class uses readonly properties, which need PHP 8.1, and SensitiveParameter takes effect from 8.2.

How should a PHP app store the API key?

Set FINOWL_API_KEY in the server environment or a .env file loaded by your framework and kept out of version control. Read it with getenv or your framework's config helper, never from client input.

Language · PHP

Use the Finowl API from PHP 8 with cURL

PHP still powers a large share of signup forms, WordPress plugins and Laravel or Symfony backends, and every one of them can call Finowl with the cURL extension that ships with most PHP 8 builds. Requests are JSON POSTs with a bearer token, and responses decode straight into associative arrays with json_decode, so you can work with breach records and gender predictions using the array syntax you already know.

The helper class below wraps cURL with a timeout, reads FINOWL_API_KEY with getenv, captures the Retry-After header through CURLOPT_HEADERFUNCTION, and throws a FinowlException with the status and error code on failure. It uses PHP 8 features such as constructor property promotion and readonly properties. If your project already uses Guzzle, the same request shape works there too, and the FAQ shows what changes.

Get an API key Read the quickstart

STEP 1

A reusable PHP 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.

PHP client

<?php

declare(strict_types=1);

final class FinowlException extends RuntimeException
{
    public function __construct(
        public readonly int $status,
        public readonly string $errorCode,
        public readonly int $retryAfter = 0,
    ) {
        parent::__construct("Finowl API error {$status}: {$errorCode}");
    }
}

final class FinowlClient
{
    private const BASE_URL = 'https://api.finowl.co';
    public function post(string $path, array $payload): array
    {
        $retryAfter = 0;
        $ch = curl_init(self::BASE_URL . $path);
        curl_setopt_array($ch, [
            CURLOPT_POST => true,
            CURLOPT_RETURNTRANSFER => true,
            CURLOPT_TIMEOUT => 10,
            CURLOPT_HTTPHEADER => [
                'Authorization: Bearer ' . getenv('FINOWL_API_KEY'),
                'Content-Type: application/json',
            ],
            CURLOPT_POSTFIELDS => json_encode($payload, JSON_THROW_ON_ERROR),
            CURLOPT_HEADERFUNCTION => function ($ch, string $header) use (&$retryAfter): int {
                if (stripos($header, 'Retry-After:') === 0) {
                    $retryAfter = (int) trim(substr($header, 12));
                }
                return strlen($header);
            },
        ]);
        $body = curl_exec($ch);
        if ($body === false) {
            throw new RuntimeException('Network error: ' . curl_error($ch));
        }
        $status = curl_getinfo($ch, CURLINFO_RESPONSE_CODE);
        $data = json_decode($body, true) ?? [];
        if ($status === 200) {
            return $data;
        }
        throw new FinowlException($status, $data['error']['code'] ?? 'unknown_error', $retryAfter);
    }
}

STEP 2

Call the API you need

Check email breaches in PHP with cURL
For PHP applications the email breach check usually runs after a registration form is submitted or from a queued Laravel job that rechecks accounts. json_decode with the associative flag turns the response into arrays, so a foreach over $result['breaches'] gives you each record's Title, BreachDate and DataClasses. implode makes the data classes readable for a notification email or an admin screen.
Check breached passwords in PHP before hashing
PHP gives you password_hash and password_verify for storage, and a breach check slots in right before password_hash during signup or a password change. The Finowl endpoint receives the plaintext over HTTPS, hashes it with SHA-1, searches by a 5-character prefix with padding, and returns breached and count. Finowl processes the password transiently and never logs, stores or returns it.
Predict gender from names in PHP 8 with cURL
In PHP, gender lookups are often used to enrich CRM records or to segment newsletter analytics. The name endpoint returns the prediction inside a data key, so after json_decode you read $result['data']['result_status'] first, then gender, confidence and source when the status is identified. A country code such as IT or US helps with names whose usage differs by country, like Andrea.

A FEW GOOD QUESTIONS

PHP questions

Other languages and frameworks

Ship with PHP today

100 free credits every month. Try every request in the sandbox first.

Start building View pricing