API Reference

The AgeEvidence API uses REST conventions with JSON request and response bodies. All endpoints require authentication via the X-API-Key header.

Authentication

AgeEvidence issues two types of API keys per client. Each key type has different permissions:

Key Type	Prefix	Use In	Permissions
Publishable	`pk_verify_`	Browser / iframe	Submit verifications only
Secret	`sk_verify_`	Server-side only	Full API access (status, records, management)

Pass the key in the X-API-Key header:

X-API-Key: sk_verify_YOUR_SECRET_KEY

Never expose your secret key in browser code. The publishable key is designed for client-side use in the iframe embed. The secret key must only be used in server-side code.

Base URL

https://ageevidence.com

Endpoints

Method	Endpoint	Key	Description
`POST`	`/v1/verify/submit`	`pk_verify_`	Submit a verification. Used by the embed widget.
`GET`	`/v1/verify/:externalId/status`	`sk_verify_`	Full verification status with DOB, estimated age, and country.
`GET`	`/v1/verify/:externalId/verified`	`sk_verify_`	Quick boolean check. Supports `?level=` filter.
`GET`	`/v1/verify/:externalId/can-submit`	`sk_verify_`	Check if the user is eligible to submit a new verification.
`GET`	`/v1/records/:externalCreatorId`	`sk_verify_`	Get performer record for 2257 compliance.

Status Endpoint Response

GET /v1/verify/:externalId/status returns detailed verification information:

{
  "data": {
    "externalId": "user_abc123",
    "status": "approved",
    "level": "full_age",
    "isVerified": true,
    "verifiedDob": "1995-03-15",
    "estimatedAge": null,
    "documentCountry": "DE",
    "expiresAt": "2027-02-06T00:00:00Z",
    "createdAt": "2026-02-06T10:30:00Z",
    "updatedAt": "2026-02-06T11:15:00Z"
  }
}

Quick Verified Check Response

GET /v1/verify/:externalId/verified returns a minimal boolean result:

{
  "data": {
    "verified": true,
    "level": "full_age",
    "expiresAt": "2027-02-06T00:00:00Z"
  }
}

You can filter by verification level using the ?level= query parameter. For example, /v1/verify/user_123/verified?level=full_kyc checks only for a full KYC verification.

Error Responses

All error responses follow a consistent format:

{
  "error": "Unauthorized",
  "correlationId": "req_abc123"
}

Common HTTP status codes: 400 (bad request), 401 (unauthorized), 403 (forbidden), 404 (not found), 429 (rate limited), 500 (internal error). Error messages are intentionally generic to avoid leaking internal details.

Rate Limits

API requests are rate-limited per IP address:

External API -- 100 requests per minute
Auth endpoints -- 10 requests per minute

When rate-limited, the API returns 429 Too Many Requests. Implement exponential backoff in your polling logic.

OpenAPI Specification

A full OpenAPI specification is available upon request. Contact us through the contact form to receive the specification document.