Face and ID - Enrol or Block API

API Endpoint

Name of the API	User Inputs Required
`enrol`	The details of the end user along with their selfie.

API Description

Objective

The Enrol API adds a user's record to the database.

API URL

  https://ind-orion.hyperverge.co/v2/enrol/application

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	This parameter defines the media type for the request payload.	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.

Inputs

The following table provides the details of the input parameters used in the API request.

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.
`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 set to "yes". 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 API 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 response 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

Sample Request

The following code shows a standard curl request for the API.

  curl --request POST \
     --url https://ind-orion.hyperverge.co/v2/enrol/application \
     --header 'accept: application/json' \
     --header 'content-type: multipart/form-data' \
     --form name=<enter_the_name> \
     --form idNumber=<enter_the_id_number> \
     --form idType=<enter_the_id_type> \
     --form dob=<enter_the_dob> \
     --form transactionId=<enter_the_transaction_id> \
     --form block=no \
     --form enrol=no \
     --form selfie=<attach_the_image>

Success Response

The following is a sample response.

 {
  "statusCode": 200,
  "metaData": {
    "requestId": "1680010592768-fe672012-6026-4c2a-9b5a-00800cdfaae3",
    "transactionId": "test-arjun-4"
  },
  "result": {
    "data": {
      "transactionId": "test-arjun-4",
      "isEnrolled": {
        "value": "yes",
        "reason": "NA"
      },
      "dashboardUrl": "https://www.orion-console.hyperverge.co/reviewportal/1680010592768-fe672012-6026-4c2a-9b5a-00800cdfaae3"
    },
    "summary": {
      "value": "Enrol successful",
      "action": "Pass"
    }
  }
}

Error Responses

The following sample codes reflect the error responses of the API.

ID Number Missing
Missing/Invalid Credentials
Face Undetected
Limit Exceeded
Internal Server Error

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

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

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

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

{
"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	""transactionId" is required	The request does not contain the transaction identification 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.

API Endpoint​

API Description​

Objective​

API URL​

Overview​

Authentication​