Skip to main content
The ProofAge API is a JSON REST API. Your backend uses it to create verifications, read their results and, if you build your own capture screens, to upload media and submit.

​
Base URL

The version is part of the path. New fields can appear in responses within v1, so ignore keys you do not know.

​
Authentication

Every request carries two headers: POST /verifications also accepts a request without a signature, but then drops external_id and callback_url. How to compute the signature, including for file uploads, is in API authentication. The server SDKs sign for you.

​
Requests and responses

  • Send JSON with Content-Type: application/json, except media uploads, which are multipart/form-data.
  • Send Accept: application/json on every request, so that every error comes back as JSON. The server SDKs do.
  • Responses are JSON objects without an envelope: GET /verifications/{id} returns the verification itself, not {"data": …}. Lists are the exception: GET /verifications returns {"data": […], "next_cursor": …}, and GET /webhook-subscriptions returns {"data": […]}.
  • IDs are UUIDs. Timestamps are ISO 8601 with a time-zone offset.
  • The objects the API returns are described in Data models; the event sent to your webhook URL in Decision webhook.

​
Errors

Errors use standard HTTP status codes. The body comes in one of four shapes, depending on where the request was stopped:
Read the code from error.code, then code, and fall back to the HTTP status when neither is present. Blocking a face answers validation errors with both error and errors. A 402 also says where the trial stands: free_verifications_remaining, trial_ends_at and trial_active. The codes and what to do about each are listed in Errors. The server SDKs parse all four shapes into one error type.

​
Rate limits

Requests are limited per IP address and workspace, and per workspace. A request over the limit gets 429 with RATE_LIMIT; see Rate limiting.

​
Trying requests

Each endpoint page has a playground. It sends X-API-Key and whatever you type into X-HMAC-Signature, but it cannot compute the signature for you, so signed endpoints answer 401 INVALID_SIGNATURE unless you paste a signature computed for exactly that request. To explore the API without signing by hand, use a server SDK, the Postman collection with its signing script, or the MCP server.

​
OpenAPI

The full specification is at /openapi.json (OpenAPI 3.1), including the webhook.