Selfie Validation API

API Description

Objective

The Selfie Validation API, also known as the Liveness API, verifies if a user's selfie has been captured by a live individual at the time of the verification indicating no fraudulent impersonation attempt. It also supports additional configurations to suit your business requirements.

Did you know?

In a fraudulent "photo-on-photo" scenario, a fraudster attempts to use an existing photograph of a different individual to deceive the verification system.

API URL

https://<regionCode>.idv.hyperverge.co/v1/checkLiveness

API Endpoint

checkLiveness

Supported Regions (`regionCode`)

The API URL accepts any of the region codes listed in the table below as values for the regionCode placeholder.

Region	regionCode Value
Africa	zaf
Europe	irl
India	ind
Indonesia	idn
Singapore	sgp
USA	usa

For example, to use this API for India, the URL would be: "https://ind.idv.hyperverge.co/v1/checkLiveness"

Overview

The API is RESTful and uses standard HTTP verbs and status codes. The responses are in JSON format and you should upload all images and ﬁles as form-data through a POST request.

Authentication

You need a unique pair of application ID ( appId ) and application key (appKey) from HyperVerge to verify your identity for accessing the API.

API Request Details

Method - `POST`

Headers

Parameter	Mandatory or Optional	Description	Valid Values
Content-type	Mandatory	The media type for the request payload.	multipart/form-data
appId	Mandatory	The application identifier shared by HyperVerge. You can find the details in the dashboard's credentials tab.	This should be a unique value.
appKey	Mandatory	The application key shared by HyperVerge. You can find the details in the dashboard's credentials tab.	This should be a unique value.
transactionId	Mandatory	A unique identifier for tracking a user journey.	This should be both unique and easily associated with the specific user's interaction in your application(s).

Inputs

The following table provides information on the parameters used in the request body for the API:

Parameter	Mandatory or Optional	Description	Allowed Values	Default Values
`image`	Mandatory	The selfie image file to be processed	Image formats: JPG, JPEG, and PNG	Not Applicable
`returnCroppedImageURL`	Optional	When enabled, returns a signed URL of the cropped face image from the uploaded selfie	`yes`, `no`	`no`

Quality Checks

Parameter	Mandatory or Optional	Description	Allowed Values	Default Values
`qualityChecks.blur`	Optional	Flag to perform blur detection on the image	`yes`, `no`	`no`
`qualityChecks.eyesClosed`	Optional	Flag to check if eyes are closed in the image	`yes`, `no`	`no`
`qualityChecks.occlusion`	Optional	Flag to check if the face is partially occluded by any object, hand, mask, or accessory	`yes`, `no`	`no`
`qualityChecks.multipleFaces`	Optional	Flag to detect multiple faces in the image	`yes`, `no`	`no`
`qualityChecks.headTurned`	Optional	Flag to detect if the head is turned in the image	`yes`, `no`	`no`
`qualityChecks.hat`	Optional	Flag to check if the individual is wearing a hat	`yes`, `no`	`no`
`qualityChecks.eyewear`	Optional	Flag to check if the individual is wearing any eyewear	`yes`, `no`	`no`
`qualityChecks.readingGlasses`	Optional	Flag to check if the individual is wearing reading glasses	`yes`, `no`	`no`
`qualityChecks.sunglasses`	Optional	Flag to check if the individual is wearing sunglasses	`yes`, `no`	`no`
`qualityChecks.dull`	Optional	Flag to check if the selfie is under-exposed	`yes`, `no`	`no`
`qualityChecks.bright`	Optional	Flag to check if the selfie is over-exposed	`yes`, `no`	`no`
`qualityChecks.nonWhiteBackground`	Optional	Flag to check if the background is not white	`yes`, `no`	`no`
`qualityChecks.nudity`	Optional	Flag to check the selfie for any explicit content	`yes`, `no`	`no`
`qualityChecks.lowQuality`	Optional	Flag to check if the overall image quality is too low for reliable processing	`yes`, `no`	`no`

Face Attribute Checks

Parameter	Mandatory or Optional	Description	Allowed Values	Default Values
`ageRange`	Optional	Returns the estimated age range of the individual in the selfie	`yes`, `no`	`no`
`checkGender`	Optional	Returns the estimated gender of the individual in the selfie	`yes`, `no`	`no`

Additional Checks

For a complete list of all quality checks, face attribute checks, and fraud checks, see our Additional Checks for Liveness page.
Depending on the checks enabled for your credentials, all or a subset of these checks would be available in your API response.

Request

The following is a sample cURL request for the API with all checks enabled:

curl --location 'https://<regionCode>.idv.hyperverge.co/v1/checkLiveness' \
--header 'appId: <Enter_the_HyperVerge_appId>' \
--header 'appKey: <Enter_the_HyperVerge_appKey>' \
--header 'transactionId: <Enter_the_transactionId>' \
--form 'image=@"<path_to_image>"' \
--form 'returnCroppedImageURL="yes"' \
--form 'qualityChecks.blur="yes"' \
--form 'qualityChecks.eyesClosed="yes"' \
--form 'qualityChecks.occlusion="yes"' \
--form 'qualityChecks.multipleFaces="yes"' \
--form 'qualityChecks.headTurned="yes"' \
--form 'qualityChecks.hat="yes"' \
--form 'qualityChecks.eyewear="yes"' \
--form 'qualityChecks.readingGlasses="yes"' \
--form 'qualityChecks.sunglasses="yes"' \
--form 'qualityChecks.dull="yes"' \
--form 'qualityChecks.bright="yes"' \
--form 'qualityChecks.nonWhiteBackground="yes"' \
--form 'qualityChecks.nudity="yes"' \
--form 'qualityChecks.lowQuality="yes"' \
--form 'ageRange="yes"' \
--form 'checkGender="yes"'

Success Response

The following is a comprehensive success response with all quality checks and face attribute checks enabled:

{
  "status": "success",
  "statusCode": 200,
  "metadata": {
    "requestId": "<Request_ID>",
    "transactionId": "<Transaction_ID>"
  },
  "result": {
    "details": {
      "liveFace": {
        "value": "yes",
        "confidence": "high"
      },
      "ageRange": {
        "low": 19,
        "high": 25,
        "value": "19-25",
        "confidence": "high"
      },
      "gender": {
        "value": "Female",
        "confidence": "high"
      },
      "qualityChecks": {
        "multipleFaces": {
          "value": "no",
          "confidence": "high"
        },
        "eyewear": {
          "value": "no",
          "confidence": "high"
        },
        "readingGlasses": {
          "value": "no",
          "confidence": "high"
        },
        "sunglasses": {
          "value": "no",
          "confidence": "high"
        },
        "nudity": {
          "value": "no",
          "confidence": "high"
        },
        "faceOccluded": {
          "value": "no",
          "confidence": "high"
        },
        "headTurned": {
          "value": "no",
          "confidence": "high"
        },
        "bright": {
          "value": "no",
          "confidence": "high"
        },
        "blur": {
          "value": "no",
          "confidence": "high"
        },
        "eyesClosed": {
          "value": "no",
          "confidence": "high"
        },
        "nonWhiteBackground": {
          "value": "no",
          "confidence": "high"
        },
        "hat": {
          "value": "no",
          "confidence": "high"
        },
        "dull": {
          "value": "no",
          "confidence": "high"
        },
        "lowQuality": {
          "value": "no",
          "confidence": "high"
        }
      }
    },
    "summary": {
      "action": "pass",
      "details": []
    },
    "croppedImageUrl": "<signed_URL_of_the_cropped_face_image>"
  }
}

Success Response Details

Parameter	Type	Description
status	string	The status of the request. Returns `success` for a successful API call.
statusCode	integer	The HTTP status code returned for the request. Returns `200` on success.
metadata.requestId	string	A unique identifier for the request, generated by HyperVerge.
metadata.transactionId	string	The transaction ID passed in the request header, used to track the user journey.
result.details.liveFace.value	string	Indicates whether the face in the image is live. Returns `yes` or `no`.
result.details.liveFace.confidence	string	The confidence level for the live face determination. Returns `high` or `low`.
result.details.ageRange.value	string	The estimated age range of the individual (e.g., `"19-25"`). Returned when `ageRange` is enabled.
result.details.ageRange.low	integer	The lower bound of the estimated age range.
result.details.ageRange.high	integer	The upper bound of the estimated age range.
result.details.ageRange.confidence	string	The confidence level for the age range estimate. Returns `high` or `low`.
result.details.gender.value	string	The estimated gender of the individual (e.g., `"Female"`, `"Male"`). Returned when `checkGender` is enabled.
result.details.gender.confidence	string	The confidence level for the gender estimate. Returns `high` or `low`.
result.details.qualityChecks.blur.value	string	Indicates whether the image is blurred. Returns `yes` or `no`. Returned when `qualityChecks.blur` is enabled.
result.details.qualityChecks.blur.confidence	string	The confidence level for blur detection.
result.details.qualityChecks.eyesClosed.value	string	Indicates whether the eyes are closed. Returns `yes` or `no`. Returned when `qualityChecks.eyesClosed` is enabled.
result.details.qualityChecks.eyesClosed.confidence	string	The confidence level for the eyes closed check.
result.details.qualityChecks.faceOccluded.value	string	Indicates if the face is partially or fully occluded by objects, hands, masks, or accessories. Returns `yes` or `no`. Returned when `qualityChecks.occlusion` is enabled.
result.details.qualityChecks.faceOccluded.confidence	string	The confidence level for the occlusion check.
result.details.qualityChecks.multipleFaces.value	string	Indicates whether multiple faces are detected. Returns `yes` or `no`. Returned when `qualityChecks.multipleFaces` is enabled.
result.details.qualityChecks.multipleFaces.confidence	string	The confidence level for the multiple faces check.
result.details.qualityChecks.headTurned.value	string	Indicates whether the head is not facing forward. Returns `yes` or `no`. Returned when `qualityChecks.headTurned` is enabled.
result.details.qualityChecks.headTurned.confidence	string	The confidence level for the head turned check.
result.details.qualityChecks.hat.value	string	Indicates whether the individual is wearing a hat. Returns `yes` or `no`. Returned when `qualityChecks.hat` is enabled.
result.details.qualityChecks.hat.confidence	string	The confidence level for the hat check.
result.details.qualityChecks.eyewear.value	string	Indicates whether the individual is wearing any eyewear. Returns `yes` or `no`. Returned when `qualityChecks.eyewear` is enabled.
result.details.qualityChecks.eyewear.confidence	string	The confidence level for the eyewear check.
result.details.qualityChecks.readingGlasses.value	string	Indicates whether the individual is wearing reading glasses. Returns `yes` or `no`. Returned when `qualityChecks.readingGlasses` is enabled.
result.details.qualityChecks.readingGlasses.confidence	string	The confidence level for the reading glasses check.
result.details.qualityChecks.sunglasses.value	string	Indicates whether the individual is wearing sunglasses. Returns `yes` or `no`. Returned when `qualityChecks.sunglasses` is enabled.
result.details.qualityChecks.sunglasses.confidence	string	The confidence level for the sunglasses check.
result.details.qualityChecks.dull.value	string	Indicates whether the selfie is under-exposed. Returns `yes` or `no`. Returned when `qualityChecks.dull` is enabled.
result.details.qualityChecks.dull.confidence	string	The confidence level for the dull (under-exposure) check.
result.details.qualityChecks.bright.value	string	Indicates whether the selfie is over-exposed. Returns `yes` or `no`. Returned when `qualityChecks.bright` is enabled.
result.details.qualityChecks.bright.confidence	string	The confidence level for the bright (over-exposure) check.
result.details.qualityChecks.nonWhiteBackground.value	string	Indicates whether the background is non-white. Returns `yes` or `no`. Returned when `qualityChecks.nonWhiteBackground` is enabled.
result.details.qualityChecks.nonWhiteBackground.confidence	string	The confidence level for the non-white background check.
result.details.qualityChecks.nudity.value	string	Indicates whether explicit content is detected. Returns `yes` or `no`. Returned when `qualityChecks.nudity` is enabled.
result.details.qualityChecks.nudity.confidence	string	The confidence level for the nudity check.
result.details.qualityChecks.lowQuality.value	string	Indicates whether the overall image quality is too low for reliable processing. Returns `yes` or `no`. Returned when `qualityChecks.lowQuality` is enabled.
result.details.qualityChecks.lowQuality.confidence	string	The confidence level for the low quality check.
result.croppedImageUrl	string	The signed URL to access the cropped face image from the uploaded selfie. Returned when `returnCroppedImageURL` is enabled.
result.summary.action	string	The final decision for the verification. Returns `pass`, `fail`, or `manualReview`.
result.summary.details	array	An array of objects providing additional context for the summary action (e.g., failure reason codes and messages).

The Summary Object

The Summary object helps in deciding the final action for a user's application.

It contains any of the following decisions:
- "Fail(reject)",
- "Manual Review",
- "Pass(approve)".
The configuration for these decisions are customisable. It can be changed to suit your business requirements through the integration and also after going live.
The configuration is hosted in the backend and not in the SDK or frontend.
New features can be supported immediately not requiring application releases at your end.

The following code samples are the 3 types of actions responses that you will find in the response.

Approve
Reject
Manual Review

This is the response where the application is approved for further processing.

"summary": {
    "action": "pass",
    "details": []
}

This is the response where the application is rejected.

"summary": {
    "action": "fail",
        "details": [
        {
            "code": "001",
            "message": "Black and white document"
        }
    ]
}

This is the response where the application is sent to manual review.

"summary": {
    "action": "manualReview",
        "details": [
        {
            "code": "011",
            "message": "Name confidence is low"
        }
    ]
}

Error Responses

A failure or error response contains a failure status with a relevant status code and error message. The following tabs show the error responses for each status code.

400 - Parse Error
400 - Unsupported File Type
401 - Unauthorized
403 - Forbidden

Returned when the request body cannot be parsed. Check that all form-data fields are correctly formatted.

{
  "statusCode": 400,
  "status": "failure",
  "result": {
    "error": "Error while parsing request body"
  },
  "metadata": {
    "transactionId": "<Transaction_ID>",
    "requestId": "<Request_ID>"
  }
}

Returned when the uploaded file format is not supported. Upload a valid JPG, JPEG, or PNG image.

{
  "statusCode": 400,
  "status": "failure",
  "result": {
    "error": "Unsupported file type",
    "summary": {
      "action": "fail",
      "details": [
        {
          "code": "111",
          "message": "Bad Request. Please refer the documentation"
        }
      ]
    }
  },
  "metadata": {
    "transactionId": "<Transaction_ID>",
    "requestId": "<Request_ID>"
  }
}

Returned when the appId or appKey is missing or invalid.

{
  "statusCode": 401,
  "status": "failure",
  "result": {
    "error": "Missing/Invalid credentials"
  },
  "metadata": {
    "requestId": "<Request_ID>"
  }
}

Returned when the credentials are valid but do not have permission to access this API.

{
  "statusCode": 403,
  "status": "failure",
  "result": {
    "error": "Unauthorized Access to API"
  },
  "metadata": {
    "requestId": "<Request_ID>",
    "transactionId": "<Transaction_ID>"
  }
}

404 - Not Found
422 - No Face Detected
429 - Rate Limit
500 - Internal Server Error
503 - Service Unavailable

Returned when the requested API endpoint does not exist. Verify the API URL.

{
  "statusCode": 404,
  "status": "failure",
  "result": {
    "error": "Not Found"
  },
  "metadata": {
    "requestId": "<Request_ID>"
  }
}

Returned when the model cannot detect a face in the submitted image.

{
  "statusCode": 422,
  "status": "failure",
  "result": {
    "error": "No face detected",
    "summary": {
      "action": "fail",
      "details": [
        {
          "code": "121",
          "message": "Face Not detected in selfie image"
        }
      ]
    }
  },
  "metadata": {
    "transactionId": "<Transaction_ID>",
    "requestId": "<Request_ID>"
  }
}

Returned when the configured rate limit for transactions per minute has been exceeded.

{
  "statusCode": 429,
  "status": "failure",
  "result": {
    "error": "Rate limit error"
  }
}

Returned when an unexpected server-side error occurs.

{
  "statusCode": 500,
  "status": "failure",
  "result": {
    "error": "Internal Server Error",
    "summary": {
      "action": "manualReview",
      "details": [
        {
          "code": "110",
          "message": "Server Error. Please contact support"
        }
      ]
    }
  },
  "metadata": {
    "transactionId": "<Transaction_ID>",
    "requestId": "<Request_ID>"
  }
}

Returned when the server is temporarily overloaded. Retry the request after a short wait.

{
  "statusCode": 503,
  "status": "failure",
  "result": {
    "error": "SERVER BUSY - retry after sometime"
  },
  "metadata": {
    "transactionId": "<Transaction_ID>",
    "requestId": "<Request_ID>"
  }
}

Error Response Details

The following table lists all error responses with their status codes and descriptions.

Status Code	Error Message	Description
400	Error while parsing request body	The request body could not be parsed. Check that all form-data fields are correctly formatted.
400	Unsupported file type	The uploaded file format is not supported. Please upload a valid JPG, JPEG, or PNG image.
401	Missing/Invalid credentials	The `appId` or `appKey` provided in the request headers is missing or incorrect.
403	Unauthorized Access to API	The credentials are valid but do not have permission to access this API endpoint.
404	Not Found	The requested API endpoint does not exist. Verify the API URL.
422	No face detected	The model failed to detect a face in the submitted selfie. Ensure the image contains a clearly visible face.
429	Rate limit error	You have exceeded the configured rate limit for transactions per minute. Retry after a short interval.
500	Internal Server Error	An unexpected server-side error occurred. Contact the HyperVerge Support team for resolution.
503	SERVER BUSY - retry after sometime	The server is temporarily overloaded. Retry the request after a short wait.

Reading Results for Selfie Validation

We recommend using the liveFace parameter in the response to decide the result.

liveFace.value = "yes" , when the face in the image taken is live
liveFace.value = "no" , when face in the image taken is not live
action parameter in the response can be used to decide whether the image sent requires manual review or not (optional)

Logic Recommended

How to assess the Liveness, based on the response returned by the API:

Approved
Rejected
Manual Review

When the following conditions are met:

statusCode = 200
liveFace.value = "yes"
action = "pass"

When the following conditions are met:

statusCode = 200
liveFace.value = "no"
action = "fail"

OR all other status codes

When the following conditions are met:

statusCode = 200
liveFace.value = "yes"/"no"
action = "manualReview"

Note: Retries can be enabled to avoid manual review. Maximum of 3 retries is recommended.

API Description​

Objective​

API URL​

API Endpoint​

Supported Regions (regionCode)​

Overview​

Authentication​

API Request Details

Method - POST

Headers

Inputs​

Quality Checks​

Face Attribute Checks​

Request​

Success Response​

Success Response Details​

The Summary Object​

Error Responses​

Error Response Details​

Reading Results for Selfie Validation​

Logic Recommended​

API Description

Objective

API URL

API Endpoint

Supported Regions (`regionCode`)

Overview

Authentication

Method - `POST`

Inputs

Quality Checks

Face Attribute Checks

Request

Success Response

Success Response Details

The Summary Object

Error Responses

Error Response Details

Reading Results for Selfie Validation

Logic Recommended