API reference

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:

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

Example request

A typical API request would have the following JSON body:

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

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.

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

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

Response

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

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

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-verify
    
 
{    "age_check": "pass"}
Copy

/age-antispoofing-verify
    
 
{    "age": {        "age_check": "pass"    },    "antispoofing": {        "prediction": "real"    }}
Copy

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?