Age Verification

k-ID provides a set of APIs to verify the age of users for the following scenarios.

API	Scenario
/age-verification/perform-access-age-verification	To verify the age of a user before getting access to a feature, mature content, or the product itself.
/age-verification/perform-trusted-adult-verification	To perform trusted adult (parent or guardian) verification for use to achieve Verifiable Parental Consent.
/age-verification/perform-facial-age-estimation	To verify the age using facial age estimation only.
/age-verification/perform-id-verification	To verify the age using Government issued ID verification only.
/age-verification/perform-age-appeal	To verify the age for suspected underage users, prior to restoring access to the product.

The Age Verification APIs are standardized in terms of the request & response format.

Request Body

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, then the original age is returned instead of asking the user to estimate or prove their age 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. This can be a temporary session ID, or hashed user ID.	No
scenarioId*	The custom scenarioId	Yes*

* Applicable only for perform-custom-age-verification API.

Sample:

{
  "jurisdiction": "US-CA",
  "subject": {
    "email": "user@example.com",
    "claimedAge": 23,
    "id": "3854909b-8888-4bed-9282-24b74c4a3c97"
  },
  "criteria": {
    "ageCategory": "DIGITAL_YOUTH_OR_ADULT"
  }
}

Response Body

A successful request to the Age Verification API will return the following response.

Property	Description
id	A unique verification id generated by Age Verification Service
url	The age verification URL that must be presented to the user, for them to verify themselves.

Sample:

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

Verification Result

Once the user has successfully has completed the age verification, or the user has retried the maximum number of times and has not succeeded, the Age Verification Result is delivered in two ways.

1. An event is sent to the registered webhook in the form of a Verification.Result event.
2. If the URL from the response body above is included in an iFrame, it is sent to the parent frame as a window message (MessageEvent).

Example of accessing the window message:

const handleMessage = (event: MessageEvent) => {
  const message = event.data;
  if (message.eventType === "Verification.Result") {
    // execute any code here for handling the result
    console.log("eventData", message);
  }
};

window.addEventListener("message", handleMessage);

While the registered webhook is invoked only in the case where the max retries are attempted or a successful verification happened, the javascript event is fired for all verification attempts. This is important if you want to tailor the user experience when users are having trouble completing the verificaiton.

The data element of the window event and the webhook event will contain the following properties.

Property	Description
id	The verification id for which this is the result.
status	Indicates a PASS or FAIL status, based on whether the user met the age criteria or not.
ageCategory	Indicates the age category the user belongs to in the jurisdiction specified in the request. Supported values are adult, digital-youth or digital-minor
method	Indicates the method used for the verification. Supported values are id-document, age-estimation, age-attestation, credit-card, social-security-number
failureReason	The reason the verification failed. Supported values are age-criteria-not-met or max-attempts-exceeded. This is only set if status is FAIL
age	Returns the lower bound and higher bound of the estimated or verified age as low and high.

Sample:

{
    "eventType": "Verification.Result",
    "data": {
        "id": "5a58e98a-e477-484b-b36a-3857ea9daaba",
        "status": "PASS",
        "ageCategory": "adult",
        "method": "id-document",
        "age": {
            "low": 25,
            "high": 25,
        }
    }
}

Sample usage of a window event:

const handleMessage = (event: MessageEvent) => {
  const message = event.data;
  if (message.eventType === "Verification.Result" && ) {
    if (message.data.status === "PASS") {
      window.location.href = `https://www.example.com/success?verificationId=${message.data.id}`
    }
    if (message.data.status === "FAIL") {
      window.location.href = `https://www.example.com/fail?verificationId=${message.data.id}`
    }
  }
};

window.addEventListener("message", handleMessage);

Checking Verification Status

In addition to sending events both in javascript and through the k-ID webhook, it is also possible to query for status for a verification. This is useful to be able to handle cases where the registered webhook was unreachable for a period of time, and the status event was never sent. To get status for a verification, use the /age-verification/get-status API. The data structure returned is identical to the data element sent to the webhook.

Supported Verification Methods

k-ID offers multiple methods to verify a user's age if it is for access to a product, feature or content.

Method	Description
age-estimation	Privacy Preserving Facial Age Estimation to estimate the user’s age. No biometric information leaves the user’s device.
id-verification	Using government issued ID cards such as passport, drivers license etc.. to verify a user’s age.
age-attestation	A verified parent can attest the age of their child.

k-ID also offers specific methods for proof of age for trusted adult verification only. Additionally, some methods like age-estimation are not allowed in some jurisdictions for trusted adult verification.

Method	Description
credit-card	Allow an adult to provide a valid credit card to prove they are of contract age.
social-security-number	Use a combination of Social Security Number and some personal information to prove age.

Verification Scenarios

k-ID supports various age assurance workflows called scenarios through its APIs. Each scenario is designed to meet specific use cases while maintaining user privacy and compliance with local regulations. Here are the default verification scenarios:

• Access Age Verification: Verify user's age before granting access to your product or service, ensuring compliance with age restrictions.
• Age Appeal: Allow users who were previously flagged as underage to verify their correct age and regain access.
• Trusted Adult Verification: Enable parents or guardians to verify their status as trusted adults for managing children's accounts.

Each scenario has one or more verification methods configured by default.

Verification Scenario	Default Verification Methods
Access Age Verification	Facial Age Estimation, ID Verification, Parental Age Attestation
Age Appeal	ID Verification, Parental Age Attestation
Trusted Adult Verification	Facial Age Estimation, ID Verification, Credit Card, Social Security Number

When custom scenarios can be created, and each has an ID. The ID is passed as the scenarioId parameter of the /perform-custom-age-verification API.

Below is a sample verification UI from k-ID

Users can use the available verification methods to verify their age.

Testing Age Verification User Experience

• Go to: https://family.k-id.com/demo
• Enter the following
  • Select Access Age Check as demo type.
  • No Email required
  • Select your jurisdiction (Country)
  • Set Age Category to Adult
• Click on Start

You will see the following:

Please select your preferred verification method and follow instructions to complete the verification.

Testing Age Verification Integration

Before trying to write code to call the k-ID API, you can try Facial Age Estimation yourself using your API key and the API Documentation.

First, follow the steps to make a simple k-ID API call.

Then, using the same browser window, make a call to /age-verification/perform-facial-age-estimation. To do this, click on this API in the list.

Then click the Try it out button, and then click the Execute button.

The URL of the iframe that will be used in your app or a separate browser window is contained in the url parameter of the response. Copy this URL into your browser. It will be something like:

https://family.k-id.com/verify?token=eyJhbGciOiJFUzM4NCIsImtpZCI6IjEiLCJ0eXAiOiJKV1QifQ.eyJpc3MiOiJnYW1lLWFwaS5rLWlkLmNvbSIsImF1ZCI6WyJodHRwczovL2ZhbWlseS5rLWlkLmNvbSJdLCJleHAiOjE3Mzg5NDg0NzAsIm5iZiI6MTczNzczODg3MCwiaWF0IjoxNzM3NzM4ODcwLCJqdGkiOiJjYzAwYzQyZC03NjllLTRmZjItYmRjMy1lOTBiZDFkZmI0YmMiLCJwaWQiOjk1MTYsInNjbiI6IjI5YTg5YTEyLTJiMmEtNDM1MS04ZTkxLWU1ZDdlNTgwNmFlNyIsInZpZCI6ImNjMDBjNDJkLTc2OWUtNGZmMi1iZGMzLWU5MGJkMWRmYjRiYyIsImp1ciI6IlVTLUNBIiwiZW1hIjoidXNlckBleGFtcGxlLmNvbSIsImFnZSI6MTMsImZsdyI6ImZhZS1vbmx5IiwiY2F0IjoiZGNhLW9yLWNhIiwiY2RiIjoiMjAwNS0wNC0xNSJ9.99KDU8lsP7eKEF0nmT8hvPPT-UFXMeMU0FEaJcvV4IMl76dHhjVDXEBneqm6CAGUT8W7SjUtzizpkFhiLNKfwiwh4rHe_Sr6MHjV3nTisNxvBDSlVp-4I3Jino0SohPA

You will then see the instructions page:

Click the Start button to try out a Facial Age Estimation for yourself. Note the liveness checks that are required for security. The result of the scan is not shown visually in this view as it is being sent as a javascript event and a webhook invocation. No camera information leaves your device in this demonstration.