DOCS

Quick Start Guide

Embed AgeEvidence verification in your platform in 4 steps.

Step 1: Add the Iframe

Place the verification widget on your page using an iframe. Use your publishable key (pk_verify_) which is safe to expose in browser code. Replace the externalIdparameter with your platform's unique user identifier.

<iframe
  id="ae-verification"
  src="https://ageevidence.com/embed/full_age
    ?apiKey=pk_verify_YOUR_KEY
    &externalId=YOUR_USER_ID
    &theme=dark
    &locale=en
    &parentOrigin=https://yoursite.com"
  width="100%"
  height="600px"
  frameborder="0"
  allow="camera"
  style="border: none; border-radius: 12px;"
></iframe>

Choose a verification level: age_only (quick 18+ face estimation), full_age (age verification with ID), or full_kyc (full identity verification with ID and liveness).

Step 2: Listen for Events

The widget communicates with your page through the window.postMessage API. Always validate the origin before processing events.

window.addEventListener('message', (event) => {
  // Always validate origin
  if (event.origin !== 'https://ageevidence.com') return;

  const { type, data } = event.data;

  switch (type) {
    case 'ae:ready':
      console.log('Widget loaded and ready');
      break;
    case 'ae:started':
      console.log('User started verification:', data.level);
      break;
    case 'ae:complete':
      console.log('Verification submitted:', data.verificationId);
      // Proceed to Step 3: poll status from your backend
      pollVerificationStatus(data.verificationId);
      break;
    case 'ae:error':
      console.error('Verification error:', data.error);
      break;
    case 'ae:cancel':
      console.log('User cancelled verification');
      break;
  }
});

Step 3: Poll Verification Status

After receiving the ae:complete event, poll the status from your backend server using your secret key (sk_verify_). Never expose the secret key in browser code.

// Your backend server (Node.js example)
app.get('/api/check-verification', async (req, res) => {
  const { externalId } = req.query;

  const response = await fetch(
    `https://ageevidence.com/v1/verify/${externalId}/status`,
    {
      headers: {
        'X-API-Key': process.env.AGEEVIDENCE_SECRET_KEY, // sk_verify_...
      },
    }
  );

  const data = await response.json();
  res.json(data);
});

The age_only level may return an instant auto-decision for clearly adult faces (estimated age 25+). For full_age and full_kyc, an admin reviews the submission manually.

Step 4: Handle the Result

The status endpoint returns one of five statuses:

  • pending -- Verification submitted, waiting for review
  • under_review -- Admin is currently reviewing
  • approved -- Verification passed, grant access
  • rejected -- Verification failed, deny access
  • resubmit_required -- User needs to resubmit (blurry ID, etc.)

For a quick boolean check, use the /v1/verify/:externalId/verified endpoint which returns { "verified": true } or { "verified": false }.

Content Security Policy

If your site uses a Content-Security-Policy header, add the following directive to allow the AgeEvidence iframe:

frame-src https://ageevidence.com;