ITR Upload

Endpoint Overview

POST /api/v1/ocr/itr-v

Description

This API endpoint allows you to upload and extract data from Income Tax Return (ITR-V) documents. It uses Optical Character Recognition (OCR) technology to automatically parse and extract key information from ITR-V forms, eliminating the need for manual data entry. The service validates the document authenticity and returns structured data that can be easily integrated into your systems.

Key Benefits

Automated extraction of financial and tax information from ITR-V documents

Reduced manual data entry errors and processing time

Structured data output for seamless integration with financial systems

Verification of document authenticity as part of the KYC process

Use Cases

Banking & Lending

Financial Services

HR & Employment

Income verification for loan applications

Customer onboarding and KYC processes

Risk assessment for credit decisions

Technical Implementation

Authentication

All API requests require authentication using a JWT Bearer token. Authentication follows these steps:

Obtain API Credentials: Register with Surepass to receive your API key.

Generate JWT Token: Use your API key to generate a JWT token.

Include in Requests: Add the token to the Authorization header as Bearer TOKEN.

Different authentication tokens are used for sandbox and production environments:

Sandbox: https://sandbox.surepass.io

Production: https://kyc-api.surepass.io

Request Parameters

Request Headers

Header	Required	Description
Authorization	Yes	Bearer token for authentication. Format: `Bearer YOUR_JWT_TOKEN`
Content-Type	Yes	Must be set to `application/json`

Request Body

Request Body Formats

1. For File Upload

Parameter	Type	Required	Description
file	Image	Yes	Upload Cheque Image
use_pdf	Boolean	No	Set to true if the file type is PDF

2. For Image URL Input

Parameter	Type	Required	Description
link	String	Yes	Cheque Image Link/URL

Example Request

Process Response

Response Parameters

Parameter	Type	Description
status_code	Integer	HTTP status code indicating the result of the request
message	String	Description of the response status
result	Object	Contains the extracted data from the ITR-V document
result.itr_info	Object	Contains detailed information extracted from the ITR-V
result.itr_info.pan	String	PAN (Permanent Account Number) of the taxpayer
result.itr_info.name	String	Full name of the taxpayer
result.itr_info.assessment_year	String	Assessment year of the ITR
result.itr_info.form_name	String	Name/type of the ITR form
result.itr_info.filing_type	String	Type of filing (Original/Revised)
result.itr_info.gross_total_income	String	Gross total income reported
result.itr_info.total_deductions	String	Total deductions claimed
result.itr_info.total_income	String	Total taxable income
result.itr_info.tax_payable	String	Total tax payable
result.itr_info.interest_payable	String	Interest payable, if any
result.itr_info.total_tax_interest_payable	String	Sum of tax and interest payable
result.itr_info.tax_paid	String	Total tax already paid
result.itr_info.refund	String	Refund amount, if applicable
result.itr_info.acknowledgement_number	String	ITR acknowledgement number
result.itr_info.filing_date	String	Date when the ITR was filed
result.ocr_confidence	Float	Confidence score of the OCR extraction (0-100)
result.verification	Object	Document verification results
result.verification.verified	Boolean	Whether the document was successfully verified
result.verification.message	String	Verification status message

Example Successful Response

{
  "status_code": 200,
  "message": "ITR-V data extracted successfully",
  "result": {
    "itr_info": {
      "pan": "ABCDE1234F",
      "name": "JOHN DOE",
      "assessment_year": "2022-23",
      "form_name": "ITR-1",
      "filing_type": "Original",
      "gross_total_income": "1250000",
      "total_deductions": "150000",
      "total_income": "1100000",
      "tax_payable": "112500",
      "interest_payable": "0",
      "total_tax_interest_payable": "112500",
      "tax_paid": "112500",
      "refund": "0",
      "acknowledgement_number": "123456789012345",
      "filing_date": "31/07/2022"
    },
    "ocr_confidence": 95.8,
    "verification": {
      "verified": true,
      "message": "Document verified successfully"
    }
  }
}

Possible Error Responses

Authentication Error

Invalid Image

Invalid File Format

Server Error

{
    "error": null,
    "message": "Your token is invalid. Please ensure that correct token is being used.",
    "status_code": 401,
    "success": false,
    "message_code": "invalid_token"
}

Occurs when the JWT token is missing, invalid, or expired.

Integration Best Practices

Security Recommendations

Store JWT tokens securely and never expose them in client-side code

Implement token refresh mechanisms to handle token expiration

Encrypt sensitive data in transit and at rest

Implement proper error handling to avoid exposing sensitive information

User Experience Guidelines

Inform users about the data being extracted and how it will be used

Provide clear feedback during document upload and processing

Implement retry mechanisms for failed uploads or extractions

Display a summary of extracted information for user verification

Code Samples

cURL

Python

Node.js

Related APIs

PAN Card OCR: Extract information from PAN cards

Aadhaar OCR: Extract information from Aadhaar cards

Bank Statement Analysis: Extract and analyze data from bank statements

Form 16 OCR: Extract information from Form 16 documents

Compliance and Legal Considerations

When using this API, ensure you have explicit user consent for processing their ITR-V documents. The data extracted contains sensitive financial information and must be handled in accordance with applicable data protection regulations. Ensure your privacy policy clearly states how this data will be used, stored, and protected. Always maintain proper audit logs of consent and data access for compliance purposes.

Provide your bearer token in the

Authorization

header when making requests to protected resources.

Example:

Authorization: Bearer ********************

{ "status_code": 200, "message": "ITR-V data extracted successfully", "result": { "itr_info": { "pan": "ABCDE1234F", "name": "JOHN DOE", "assessment_year": "2022-23", "form_name": "ITR-1", "filing_type": "Original", "gross_total_income": "1250000", "total_deductions": "150000", "total_income": "1100000", "tax_payable": "112500", "interest_payable": "0", "total_tax_interest_payable": "112500", "tax_paid": "112500", "refund": "0", "acknowledgement_number": "123456789012345", "filing_date": "31/07/2022" }, "ocr_confidence": 95.8, "verification": { "verified": true, "message": "Document verified successfully" } } }

ITR Upload

ITR Upload#

Description#

Use Cases#

Technical Implementation#

Request Headers#

Request Body#

Request Body Formats#

1. For File Upload#

2. For Image URL Input#

Example Request#

Response Parameters#

Example Successful Response#

Possible Error Responses#

Integration Best Practices#

Code Samples#

Request

Responses

ITR Upload

Description

Use Cases

Technical Implementation

Request Headers

Request Body

Request Body Formats

1. For File Upload

2. For Image URL Input

Example Request

Response Parameters

Example Successful Response

Possible Error Responses

Integration Best Practices

Code Samples