Liveness Check

Liveness API

POST https://{vida.host}/biometrics/v2/services/face/liveliness

Headers

Name	Type	Description
Authorization*		OAuth access token. Get the token by calling the Authentication API
Content-Type*	application/json	Format type of request body

Request Body

Name	Type	Description
image*	String	Data URI scheme, Base64 encoded image.
partnerTrxId*	String	A partner can optionally send a transaction id to co-relate their transaction with VIDA transaction. However, it is an optional parameter and is maintained by the partner.
imgManipulationCheckEnabled	boolean	Enable this option to identify morph patterns commonly present in photoshopped images, generated swapped selfie images, and deep fakes.

API Response

Liveness Detection Successful

HTTP Status Code: 200

JSON Response

The system detected a higher confidence of live selfie when the liveness score < 0.95.

{
   "data": {
      "code": 1043,
      "message": "Selfie photo is a live photo",
      "score": "0.001102",
      "imgManipulationScore": "0.098010", //Available only when imgManipulation is enabled
      "transactionId": "f373342c-77f8-406e-95ca-1a9744369b28"
   }
} 

The success response in live selfie will consist of:

• score

• transactionId.

The liveness score ranges from 0 to 1. The score of 0 (zero) represents maximum liveness, and the score of 1 represents minimum liveness of the selfie. The default threshold is a 0.95 score.

Liveness Score below the Threshold

HTTP Status Code: 200

JSON Response

{
   "data": {
      "code": 1041,
      "message": "Photo liveness score is below the threshold",
      "score": "0.950057",
      "imgManipulationScore": "0.997923", //Available only when imgManipulation is enabled
      "transactionId": "b3be6fd3-b507-4bc5-9e79-e487ae869624"
   }
}

The system detected a higher confidence of spoofed or hacked selfie when the liveness score >= 0.95.

The success response in spoof or hacked selfie will consist of:

• score

• transactionId

The liveness score ranges from 0 to 1. The score of 0 (zero) represents maximum liveness and the score of 1 represents minimum liveness of the selfie. The default threshold is a 0.95 score.

Face Occluded

HTTP Status Code: 400

Recommendation : The partner must ensure there is no occluded object when capturing the selfie.

JSON Response

{
   "errors": [
      {
         "code": 1051,
         "title": "detect un-standardized image quality",
         "detail": "Face Occluded"
      }
   ],
 "transactionId": "ea6385be-7d24-459c-a526-e34f099afdd9"
}

The face in the selfie is occluded by an object.

Face Too Small

HTTP Status Code: 400

Recommendation: The partner must capture the face size area greater than 50x50 pixels.

JSON Response

{
   "errors": [
      {
         "code": 1052,
         "title": "detect un-standardized image quality",
         "detail": "Face too small"
      }
   ],
    "transactionId": "3b893cc2-e18f-47eb-a44e-80e7d879fdaa"
}

The face size area is smaller than 50 x 50 pixels.

Image quality low

HTTP Status Code: 400

Recommendation: The partner needs to ensure the image input is in good quality condition.

JSON Response

{
   "errors": [
      {
         "code": 1053,
         "title": "detect un-standardized image quality",
         "detail": "Image quality low"
      }
   ],
    "transactionId": "3b893cc2-e18f-47eb-a44e-80e7d879fdaa"
}

The system captures the possibility of broken image, corrupted image, or low quality.

Multiple faces detected

HTTP Status Code: 400

Recommendation: The partner needs to ensure that only one face is in the frame.

JSON Response

{
   "errors": [
      {
         "code": 1054,
         "title": "detect un-standardized image quality"",
         "detail": "More than one face"
      }
   ],
    "transactionId": "3b893cc2-e18f-47eb-a44e-80e7d879fdaa"
}

Multiple faces are detected in the frame.

No face detected

HTTP Status Code: 400

Recommendation: The partner needs to ensure at least one face is present in the frame.

JSON Response

{
   "errors": [
      {
         "code": 1055,
         "title": "detect un-standardized image quality",
         "detail": "No face detected"
      }
   ],
    "transactionId": "3b893cc2-e18f-47eb-a44e-80e7d879fdaa"
}

No face object found in the image frame.

Unnatural Colour Detected

HTTP Status Code: 400

Recommendation: The partner needs to ensure the selfie should be clean and undamaged.

JSON Response

{
   "errors": [
      {
         "code": 1063,
         "title": "Image Quality Is Below Threshold",
         "detail": "Unnatural colour"
      }
   ],
    "transactionId": "3b893cc2-e18f-47eb-a44e-80e7d879fdaa"
}

Damaged image or saturated image is detected.

Under Exposure Detected

HTTP Status Code: 400

Recommendation: The partner needs to ensure the selfie should be well-lit and properly exposed.

JSON Response

{
   "errors": [
      {
         "code": 1074,
         "title": "Image Quality Is Below Threshold",
         "detail": "Under Exposure"
      }
   ],
    "transactionId": "3b893cc2-e18f-47eb-a44e-80e7d879fdaa"
}

A low lighting selfie is detected.

Over Exposure Detected

HTTP Status Code: 400

Recommendation: The partner needs to ensure the selfie should be properly exposed with no blown-out highlight.

JSON Response

{
   "errors": [
      {
         "code": 1075,
         "title": "Image Quality Is Below Threshold",
         "detail": "Over Exposure"
      }
   ],
    "transactionId": "3b893cc2-e18f-47eb-a44e-80e7d879fdaa"
}

Overexposure or blown-out highlights in a selfie are detected.

Blurry Image Detected

HTTP Status Code: 400

Recommendation: The partner needs to ensure the selfie should be sharp and in focus.

JSON Response

{
   "errors": [
      {
         "code": 1076,
         "title": "Image Quality Is Below Threshold",
         "detail": "Image is blur"
      }
   ],
    "transactionId": "3b893cc2-e18f-47eb-a44e-80e7d879fdaa"
}

Blurry conditions or defocused face in a selfie are detected.

Multiple Error Example

The error response format in case of multiple error.

Recommendation: The partner needs to ensure all the errors are addressed.

HTTP Status Code: 400

Over Exposure, Image is Blur and Unnatural color

JSON Response

{
    "errors": [
        {
            "code": 1075,
            "title": "Image Quality Is Below Threshold",
            "detail": "Over Exposure"
        },
        {
            "code": 1076,
            "title": "Image Quality Is Below Threshold",
            "detail": "Image Is Blur"
        },
        {
            "code": 1063,
            "title": "Image Quality Is Below Threshold",
            "detail": "Unnatural colour"
        }
    ],
    "transactionId": "3392154b-fce8-49ea-92cb-75272b7ea016"
}

Unnatural Color and Under Exposure

JSON Response

{
    "errors": [
        {
            "code": 1063,
            "title": "Image Quality Is Below Threshold",
            "detail": "Unnatural colour"
        },
        {
            "code": 1074,
            "title": "Image Quality Is Below Threshold",
            "detail": "Under Exposure"
        }
    ],
    "transactionId": "9e9f0a0e-ef36-4579-a844-240debf1c235"
}

Unnatural Color and Blur Image

JSON Response

{
    "errors": [
        {
            "code": 1076,
            "title": "Image Quality Is Below Threshold",
            "detail": "Image Is Blur"
        },
        {
            "code": 1063,
            "title": "Image Quality Is Below Threshold",
            "detail": "Unnatural colour"
        }
    ],
    "transactionId": "9488b3d0-530c-42e3-9191-5bf63f1e63fe"
}