Age Estimation v2

Once you've set up your organisation account on the Yoti Hub, you’re ready to start integrating with the Age estimation and anti-spoofing (liveness) API.

Face Capture

For optimal results, Yoti provides the Yoti Face Capture modules, which are designed to capture optimal images meeting the requirements of the API. This is available as a Native package, and Web implementation.

Integration

Install the SDK

After completing the Yoti onboarding, you will need to complete authentication for the API by using the Yoti SDK to simplify the process. The Yoti SDKs are available via popular dependency management systems.

npm install -S -E yoti

Create a request

You can create three types of requests using the API:

Once you have added the Yoti SDK dependency to your project, you can use it to build and send your request. See the code snippets below for examples.

const PATHS = {

    AGE: '/age',

    LIVENESS: '/antispoofing',

    AGE_LIVENESS: '/age-antispoofing',

};

​

const data = {

    "img": "base64_image",

    "metadata": {

        "device": "mobile | laptop"

    },

    "secure": {

        "version": "<module version>",

        "token": "<session jwt>",

        "signature": "<payload>"

    }

};

​

const request = new RequestBuilder()

    .withBaseUrl('https://api.yoti.com/ai/v1')

    .withPemFilePath('<YOTI_KEY_FILE_PATH>')

    .withEndpoint(PATHS.AGE_LIVENESS) // optionally PATHS.AGE or PATHS.LIVENESS

    .withPayload(new Payload(data))

    .withMethod('POST')

    .withHeader('X-Yoti-Auth-Id', '<YOTI_CLIENT_SDK_ID>')

    .withQueryParam('secure', true)

    .build();

​

const response = request.execute();

The JSON string for the payload must be in the following format. This is sent with the withPayload method provided in the SDK. The face capture module will automatically return “img” and “secure” on success. Do not modify these fields manually.

{

    "img": "base64_image",

    "metadata": {

        "device": "mobile | laptop"

    },

    "secure": {

        "version": "<module version>",

        "token": "<session jwt>",

        "signature": "<payload>"

    }

}

img is the mandatory parameter that contains the captured image in Base64 Encoded format.

metadata is an optional parameter but is strongly recommended for better results. It is used to specify what type of device is being used. You can choose between mobile or laptop.

secure is a mandatory parameter that is returned by the face capture module.

Multiframe

If you're using Multiframe within the FCM - you must include the query parameter multiframe=true

The payload size will increase when using Multiframe

If there is a mismatch between the Face Capture's multiframe setting and the multiframe query parameter in the request, the response will always be UNTRUSTED_SECURE_SESSION

Retrieve the results

The endpoint will return the Anti-spoofing result alongside Age estimation.

{

   "antispoofing": {

       "prediction": "real | fake"

   },

   "age": {

       "st_dev": float,

       "age": float

   }

}

If requesting age only, the response will look as follows:

{

    "age": float,

    "st_dev": float

}

If integrating into a non-browser client, we recommend contacting us here for additional support.

Relaxed image requirements

When using the Age only endpoint, it is possible to lower the threshold for face detection and image validation on images. A reason for this might be that images are not being captured live through Yoti's Face Capture module, or you may want to age estimate images where there is no case to perform a liveness check.

This feature is utilised by setting the image validation level to low, as shown in the example payload.

Note that this may only be used with the age endpoint.

See this page for more details on the image requirements.

{

    "img": "/9j/4AAQSkZJRgABAgAAAQABAAD/2wAcHNXCKigjEaYH51Me1Zy1Za0P/Z....",

    "img_validation_level": "low"

}

Terminal integrations

Optionally, additional headers may be provided to the request to allow Yoti to track error responses coming from a particular machine. This would typically be used in a non-browser client scenario, such as an ePOS terminal where each individual machine must be registered by the business.

In order to do this, the following headers should be applied:

Example responses

The response received from the API will be below, depending on the endpoint used.

{

    "antispoofing": {

        "prediction": "real"

    },

    "age": {

        "age": 25.1,

        "st_dev": 3.5

    }

}

{

    "age": 43.2, 

    "st_dev": 4.4

}

{

    "prediction": "real"

}

Error codes

In case of any failure, you will receive the following error responses: