Quickstart

Create a verification session from your backend, send the user to the hosted verification page, and handle the result on your server.

1. Get a test key

Get a test key from the tenant dashboard's Developers section.

Test keys start with agvf_test_. Keep the key on your server and never expose it in browser code.

2. Register callback URLs

In the tenant dashboard, open Settings and register your Success URL, Cancel URL, and Webhook URL. These are the default browser and server-to-server destinations for every session.

3. Create a session

Call the gateway from your backend with the required target_age. The registered Success URL and Cancel URL are used when success_url and cancel_url are omitted.

bash

curl https://api.agerail.com/api/v1/sessions/create \
  --request POST \
  --header "Content-Type: application/json" \
  --header "X-API-Key: agvf_test_your_key" \
  --data '{
    "target_age": 18
  }'

The gateway returns HTTP 201:

json

{
  "session_id": "018f2f43-7d8b-7a9c-b123-123456789abc",
  "verification_url": "https://verify.agerail.com/v/018f2f43-7d8b-7a9c-b123-123456789abc",
  "expires_at": "2026-07-21T14:30:00Z"
}

target_age must be an integer from 13 through 99. You may supply success_url or cancel_url for a session, but the path and query may vary: its lowercased host and port must exactly match a host and port from one of the registered callback URLs. Sending an unregistered host, creating a session before a Success URL or Cancel URL is registered, or sending the removed webhook_url request field returns HTTP 422.

4. Redirect the user

Redirect the user's browser to the returned verification_url. The hosted flow completes the verification and handles the next browser destination. See the verification and redirect flow for the exact result contract.

5. Receive the webhook

AgeRail sends completion events only to the registered Webhook URL. Process the event on your backend and follow the webhook guide for signature verification; do not implement signature handling from the redirect query alone.

6. Optionally obtain the estimated age

By default, the verification response, webhook, and redirect contain only the signed result and its status, and no estimated age. If your tenant enables estimated age visibility, your backend can obtain the estimate through a separate authenticated operation only for sessions whose shoppers accepted the visibility disclosure. The estimate is stored only for those consented sessions and is deleted when its session record is deleted; session records currently have no fixed automatic deletion period.

After a verified completion webhook, call the estimate operation with the webhook's session_id:

bash

curl https://api.agerail.com/api/v1/sessions/018f2f43-7d8b-7a9c-b123-123456789abc/detected-age \
  --header "X-API-Key: agvf_test_your_key"

An available estimate returns:

json

{
  "session_id": "018f2f43-7d8b-7a9c-b123-123456789abc",
  "detected_age": 40.2,
  "availability": "available"
}

The webhook signals completion but never carries the estimate. See Obtain the optional estimated age for all availability values and the 404 privacy behavior.

Use test mode to exercise each outcome without billing.
Review errors before enabling live traffic.
See the exact schemas in the API Reference.

Quickstart ​

1. Get a test key ​

2. Register callback URLs ​

3. Create a session ​

4. Redirect the user ​

5. Receive the webhook ​

6. Optionally obtain the estimated age ​

Next ​