Quick Start

This guide walks you through a complete verification flow using curl. By the end, you will have created a verification session, uploaded a selfie, and submitted it for processing.

Prerequisites

• Your API key and secret key from the ProofAge dashboard.
• curl installed on your machine.
• A selfie image file (e.g., selfie.jpg).

Replace YOUR_API_KEY with your actual API key and YOUR_HMAC_SIGNATURE with a computed HMAC-SHA256 signature in every request. See the Authentication guide for how to compute signatures.

1. Create a Verification Session

Start by creating a new verification. The flow type and check method are determined by your workspace configuration — you don't need to specify them per request. You can pass an optional external_id to correlate the verification with your own system.

curl -X POST https://api.proofage.com/v1/verifications \
  -H "Content-Type: application/json" \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "X-HMAC-Signature: YOUR_HMAC_SIGNATURE" \
  -d '{
    "external_id": "user_12345"
  }'

Response (201 Created):

{
  "data": {
    "id": "ver_abc123def456",
    "status": "created",
    "external_id": "user_12345",
    "url": "https://verify.proofage.com/ver_abc123def456",
    "created_at": "2026-03-19T10:00:00Z"
  }
}

Save the id value — you will use it in every subsequent request.

Note: The X-HMAC-Signature header is optional on POST /v1/verifications if your workspace does not enforce it. All other endpoints require it.

TIP

This guide demonstrates the selfie-only Age Estimation flow. If your workspace uses ID Age Verification or KYC, you will also need to upload document images — see step 4.

2. Get Consent Text

Before uploading any media, you must present the consent text to your user and record their acceptance.

curl -X GET https://api.proofage.com/v1/consent \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "X-HMAC-Signature: YOUR_HMAC_SIGNATURE"

Response (200 OK):

{
  "data": {
    "consent_text": "I consent to ProofAge processing my biometric data for identity verification purposes. My data will be handled in accordance with the privacy policy.",
    "version": "2.1"
  }
}

Display the consent_text to your user and proceed only after they accept.

3. Accept Consent

Record the user's consent against the verification session.

curl -X POST https://api.proofage.com/v1/verifications/ver_abc123def456/consent \
  -H "Content-Type: application/json" \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "X-HMAC-Signature: YOUR_HMAC_SIGNATURE" \
  -d '{
    "consent_version": "2.1",
    "accepted": true
  }'

Response (200 OK):

{
  "data": {
    "id": "ver_abc123def456",
    "consent_accepted": true,
    "consent_version": "2.1",
    "consented_at": "2026-03-19T10:00:05Z"
  }
}

4. Upload a Selfie

Upload a selfie image to the verification session. This is a multipart form request.

curl -X POST https://api.proofage.com/v1/verifications/ver_abc123def456/media \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "X-HMAC-Signature: YOUR_HMAC_SIGNATURE" \
  -F "type=selfie" \
  -F "[email protected]"

Response (201 Created):

{
  "data": {
    "id": "med_789xyz",
    "verification_id": "ver_abc123def456",
    "type": "selfie",
    "status": "uploaded",
    "created_at": "2026-03-19T10:00:10Z"
  }
}

Note: For KYC flows, repeat this step to upload a document image with "type=document". You can call this endpoint multiple times to upload additional files.

HMAC for multipart requests: Computing the HMAC signature for file uploads requires hashing each file's contents. See the Authentication guide for the full algorithm. During development with test keys, you can use a placeholder signature.

5. Submit for Processing

Once all media is uploaded, submit the verification for processing.

curl -X POST https://api.proofage.com/v1/verifications/ver_abc123def456/submit \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "X-HMAC-Signature: YOUR_HMAC_SIGNATURE"

Response (200 OK):

{
  "data": {
    "id": "ver_abc123def456",
    "status": "processing",
    "submitted_at": "2026-03-19T10:00:15Z"
  }
}

The verification is now queued for processing. You will receive the result via your configured webhook.

6. Check Status

You can poll the verification status at any time.

curl -X GET https://api.proofage.com/v1/verifications/ver_abc123def456 \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "X-HMAC-Signature: YOUR_HMAC_SIGNATURE"

Response (200 OK):

{
  "data": {
    "id": "ver_abc123def456",
    "status": "approved",
    "external_id": "user_12345",
    "result": {
      "decision": "approved",
      "estimated_age": 27,
      "age_range": {
        "min": 24,
        "max": 30
      },
      "confidence": 0.94
    },
    "created_at": "2026-03-19T10:00:00Z",
    "submitted_at": "2026-03-19T10:00:15Z",
    "completed_at": "2026-03-19T10:00:22Z"
  }
}

Possible status values: created, consented, processing, approved, declined, resubmission_requested.

Rate Limits

The API allows 60 requests per minute per workspace. If you exceed this limit, you will receive a 429 Too Many Requests response with a Retry-After header indicating how many seconds to wait.

Next Steps

• Authentication — Learn how to compute HMAC signatures for production use.
• Verification Flow — Detailed guide covering all edge cases, webhook handling, and error recovery.