Cheque OCR API

API Description

Objective

The Cheque OCR API extracts the textual information from a scanned image of a cheque.

Input	Output
An image or PDF file containing a cheque document	The textual information extracted from the document

API URL

https://ind.thomas.hyperverge.co/v1/readCheque

API Endpoint

/readCheque

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	Allowed 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.

Inputs

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

Parameter	Description	Mandatory or Optional	Allowed Values	Default Value
`image`	The image file for OCR extraction	Mandatory	The file format can be JPG, JPEG, PNG, or PDF	Not Applicable
`outputImageBase64`	Returns the image in base64 format	Optional	'yes' or 'no'	no
`outputAccountType`	Returns the account type in the response details	Optional	'yes' or 'no'	no
`returnS3Url`	Returns the S3 URL for the log	Optional	'yes' or 'no'	no

Request

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

curl --location --request POST 'https://ind.thomas.hyperverge.co/v1/readCheque' \
--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=@"<path_to_cheque_image>"' \
--form 'outputImageBase64="<Enter_yes_or_no>"' \
--form 'outputAccountType="<Enter_yes_or_no>"' \
--form 'returnS3Url="<Enter_yes_or_no>"'

Success Response

The following code is a of success response from the API:

{
    "status": "success",
    "statusCode": "200",
    "result": [
        {
            "details": {
                "account_number": {
                    "value": "<Masked_Account_Number>",
                    "conf": "<Confidence_Score_for_Account_Number>",
                    "to-be-reviewed": "<Review_Status_For_Account_Number>"
                },
                "name": {
                    "value": "<Name_of_the_Account_Holder>",
                    "conf": "<Confidence_Score_for_Name>",
                    "to-be-reviewed": "<Review_Status_For_Name>"
                },
                "ifsc_code": {
                    "value": "<IFSC_Code>",
                    "conf": "<Confidence_Score_for_IFSC_Code>",
                    "to-be-reviewed": "<Review_Status_For_IFSC_Code>"
                },
                "cheque_number": {
                    "value": "<Masked_Cheque_Number>",
                    "conf": "<Confidence_Score_for_Cheque_Number>",
                    "to-be-reviewed": "<Review_Status_For_Cheque_Number>"
                },
                "acc_type": {
                    "value": "<Account_Type>",
                    "conf": "<Confidence_Score_for_Account_Type>",
                    "to-be-reviewed": "<Review_Status_For_Account_Type>"
                },
                "bank_name": {
                    "value": "<Bank_Name>",
                    "conf": "<Confidence_Score_for_Bank_Name>",
                    "to-be-reviewed": "<Review_Status_For_Bank_Name>"
                }
            },
            "type": "<Document_Type>",
            "base64Image": "<Base64_Encoded_Image>",
            "s3Url": "<S3_URL>"
        }
    ]
}

Success Response Details

Parameter	Type	Description
status	string	The status of the request
statusCode	integer	The HTTP status code returned in the response
result	array	The array containing the result details
details	object	An object holding specific details of the document
account_number.value	string	The masked account number from the document
account_number.conf	string	The confidence score for the extracted account number
account_number.to-be-reviewed	string	The review status of the extracted account number
name.value	string	The name of the account holder
name.conf	string	The confidence score for the extracted name
name.to-be-reviewed	string	The review status of the extracted name
ifsc_code.value	string	The IFSC code of the bank account
ifsc_code.conf	string	The confidence score for the extracted IFSC code
ifsc_code.to-be-reviewed	string	The review status of the extracted IFSC code
cheque_number.value	string	The masked cheque number from the document
cheque_number.conf	string	The confidence score for the extracted cheque number
cheque_number.to-be-reviewed	string	The review status of the extracted cheque number
acc_type.value	string	The type of account (e.g., savings)
acc_type.conf	string	The confidence score for the extracted account type
acc_type.to-be-reviewed	string	The review status of the extracted account type
bank_name.value	string	The name of the bank
bank_name.conf	string	The confidence score for the extracted bank name
bank_name.to-be-reviewed	string	The review status of the extracted bank name
type	string	The document type being processed
base64Image	string	The base64 encoded image of the document
s3Url	string	The URL of the document stored in the S3 bucket

Failure Response

Failure - No Document Detected

The following is a failure response where the API fails to detect a document from the image.

{
"status": "failure",
"statusCode": 422,
"error": "No Document detected",
"requestId" : "<Request_ID>"
}

Error Response

The following are the error responses for the API.

Missing Input Image
Multiple Input Images
Image Size Issue
Input Validation Error

{
"status": "failure",
"statusCode": "400",
"error": "API call requires one input image",
"requestId" : "<Request_ID>"
}

{
"status": "failure",
"statusCode": "400",
"error": "API call handles only one input image",
"requestId" : "<Request_ID>"
}

{
"status": "failure",
"statusCode": "400",
"error": "image size cannot be greater than 12MB",
"requestId" : "<Request_ID>"
}

{
  "message": "Input Validation Error: is not one of enum values: yes,no",
    "statusCode": 400,
    "status": "failure"
}

Failure and Error Response Details

A failure or error response from the API contains a failure status, with a relavant status code and error message. The following table lists all error responses.

Status Code	Error Message	Error Description
400	API call requires one input image	The request missed the `image` input
400	API call handles only one input image	The request had more than one `image` file input. It expects only one file in the request.
400	image size cannot be greater than 12MB	The image size is larger than the allowed limit
400	Input Validation Error: is not one of enum values: yes,no	The input parameters (other than image) are provided with values other than yes/no
422	Document not detected from Image	The API failed to detect a document in the image. Ensure that the image captures the document following the guidlines mentioned under the Input Image Guidelines section.
5xx	Internal Server Error	Please check the request headers or contact the HyperVerge team for resolution

API Description​

Objective​

API URL​

API Endpoint​

Overview​

Authentication​

API Request Details

Method - POST

Headers

Inputs​

Request​

Success Response​

Success Response Details​

Failure Response​

Error Response​

Failure and Error Response Details​