Identity Document OCR API

This document outlines the details of the Identity Document OCR API.

API Description

Objective

The Identity Document OCR API extracts information from valid identity documents using optical character recognition (OCR) and returns the extracted data in JSON format. The API classifies documents as either KYC or KYB and identifies document types (PAN, Aadhaar, Driving License, GST certificate, etc).

Input	Output
An image of KYC or KYB documents	Document classification, document ID identification, and extracted details from the document

API URL

https://ind-engine.thomas.hyperverge.co/v1/readIdentity

API Endpoint

readIdentity

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 for accessing the API.

API Request Details

Method - POST

Headers

Parameter	Mandatory or Optional	Type	Description	Valid Values
content-type	Mandatory	string	This parameter defines the media type for the request payload.	multipart/form-data
appId	Mandatory	string	The application ID shared by HyperVerge	Not Applicable - this is a unique value.
appKey	Mandatory	string	The application key shared by HyperVerge	Not Applicable - this is a unique value.
transactionId	Mandatory	string	The unique ID for the customer journey.	Not Applicable - this is a unique value related to a transaction in your application.

Input

The following table provides the details of the parameter required for the API's request body:

Parameter	Mandatory or Optional	Description	Allowed Values	Default Values
image	Mandatory	Provide an image of KYC or KYB documents, such as PAN, Aadhaar, Driving License and GST certificates	The file format can be JPEG, PNG, TIFF, or PDF	Not Applicable

Caution

• If multiple images are sent to the server in the same call, only one of the images will be read. Hence it is advisable to only send one image per call.
• If the PDF file has multiple pages, only the first page will be considered for the OCR extraction.

Request

The following code snippet demonstrates a standard curl request for the API:

curl --location --request POST 'https://ind-engine.thomas.hyperverge.co/v1/readIdentity' \
--header 'Content-Type: multipart/form-data' \
--header 'appId: <Enter_the_HyperVerge_appId>' \
--header 'appKey: <Enter_the_HyperVerge_appKey>' \
--header 'transactionId: <Enter_the_HyperVerge_transactionID>' \
--form 'image=@"<Attach_the_image_file>"'

Success Responses

The following code snippets demonstrate a few success responses from the API for different document types and IDs:

KYC Document - PAN

{
    "status": "success",
    "statusCode": 200,
    "result": {
        "documentType": "KYC",
        "documentId": "pan",
        "details": {
            "fieldsExtracted": {
                "firstName": {
                    "value": "<First_Name_of_the_User>"
                },
                "middleName": {
                    "value": "<Middle_Name_of_the_User>"
                },
                "lastName": {
                    "value": "<Last_Name_of_the_User>"
                },
                "fullName": {
                    "value": "<Full_Name_of_the_User>"
                },
                "dateOfBirth": {
                    "value": "<Date_Of_Birth_in_DD-MM-YYYY_Format>"
                },
                "dateOfIssue": {
                    "value": "<Date_Of_Issue_in_DD-MM-YYYY_Format>"
                },
                "dateOfExpiry": {
                    "value": "<Date_Of_Expiry_in_DD-MM-YYYY_Format>"
                },
                "countryCode": {
                    "value": "<Country_Code>"
                },
                "type": {
                    "value": "<Type_of_PAN_Card>"
                },
                "address": {
                    "value": "<Address_Of_The_User>",
                    "houseNumber": "<House_Number>",
                    "additionalInfo": "<Additional_Address_Information>",
                    "province": "<Province>",
                    "district": "<District>",
                    "street": "<Street>",
                    "zipCode": "<Zip_Code>"
                },
                "gender": {
                    "value": "<Gender>"
                },
                "idNumber": {
                    "value": "<PAN_Number>"
                },
                "placeOfBirth": {
                    "value": "<Place_Of_Birth>"
                },
                "placeOfIssue": {
                    "value": "<Place_Of_Issue>"
                },
                "yearOfBirth": {
                    "value": "<Year_Of_Birth>"
                },
                "age": {
                    "value": "<Age>"
                },
                "fatherName": {
                    "value": "<Father_Name>"
                },
                "motherName": {
                    "value": "<Mother_Name>"
                },
                "husbandName": {
                    "value": "<Husband_Name>"
                },
                "spouseName": {
                    "value": "<Spouse_Name>"
                },
                "nationality": {
                    "value": "<Nationality>"
                },
                "mrzString": {
                    "value": "<MRZ_String>",
                    "idNumber": "<ID_Number_from_MRZ>",
                    "fullName": "<Full_Name_from_MRZ>",
                    "dateOfBirth": "<Date_Of_Birth_from_MRZ>",
                    "dateOfExpiry": "<Date_Of_Expiry_from_MRZ>",
                    "gender": "<Gender_from_MRZ>",
                    "nationality": "<Nationality_from_MRZ>"
                },
                "homeTown": {
                    "value": "<Home_Town>"
                }
            },
            "croppedImageUrl": "<URL_To_Cropped_Image>"
        },
        "summary": {
            "action": "<Action_Status>",
            "details": []
        }
    },
    "metaData": {
        "requestId": "<Request_ID>",
        "transactionId": "<Transaction_ID>"
    }
}

KYC Document - Driving License

{
    "status": "success",
    "statusCode": 200,
    "result": {
        "documentType": "KYC",
        "documentId": "dl",
        "details": {
            "firstName": {
                "value": "<First_Name_of_the_User>"
            },
            "middleName": {
                "value": "<Middle_Name_of_the_User>"
            },
            "lastName": {
                "value": "<Last_Name_of_the_User>"
            },
            "fullName": {
                "value": "<Full_Name_of_the_User>"
            },
            "dateOfBirth": {
                "value": "<Date_Of_Birth_in_DD-MM-YYYY_Format>"
            },
            "dateOfIssue": {
                "value": "<Date_Of_Issue_in_DD-MM-YYYY_Format>"
            },
            "dateOfExpiry": {
                "value": "<Date_Of_Expiry_in_DD-MM-YYYY_Format>"
            },
            "countryCode": {
                "value": "<Country_Code>"
            },
            "type": {
                "value": "<Type_of_License>"
            },
            "address": {
                "district": "<District>",
                "street": "<Street>",
                "value": "<Complete_Address_Of_The_User>",
                "houseNumber": "<House_Number>",
                "zipCode": "<Zip_Code>",
                "province": "<Province>",
                "additionalInfo": "<Additional_Address_Information>"
            },
            "gender": {
                "value": "<Gender>"
            },
            "idNumber": {
                "value": "<Driving_License_Number>"
            },
            "placeOfBirth": {
                "value": "<Place_Of_Birth>"
            },
            "placeOfIssue": {
                "value": "<Place_Of_Issue>"
            },
            "yearOfBirth": {
                "value": "<Year_Of_Birth>"
            },
            "age": {
                "value": "<Age>"
            },
            "fatherName": {
                "value": "<Father_Name>"
            },
            "motherName": {
                "value": "<Mother_Name>"
            },
            "husbandName": {
                "value": "<Husband_Name>"
            },
            "spouseName": {
                "value": "<Spouse_Name>"
            },
            "nationality": {
                "value": "<Nationality>"
            },
            "mrzString": {
                "value": "<MRZ_String>",
                "idNumber": "<ID_Number_from_MRZ>",
                "fullName": "<Full_Name_from_MRZ>",
                "dateOfBirth": "<Date_Of_Birth_from_MRZ>",
                "dateOfExpiry": "<Date_Of_Expiry_from_MRZ>",
                "gender": "<Gender_from_MRZ>",
                "nationality": "<Nationality_from_MRZ>"
            },
            "homeTown": {
                "value": "<Home_Town>"
            }
        }
    },
    "metaData": {
        "requestId": "<Request_ID>",
        "transactionId": "<Transaction_ID>"
    }
}

KYB Document - GST Certificate

{
    "status": "success",
    "statusCode": 200,
    "result": {
        "documentType": "KYB",
        "documentId": "GST certificate",
        "details": {
            "regNo": {
                "value": "<GST_Registration_Number>",
                "conf": "<Confidence_Score>",
                "toBeReviewed": "<Review_Status>"
            },
            "legalName": {
                "value": "<Legal_Name_of_Business>",
                "conf": "<Confidence_Score>",
                "toBeReviewed": "<Review_Status>"
            },
            "tradeName": {
                "value": "<Trade_Name_of_Business>",
                "conf": "<Confidence_Score>",
                "toBeReviewed": "<Review_Status>"
            },
            "businessConstitution": {
                "value": "<Business_Constitution_Type>",
                "conf": "<Confidence_Score>",
                "toBeReviewed": "<Review_Status>"
            },
            "address": {
                "value": "<Business_Address>",
                "conf": "<Confidence_Score>",
                "toBeReviewed": "<Review_Status>"
            },
            "dateLiability": {
                "value": "<Date_of_Liability>",
                "conf": "<Confidence_Score>",
                "toBeReviewed": "<Review_Status>"
            },
            "validFrom": {
                "value": "<Valid_From_Date>",
                "conf": "<Confidence_Score>",
                "toBeReviewed": "<Review_Status>"
            },
            "validTill": {
                "value": "<Valid_Till_Date>",
                "conf": "<Confidence_Score>",
                "toBeReviewed": "<Review_Status>"
            },
            "type": {
                "value": "<GST_Certificate_Type>",
                "conf": "<Confidence_Score>",
                "toBeReviewed": "<Review_Status>"
            }
        }
    },
    "metaData": {
        "requestId": "<Request_ID>",
        "transactionId": "<Transaction_ID>"
    }
}

Success Response Details

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

Parameter	Type	Description
status	string	The status of the request
statusCode	integer	The HTTP status code returned for the request
result	object	Contains the extracted details from the identity document
documentType	string	Classification of the document (KYC or KYB)
documentId	string	Type of document (pan, dl, GST certificate, etc)
details	object	Contains the extracted fields with their values and confidence scores
fieldsExtracted	object	Container for all extracted fields from KYC documents
firstName	object	The first name of the document holder
middleName	object	The middle name of the document holder
lastName	object	The last name of the document holder
fullName	object	The complete name of the document holder
dateOfBirth	object	The date of birth of the document holder
dateOfIssue	object	The date when the document was issued
dateOfExpiry	object	The expiry date of the document
countryCode	object	The country code associated with the document
type	object	The type or category of the document
address	object	The address information of the document holder
houseNumber	string	The house or building number in the address
additionalInfo	string	Additional address information or landmarks
province	string	The province or state in the address
district	string	The district in the address
street	string	The street name in the address
zipCode	string	The postal or zip code in the address
gender	object	The gender of the document holder
idNumber	object	The identification number of the document
placeOfBirth	object	The place of birth of the document holder
placeOfIssue	object	The place where the document was issued
yearOfBirth	object	The year of birth of the document holder
age	object	The age of the document holder
fatherName	object	The name of the father of the document holder
motherName	object	The name of the mother of the document holder
husbandName	object	The name of the husband of the document holder
spouseName	object	The name of the spouse of the document holder
nationality	object	The nationality of the document holder
mrzString	object	Machine Readable Zone string containing encoded document information
homeTown	object	The hometown of the document holder
croppedImageUrl	string	URL to the cropped image of the processed document
summary	object	Summary information about the document processing
action	string	The action status of the document processing
regNo	object	The registration number for business documents
legalName	object	The legal name of the business entity
tradeName	object	The trade name of the business entity
businessConstitution	object	The constitution type of the business entity
dateLiability	object	The date of liability for business documents
validFrom	object	The validity start date of the document
validTill	object	The validity end date of the document
conf	number	The confidence score for the extracted field value
toBeReviewed	string	Indicates whether the field value needs manual review
value	string	The actual value extracted from the document field
metaData	object	Contains request and transaction identifiers
requestId	string	A unique identifier for the API request
transactionId	string	A unique identifier for the customer journey

Error Responses

The following are some error responses from the API:

No Image Found

{
    "message": "No file or image found",
    "statusCode": 400,
    "status": "failure",
    "metaData": {
        "requestId": "<Request_ID>",
        "transactionId": "<Transaction_ID>"
    }
}

Input Validation Error

{
    "message": "Input Validation Error: requires property \"image\"",
    "statusCode": 400,
    "status": "failure"
}

Invalid File Type

{
    "message": "Invalid file type for: image",
    "statusCode": 400,
    "status": "failure"
}

Invalid Credentials

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

Document Not Detected

{
    "message": "Document Not Detected",
    "statusCode": 422,
    "status": "failure",
    "metaData": {
        "requestId": "<Request_ID>",
        "transactionId": "<Transaction_ID>"
    }
}

Internal Server Error

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

Error Response Details

A failure or error response from the module 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	Missing required request parameters	Some mandatory request parameters are missing in the API request made
400	No file or image found	The request did not contain the mandatory image file input
400	Input Validation Error: requires property "image"	The image parameter is missing from the request
400	Invalid file type for: image	The uploaded file format is not supported
401	Missing/Invalid credentials	The request is either missing the mandatory appId and appKey combination or has invalid values
403	Access Denied	Please contact HyperVerge for access permissions
422	Document Not Detected	No valid identity document could be detected in the provided image
500	Internal Server Error	Please check the request headers or contact the HyperVerge team for resolution