Face and ID - Enrol or Block API

This document outlines the details of the Face and ID - Enrol or Block API.

API Description

Objective

The Face and ID - Enrol or Block API adds a user's record to the deduplication database, with an option to add the application to a blocklist.

Input	Output
The details of the end user along with their selfie image.	The enrolment result indicating whether the user was successfully enrolled and their dashboard URL.

API URL

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

API Endpoint

enrol/application

Overview

The Face and ID - 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 and ID - Enrol or Block API.

API Request Details

Method - POST

Headers

Header	Mandatory / Optional	Description	Input Format
content-type	Mandatory	This parameter defines 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.	Not Applicable - this is a unique value
appKey	Mandatory	The application key shared by HyperVerge. You can find the details in the dashboard's credentials tab.	Not Applicable - this is a unique value

Inputs

The following table provides the details of the parameters required for the Face and ID - Enrol or Block API's request body:

Parameter	Mandatory / Optional	Type	Description	Input Format	Default Value
name	Mandatory	string	The name of the customer	Not Applicable	Not Applicable
idNumber	Mandatory	string	The identification number of the customer from the identity document	Not Applicable	Not Applicable
idType	Mandatory	string	The type of the identity document	Not Applicable	Not Applicable
transactionId	Mandatory	string	The unique identifier for the customer's application	Not Applicable	Not Applicable
block	Mandatory	string	To add this application to the blocklist if set to yes	yes or no	Not Applicable
selfie	Mandatory	file	The selfie image of the user. The maximum image size is 6 MB.	JPEG, PNG, or TIFF image file	Not Applicable
dob	Optional	string	The date of birth of the customer	DD-MM-YYYY	Not Applicable

General Image Input Guidelines

• The Face and ID - Enrol or Block API supports JPEG, PNG, and TIFF image inputs.
• Ensure that the document in the image is legible. This is a rule of thumb for the 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. 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 the 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. Utmost care should be taken while resizing the image to maintain the aspect ratio.

Request

The following code snippet demonstrates a standard curl request for the Face and ID - Enrol or Block API:

curl --location --request POST 'https://ind-orion.hyperverge.co/v2/enrol/application' \
--header 'Content-Type: multipart/form-data' \
--header 'appId: <Enter_The_HyperVerge_AppId>' \
--header 'appKey: <Enter_The_HyperVerge_AppKey>' \
--header 'transactionId: <Enter_The_Transaction_ID>' \
--form name="<Customer_Name>" \
--form idNumber="<ID_Number>" \
--form idType="<ID_Type>" \
--form dob="<DD-MM-YYYY>" \
--form transactionId="<Transaction_ID>" \
--form block="no" \
--form 'selfie=@<Path_To_Selfie_Image_File>'

Success Response

The following is a sample success response from the Face and ID - Enrol or Block API:

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

Success Response Details

The following table outlines the details of the success response from the Face and ID - Enrol or Block API:

Parameter	Type	Description
statusCode	integer	The HTTP status code of the response
metaData.requestId	string	The unique identifier for the request
metaData.transactionId	string	The transaction ID associated with the request
result.data.transactionId	string	The transaction ID of the enrolment
result.data.isEnrolled.value	string	Indicates whether the user was enrolled (yes or no)
result.data.isEnrolled.reason	string	The reason for the enrolment result
result.data.dashboardUrl	string	The URL to view the enrolment record in the Orion dashboard
result.summary.value	string	A human-readable summary of the enrolment outcome
result.summary.action	string	The action derived from the enrolment result

Error Responses

The following are the error responses from the Face and ID - Enrol or Block API:

Transaction ID Missing

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

Missing/Invalid Credentials

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

Forbidden

{
  "status": "failure",
  "statusCode": 403,
  "error": "Forbidden"
}

Face Undetected

{
  "status": "failure",
  "metaData": {
    "requestId": "<Request_ID>",
    "transactionId": "<Transaction_ID>"
  },
  "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": "<Request_ID>",
    "transactionId": "<Transaction_ID>"
  },
  "error": "Internal Server Error",
  "statusCode": 500
}

Error Response Details

A failure or error response from the Face and ID - Enrol or Block API 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
400	"transactionId" is required	The request does not contain the transaction identification number	Include a valid transactionId in the request body
401	Missing/Invalid credentials	The request is either missing the mandatory appId and appKey combination or has invalid values	Provide valid appId and appKey in the request headers. Check the dashboard's credentials tab
403	Forbidden	The provided credentials do not have access to this API	Contact the HyperVerge team for resolution
422	Face not detected in Selfie image	The AI model failed to detect a face in the provided selfie image	Ensure the selfie image contains a clear, front-facing photo of the user
429	Requests rate limit exceeded	The number of transactions per minute has crossed the limit set for your credentials	Contact the HyperVerge team to review your rate limit configuration
500	Internal Server Error	There is an issue with the service. Kindly contact the HyperVerge Team for support.	Contact the HyperVerge team for investigation and resolution