API Documentation

Integrate ageefy into your project with a simple REST API.

Overview

ageefy provides a simple two-step API. First, create a verification session. Then, the user completes the verification on our page and you receive the result via callback.

Your server calls POST /api/verification/new with the user's IP and your callback URL.
We return a verificationUrl. Redirect your user to this URL.
The user completes face detection, liveness check, and age/gender estimation.
We POST the result to your callbackUrl and redirect the user to your redirectUrl.

Quick Start

JavaScript / TypeScript

const response = await fetch('/api/verification/new', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({
    internalId: 'user_123',          // optional
    redirectUrl: 'https://yourapp.com/done?id=%verificationId%',
    callbackUrl: 'https://yourapp.com/webhook',
    ip: req.ip,
    minAge: 18,                      // optional
    maxAge: 99,                      // optional
    allowedVerificationMethods: ['face', 'id'],  // optional — default: both
    requireMobileDevice: true,       // optional
    requireNewVerification: false,   // optional
  }),
});

const { id, verificationUrl } = await response.json();

// Redirect your user to verificationUrl
window.location.href = verificationUrl;

POST/api/verification/new

Create Verification

Creates a new verification session and returns a verification URL to redirect your user to.

Fields

Field	Type	Required	Description
redirectUrl	string	Required	Where to redirect after verification. Supports `%verificationId%` placeholder.
ip	string	Required	IP address of the user being verified
internalId	string	Optional	Your internal user identifier. Returned in the callback payload.
callbackUrl	string	Optional	URL to receive the verification result via POST
minAge	integer	Optional	Minimum accepted age (inclusive). If the estimated age is below this value the user sees an age-restriction notice instead of the normal completion screen.
maxAge	integer	Optional	Maximum accepted age (inclusive). If the estimated age is above this value the user sees an age-restriction notice instead of the normal completion screen.
requireMobileDevice	boolean	Optional	When true, desktop users see a QR code and must scan it with a mobile phone to complete verification. The desktop page polls every 5 s and automatically redirects once the mobile session completes.
allowedVerificationMethods	string[]	Optional	Which methods the user may choose from. Accepted values: `"face"` (live selfie scan) and `"id"` (passport / driver's licence with MRZ). Defaults to both when omitted.
requireNewVerification	boolean	Optional	When true, the Passkey "skip" option is hidden and the user must always complete a fresh scan. Use this when you need a live liveness check regardless of prior verifications (e.g. high-security flows).

Request

POST /api/verification/new
Content-Type: application/json

{
  "internalId": "user_123",          // optional
  "redirectUrl": "https://yourapp.com/done?id=%verificationId%",
  "callbackUrl": "https://yourapp.com/webhook",  // optional
  "ip": "192.168.1.1",
  "minAge": 18,                      // optional — minimum accepted age
  "maxAge": 99,                      // optional — maximum accepted age
  "allowedVerificationMethods": ["face", "id"],  // optional — default: both
  "requireMobileDevice": true,       // optional — force mobile-only verification
  "requireNewVerification": false    // optional — disable Passkey reuse, force fresh scan
}

Response

HTTP/1.1 201 Created

{
  "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "verificationUrl": "https://ageefy.app/verification?id=a1b2c3d4-..."
}

POST/api/verification/check

Check Verification

Check the status and result of a verification by its ID.

Request

POST /api/verification/check
Content-Type: application/json

{
  "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890"
}

Response

HTTP/1.1 200 OK

{
  "id": "a1b2c3d4-...",
  "internalId": "user_123",
  "status": "completed",
  "detectedAge": 28,
  "detectedGender": "male",
  "minAge": 18,
  "maxAge": 99,
  "redirectUrl": "https://yourapp.com/done?id=...",
  "callbackUrl": "https://yourapp.com/webhook",
  "createdAt": "2026-04-12T10:00:00.000Z",
  "completedAt": "2026-04-12T10:01:05.000Z"
}

Callback Payload

When verification is complete, we POST this payload to your callbackUrl:

Callback Request

POST https://yourapp.com/webhook
Content-Type: application/json

{
  "detectedAge": 28,
  "detectedGender": "male",
  "internalId": "user_123",
  "id": "a1b2c3d4-...",
  "minAge": 18,
  "maxAge": 99
}