Mask Aadhaar API

API Description

Objective

The Mask Aadhaar API hides the valid Aadhaar numbers and the associated QR (quick response) code in any document by blurring them for privacy and security reasons.

Input	Output
Images or files with user's Aadhaar	The masked Aadhaar

API URL

https://ind-ckyc.hyperverge.co/api/v1/maskAadhaar

API Endpoint

maskAadhaar

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 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 and access 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 ID provided by HyperVerge	This should be a unique value provided by HyperVerge.
appKey	Mandatory	The Application Key provided by HyperVerge	This should be a unique value provided by HyperVerge.
transactionId	Mandatory	A custom unique identifier for a user journey or transaction.	This should be a unique value configured by you.

Input

The following table provides the complete information on the parameters used in the request body for the API call.

Parameter	Description	Mandatory or Optional	Accepted Values	Default Value
file	Images or files to be masked	Mandatory	Not applicable	Not applicable
maskStandardAadhaarOnly	If set to "yes", masks only the first 8 digits of the user's Aadhaar number	Optional	"yes" or "no"	"no"
maskFullAadhaar	If set to "yes", masks all 12 digits of the user's Aadhaar number	Optional	"yes" or "no"	"no"
maskQR	If set to "yes", masks the QR code associated with the user's Aadhaar	Optional	"yes" or "no"	"yes"
returnMaskingInfo	If set to "yes", the API returns the maskingInfo.masked field with the details of the masking result	Optional	"yes" or "no"	"no"
returnInputImage	If set to "yes", the API returns the input image as a URL that expires after 15 minutes	Optional	"yes" or "no"	"no"
maskAllAadhaarNumbers	If set to "yes", the API uses a more generic OCR to mask all Aadhaar numbers in the document	Optional	"yes" or "no"	"no"
flagNonAadhaarCards	Parameter to enhance Non-Aadhaar document classification; this works only when maskAllAadhaarNumbers is set to "yes".	Optional	"yes" or "no"	"no"
checkPreMasked	If set to "yes", the API checks if the Aadhaar is already masked. Note Ensure that you enable the returnMaskingInfo parameter to retrieve the pre-masked information under the returnMaskingInfo field of the response, if applicable.	Optional	"yes" or "no"	"no"

Request

The following code snippets demonstrate standard curl requests for the API:

Request without QR Masking

curl --location --request POST 'https://ind-ckyc.hyperverge.co/api/v1/maskAadhaar' \
--header 'appId: <Enter_the_HyperVerge_appId>' \
--header 'appKey: <Enter_the_HyperVerge_appKey>' \
--header 'transactionId: <Enter_the_HyperVerge_transactionID>' \
--form 'file=@"<Path_to_the_File(s)>"'

Request with QR Masking

curl --location --request POST 'https://ind-ckyc.hyperverge.co/api/v1/maskAadhaar' \
--header 'appId: <Enter_the_HyperVerge_appId>' \
--header 'appKey: <Enter_the_HyperVerge_appKey>' \
--header 'transactionId: <Enter_the_HyperVerge_transactionID>' \
--form 'file=@"<Path_to_the_File(s)>"' \
--form 'maskQR="yes"'

Success Response

The following code snippet demonstrates a success responses from the API. It includes information about the document type, input file name, masked file name, occurrences of standard and non-standard Aadhaar numbers, masked file URL, total pages, and page-wise masked occurrences.

{
  "status": "success",
  "statusCode": "200",
  "result": {
    "docType": "<STANDARD_AADHAAR or NON_STANDARD_AADHAAR or NOT_AADHAAR or NOT_SURE>",
    "inputFile": "fileName",
    "maskedFile": "fileName_Masked",
    "maskedOccurrences": {
      "standardAadhaar": 0,
      "nonStandardAadhaar": 2
    },
    "maskedFileUrl": "<masked_url>",
    "totalPages": 1,
    "pageDetails": [
      {
        "page": 1,
        "maskedOccurrences": {
          "standardAadhaar": 0,
          "nonStandardAadhaar": 2
        }
      }
    ]
  }
}

Output Sample

caution

To ensure user privacy, the name and photograph in the preceding image have been intentionally blurred. In the final output, only the Aadhaar number and the QR code will be masked.

Success Response Details

The following table outlines the details of the success response from the API:

Parameter	Value	Description
docType	STANDARD_AADHAAR	Detected a basic or standard Aadhaar
	NON_STANDARD_AADHAAR	Detected a non-standard or alternative format of Aadhaar
	NOT_AADHAAR	Detected a document that is not an Aadhaar
	NOT_SURE	Detected a document that is not identified as any of the aforementioned typess
maskingInfo.masked	"yes"	The document was masked successfully
	"pre_masked"	The document is already masked
	"not_sure"	The masking was unsuccessful and the API failed to determine if the card was pre-masked

Error Responses

The following are some error responses from the API:

Missing Input

{
  "status": "failure",
  "statusCode": "400",
  "error": {
    "code": "ER_FILE_NOT_FOUND",
    "message": "No file attached"
  }
}

Page Limit Exceeded

{
  "status": "failure",
  "statusCode": "400",
  "error": {
    "code": "ER_PAGE",
    "message": "pages exceeded the supported length of 5"
  }
}

Missing or Invalid Credentials

{
  "status": "failure",
  "statusCode": "401",
  "error": "Missing/Invalid credentials"
}

File Size Error

{
  "status": "failure",
  "statusCode": "413",
  "error": {
    "code": "ER_SERVER",
    "message": "File too large"
  }
}

Service Unavailable

{
  "status": "failure",
  "statusCode": "500",
  "error": {
    "code": "ER_SERVER",
    "message": "Internal Server Error"
  }
}

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
400	No file attached	The request is missing the file that should have the user's Aadhaar.
400	Pages exceeded the supported length of 5	The API supports input files up to five pages in length.
401	Missing/Invalid credentials	Missing or invalid credentials in the request.
413	File too large	The API does not support the input file size.
500	Internal Server Error	Kindly check the request headers or contact the HyperVerge team for resolution.