WebhooksEvent types

Verification.Result

Emitted with the result of a verification attempt.

Delivery and recovery

Webhook events are retried up to 2 times on failure. If your server misses an event, poll GET /age-verification/get-status with the saved verification ID. See Delivery, retries, and recovery for details.

Fields

FieldTypeRequiredDescription
eventTypestringyesAlways "Verification.Result"
dataobjectyesVerification result data
data.idstring (UUID)yesThe unique verification ID
data.statusstringyesCan be PASS or FAIL
data.ageCategorystringnoThe estimated age category. Can be adult, digital-youth, or digital-minor. Present for PASS status when your product's setting includes it. For FAIL status, only present when failureReason is age-criteria-not-met and age is present. See Choose which age fields you receive
data.ageBandobjectnoThe age band the age falls in. Present only when ageCategory is present and the age falls inside a band for the verification's jurisdiction. See Age band
data.ageBand.keystringyesA stable identifier for the band. Match on this value, not on name
data.ageBand.namestringyesThe band name, for example 11-13 or 18+
data.ageBand.lowerAgenumberyesThe lowest age in the band
data.ageBand.upperAgenumbernoThe highest age in the band. Absent for an open-ended band such as 18+
data.methodstringnoThe verification method used. Always present for PASS status. For FAIL status, only present if failureReason is age-criteria-not-met
data.providerstringnoThe vendor that ran the method. Present whenever method is present
data.failureReasonstringnoThe reason the verification failed. Always present when status is FAIL. Can be age-criteria-not-met, max-attempts-exceeded, or fraudulent-activity-detected
data.ageobjectnoThe age details. Present when both age.low and age.high are available and your product's setting includes it. For FAIL status, only present if failureReason is age-criteria-not-met
data.age.lownumbernoThe lower bound of the estimated age. In the case of a hard age verification method, such as an ID document check, this is the exact age
data.age.highnumbernoThe upper bound of the estimated age. In the case of a hard age verification method, such as an ID document check, this is the exact age
data.dobstring (YYYY-MM-DD)noVerified date of birth. Only included when the verification method provides it and your product's Webhooks setting includes it

Example

{
  "eventType": "Verification.Result",
  "data": {
    "id": "4e57301e-a4d1-498f-ac3f-f3d4de19abf6",
    "status": "PASS",
    "method": "id-document",
    "provider": "veratad",
    "age": {
      "low": 43,
      "high": 43
    },
    "dob": "1981-06-20"
  }
}

Choose which age fields you receive

You choose which age fields k-ID returns for each way your product receives a verification result. In Compliance Studio, open your product, go to Product access, and find the Age result card. For where this sits in the editor, see Product configuration: API configuration.

The card has three channels:

ChannelWhat it covers
Get statusThe response to GET /age-verification/get-status
WebhooksWebhook events that carry a verification result, such as Verification.Result
JavaScript resultThe result message the verification screen posts to your page

Each channel has three toggles:

  • Date of birth controls dob.
  • Age controls age.
  • Age category controls ageCategory and ageBand.

k-ID returns a field in a channel only when that channel's setting includes it. Each channel's setting is separate from the others.

Until you change a toggle and save, your product has no setting of its own. k-ID then follows your organization's settings. The card shows the current default.

A setting change takes effect after you publish the product. See Testing and publishing.

The includeDob query parameter

The includeDob query parameter on GET /age-verification/get-status decides whether the response includes dob. The order of precedence depends on whether your product has a saved Age result setting.

Your productincludeDob valueResult
Has a saved settingtrue or falseThe parameter wins over the Get status Date of birth toggle
Has a saved settingNot sentThe Get status Date of birth toggle decides
Has no saved settingtruedob is included, unless your organization returns only a pass or fail result
Has no saved settingfalse or not sentdob is not included

The includeDob parameter only applies to get-status. Webhook events and the JavaScript result follow their own toggles.

Verification event contract

Overview

This section defines the API contract for verification status delivered to you through two mechanisms:

  1. Webhook Events: Verification.Result webhook events sent when a verification completes
  2. API Endpoint: GET /age-verification/get-status endpoint for polling verification status

This contract specifies field presence rules, data types, and interpretation guidance for all possible outcome types. While both mechanisms provide similar data, there are important differences in status values, field presence, and structure that you must be aware of.

DOM Messages Aren't Authoritative

Verification results are also communicated to front-end applications via DOM messages for UI control purposes. However, only webhook events and the GET /age-verification/get-status endpoint responses should be considered reliable, authoritative data sources for integration logic. DOM messages are provided solely for front-end application state management and shouldn't be used as the basis for critical business decisions or data persistence.

Data structures

Webhook event structure

Webhook events are wrapped in an event envelope:

{
  "eventType": "Verification.Result",
  "data": {
    "id": "uuid",
    "status": "PASS" | "FAIL",
    "ageCategory": "adult" | "digital-youth" | "digital-minor",
    "ageBand": {
      "key": string,
      "name": string,
      "lowerAge": number,
      "upperAge": number
    },
    "method": "id-document" | "credit-card" | "self-confirmation" | "social-security-number" | "email-confirmation" | "age-estimation-scan",
    "provider": string,
    "age": {
      "low": number,
      "high": number
    },
    "dob": "YYYY-MM-DD",
    "failureReason": string
  }
}

API endpoint response structure

The GET /age-verification/get-status endpoint returns a direct response:

{
  "id": "uuid",
  "status": "PASS" | "FAIL" | "PENDING" | "IN_PROGRESS",
  "ageCategory": "adult" | "digital-youth" | "digital-minor",
  "ageBand": {
    "key": string,
    "name": string,
    "lowerAge": number,
    "upperAge": number
  },
  "method": "id-document" | "credit-card" | "self-confirmation" | "social-security-number" | "email-confirmation" | "age-estimation-scan",
  "provider": string,
  "age": {
    "low": number,
    "high": number
  },
  "dob": "YYYY-MM-DD",
  "failureReason": string
}

ageBand is optional, and upperAge is absent for an open-ended band. The fields are shown together here for reference. Each field is present only under the rules in this contract.

Query Parameters:

  • id (required): The verification ID
  • includeDob (optional): If true or false, overrides the Get status Date of birth toggle when your product has a saved Age result setting. Without a saved setting, true includes the dob field when available and any other value leaves it out. See The includeDob query parameter

For complete endpoint documentation, see GET /age-verification/get-status.

Key differences between webhook and API endpoint

AspectWebhook EventAPI Endpoint
Status ValuesOnly PASS or FAILPASS, FAIL, PENDING, IN_PROGRESS
StructureWrapped in { eventType, data }Direct response object
DOB FieldIncluded if available and the Webhooks Date of birth toggle allows itFollows the includeDob query parameter and the Get status Date of birth toggle (see precedence)
AgeCategoryPresent for PASS status when your product's setting includes it, and for FAIL status when failureReason is age-criteria-not-metPresent for both PASS and FAIL statuses when age data is available and your product's setting includes it
MethodOnly present when status is PASSPresent for both PASS and FAIL statuses
When AvailableOnly when verification completesCan be polled at any time, including during verification

Status types

PASS

The verification successfully determined that the user meets the age criteria.

Availability:

  • Webhook: ✅ Sent when verification completes successfully
  • API Endpoint: ✅ Returned when verification is complete and successful

FAIL

The verification determined that the user doesn't meet the age criteria, or the verification process failed because a conclusive age determination couldn't be made, or deceptive behavior was detected. These scenarios result in a FAIL status with the appropriate failureReason values.

Availability:

  • Webhook: ✅ Sent when verification completes with failure
  • API Endpoint: ✅ Returned when verification is complete and failed

Status: PENDING

The verification request has been created but hasn't yet started processing.

Availability:

  • Webhook: ❌ Never sent (webhooks only fire on completion)
  • API Endpoint: ✅ Returned when verification is in initial state

API Endpoint Response for PENDING:

  • id (UUID) - always included
  • status ("PENDING") - always included
  • All other fields are absent

Status: IN_PROGRESS

The verification is currently being processed.

Availability:

  • Webhook: ❌ Never sent (webhooks only fire on completion)
  • API Endpoint: ✅ Returned when verification is actively being processed

API Endpoint Response for IN_PROGRESS:

  • id (UUID) - always included
  • status ("IN_PROGRESS") - always included
  • All other fields are absent

Field presence rules by status

Webhook events

Webhook events are only sent when a verification completes (status is PASS or FAIL). They don't include intermediate statuses such as PENDING or IN_PROGRESS.

Status: PASS

Webhook events

Always included:

  • id (UUID)
  • status ("PASS")
  • method (string) - The verification method used
  • provider (string) - The vendor that ran the method

Included when your product's setting includes them:

  • age (object) - Contains both low and high bounds
  • ageCategory (string) - One of: adult, digital-youth, digital-minor

Sometimes included:

  • ageBand (object) - The age band the age falls in. Only present when ageCategory is present (see Age band)
  • dob (string, YYYY-MM-DD format) - Verified date of birth, only when the verification method provides it and your product's Webhooks setting includes it (see Date of birth field section for specific methods).

Never included:

  • failureReason

API endpoint

Always included:

  • id (UUID)
  • status ("PASS")
  • method (string) - The verification method used (if available)
  • provider (string) - The vendor that ran the method (if available)

Included when your product's setting includes them:

  • age (object) - Contains both low and high bounds
  • ageCategory (string) - One of: adult, digital-youth, digital-minor

Sometimes included:

  • ageBand (object) - The age band the age falls in. Only present when ageCategory is present (see Age band)
  • dob (string, YYYY-MM-DD format) - Only included when the includeDob query parameter or the Get status Date of birth toggle allows it AND the verification method provides it (see The includeDob query parameter and the Date of birth field section for specific methods)

Never included:

  • failureReason

What you need to know

  • Treat PASS status as a successful verification
  • All verification methods that result in PASS provide age information, but your product's setting decides whether age, ageCategory, and dob are included in each channel. Don't assume age or ageCategory is present
  • Use the ageCategory field to determine user permissions and access levels
  • Don't rely solely on age.low or age.high for access control, use ageCategory instead
  • You can use dob if it's provided, but don't assume it's always available
  • For the API endpoint: Set includeDob=true in your query parameters if you need DOB data. If your product has a saved Age result setting, the parameter wins over the toggle (see GET /age-verification/get-status and precedence)

Status: FAIL

Webhook events

Always included:

  • id (UUID)
  • status ("FAIL")
  • failureReason (string) - Reason for the failure

Sometimes included:

  • method (string) - Only present if failure isn't due to max-attempts-exceeded or fraudulent-activity-detected
  • provider (string) - Only present when method is present
  • age (object) - Only present if failureReason is age-criteria-not-met
  • ageCategory (string) - Only present when failureReason is age-criteria-not-met and age is present
  • ageBand (object) - Only present when ageCategory is present (see Age band)
  • dob (string) - Only present when the verification method provides it and your product's Webhooks setting includes it (see Date of birth field section for specific methods).

API endpoint

Always included:

  • id (UUID)
  • status ("FAIL")
  • failureReason (string) - Reason for the failure

Sometimes included:

  • method (string) - Only present if failure is due to age-criteria-not-met
  • provider (string) - Only present when method is present
  • age (object) - Only present if failureReason is age-criteria-not-met
  • ageCategory (string) - Only present if age is present
  • ageBand (object) - Only present when ageCategory is present (see Age band)
  • dob (string) - Only included when the includeDob query parameter or the Get status Date of birth toggle allows it AND the verification method provides it (see Date of birth field section for specific methods)

Never included:

  • ageCategory when age isn't present

What you need to know

  • Treat FAIL status as an unsuccessful verification, don't grant access or permissions
  • Always check failureReason to understand why the verification failed
  • Don't assume age fields are present for FAIL status, they might not be available
  • If age is present in a FAIL result, you can use it for logging or analytics, but don't use it for access control decisions
  • Handle cases where method and age are absent, this indicates a system-level failure, not an age determination failure
  • For webhook events: ageCategory might be present for FAIL status when failureReason is age-criteria-not-met, but don't use it for access control decisions
  • For API endpoint: Even if ageCategory is present for FAIL status, don't use it for access control decisions

Common Failure Reasons:

  • age-criteria-not-met - User's verified age doesn't meet the required threshold
  • max-attempts-exceeded - User has exhausted all available verification attempts (this is the final failure reason when users exhaust retries after failed or inconclusive age determinations)
  • fraudulent-activity-detected - System detected suspicious or fraudulent behavior

Age field population rules

When age object is present

The age object contains two fields:

  • low (number): The lower bound of the age estimate, or the exact age for hard verification methods (for example, ID document). When an exact age isn't provided by the verification method, this is the threshold minimum age required for the verification.
  • high (number): The upper bound of the age estimate, or the exact age for hard verification methods. When an exact age isn't provided by the verification method, this is 100.

Conditions for age to be present:

  • For PASS status: present when your product's setting includes age for the channel. All verification methods that result in PASS provide age information
  • For FAIL status: failureReason is age-criteria-not-met

What you need to know

  • For PASS status, age can be absent if your product's setting leaves it out for the channel. Use ageCategory for access decisions
  • Always check that the age object exists, and that both age.low and age.high exist, before you read them
  • Don't assume that age.low === age.high means you have an exact age, it might, but it depends on the verification method
  • Don't use age fields for access control when status isn't PASS
  • For PASS status, prefer using ageCategory over raw age values when making access decisions

When ageCategory is present

The ageCategory field is derived from the age and jurisdiction information.

Values:

  • adult - User is classified as an adult
  • digital-youth - User is classified as a digital youth (age-restricted but not a minor)
  • digital-minor - User is classified as a digital minor

Conditions for ageCategory to be present:

  • For PASS status: present when your product's setting includes ageCategory for the channel. k-ID always calculates it when a verification passes
  • For FAIL status: Present when failureReason is age-criteria-not-met and age data is available (both age.low and age.high are present)

What you need to know

  • For PASS status, ageCategory is present when your product's setting includes it for the channel. If it is present, you can use it for access control decisions
  • Use ageCategory for access control decisions rather than raw age values
  • For FAIL status, don't use ageCategory for access control decisions, even if it's present

When age and ageCategory are absent

Conditions:

  • The verification passed, and your product's setting left the field out for that channel. A PASS result can then arrive without age, ageCategory, or both
  • The verification failed with failureReason of max-attempts-exceeded - No age determination was made
  • The verification failed with failureReason of fraudulent-activity-detected - Age data is excluded for security reasons
  • The verification method didn't provide age information

What you need to know

  • Don't assume age information is always available, handle missing age fields gracefully
  • Don't try to infer age from other fields when age is absent
  • For FAIL status without age fields, rely on failureReason to understand what went wrong

Age band

The ageBand field names the age band the verified age falls in. The bands come from your product's age bands for the verification's jurisdiction. Set them in Compliance Studio on the Product access tab, in the Age bands card.

The ageBand object has these fields:

  • key (string): A stable identifier. Match on this value, because the name can change.
  • name (string): The band name, for example 11-13.
  • lowerAge (number): The lowest age in the band.
  • upperAge (number): The highest age in the band, inclusive. It is absent for an open-ended band such as 18+.

Conditions for ageBand to be present:

  • ageCategory is included for the channel. When ageCategory is left out, ageBand is left out too.
  • The age falls inside a band for the verification's jurisdiction. k-ID places the age by age.low.
  • Bands exist for that jurisdiction. Your product's own bands for the exact jurisdiction apply first, then your own bands for its country, then k-ID's default bands for the country. Only Indonesia (ID) has k-ID default bands. Other markets need bands you set.

When ageBand is absent:

  • The age is below the first band.
  • No bands apply to the jurisdiction.
  • ageCategory is not included for the channel.

When k-ID works out the band:

  • The webhook carries the band from the moment the verification completed.
  • get-status works out the band from your current bands each time you call it.
  • If you change your bands after a verification completes, get-status can return a different band than the webhook sent for that verification.

Bands differ by market. Each market uses its own bands, so the same age can fall in different bands in different markets. If you want one grouping everywhere, set the same bands in every market.

The ManualAgeAppeal.PendingReview event follows the Age and Age category toggles for the Webhooks channel, but it never carries ageBand.

Example: 18+ band with no upperAge

{
  "eventType": "Verification.Result",
  "data": {
    "id": "0b83055f-642a-44f5-8abb-e37cb907dfcd",
    "status": "PASS",
    "ageCategory": "adult",
    "ageBand": {
      "key": "18-plus",
      "name": "18+",
      "lowerAge": 18
    },
    "method": "id-document",
    "provider": "veratad",
    "age": {
      "low": 30,
      "high": 30
    }
  }
}

What you need to know

  • Treat ageBand as optional, and don't use it for access control. Use ageCategory.
  • Match on ageBand.key, not on ageBand.name.
  • A missing ageBand doesn't mean the verification failed.
  • ageBand is your own grouping, for your internal use. ageCategory is the legal category that k-ID's compliance engine works out from the jurisdiction's rules.
  • The two can disagree. In Indonesia, for example, a 19-year-old falls in the default 18+ band but is digital-youth, because Indonesia's age of majority is 21.

Date of birth field

Format: YYYY-MM-DD (ISO 8601 date format)

When present: The dob field is only included when the verification method provides a verified date of birth and your product's setting for the channel includes it. It's not included for methods that only provide age estimates or age ranges. Given the various combinations of verification methods and jurisdictions, you shouldn't perform validation or have expectations about when dob must be present. The field is provided when it's available from the verification method, but its presence can't be guaranteed across all scenarios.

Methods that can provide dob:

  • id-document - When the ID document contains readable date of birth information
  • privy - Always provided (Indonesian identity verification)
  • korean-real-name - Always provided (Korean real-name verification via Inicis)
  • age-attestation - When the attestation includes birth date information
  • singpass - Always provided (Singapore national identity verification)

Methods that NEVER provide dob:

  • age-estimation-scan - Only provides age ranges, not verified DOB
  • connect-id - Confirms the age threshold only, not a birth date
  • credit-card - Confirms an adult cardholder, not a birth date
  • email-estimation - Only provides age estimates, not verified DOB
  • social-security-number - Confirms an adult identity record, not a birth date

Status conditions:

  • Present for PASS status when the method provides it
  • Present for FAIL status when the method provided it before determining the user didn't meet age criteria

What you need to know

  • Don't assume dob is always present, even for PASS status
  • If dob is present, validate that it's in YYYY-MM-DD format
  • You can use dob for additional validation or logging, but don't rely on it as your primary way to determine age

Method field

When present:

  • Always present for PASS status
  • Present for FAIL status when failureReason is age-criteria-not-met

Possible values:

  • age-attestation - Age attestation via k-ID (can include DOB)
  • age-estimation-scan - Facial age estimation scan (no DOB, returns age range)
  • age-key - A previously issued AgeKey
  • brazil-cpf - Brazilian CPF verification
  • connect-id - Australian ConnectID verification
  • credit-card - Credit card verification
  • email-confirmation - Confirmed parent email address
  • email-estimation - Email-based age estimation (no DOB, only age estimates)
  • id-document - Government-issued ID document verification (can include DOB)
  • korean-real-name - Korean real-name verification via Inicis (always includes DOB)
  • pre-verified - A parent your organization asserted as verified ahead of time
  • privy - Indonesian identity verification (always includes DOB)
  • self-confirmation - Parent self-confirmation
  • singpass - Singapore national identity verification (always includes DOB)
  • social-security-number - SSN-based verification

What you need to know

  • You can use method for analytics or logging purposes
  • Don't use method for access control decisions

Provider field

When present:

  • Present whenever method is present

Possible values: connect-id, inicis, k-id, kws, openage, persona, pre-verified, privateid, privately, privy, serpro, singpass, spruce-id, stripe, veratad, verify-my, xsolla

A method doesn't imply a provider. age-estimation-scan is served by several vendors, and credit-card carries the merchant of record when a payment stood in for the check.

What you need to know

  • You can use provider for analytics or logging purposes
  • Don't use provider for access control decisions
  • Handle unknown provider values gracefully, k-ID adds vendors over time

Failure reason values

Common failureReason values:

  • age-criteria-not-met - User's verified age doesn't meet the required threshold
  • max-attempts-exceeded - User has exhausted all available verification attempts
  • fraudulent-activity-detected - System detected suspicious or fraudulent behavior

What you need to know

  • Handle unknown failureReason values gracefully, don't break if you see something unexpected
  • Don't make access decisions based solely on failureReason, always consider the status field
  • It's a good idea to log failureReason for debugging and analytics purposes

Complete field matrix

Webhook events

FieldPASSFAIL
idalwaysalways
statusalwaysalways
methodalwayssometimes¹
provideralwayssometimes¹
agesometimes⁴sometimes²
ageCategorysometimes⁴sometimes²
ageBandsometimes⁵sometimes⁵
dobsometimes³sometimes³
failureReasonneveralways

¹ Present unless failureReason is max-attempts-exceeded or fraudulent-activity-detected
² Present only if both age.low and age.high are available AND failureReason is age-criteria-not-met
³ Included when the verification method provides it and the Webhooks Date of birth toggle allows it
⁴ Present when your product's setting includes the field for the channel
⁵ Present only when ageCategory is present and the age falls inside a band for the jurisdiction

API endpoint

FieldPENDINGIN_PROGRESSPASSFAIL
idalwaysalwaysalwaysalways
statusalwaysalwaysalwaysalways
methodneverneversometimes²sometimes¹
providerneverneversometimes²sometimes¹
ageneverneversometimes⁶sometimes³
ageCategoryneverneversometimes⁶sometimes⁴
ageBandneverneversometimes⁷sometimes⁷
dobneverneversometimes⁵sometimes⁵
failureReasonneverneverneveralways

¹ Present unless failureReason is max-attempts-exceeded or fraudulent-activity-detected
² Present if available from the verification method
³ Present only if both age.low and age.high are available AND failureReason is age-criteria-not-met
⁴ Present only when age category was successfully calculated from the age and jurisdiction (for FAIL status)
⁵ Included when the includeDob query parameter or the Get status Date of birth toggle allows it AND the verification method provides it (see precedence)
⁶ Present when your product's setting includes the field for the channel
⁷ Present only when ageCategory is present and the age falls inside a band for the jurisdiction

Example payloads

Webhook event examples

PASS status with age information

{
  "eventType": "Verification.Result",
  "data": {
    "id": "123e4567-e89b-12d3-a456-426614174000",
    "status": "PASS",
    "method": "id-document",
    "provider": "veratad",
    "ageCategory": "adult",
    "age": {
      "low": 25,
      "high": 25
    },
    "dob": "1998-05-15"
  }
}

FAIL status with age information

{
  "eventType": "Verification.Result",
  "data": {
    "id": "123e4567-e89b-12d3-a456-426614174001",
    "status": "FAIL",
    "method": "age-estimation-scan",
    "provider": "privately",
    "failureReason": "age-criteria-not-met",
    "age": {
      "low": 16,
      "high": 17
    },
    "ageCategory": "digital-minor"
  }
}

FAIL status without age information

{
  "eventType": "Verification.Result",
  "data": {
    "id": "123e4567-e89b-12d3-a456-426614174002",
    "status": "FAIL",
    "failureReason": "max-attempts-exceeded"
  }
}

API endpoint response examples

PENDING status

{
  "id": "123e4567-e89b-12d3-a456-426614174003",
  "status": "PENDING"
}

IN_PROGRESS status

{
  "id": "123e4567-e89b-12d3-a456-426614174004",
  "status": "IN_PROGRESS"
}

PASS status with age information (without DOB)

{
  "id": "123e4567-e89b-12d3-a456-426614174000",
  "status": "PASS",
  "method": "id-document",
  "provider": "veratad",
  "ageCategory": "adult",
  "age": {
    "low": 25,
    "high": 25
  }
}

PASS status with DOB (includeDob = true)

{
  "id": "123e4567-e89b-12d3-a456-426614174000",
  "status": "PASS",
  "method": "id-document",
  "provider": "veratad",
  "ageCategory": "adult",
  "age": {
    "low": 25,
    "high": 25
  },
  "dob": "1998-05-15"
}

FAIL status with age information

{
  "id": "123e4567-e89b-12d3-a456-426614174001",
  "status": "FAIL",
  "method": "age-estimation-scan",
  "provider": "privately",
  "failureReason": "age-criteria-not-met",
  "age": {
    "low": 16,
    "high": 17
  },
  "ageCategory": "digital-minor"
}

FAIL status without age information

{
  "id": "123e4567-e89b-12d3-a456-426614174002",
  "status": "FAIL",
  "failureReason": "max-attempts-exceeded"
}

Implementation checklist

Webhook events

  • Handle both status types: PASS and FAIL (webhooks never send PENDING or IN_PROGRESS)
  • Check for presence of age object before accessing age.low or age.high
  • Use ageCategory for access control when status is PASS and ageCategory is present
  • Don't use ageCategory for access control when status is FAIL, even if it's present
  • Handle cases where method is absent (system-level failures)
  • Handle cases where age and ageCategory are absent (certain failure scenarios, or fields your product's setting leaves out)
  • Treat ageBand as optional
  • Validate dob format (YYYY-MM-DD) if present
  • Log failureReason for debugging
  • Don't grant access for FAIL status
  • Handle unknown failureReason values gracefully

API endpoint

  • Handle all status types: PENDING, IN_PROGRESS, PASS, and FAIL
  • For PENDING and IN_PROGRESS statuses, only expect id and status fields
  • Set the includeDob query parameter if you need DOB data. It wins over the toggle when your product has a saved setting (see GET /age-verification/get-status)
  • Check for presence of age object before accessing age.low or age.high
  • Use ageCategory for access control when status is PASS and ageCategory is present
  • Don't use ageCategory for access control when status is FAIL, even if present
  • Handle cases where method is absent (system-level failures)
  • Handle cases where age and ageCategory are absent (certain failure scenarios, or fields your product's setting leaves out)
  • Treat ageBand as optional
  • Validate dob format (YYYY-MM-DD) if present
  • Log failureReason for debugging
  • Don't grant access for FAIL status
  • Handle unknown failureReason values gracefully
  • Implement appropriate polling strategy for PENDING and IN_PROGRESS statuses

Implementation notes

AgeCategory behavior

The ageCategory field is included for PASS status in webhook events when your product's setting includes it. For FAIL status, ageCategory might be included when failureReason is age-criteria-not-met and age data is available. However, you should never use ageCategory for access control decisions when the status is FAIL, regardless of whether it's present. The API endpoint follows the same pattern - ageCategory can be present for FAIL status when age data is available, but shouldn't be used for access control decisions.

Version history

  • 2026-11-12: Each channel (get-status, webhooks, and the JavaScript result) follows your product's Age result setting for age, ageCategory, and dob, so a PASS result can arrive without age or ageCategory. Added the optional ageBand field and documented includeDob precedence.
  • 2026-09-01: provider field added to webhook events and to the API endpoint, naming the vendor that ran the method.
  • 2026-01-07: ageCategory field is now included in FAIL status webhook events when failureReason is age-criteria-not-met and age data is available.
  • 2025-12-04: Initial API contract document

On this page