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 yotiYou can create three types of requests using the API:
| Endpoint | Description |
|---|---|
| https://api.yoti.com/ai/v1/age?secure=true | Use Yoti's Age estimation service. |
| https://api.yoti.com/ai/v1/antispoofing?secure=true | Use Yoti's Anti-spoofing (liveness) check. |
| https://api.yoti.com/ai/v1/age-antispoofing?secure=true | Use Yoti's Age estimation service and the Anti-spoofing (liveness) check. |
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>" }}| Parameter | Explained |
|---|---|
| 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 Face Capture Module - 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
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. |
Retrieve the results
The endpoint will return the Anti-spoofing result alongside Age estimation.
{ "antispoofing": { "prediction": "real | fake" }, "age": { "st_dev": float, "age": float }}| Response | Explained |
|---|---|
| Prediction - real | Yoti has detected a real user. |
| Prediction - fake | Yoti has detected a spoof attempt. |
| Age - age | The age estimation of the user. |
| Age - st_dev | The st_dev value is a quality score. Yoti advises rejecting any response with a value higher than 6.0, as this usually suggests an issue with image capture. |
Error codes
In case of any failure, you will receive the following error responses:
| Error code | Error | Description |
|---|---|---|
| 404 | APP_NOT_FOUND | Application app_id not found. |
| 401 | INVALID_X_YOTI_AUTH_ID |
|
| 400 | INVALID_APP_ID | Application id cannot be empty. |
| 400 | INVALID_PUBLIC_KEY | Application public key cannot be empty. |
| 403 | DISABLED_APP_STATE | Application must be enabled. |
| 400 | INVALID_ORG_ID | Organisation id cannot be empty. |
| 400 | INVALID_BILLING_SOURCE_ID | Application billing source id cannot be empty. |
| 404 | ORG_NOT_FOUND | Organisation org_id not found. |
| 401 | INVALID_YOTI_AUTH_DIGEST |
|
| 401 | INVALID_NONCE |
|
| 401 | INVALID_TIMESTAMP |
|
| 401 | INVALID_PUBLIC_KEY_ENCODING | Failed to load public key. key is not der encoded. |
| 401 | UNSUPPORTED_ALGORITHM | Serialised key is of a type that is not supported by the backend. |
| 401 | INVALID_SIGNATURE | Failed to verify signature. |
| 403 | INVALID_ORG_STATUS | Organisation has an invalid status. |
| 404 | INVALID_METADATA_DEVICE | Invalid device metadata provided. |
| 400 | INVALID_BODY_ENCODING | Request body should be a valid JSON. |
| 404 | INVALID_ENDPOINT | The endpoint request is invalid. |
| 413 | PAYLOAD_TOO_LARGE | Payload too large. |
| 400 | IMAGE_NOT_PROVIDED | Image has not been provided. |
| 400 | INVALID_B64_IMAGE |
|
| 400 | UNSUPPORTED_IMAGE_FORMAT | Image format not supported. Please use JPEGs (95 to 100 quality) and PNGs. |
| 400 | IMAGE_SIZE_TOO_BIG | Image size too big, the maximum size is 1.5MB. |
| 400 | IMAGE_SIZE_TOO_SMALL | Image size too small, the minimum size is 50KB. |
| 400 | MIN_HEIGHT | The image height is incorrect. Image minimum height required is 300 pixels. |
| 400 | MAX_HEIGHT | The image height is incorrect. Image maximum height required is 2000 pixels. |
| 400 | MIN_WIDTH | The image width is incorrect. Image minimum width required is 300 pixels. |
| 400 | MAX_WIDTH | The image width is incorrect. Image maximum width required is 2000 pixels. |
| 400 | MIN_PIXELS | To process the image the minimum number of pixels required is 90,000 pixels. |
| 400 | MAX_PIXELS | To process the image the maximum number of pixels required is 2,100,000 pixels. |
| 400 | IMAGE_WRONG_CHANNELS | Missing colour channel, the input image must be RGB or RGBA. |
| 400 | IMAGE_GRAYSCALE_NOT_SUPPORTED | Grayscale images not supported. |
| 503 | SERVICE_UNAVAILABLE | The service is temporarily unavailable. |
| 400 | FACE_NOT_FOUND | Face not found. |
| 400 | MULTIPLE_FACES | Multiple faces in the image provided. |
| 400 | FACE_BOX_TOO_SMALL | The face in the image provided is too small. |
| 400 | FACE_TO_IMAGE_RATIO_TOO_LOW | Face ratio is lower than the minimum ratio. |
| 400 | FACE_TO_IMAGE_RATIO_TOO_HIGH | Face ratio is bigger than the maximum ratio. |
| 400 | INSUFFICIENT_AREA_AROUND_THE_FACE | Insufficient area around the face in the image provided. |
| 400 | IMAGE_TOO_BRIGHT | Image too bright.. |
| 400 | IMAGE_TOO_DARK | Image too dark. |
| 400 | INVALID_LEVEL_OF_ASSURANCE | Invalid antispoofing level of assurance provided. |
| 400 | INVALID_REQUEST_BODY | Request body is invalid, '-' field is invalid. |
| 400 | INVALID_IMG_VALIDATION_LEVEL | The image validation level is invalid. |
| 401 | UNAUTHORIZED | The X-Yoti-Auth-Id provided isn't authorized to access this resource. |
| 500 | FAIL_PREDICTION |
|
| 500 | UNSPECIFIED_ERROR | An internal server error occurred. |
| 400 | SECURE_REQUEST_IS_EMPTY | Secure request field is empty. |
| 400 | SECURE_SESSION_NOT_FOUND | Secure session not found. |
| 400 | SECURE_SIGNATURE_NOT_FOUND | Secure signature not found. |
| 400 | SECURE_VERSION_NOT_FOUND | Secure version not found. |
| 400 | INVALID_SECURE_SIGNATURE | Failed to verify secure session signature. |
| 400 | SECURE_VERIFICATION_NOT_FOUND | Secure verification not found. |
| 400 | UNTRUSTED_SECURE_SESSION | Untrusted secure session |
| 401 | INVALID_SECURE_SESSION | Invalid secure session token. |
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.
##