proofage — ProofAge for Python

Python client for ProofAge, the age and identity verification API. It gives you a sync and an async client for every /v1 endpoint, typed Pydantic models, typed errors and webhook verification — enough to go from pip install to a verified result in a few minutes, from a backend, a Telegram bot or an AI agent.

Install

pip install proofage
# or
uv add proofage

Quick start

Set PROOFAGE_API_KEY and PROOFAGE_SECRET_KEY (from your workspace in the ProofAge console), then:

from proofage import ProofAge

with ProofAge() as client:
    verification = client.verifications.create(
        external_id="candidate-42",
        callback_url="https://your-app.example/verified",
    )
    print(verification.url)  # send the person here

    # later, or when the webhook arrives
    print(client.verifications.get(verification.id).status)

The person opens verification.url on their phone, ProofAge runs the checks, and you learn the outcome from a webhook (below) or by calling get().

Async

AsyncProofAge has the same methods, awaited — the natural choice in aiogram bots, FastAPI and other asyncio code:

from proofage import AsyncProofAge

async with AsyncProofAge() as client:
    verification = await client.verifications.create(external_id="tg-12345")

Receiving results (webhooks)

ProofAge POSTs the outcome to your workspace's webhook URL. Verify it with the raw request body — not a re-serialised copy of its JSON — and answer 2xx.

FastAPI:

from fastapi import FastAPI, Request, Response
from proofage import WebhookVerificationError, verify_webhook

app = FastAPI()


@app.post("/webhooks/proofage")
async def proofage_webhook(request: Request) -> Response:
    try:
        event = verify_webhook(await request.body(), request.headers)
    except WebhookVerificationError as error:
        return Response(status_code=error.http_status)
    print(event.verification_id, event.status, event.reason)
    return Response(status_code=200)

Django:

from django.http import HttpResponse
from django.views.decorators.csrf import csrf_exempt
from django.views.decorators.http import require_POST
from proofage import WebhookVerificationError, verify_webhook


@csrf_exempt
@require_POST
def proofage_webhook(request):
    try:
        event = verify_webhook(request.body, request.headers)
    except WebhookVerificationError as error:
        return HttpResponse(status=error.http_status)
    ...
    return HttpResponse(status=200)

A delivery can arrive more than once: de-duplicate on event.delivery_id, which stays the same on every automatic retry. Ready-made FastAPI, Django and Flask integrations are coming in 0.1.x.

Statuses

event.status and verification.status are VerificationStatus members (APPROVED, DECLINED, RESUBMISSION_REQUESTED, REVIEW, …). A status this version does not know yet arrives as a plain string instead of raising, so compare with ==:

from proofage import VerificationStatus

if event.status == VerificationStatus.APPROVED:
    ...

Unknown fields are kept too, in model.model_extra; model.model_dump(mode="json") gives a plain dict.

Errors

from proofage import PaymentRequiredError, ProofAgeError, RateLimitError, ValidationError

try:
    client.verifications.create(external_id="x" * 300)
except ValidationError as error:
    print(error.errors)  # {"external_id": ["..."]}
except PaymentRequiredError:
    print("Add a payment method to the workspace")
except RateLimitError as error:
    print("Try again in", error.retry_after, "seconds")
except ProofAgeError as error:
    print(error.status_code, error.code, error.message)

AuthenticationError (401), PaymentRequiredError (402), PermissionDeniedError (403), NotFoundError (404), ValidationError (422), RateLimitError (429), ServerError (5xx) and TransportError (no response) all extend ProofAgeError. ConfigurationError is raised when a client is built with missing or invalid settings. A response whose shape this SDK version does not recognise raises ProofAgeError naming the fields (never their values).

Configuration

The environment variables use the same names and units as the ProofAge Laravel and PHP SDKs, so one .env serves all of them (the Node SDK reads PROOFAGE_TIMEOUT in milliseconds). Constructor arguments are seconds.

timeout limits each network operation (connecting, each read, each write), not the whole request. Pass your own httpx.Client / httpx.AsyncClient as http_client for proxies or custom TLS; the SDK never closes a client you pass in.

Retries

• A GET is retried on 408, 429, 5xx, timeouts and connection failures.
• A POST is retried only on 429 and when the connection never opened. It is never retried on a 5xx or once sending began, because the server may already have created the verification.
• A 429 waits for its Retry-After, up to 60 seconds; a longer Retry-After raises RateLimitError at once (with retry_after set) instead of blocking your thread. Otherwise the wait grows by retry_delay per attempt.
• Media downloads never retry an HTTP status; run them from a queue and let its backoff wait.

Media

document = client.verifications.document(verification_id)
for item in document.media:
    if item.url is not None:  # None once purged or past retention
        client.verifications.download_media_to(verification_id, item.id, f"{item.id}.jpg")

Hosted flow first

accept_consent, upload_media and submit exist for custom capture flows. Most integrations only create a session, send the person to its url, and read the result.

For packages that wrap this SDK

A plugin or bot template built on this SDK can name itself in the X-ProofAge-Sdk header, which helps ProofAge support tell integrations apart:

ProofAge(sdk_tokens=["telegram-bot/1.2.0"])  # X-ProofAge-Sdk: telegram-bot/1.2.0 python/0.1.0

user_agent= replaces the default ProofAge-Python/<version> (Python <x.y.z>) User-Agent.

Supported versions

A Python version stays supported for 12 months after its upstream end of life, or until httpx or Pydantic stop supporting it, whichever comes first. A version leaves only in a minor release, announced one release ahead in the changelog.

AI agents

The package ships AGENTS.md next to its code: the full request and response contract of every method, written for coding agents. Agents that speak MCP can also use the ProofAge MCP server directly.

License

MIT