API reference

AI Tools

The following provides information about API endpoints, response and error codes.

Endpoints

You can create two types of requests using the API:

Endpoint	Description
POST https://api.yoti.com/ai/v1/age-verify	Use Yoti's Age estimation verify service.
POST https://api.yoti.com/ai/v1/age-antispoofing-verify	Use Yoti's Age estimation verify service and the Anti-spoofing check.

Request

The JSON object body for the API request has the following structure:

{ "img": "base64_image", "threshold": "age_threshold", "operator": "OVER" | "UNDER", "metadata": (Optional) { "device": "mobile", "laptop", "unknown" }, }

Example request

A typical API request would have the following JSON body:

{ "img": "/9j/4AAQSkZJRgABAgAAAQABAAD/2wAcHNXCKigjEaYH51Me1Zy1Za0P/Z....", "threshold": 25, "operator": "OVER", "metadata": { "device": "mobile" } }

Relaxed image requirements

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

{ "img": "/9j/4AAQSkZJRgABAgAAAQABAAD/2wAcHNXCKigjEaYH51Me1Zy1Za0P/Z....", "img_validation_level": "low" }

Note: This may only be used with the age endpoint.

Response

The JSON object body returned from the API has the following structure:

{ "age": { "age_check": "pass | fail" (string) }, "antispoofing": { "prediction": "real | fake" } }

Response	Explained
Prediction - real	Yoti has detected a real user.
Prediction - fake	Yoti has detected a spoof attempt.
Age - pass	The estimation age of the user has passed the age threshold.
Age - fail	The estimation age of the user has failed the age threshold.

Example response

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

{ "age_check": "pass" }

{ "age": { "age_check": "pass" }, "antispoofing": { "prediction": "real" } }

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	X-Yoti-Auth-Id header not provided. auth id is not a valid uuid.
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	X-Yoti-Auth-Digest header is missing. X-Yoti-Auth-Digest is not base64 encoded.
401	INVALID_NONCE	Nonce is missing. nonce parameter is mandatory Provided nonce is not a valid uuid.
401	INVALID_TIMESTAMP	Timestamp is missing. timestamp parameter is mandatory. Provided timestamp is not a valid unix 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	Base64 image is incorrectly padded. Cannot create image from base64 decoded bytes
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	Age distribution is empty. Standard deviation is empty. Cannot build model result. Antispoofing prediction failed.
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.

Last updated on

Was this page helpful?