Age Verification

As an online service provider, there may be various scenarios in which you may have to 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.

This document covers the Age Verification APIs offered by k-ID to help you support age verification for your 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	Information related to the subject of the verification	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
  },
  "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 completed the age verification, the Age Verification Result is delivered in two ways.

It is sent to the registered web-hook in the form of a Verification.Result event.
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);

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`.

Also returns the confidence score which is a float between 0 and 1 which indicates the confidence in the estimated age range. |

Sample:

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

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);

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)
Trusted Adult Verification	`Allowed verification methods based on the jurisdiction an your product configuration`

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.

Reducing User Friction and minimizing re-verifications

The subject is an optional property of the age verification request, but it can go a long way to reduce user friction. If a specific user has previously verified themselves to meet the specified age criteria, then the verification can be reused, the Verification.Result web-hook event will be fired with PASS status and the user would not have to reverify themselves.

Please note that, it is the responsibility of the service calling this API to ensure the subject is verified and is consenting to have their age verification status checked.

Self-Serve Configuring your Verification Scenarios (Alpha)

k-ID allows you to self serve configure your various verification scenarios. You can override the allowed verification methods, threshold ages for Digital Consent Age & Civil Age and also configure what properties will be returned as part of the Verification.Result web-hook event.

In addition, if the out of the box verification scenarios are not sufficient for your use case then k-ID allows you to create your own custom verification scenarios with their own scenarioId.

This feature is currently in Alpha, so please talk to your account manager to configure verification scenarios for you or to give you early access to our Self Serve Verification Scenario Configuration.

Testing Age Verification User Experience

Go to: https://family.k-id.com/verify/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: Testing Age Verification

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. Sample Age Verification API Request

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

Sample Age Verification API Response

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: Sample Age Verification Instrucutions

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.

Age Verification