Deprecation warning
This documentation is for our legacy Age Estimation API. For new integrations, we recommend you follow these docs.
Once you've set up your organisation account on the Yoti Hub, you’re ready to start integrating.
Help Please contact us though our support form for any advice on integrating this product.
Image requirements
The image requirements to use our services are:
Condition | Age estimation |
|---|
Quantity | Only one single face in the image. |
Image type | Yoti only accepts JPEG’s encoded as a base64 image |
Image resolution | The minimum face dimensions we accept is 96 x 96 pixels |
Colour | The image must be colour (RGB). Yoti does not accept black and white or filtered images. |
Size | Base64 body must be below 100KB (~70KB JPEG) |
There’s a tradeoff between estimation accuracy and camera quality / light conditions, false-negative errors such as face not detected or spoofing attempt detected may be higher than expected due to one or more of the following factors:
Condition | Description |
|---|
Lighting | Provide UX and guidance to the user. Jump to User experience for more information. |
Face positioning | Guide the users to place their face in the middle of the photo you are capturing. A near frontal pose with no obstruction to the facial features. The minimum inter ocular distance is 120 pixels. |
Camera angle | Please try to get a face-on photo of the user to get the best result. The camera’s field of view is too small to provide suitable context around the facial image captured. |
Camera type | The API does not work on infrared cameras. To ensure the best performance we are happy to support your testing when evaluating camera options. |
Image cropping | Further image cropping can also reduce the context around the facial image captured. This can negatively impact the ability of the algorithm to compare to other ‘normal’ images in its learned model. |
Glare / Blur | Insufficient anti-glare capabilities of either the lens or the glass will make it harder for the anti-spoofing to accurately detect edges around faces. This can negatively impact the ability of the algorithm to compare to other ‘normal’ images in its learned model. |
Zoom | Optical zoom effects can reduce the context around the facial image captured. This can negatively impact the ability of the algorithm to compare to other ‘normal’ images in its learned model. A distorted lens structure, such as a ‘fish-eye’ lens which is not how the AI model has been trained. |
Image compression | Too much image compression is applied to the captured image which creates ‘artefacts’ and inaccuracies in the image (ideally no more than 90% compression). This can negatively impact the ability of the algorithm to compare to other ‘normal’ images in its learned model. |
Create a request
After completing the Yoti onboarding, you will need to complete authentication for the API by using the Yoti SDK to simplify the process for requesting to Yoti. The Yoti SDKs are available via popular dependency management systems. Further details can be found on the pages of the specific projects.
// If you are using Maven, add the following dependency:
<dependency>
<groupId>com.yoti</groupId>
<artifactId>yoti-sdk-api</artifactId>
<version>3.0.0</version>
</dependency>
// If you are using Gradle, add the following dependency:
compile group: 'com.yoti', name: 'yoti-sdk-api', version: '3.0.0'
// Get the Yoti PHP SDK library via a Composer package
composer require yoti/yoti-php-sdk
// To install the Yoti NuGet package you will need to install NuGet.
// To import the latest Yoti SDK into your project, enter the following
// command from NuGet Package Manager Console in Visual Studio:
Install-Package Yoti
// For other installation methods, see https://www.nuget.org/packages/Yoti
// As of version 2.4.0, modules are used. This means it's not necessary to get a copy or fetch all dependencies
// as instructed below, as the Go toolchain will fetch them as necessary.
// You can simply add a `require github.com/getyoti/yoti-go-sdk/v2` to go.mod.
// To download and install the Yoti SDK and its dependencies, run the following command from your terminal:
go get "github.com/getyoti/yoti-go-sdk/v3"
gem install yoti
# The gem provides a configuration generator for Ruby on Rails:
rails generate yoti:install
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 { RequestBuilder, Payload } = require('yoti');
const request = new RequestBuilder()
.withBaseUrl('https://api.yoti.com/api/v1/age-verification')
.withPemFilePath('<YOTI_KEY_FILE_PATH>')
.withEndpoint('/checks')
.withPayload(new Payload(data))
.withMethod('POST')
.withHeader('X-Yoti-Auth-Id', '<YOTI_CLIENT_SDK_ID>')
.build();
//get Yoti response
const response = request.execute();
JsonObject body = new JsonObject();
body.put("data", imageBytes);
byte[] payload = body.encode().getBytes();
try {
SignedRequest signedRequest = new SignedRequestBuilder()
.withKeyPair(<YOTI_KEY_FILE_PATH>)
.withBaseUrl("https://api.yoti.com/api/v1/age-verification")
.withEndpoint("/checks")
.withPayload(payload)
.withHttpMethod("POST")
.withHeader("X-Yoti-Auth-Id", "<YOTI_CLIENT_SDK_ID>")
.build();
YourPojo yourPojo = signedRequest.execute(YourPojo.class);
} catch (GeneralSecurityException | URISyntaxException | IOException | ResourceException ex) {
ex.printStackTrace();
}
<?php
use Yoti\Http\RequestBuilder;
use Yoti\Http\Payload;
$data = [ "data" => "base64Image" ];
$request = (new RequestBuilder())
->withBaseUrl('https://api.yoti.com/api/v1/age-verification')
->withPemFilePath('<YOTI_KEY_FILE_PATH>')
->withEndpoint('/checks')
->withPayload(Payload::fromJsonData($data)) // For version < 3, use ->withPayload(new Payload(data))
->withMethod('POST')
->withHeader('X-Yoti-Auth-Id', '<YOTI_CLIENT_SDK_ID>')
->build();
// Execute request
$response = $request->execute();
// Get response body
$body = $response->getBody();
from yoti_python_sdk.http import SignedRequest, RequestHandler
import json
import requests
def generate_session():
data = {"data": "base64encodedstring"}
payload_string = json.dumps(data).encode()
signed_request = (
SignedRequest
.builder()
.with_pem_file("<YOTI_KEY_FILE_PATH>")
.with_base_url("https://api.yoti.com/api/v1/age-verification")
.with_endpoint("/checks")
.with_http_method("POST")
.with_header("X-Yoti-Auth-Id", "<YOTI_CLIENT_SDK_ID>")
.with_payload(payload_string)
.build()
)
# get Yoti response
response = signed_request.execute()
response_payload = json.loads(response.text)
using System;
using System.IO;
using System.Net.Http;
using System.Text;
using Microsoft.AspNetCore.Mvc;
using Yoti.Auth.Web;
HttpClient httpClient = new HttpClient();
StreamReader privateKeyStream = System.IO.File.OpenText(_pemFilePath);
string serializedRequest = Newtonsoft.Json.JsonConvert.SerializeObject(new
{
data = _base64Face
});
byte[] byteContent = Encoding.UTF8.GetBytes(serializedRequest);
Uri _baseUrl = new UriBuilder("https", "api.yoti.com", 443, "/api/v1/age-verification").Uri;
Yoti.Auth.Web.Request ageScanRequest = new RequestBuilder()
.WithStreamReader(privateKeyStream)
.WithBaseUri(_baseUrl)
.WithEndpoint("/checks")
.WithHttpMethod(HttpMethod.Post)
.WithContent(byteContent)
.WithHeader("X-Yoti-Auth-Id", _clientSdkId)
.Build();
HttpResponseMessage response = ageScanRequest.Execute(httpClient).Result;
import (
"io/ioutil"
"net/http"
"github.com/getyoti/yoti-go-sdk/v2/requests"
)
key, _ := ioutil.ReadFile("<YOTI_KEY_FILE_PATH>")
// Create session
request,_ := requests.SignedRequest{
HTTPMethod: http.MethodPost,
BaseURL: "https://api.yoti.com/api/v1/age-verification",
Endpoint: "/checks",
Headers: map[string][]string{
"Content-Type": {"application/json"},
"Accept": {"application/json"},
"X-Yoti-Auth-Id":{"<YOTI_CLIENT_SDK_ID>"},
},
Body: func(data []byte, _ error) []byte {
return data
}(json.Marshal(jsonobj{ data },
})),
}.WithPemFile(key).Request()
//get Yoti response
response, _ := http.DefaultClient.Do(request)
require 'yoti'
Yoti.configure do |config|
config.client_sdk_id = '<YOTI_CLIENT_SDK_ID>'
config.key_file_path = '<YOTI_KEY_FILE_PATH>'
end
request = Yoti::Request
.builder
.with_base_url('https://api.yoti.com/api/v1/age-verification')
.with_http_method('POST')
.with_endpoint('checks')
.with_payload(data: 'base64Image')
.with_header('X-Yoti-Auth-Id', Yoti.configuration.client_sdk_id)
.build
response = request.execute
body = response.body
puts body
This JSON string will be the data parameter in the withPayload above code snippet.
{
"data": "/9j/4AAQSkZJRgABAgAAAQABAAD/2wAcHNXCKigjEaYH51Me1Zy1Za0P/Z....",
}
If integrating into a non-browser client, we recommend contacting clientsupport@yoti.com for additional support.
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:
Header | Description |
|---|
Terminal-Id | Unique ID per machine. Mandatory for non-browser integrations. |
Session-Id | May be provided to demonstrate multiple attempts are from a single user transaction. |
Example responses
The response received from the API will be below:
The uncertainty value is a confidence score. Yoti recommends rejecting any response with an uncertainty greater than 6.0. Typically this indicates a problem with image capture. This should only be treated as a quality score.
{
"pred_age": 29.7475,
"uncertainty": 2.04677
}
Error codes
Error code | Description |
|---|
1 | Image too big |
2 | Unable to decode image (not a jpeg or wrong base64 string) |
4 | No face detected |
6 | Image not present |
7 | Generic bad request |
8 | No image detected |
9 | Internal server error |
