Face and ID - Search, Enrol or Block

Description

Objective

The Face and ID - Search, Enrol or Block module determines if the given identity number and the selfie are present in the database.

Inputs

The following table provides the details of the input parameters.

Parameter	Mandatory or Optional	Type	Description
name	Mandatory	string	The name of the customer.
idNumber	Mandatory	string	The identification number of the customer from the identity document.
idType	Mandatory	string	The type of the identity document. It can be PAN, Voter ID or Aadhaar.
dob	Optional	string	The date of birth of the customer in dd-mm-yyyy format.
transactionId	Mandatory	string	The unique identifier for the customer's application.
block	Mandatory	string	To add this application to blocklist if enrol is yes. It accepts either of "yes" or "no" as its value.
enrol	Mandatory	string	The flag to indicate if HyperVerge should enrol this application into your database. It accepts either of "yes" or "no" as its value.
selfie	Mandatory	file	This is the selfie image of the user. The maximum image size is 6 MB.

General Image Input Guidelines

• The module supports JPEG, PNG and TIFF images and PDFs inputs.
• Ensure that the document in the image is legible. This is a rule of thumb for our OCR servers to accurately extract any text from an image.
• Reduce the size of the image as much as possible to optimise the reponse time while also ensuring its legibility criteria as mentioned earlier. Larger image sizes lead to higher uploading and processing time.
• You can keep the width of the ID card image at least 800 pixels and the JPEG compression quality factor above 80%.
• For our DL server to extract text from the document, the aspect ratio of the input image should be the same as the aspect ratio of the original document. Hence utmost care should be taken while resizing the image to maintain the aspect ratio

Success Response

The following is a sample response.

{
  "statusCode": 200,
  "status": "success",
  "metaData": {
    "requestId": "1622697947985-4cfbcaf8-28ca-497e-8d22-323dea6aa2f6",
    "transactionId": "290101"
  },
  "result": {
    "data": {
      "isEnrolled": {
        "value": "yes",
        "reason": "NA"
      },
      "matches": {
        "count": 1,
        "internal": [
          {
            "enrolDate": "11-04-2021",
            "transactionId": "123456",
            "clientId": "290101",
            "matchScore": {
              "selfie": "97.4"
            },
            "idNumber": {
              "value": "XXXX",
              "match": "yes | no | NA"
            },
            "dob": {
              "value": "XXXX",
              "match": "yes | no | NA"
            },
            "name": {
              "value": "XXXX",
              "match": "yes | no | NA"
            },
            "selfie": {
              "url": "https://orion.com/1234/test.png",
              "match": "yes | no | NA"
            },
            "category": "sameFaceSameDetails"
          }
        ]
      },
      "suspiciousMatches": {
        "count": 1,
        "internal": [
          {
            "enrolDate": "11-04-2021",
            "transactionId": "123456",
            "clientId": "290101",
            "matchScore": {
              "selfie": "97.4"
            },
            "idNumber": {
              "value": "XXXX",
              "match": "yes | no | NA"
            },
            "dob": {
              "value": "XXXX",
              "match": "yes | no | NA"
            },
            "name": {
              "value": "XXXX",
              "match": "yes | no | NA"
            },
            "selfie": {
              "url": "https://orion.com/1234/test.png",
              "match": "yes | no | NA"
            },
            "category": "diffFaceSameDetails"
          }
        ]
      },
      "blocklist": {
        "count": 1,
        "internal": [
          {
            "enrolDate": "11-04-2021",
            "transactionId": "123456",
            "clientId": "290101",
            "matchScore": {
              "selfie": "97.4"
            },
            "idNumber": {
              "value": "XXXX",
              "match": "yes | no | NA"
            },
            "dob": {
              "value": "XXXX",
              "match": "yes | no | NA"
            },
            "name": {
              "value": "XXXX",
              "match": "yes | no | NA"
            },
            "selfie": {
              "url": "https://orion.com/1234/test.png",
              "match": "yes | no | NA"
            },
            "category": "sameFaceSameDetails_BlockedApplication"
          }
        ]
      },
      "dashboardUrl": "dashboardurl"
    },
    "summary": {
      "value": "Match with blocklist",
      "action": "Manual Review"
    }
  }
}

Error Responses

The following sample codes reflect the error responses.

ID Number Missing

{
"status": "failure",
"metaData": {
  "requestId": "1622697947985-4cfbcaf8-28ca-497e-8d22-323dea6aa2f6",
  "transactionId": "290101"
},
"statusCode": 400,
"error": "\"idNumber\" is required"
}

Missing/Invalid Credentials

{
"status": "failure",
"metaData": {
  "requestId": "1622697947985-4cfbcaf8-28ca-497e-8d22-323dea6aa2f6",
  "transactionId": "290101"
},
"statusCode": 401,
"error": "Missing/Invalid credentials"
}

Face Undetected

{
"status": "failure",
"metaData": {
  "requestId": "1622697947985-4cfbcaf8-28ca-497e-8d22-323dea6aa2f6",
  "transactionId": "290101"
},
"statusCode": 422,
"error": "Face not detected in Selfie image"
}

Limit Exceeded

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

Internal Server Error

{
"status": "failure",
"metaData": {
  "requestId": "1622697947985-4cfbcaf8-28ca-497e-8d22-323dea6aa2f6",
  "transactionId": "290101"
},
"error": "Internal Server Error",
"statusCode": 500
}

Status Code	Error Message	Error Description
400	""idNumber" is required	The request does not contain the identity number.
401	Missing/Invalid credentials	The request either does not contain the mandatory credentials or contains invalid credentials.
422	Face not detected in Selfie image	The AI model failed to detect the face in the image of the identification document.
429	Requests rate limit exceeded	The number of transactions per minute has crossed the limit set for your credentials.
500	Internal Server Error	There is an error with HyperVerge's server. Kindly contact the HyperVerge team for resolution.