The Fingerly API is a small JSON-over-HTTPS API with three audiences. Client SDKs call the client API with a public key to identify visitors. Your backend calls the server API with a secret key to read what was identified. Your automation calls the management API with a management key to manage keys, webhook endpoints and risk weights. Most integrations never call the client API directly: the SDKs do.
Base URL
Each region has its own API, and every key belongs to one region. Use the base URL of your key's region.
| Region | Base URL | Keys | Status |
|---|---|---|---|
| United States | https://us.api.fingerly.io/api/v1 | fly_pk_us_…, fly_sk_us_…, fly_px_us_… | Available |
| European Union | https://eu.api.fingerly.io/api/v1 | fly_pk_eu_…, fly_sk_eu_…, fly_px_eu_… | Coming soon |
Management keys, fly_mk_us_… and fly_mk_eu_…, belong to a region the same way.
The SDKs read the region from the key and choose the base URL for you. A key sent to another region's API is refused. See regions and data residency.
Endpoints
| Endpoint | Key | Purpose |
|---|---|---|
GET /events | Secret | List events in a time window. |
GET /events/{request_id} | Secret | Read one event with its archived detail. |
POST /identify | Public | Submit a signal report and get the verdict. |
POST /events/{request_id}/supplement | Public | Attach the deferred report to an identification. |
POST /attestation/challenge | Public | Issue a one-time attestation challenge for the Android SDK. |
/management/… | Management | Manage SDK keys, proxy keys, webhook endpoints and risk weights. |
Conventions
- Request and response bodies are JSON (
application/json). Unknown request fields are rejected. - Request bodies are limited to 1 MiB. Client API requests may be sent with
Content-Encoding: gzip, and the limit applies after decompression. - Timestamps are RFC 3339 in UTC, such as
2026-09-16T09:41:12.482Z. - Request IDs are UUIDv7, so they sort by time and carry their own timestamp.
- Optional response fields are omitted when they do not apply, unless a page says a field is
null. - Every response carries an
X-Request-Idheader. Include it when you contact support.
Versioning
The version is part of the path, /api/v1. Within a version, Fingerly adds fields and endpoints but does not remove or rename them, and never changes what a field means. Write clients that ignore fields they do not know.
Signal names are permanent too. If a detection ever changes what it measures, it gets a new name.
Health
GET /api/v1/healthz answers when the API process is up; GET /api/v1/readyz answers when it can serve traffic. Neither needs a key.
OpenAPI
The whole public API is described in an OpenAPI 3.1 document, with a Postman collection generated from it. See OpenAPI and Postman.