Age Verification

There are various scenarios where you must verify the age of a user, such as before granting access to your product, when restoring access to suspected underage accounts, or when providing access to age-restricted content.

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

Age Verification APIs

k-ID offers the following APIs for the various age verification scenarios.

API	Scenario
/age-verification/perform-access-age-verification	To verify the age prior to gaining access to the product.
/age-verification/perform-age-appeal	To verify the age for suspected underage users, prior to restoring access to the product.
/age-verification/perform-trusted-adult-verification	To perform trusted adult (parent or guardian) verification.
/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.

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.

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.

Additional verification methods such as credit-card, social-security-number etc.. are available for trusted adult verification based on what is allowed in the jurisdictions & based on your product configuration.

Verification Scenarios

k-ID supports various age verification 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 key 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 (as appropriate)
Age Appeal	ID Verification, Parental Age Attestation (as appropriate)

Below is a sample verification UI from k-ID

k-ID allows the users to use the available verification methods, to verify their age and also handles retries and switching between the various verification methods in between verification attempts.

In certain scenarios, you may want to use specific verification methods only such as Facial Age Estimation or ID Verification. k-ID also offers APIs which deal with just these specific verification methods.

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.