Single method flow

When you need to choose verification methods dynamically through API calls rather than using your product's static configuration, you can use method-specific endpoints to create a custom UI for selecting verification methods. This approach gives you full control over which verification methods are presented and how users select them.

tip

For the recommended approach where verification methods are determined by your product configuration, see Waterfall flow.

Method-specific endpoints

Method-specific endpoints bypass the automatic method selection and go directly into the verification process for the selected method. k-ID provides several method-specific endpoints:

Endpoint	Verification Method
/age-verification/perform-facial-age-estimation	Facial age estimation scan
/age-verification/perform-id-verification	ID scan verification
/age-verification/perform-age-key-verification	AgeKey
/age-verification/perform-connect-id-verification	ConnectID (Australia)
/age-verification/perform-inference	Email address age estimation

For detailed information about verification methods, including what methods are available and how they work, see the Verification Methods guide. For a complete list of all available age verification endpoints, see the Age verification endpoints in the API Reference.

Creating a custom verification UI

With method-specific endpoints, you can build a custom UI that:

1. Displays available verification methods to the user
2. Lets the user choose their preferred method
3. Calls the appropriate endpoint based on their selection
4. Falls back to other methods if the selected method fails

Request format

All age verification endpoints use the same request format:

Property	Description	Required?
jurisdiction	The jurisdiction in which the age verification should happen	Yes
criteria	The criteria for age verification	Yes
subject.email	If the user verified their age with k-ID in any other context with an email address, the original age is returned instead of asking the user to verify again	No
subject.claimedAge	If a user was asked for their age in an age gate, used to inform the age estimation process	No
subject.id	An identifier used across multiple verification methods to report multiple failed attempts	No
options.redirectUrl	The URL to redirect to after verification completes. Supports HTTP/HTTPS URLs or mobile deeplinks with custom protocol schemes. The redirect only occurs when the verification URL is opened directly in a browser or webview (not embedded in an iframe). When a redirect occurs, the URL includes verificationId and result (PASS or FAIL) as query string parameters.	No

Example request

POST /api/v1/age-verification/perform-facial-age-estimation
Content-Type: application/json
Authorization: Bearer your-api-key

{
  "jurisdiction": "US-CA",
  "criteria": {
    "ageCategory": "ADULT"
  },
  "subject": {
    "claimedAge": 23
  },
  "options": {
    "redirectUrl": "https://example.com/verification-complete"
  }
}

Redirect URL

The redirectUrl parameter allows you to specify where users should be redirected after completing verification. This is useful for:

• Browser-based flows: Redirecting to another web page after verification completes
• Custom success screens: Displaying your own custom success or failure page
• Mobile app deeplinks: Using custom protocol schemes (for example, myapp://verification-complete) to return control to your mobile app

important

The redirect only occurs when the verification URL is opened directly in a browser or webview (not embedded in an iframe). When embedded in an iframe, verification results are delivered via DOM events instead.

When a redirect occurs, the redirect URL includes the following query string parameters:

• verificationId: The unique verification ID
• result: The verification result, either PASS or FAIL

Example redirect URL:

https://example.com/verification-complete?verificationId=7854909b-9124-4bed-9282-24b44c4a3c97&result=PASS

Response format

All age verification endpoints return the same response format:

Property	Description
id	A unique verification ID
url	The age verification URL that must be presented to the user in an iframe

Example response

{
  "id": "7854909b-9124-4bed-9282-24b44c4a3c97",
  "url": "https://family.k-id.com/verify?token=eyJhbGciOiJFUzM4NCIs..."
}

Embedding the verification widget

Once you receive the verification URL, embed it in an iframe exactly as you would with the standard approach:

<iframe 
  src="VERIFICATION_URL" 
  width="100%" 
  height="600"
  frameborder="0"
  allow="camera;payment;publickey-credentials-get;publickey-credentials-create">
</iframe>

Receiving verification results

Implementations should use a combination of client-side and server-side methods: client-side events are best for controlling UI elements, while for data integrity, the actual results should come from either a webhook or a call to /age-verification/get-status.

For detailed information about analyzing verification results, including field presence rules, status types, and implementation guidance, see the Verification Event Contract.

Client-side (DOM events)

Use DOM Events for responsive UI updates when verification completes. For detailed information about the event structure, see Verification.Result.

window.addEventListener('message', (event) => {
  if (!event.origin.endsWith('.k-id.com')) {
    return;
  }
  
  const message = event.data;
  
  if (message.eventType === 'Verification.Result') {
    if (message.data.status === 'PASS') {
      // User passed verification - update UI immediately
      console.log('Age verified:', message.data.ageCategory);
      updateUI();
    } else if (message.data.status === 'FAIL') {
      // User failed verification - update UI immediately
      console.log('Verification failed:', message.data.failureReason);
      updateUI();
    }
  }
});

Server-side (webhooks, API calls)

Use webhooks or API calls for data integrity and reliable state management. For data integrity, always verify results with events from webhooks or by calling /age-verification/get-status rather than relying solely on DOM Events.

Webhooks

For detailed information about the webhook event structure, see Verification.Result.

Configure a webhook endpoint to receive Verification.Result events. For more information, see Webhooks.

API calls

You can query the verification status by using /age-verification/get-status with the verification ID. This is useful if your webhook was unreachable when the result was sent. For detailed information about analyzing verification results, including field presence rules, status types, and implementation guidance, see the Verification Event Contract.

Age appeal

If a verification fails, you can allow users to appeal by calling the /age-verification/perform-age-appeal endpoint. This presents the user with ID verification and Trusted Adult Attestation options (age estimation isn't available for appeals).

Available endpoints

The following are common method-specific age verification endpoints:

Endpoint	Description
/age-verification/perform-facial-age-estimation	Only offers facial age estimation
/age-verification/perform-id-verification	Only offers ID document verification
/age-verification/perform-age-key-verification	Only offers AgeKey verification
/age-verification/perform-connect-id-verification	Only offers ConnectID verification
/age-verification/perform-inference	Only offers email age estimation
/age-verification/perform-age-appeal	For previously failed verifications (ID verification and Trusted Adult Attestation only)
/age-verification/get-status	Query the status of a verification

For a complete and up-to-date list of all available age verification endpoints, see the Age verification endpoints in the API Reference.