Age Verification [Developer Preview]

The “Age verification” insight solves the dual challenge of regulatory compliance and protecting underage individuals by enabling applications to verify a user's age with minimal friction. It addresses the shortcomings of traditional age checks, which are often easily bypassed or require intrusive document scanning. The API achieves this by leveraging verified user data held securely by mobile operators and trusted third-party data sources to confirm if the user is above a required age threshold.

Amongst the most common use cases where Age verification can bring benefit, there are:

  • Age-restricted access (for light/no verification sites): Age verification allows platforms that typically rely on minimal registration details (e.g., social networks) to integrate a secure age check into their access processes. This measure prevents minors from accessing sensitive or inappropriate content while enhancing safety on the platform.
  • Age validation during onboarding processes: This feature enables businesses to implement high-assurance age verification during user registration, complying with legal requirements for services like banking or betting, as well as supporting companies to protect certain audiences from purchasing age-restricted goods online.
  • Content restrictions based on age: Age verification enables businesses to tailor and restrict the type of content shown to the user in their applications and platforms, based on their age. Through the use of this feature it is possible to protect vulnerable users from media not suitable for their consumption, as well as to comply with required regulations.
  • Advertisement restrictions based on age: By using Age Verification, businesses can enable precise, compliant digital advertising by preventing the delivery of age-restricted advertisements to users identified as minors. This ensures adherence to regulations and optimizes ad spend by targeting only audiences that can legally consume the ads.

Prerequisites

To use Identity Insights, you must ensure your account is configured correctly; see the Getting Started guide for more information on:

  • Creating your account,
  • Creating a Vonage application for use with the Identity Insights API,
  • The different environments available and how to configure your account to use them,
  • And how to use the Dashboard Getting Started UI to use the API without writing any code.

This guide will explain how to use the Age Verification Insight programmatically using cURL.

The Identity Insights API is available via multiple regional endpoints. The examples in this guide use the EU endpoint, but you can find the full list in Technical Details.

Making an API Call

Authentication for the Identity Insights API is done via JWTs, a compact and self-contained JSON token. To generate a JWT, you can use our online generator, or alternatively use the Vonage CLI. You will need your application ID and private key to generate the JWT. Once you have your JWT, you can send a request to the API.

This example shows a cURL request for the Age verification insight to check if a subscriber associated with the given phone number is over the age of 18; this is defined by the age_threshold parameter, which can be set to anywhere between 0 and 120 years:

curl -X POST https://api-eu.vonage.com/identity-insights/v1/requests  \
  -H "Authorization: Bearer $JWT" \
  -H "Content-Type: application/json" \
  -d '{
    "phone_number": "14040000000",
    "purpose": "FraudPreventionAndDetection",
    "insights": {
        "age_verification": {
         	"age_threshold": 18,
          "id_document": "66666666q",
          "name": "Federica Sanchez Arjona",
          "given_name": "Federica",
          "family_name": "Sanchez Arjona",
          "middle_names": "Sanchez",
          "family_name_at_birth": "YYYY",
          "birthdate": "1978-08-22",
          "email": "federicaSanchez.Arjona@example.com",
          "include_content_lock": true,
          "include_parental_control": true
        }
      }
     }
   }'

The API will then compare the information associated with the particular mobile phone user with that on file (and verified) from the mobile phone user's operator's own records, and return a confirmation on age based on the given threshold, an overall identity score for the identity attributes provided, as well as information on the content and parental control restrictions set, if applicable:

{
  "request_id": "f41087de-b9fc-4081-ab85-9d6475a19706",
  "insights": {
      "age_verification": {
          "is_age_threshold_met": "TRUE",
          "is_verified": true,
          "identity_match_score": 90,
          "content_lock": "TRUE",
          "parental_control": "TRUE",
          "status": {
              "code": "OK",
              "message": "Success"
          }
      }
  }
}

You'll see the following fields in the age_verification object:

Here, the status object indicates the status of the information returned for the specified phone number:

Field Description
status.code Code indicating the status of the request. Must be one of:

NO_COVERAGE: The country or mobile network is not supported by available suppliers.
INVALID_PURPOSE: The purpose used is not valid or allowed for this Insight.
UNAUTHORIZED: The request could not be authorized for the combination of application, supplier, and phone number.
INTERNAL_ERROR: An internal error occurred while processing the request.
SUPPLIER_ERROR: The supplier returned an error while processing the request.
NOT_FOUND: The phone number could not be found for this Insight.
UNSUPPORTED_NETWORK_TYPE: The network type is not supported for this Insight.
INVALID_NUMBER_FORMAT: The phone number format is not valid for assignment by carriers to users.
OK: The insight was processed successfully.
status.message More detailed status description.

If status.code in the response is OK, you may also see the fields described in the table below. If a field is marked as 'Yes' in the 'Mandatory' column, it will always be returned when the status is OK. If a field is marked as 'No', it may or may not be returned.

Name Description Mandatory
is_age_threshold_met Enum: "TRUE" "FALSE", "DATA_UNAVAILABLE"
Indicate TRUE when the age of the user is the same age or older than the age threshold (age >= age threshold), and FALSE if not (age < age threshold). If the API Provider doesn't have enough information to perform the validation, DATA_UNAVAILABLE will be returned.		 Yes
is_verified Indicate "TRUE" if the information provided has been compared against information based on an identification document legally accepted as an age verification document (Note), otherwise indicate "FALSE". No
identity_match_score The overall score of identity information available in the API Provider. It is optional for the API Provider to return the Identity match score.
Min: 0, Max: 100		 No
content_lock Indicate "TRUE"if the subscription associated with the phone number has any kind of content lock (i.e certain web content blocked) and "FALSE" if not. If the API Provider doesn't have information to retrieve the content_lock value, DATA_UNAVAILABLE will be returned. No
parental_control Indicate "TRUE" if the subscription associated with the phone number has any kind of parental control activated and "FALSE" if not. If the API Provider doesn't have information to retireve the parental_control value, DATA_UNAVAILABLE will be returned. No

Further Reading