Face Search, Enrol or Block API

Description

Objective

The Face Search, Enrol or Block API enrols a user in the database, provides a reason for the enrolment rejection or adds it to a block-list.

Input	Output
The selfie of the customer and the unique transaction ID.	A response that reflects the success or failure of the customer enrolment process, or the addition to your block-list. The reason for rejecting the enrolment application is also returned if the enrolment fails.

Next Step

To enrol a face without running a search first, use the India Enrol Face flow or the same API with enrol and omitSearch set appropriately.

API URL

https://ind-orion.hyperverge.co/v2/search/face

API Endpoint

search/face

Overview

The Face Search, Enrol or Block API is RESTful and uses standard HTTP verbs and status codes. The responses are in JSON format and you should upload all images and files 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 Face Search, Enrol or Block API.

API Request Details

Method

POST

Headers

The following table provides the complete information on the request headers for the Face Search, Enrol or Block API.

Header	Mandatory / Optional	Description	Input Format
Content-Type	Mandatory	This parameter defines the media type for the request payload.	multipart/form-data
accept	Mandatory	This parameter defines the media type for the response.	application/json
appId	Mandatory	Application ID shared by HyperVerge.	N/A. This is a unique value.
appKey	Mandatory	Application Key shared by HyperVerge.	N/A. This is a unique value.
transactionId	Mandatory	Unique ID for the customer journey.	Any defined unique value mapped to a transaction in your business ecosystem.

Input

The following table provides the complete information on the input parameters used in the request body for the Face Search, Enrol or Block API.

Parameter	Mandatory or Optional	Valid Values	Type	Description
transactionId	Mandatory	N/A. This is a unique value.	string	The unique identifier for the customer's application.
selfie	Mandatory	N/A	file	The selfie image of the user. Note The maximum image size supported is 6 MB.
block	Optional	yes or no	string	To add this application to blocklist if enrol is set to yes.
enrol	Optional	yes or no	string	If this flag is set to yes, this customer application will be enrolled in your database.
omitSearch	Optional	yes or no	string	If this flag is set to yes, the Face Search, Enrol or Block API skips searching the database for a matching record. Note When both enrol and omitSearch are set to yes, the Face Search, Enrol or Block API only performs the enrollment for the application without searching for a matching record in the database.

Request

The following code snippet demonstrates a standard curl request for the Face Search, Enrol or Block API:

curl --location --request POST 'https://ind-orion.hyperverge.co/v2/search/face' \
--header 'accept: application/json' \
--header 'Content-Type: multipart/form-data' \
--header 'appId: <Enter_the_appId-Shared-by-HyperVerge>' \
--header 'appKey: <Enter_the_appKey-shared-by-HyperVerge>' \
--form 'transactionId=<Enter_the_Transaction_ID>' \
--form 'selfie=<Attach_The_Image>' \
--form 'enrol=<Yes_or_No>' \
--form 'omitSearch=<Yes_or_No>'

Success Response

The following are success responses (HTTP 200) when result.summary.action is Pass or Manual Review: no duplicates, verified match, blocklist match (manual review), or successful enrolment. Use result.summary.action and result.summary.value to determine the outcome.

No record found

No face duplicates found. summary.action is Pass, isEnrolled.value is no.

{
  "statusCode": 200,
  "metaData": { "requestId": "<Request_ID>", "transactionId": "<Transaction_ID>" },
  "result": {
    "data": {
      "transactionId": "<Transaction_ID>",
      "isEnrolled": { "value": "no", "reason": "NA" },
      "matches": { "internalCount": 0, "externalCount": 0, "count": 0, "internal": [], "external": [] },
      "blocklist": { "internalCount": 0, "externalCount": 0, "count": 0, "internal": [], "external": [] },
      "dashboardUrl": "..."
    },
    "summary": { "value": "No record found", "action": "Pass" }
  }
}

Verified

Face matches found, none blocklisted. summary.action is Pass, isEnrolled.value is no.

{
  "statusCode": 200,
  "metaData": { "requestId": "<Request_ID>", "transactionId": "<Transaction_ID>" },
  "result": {
    "data": {
      "transactionId": "<Transaction_ID>",
      "isEnrolled": { "value": "no", "reason": "NA" },
      "matches": {
        "internalCount": 1,
        "externalCount": 0,
        "count": 1,
        "internal": [
          {
            "transactionId": "<Transaction_ID>",
            "enrolDate": "...",
            "clientId": "...",
            "category": "...",
            "selfie": { "match": "yes", "url": "..." },
            "matchScore": { "selfie": 85 }
          }
        ],
        "external": []
      },
      "blocklist": { "internalCount": 0, "externalCount": 0, "count": 0, "internal": [], "external": [] },
      "dashboardUrl": "..."
    },
    "summary": { "value": "Verified", "action": "Pass" }
  }
}

Match with blocklist

Match found on blocklist. summary.action is Manual Review.

{
  "statusCode": 200,
  "metaData": { "requestId": "<Request_ID>", "transactionId": "<Transaction_ID>" },
  "result": {
    "data": {
      "transactionId": "<Transaction_ID>",
      "isEnrolled": { "value": "no", "reason": "NA" },
      "matches": { "internalCount": 0, "externalCount": 0, "count": 0, "internal": [], "external": [] },
      "blocklist": {
        "internalCount": 1,
        "externalCount": 0,
        "count": 1,
        "internal": [
          {
            "transactionId": "<Transaction_ID>",
            "enrolDate": "...",
            "clientId": "...",
            "category": "...",
            "selfie": { "match": "yes", "url": "..." },
            "matchScore": { "selfie": 78 }
          }
        ],
        "external": []
      },
      "dashboardUrl": "..."
    },
    "summary": { "value": "Match with blocklist", "action": "Manual Review" }
  }
}

Enrol successful

enrol=yes and enrolment succeeded. summary.action is Pass, isEnrolled.value is yes.

{
  "statusCode": 200,
  "metaData": { "requestId": "<Request_ID>", "transactionId": "<Transaction_ID>" },
  "result": {
    "data": {
      "transactionId": "<Transaction_ID>",
      "isEnrolled": { "value": "yes", "reason": "NA" },
      "dashboardUrl": "..."
    },
    "summary": { "value": "Enrol successful", "action": "Pass" }
  }
}

Success Response Details

The following table provides the details of the parameters in a successful response.

Object	Field	Description
metaData	requestId	A unique identifier to track the customer's application.
metaData	transactionId	The same transactionId used in the API request.
isEnrolled	value	If the value is yes, the application was successfully enrolled in your database. If the value is no, the reason field explains the corresponding reason of non-enrollment.
result.data	matches	Count and list of matching records (same face). Contains internalCount, externalCount, count, internal, and external arrays.
result.data	blocklist	Count and list of blocklist matches. Same structure as matches.
result.data	dashboardUrl	URL to view results in the dashboard.
summary	value	Outcome label: No record found, Verified, Match with blocklist, Quality Insufficient, Enrol successful, or Enrol failed with message: '...'. Use with summary.action to determine the recommended next step.
summary	action	It displays the recommended decision for the customer. It can take any of the values from the following table. Action Recommendation Pass You can proceed with the application. Returned when value is No record found (no duplicates), Verified (face match, not blocklisted), or Enrol successful. Manual Review Requires manual review for further approval or rejection. Returned when value is Match with blocklist. Fail The enrolment failed either because of an image quality issue (Quality Insufficient), a matching transactionId pre-existing in the database, or enrol-only failure (Enrol failed with message: '...'). See error and errorCode when present.

Failure Response

The following are failure responses (HTTP 200 with result.summary.action = Fail): selfie quality insufficient (blur or liveness failed), or enrolment requested but failed. Use result.summary.value, and when present error and errorCode, to determine the reason.

Quality Insufficient

Selfie blur or liveness failed. summary.action is Fail, summary.value is Quality Insufficient, isEnrolled.value is no.

{
  "statusCode": 200,
  "metaData": { "requestId": "<Request_ID>", "transactionId": "<Transaction_ID>" },
  "result": {
    "data": {
      "transactionId": "<Transaction_ID>",
      "isEnrolled": { "value": "no", "reason": "Quality Insufficient" },
      "matches": { "internalCount": 0, "externalCount": 0, "count": 0, "internal": [], "external": [] },
      "blocklist": { "internalCount": 0, "externalCount": 0, "count": 0, "internal": [], "external": [] },
      "dashboardUrl": "..."
    },
    "summary": { "value": "Quality Insufficient", "action": "Fail" }
  }
}

Enrol failed

enrol=yes but enrolment failed. summary.action is Fail, summary.value is Enrol failed with message: '...'. The error and errorCode fields contain the failure reason.

{
  "statusCode": 200,
  "metaData": { "requestId": "<Request_ID>", "transactionId": "<Transaction_ID>" },
  "result": {
    "data": {
      "transactionId": "<Transaction_ID>",
      "isEnrolled": { "value": "no", "reason": "" },
      "dashboardUrl": "..."
    },
    "summary": { "value": "Enrol failed with message: '....'", "action": "Fail" }
  },
  "error": "ApplicationId already exists",
  "errorCode": "E_006"
}

Error Responses

The following are the error responses for the Face Search, Enrol or Block API.

Missing Transaction ID

The following is a response for a request missing the transactionId.

{
  "status": "failure",
  "metaData": {
    "requestId": "<Request_ID>",
    "transactionId": "<Transaction_ID>"
  },
  "statusCode": 400,
  "error": "\"transactionId\" is required"
}

Face not detected in Selfie

No face detected in the selfie image. Status code is 400.

{
  "error": "Face not detected in Selfie image",
  "statusCode": 400,
  "status": "failure",
  "requestId": "<Request_ID>",
  "transactionId": "<Transaction_ID>"
}

Missing/Invalid Credentials

{
  "status": "failure",
  "metaData": {
    "requestId": "<Request_ID>",
    "transactionId": "<Transaction_ID>"
  },
  "statusCode": 401,
  "error": "Missing/Invalid credentials"
}

Rate Limit Exceeded

{
  "status": "failure",
  "message": "Requests rate limit exceeded",
  "statusCode": 429
}

Internal Server Error

{
  "error": "Internal Server Error",
  "statusCode": 500,
  "status": "failure",
  "requestId": "<Request_ID>",
  "transactionId": "<Transaction_ID>"
}

Failure and Error Response Details

A failure or error response contains a failure status with a relevant status code and error message.
The following table lists all error responses:

Status Code	Error Message	Error Description	Error Resolution
200	Quality Insufficient	Selfie blur or liveness check failed. result.summary.action is Fail, result.summary.value is Quality Insufficient.	Ask the user to retake the selfie with better lighting and clarity; ensure the face is clearly visible and live.
200	ApplicationId already exists	enrol=yes was sent but enrolment failed. result.summary.action is Fail. The error and errorCode fields (e.g. "ApplicationId already exists", E_006) contain the reason.	Check error and errorCode in the response; resolve the underlying issue (e.g. use a different transactionId if ApplicationId already exists) and retry.
400	"transactionId" is required	The request does not contain the transaction identification number.	Include a valid transactionId in the request body or headers.
400	Face not detected in Selfie image	No face was detected in the selfie image	Ensure the selfie contains a single, clearly visible face and retry.
401	Missing/Invalid credentials	The request either does not contain the mandatory credentials or contains invalid credentials.	Provide valid appId and appKey headers.
429	Requests rate limit exceeded	The number of transactions per minute has crossed the limit set for your credentials.	Throttle requests or contact HyperVerge to increase the rate limit.
500	Internal Server Error	There is an error with HyperVerge's server. Kindly contact the HyperVerge team for resolution.	Contact the HyperVerge team for resolution.