Claims Reference

Overview

CAIRL returns verified claims — boolean or structured assertions about a user's identity — instead of raw identity data. You never receive documents, names, or PII. You receive only the specific claims you requested.

Claims are returned in two places:

• The access token JWT (decoded client-side or server-side)
• The /api/oauth/userinfo endpoint response
• The claims field of vae.resolved webhook events

Requesting claims

Specify claims using the scope parameter in the authorization URL. Multiple claims are space-delimited:

scope=age_18_plus identity_verified document_active

Users see exactly what you request on CAIRL's consent screen. Request only what your application needs.

Claim reference

Identity claims

Freshness claims

Freshness policy is configured per API key (daily, weekly, monthly, quarterly, annual). If the user's last full verification is older than your policy window, freshness_current is false.

Comparison claims

These claims require the user to submit data (name, date of birth, address) which CAIRL compares against the verified identity record. The comparison result — match or no-match — is returned, not the data itself.

Comparison claims require the partner to be at the activation funnel stage. Contact CAIRL to enable them.

Claim values

Claims are always returned with their requested values:

{
  "sub": "pws_v1_abc123...",
  "age_18_plus": true,
  "identity_verified": true,
  "document_active": true,
  "freshness_current": false
}

A claim is only false if the user fails the check — not because data is unavailable. If a claim cannot be evaluated (e.g., the user's document is too old to evaluate freshness), CAIRL returns the most conservative value.

The sub field

Every token and userinfo response includes sub — a stable, per-partner pseudonymous user identifier:

pws_v1_abc123def456...

Properties of sub:

• Stable — the same user always gets the same sub with your application
• Per-partner — the same user has a different sub with each CAIRL partner (prevents cross-partner tracking)
• Non-reversible — CAIRL cannot reverse-engineer the real user from sub

Use sub as the stable identifier to link returning users to your application's records.

Claims and billing

Billing occurs at the token exchange step — only when you successfully retrieve a token. Abandoned sessions and failed exchanges are not billed.

Evaluation timing

Claims are evaluated at token exchange, not at verification time. This means:

• If a user's document expires between their verification and your token exchange, document_active will reflect the current state
• freshness_current is evaluated against your key's freshness policy at exchange time
• Comparison claims are evaluated with the submitted data you provided at verification initiation

Adding claims after launch

You can request additional claims by updating the scope parameter in your authorization URL. Users will see the new claims on the consent screen the next time they authenticate.

If you require comparison claims (name_match, dob_match, address_match), contact CAIRL to enable them for your account.