ITR OCR API

The following document highlights the details of the ITR OCR API.

API Description

Objective

The ITR OCR API extracts accurate information from a user's Income Tax Return (ITR) document using optical character recognition (OCR) and returns the extracted data in a JSON format.

Input	Output
An image or PDF file of the user's ITR document	The data extracted from the ITR document and converted into a JSON format. The complete list of output fields is provided under the Success Response Details section.

API URL

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

API Endpoint

readITR

Overview

The ITR OCR 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.

Method - POST

Authentication

You need a unique pair of application ID ( appId ) and application key ( appKey ) from HyperVerge to verify your identity for accessing the ITR OCR API.

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	This should be a unique value
appKey	Mandatory	The application key shared by HyperVerge. You can find the details in the dashboard's credentials tab	This should be a unique value
transactionId	Mandatory	Unique ID for the customer journey	Any defined unique value mapped to a transaction in your business ecosystem

Inputs

The following table provides the details of the parameters required for the ITR OCR API's request body:

Parameter	Mandatory / Optional	Type	Description	Input Format	Default Value
image	Mandatory	file	The image file for OCR extraction	Image file (JPEG, JPG, PNG) or PDF	Not Applicable

Request

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

curl --location --request POST 'https://ind-engine.thomas.hyperverge.co/v1/readITR' \
--header 'appid: <Enter_the_appId-Shared-by-HyperVerge>' \
--header 'appkey: <Enter_the_appKey-shared-by-HyperVerge>' \
--header 'transactionId : <Enter_the_Transaction_ID>' \
--form 'image=@"<path_to_image_file>"'

Document Sample

The following is an ITR Document.

Success Response

The following code snippet demonstrates a success response from the ITR OCR API:

{
  "status": "success",
  "statusCode": "200",
  "result": {
    "details": [
      {
        "fieldsExtracted": {
          "name": {
            "value": "<Name_of_the_Individual>"
          },
          "dateOfFiling": {
            "value": "<Date_Of_Filing_in_DD-MM-YYYY_Format>"
          },
          "acknowledgementNumber": {
            "value": "<Acknowledgement_Number>"
          },
          "totalIncome": {
            "value": "<Total_Income>"
          },
          "status": {
            "value": "<Filing_Status>"
          },
          "assessmentYear": {
            "value": "<Assessment_Year>"
          },
          "formNumber": {
            "value": "<Form_Number>"
          },
          "PANNumber": {
            "value": "<10_digit_PAN>"
          }
        },
        "type": "<Document_Type>"
      }
    ]
  },
  "metaData": {
    "requestId": "<Unique_Request_ID>"
  }
}

Success Response Details

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

info

The response's field values reflect only the data recorded in the user's document.

Parameter	Type	Description
status	string	The status of the API response
statusCode	string	The HTTP status code for the response
result	object	The JSON object containing the extracted ITR details
details	array	An array containing the extracted document information
fieldsExtracted	object	The JSON object containing all the fields extracted from the ITR document
name	string	The name of the user
status	string	The status associated with the ITR document. For example, "Individual".
dateOfFiling	string	The date of electronic filing of the ITR
acknowledgementNumber	string	The E-Filing acknowledgement identifier
totalIncome	string	The total income of the user
assessmentYear	string	The assessment year for the ITR
formNumber	string	The form number used for filing the ITR
PANNumber	string	The PAN of the user
type	string	The type of document detected
metaData	object	The JSON object containing request identifiers
requestId	string	Unique identifier for the request

Failure Response

The following code snippet demonstrates a failure response from the ITR OCR API:

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

Error Responses

The following are some error responses from the ITR OCR API:

No Image Input

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

Image Size Exceeds Limit of 6MB

{
  "status": "failure",
  "statusCode": 400,
  "error": "Image size cannot be greater than 6MB"
}

Document Not Detected

{
  "status": "failure",
  "statusCode": 422,
  "error": "Document Not Detected"
}

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	Error Resolution
400	API call requires one input image	The request does not include an input image, which is mandatory for processing.	Ensure the request includes the image parameter with a valid image or PDF file
400	Image size cannot be greater than 6MB	The provided image exceeds the maximum allowed size of 6MB.	Reduce the image file size to 6MB or less before submitting the request
422	Document Not Detected	The system was unable to detect any document in the provided image.	Ensure the image contains a clear and visible ITR document, or contact the HyperVerge team if the issue persists