API reference

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

Endpoints

You can create the age estimation and anti-spoofing request using the API:

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

Headers

The API supports the following headers:

Header	Description
X-Yoti-Auth-Id	SDK ID for the Yoti Hub application.
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. Optional.

Request

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

JSON
    
 
{    "img": "base64encoded_image"}
Copy

Example request

A typical API request will have a JSON body similar to the following:

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

Response

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

JSON
    
 
{   "antispoofing": {       "prediction": "real | fake"   },   "age": {       "age": float,       "st_dev": float   }}
Copy

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 an uncertainly value. 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.

Example response

The response received from the API will be similar to the following:

/self-checkout/age-antispoofing
    
 
{    "antispoofing": {        "prediction": "real"    },    "age": {        "age": 25.1,        "st_dev": 3.5    }}
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?