Get ITR Details

Endpoint Overview

GET /api/v1/itr/get-itr-details/{client_id}

Description

This API retrieves detailed Income Tax Return (ITR) information for a specific client. It provides comprehensive tax filing data including personal details, income information, address, and the complete raw ITR data. This endpoint is valuable for financial institutions, lending platforms, and verification services that need to verify income and tax compliance.

Key Benefits

Access verified income data directly from official ITR records

Obtain comprehensive financial profile including gross and total income

Retrieve personal identification details like name, address, and Aadhaar

Access employment information including company name and address

Use Cases

Financial Services

Employment Verification

Wealth Management

Income verification for loan applications

Credit risk assessment using verified income data

KYC enhancement with tax filing information

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
Content-Type	Yes	application/json

Path Parameters

Parameter	Type	Required	Description
client_id	String	Yes	Unique identifier of the client/query

Query Parameters

Parameter	Type	Required	Description
itr_id	Integer	Yes	Enter ITR Id to retrieve specific ITR details

Process Response

Response Parameters

Parameter	Type	Description
gender	String	Gender as per ITR details
name	String	Name as per ITR details
fathers_name	String	Father's name as per ITR details
email	String	Email as per ITR details
pincode	Integer	Pincode as per ITR details
aadhaar_no	String	Aadhaar number as per ITR details
mobile_no	String	Mobile number as per ITR details
address	String	Address as per ITR details
income	Object	Income details object (see below)
gross_income	Integer	Gross income as per ITR details
itr_type	String	ITR type as per ITR details (e.g., itr_3)
dob	String	Date of birth as per ITR details (YYYY-MM-DD format)
doi	String	DOI as per ITR details
raw_itr	Object	Complete raw ITR data

Income Object Parameters

Parameter	Type	Description
total_income	Integer	Total income as per income details
gross_income	Integer	Gross income as per income details
company_name	String	Company name as per income details
company_address	String	Company address as per income details

Example Successful Response

{
    "data": {
        "gender": null,
        "name": "SURBI",
        "fathers_name": "SURENDRA",
        "email": "surbhia@gmail.com",
        "pincode": 700000,
        "aadhaar_no": "12345352161",
        "mobile_no": "9873612345",
        "address": "21/, GORA  ROAD,  Intally S.O",
        "income": {
            "total_income": 2156580,
            "gross_income": 2407081,
            "company_name": "AGRO LIMITED",
            "company_address": "34, D H, 700000, WEST"
        },
        "gross_income": 2407081,
        "itr_type": "itr_3",
        "dob": "1981-07-12",
        "doi": null,
        "raw_itr": {
            "ITR": {
                "ITR3": {
                    // Detailed ITR data structure
                    // (truncated for brevity)
                }
            }
        }
    },
    "status_code": 200,
    "message_code": "success",
    "message": "Data extracted successfully",
    "success": true
}

Possible Error Responses

Authentication Error

Resource Not Found

Bad Request

{
    "status_code": 401,
    "message_code": "unauthorized",
    "message": "Invalid authentication token",
    "success": false
}

This error occurs when the JWT token is invalid, expired, or missing.

Integration Best Practices

Security Recommendations

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

Implement proper error handling to avoid exposing sensitive information

Use HTTPS for all API communications to ensure data encryption in transit

Implement token refresh mechanisms to handle token expiration gracefully

User Experience Guidelines

Implement proper loading states while waiting for API response

Display clear error messages to users when verification fails

Consider caching responses to improve performance for repeated queries

Format financial data appropriately with proper currency symbols and decimal places

Code Samples

cURL

Python

Node.js

Related APIs

Aadhaar Verification API: Verify Aadhaar details of individuals

PAN Verification API: Verify PAN card details of individuals

Bank Account Verification API: Verify bank account details for financial transactions

Employment Verification API: Verify employment details of individuals

Compliance and Legal Considerations

When handling ITR data, ensure compliance with data protection regulations. The data contains sensitive personal and financial information that must be handled securely. Obtain proper consent before accessing or storing this information, and implement appropriate data retention policies. Usage of this API may be subject to regulatory requirements in financial services and lending sectors.

{ "data": { "gender": null, "name": "SURBI", "fathers_name": "SURENDRA", "email": "surbhia@gmail.com", "pincode": 700000, "aadhaar_no": "12345352161", "mobile_no": "9873612345", "address": "21/, GORA ROAD, Intally S.O", "income": { "total_income": 2156580, "gross_income": 2407081, "company_name": "AGRO LIMITED", "company_address": "34, D H, 700000, WEST" }, "gross_income": 2407081, "itr_type": "itr_3", "dob": "1981-07-12", "doi": null, "raw_itr": { "ITR": { "ITR3": { "CreationInfo": { "SWVersionNo": "R1", "SWCreatedBy": "SW1001234", "JSONCreatedBy": "SW1001453", "JSONCreationDate": "2022-12-14", "Digest": "efCuJcocAXign08h+NwX2gV/xPNLhc=", "IntermediaryCity": "Delhi" }, "Form_ITR3": { "FormName": "ITR-3", "Description": "Indls, HUFs having incom and gains of business", "AssessmentYear": "2022", "SchemaVer": "Ver1.0", "FormVer": "Ver1.0" }, "PartA_GEN1": { "PersonalInfo": { "AssesseeName": { "FirstName": "SURBI", "SurNameOrOrgName": "" }, "Address": { "ResidenceNo": "21/H", "ResidenceName": "GORA ROAD", "RoadOrStreet": "", "LocalityOrArea": "", "CityOrTownOrDistrict": "Intally S.O", "StateCode": "2", "CountryCode": "91", "PinCode": 700000, "CountryCodeMobile": 91, "MobileNo": 98736789456, "EmailAddress": "surbhi@.com" }, "PAN": "AAPPL2222A", "DOB": "1981-07-12", "Status": "I", "AadhaarCardNo": "7631234552161" }, "FilingStatus": { "CompDirectorPrvYr": { "CompDirectorPrvYrDtls": [ { "NameOfCompany": "GLOBAL PRIVATE LIMITED", "CompanyType": "D", "PAN": "AAPPL2222A", "SharesTypes": "U", "DIN": "08123610" } ] }, "ReturnFileSec": 12, "NewTaxRegime": "N", "OptingNewTaxRegime": 2, "SeventhProvisio139": "N", "DepAmtAggAmtExcd1CrPrYrFlg": "N", "IncrExpAggAmt2LkTrvFrgnCntryFlg": "N", "IncrExpAggAmt1LkElctrctyPrYrFlg": "N", "clauseiv7provisio139i": "N", "ResidentialStatus": "RES", "ConditionsResStatus": "1", "BenefitUs115HFlg": "N", "PortugeseCC5A": "N", "AsseseeRepFlg": "N", "CompDirectorPrvYrFlg": "Y", "PartnerInFirmFlg": "N", "HeldUnlistedEqShrPrYrFlg": "N", "NriSEPinIndia": "N", "ForeignExchangeFlag": "N" } }, "PartA_GEN2": { "AuditInfo": { "AuditDetails": [ { "OthAuditDtls": "N" } ], "AuditReportDetails": [ { "OtherITActFlag": "N" } ], "LiableSec44AAflg": "N", "IncDclrdUs": "N", "TotalSalesExcOneCr": "N", "LiableSec44ABflg": "N", "LiableSec92Eflg": "N",

Provide your bearer token in the

Authorization

header when making requests to protected resources.

Example:

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

Get ITR Details 1

Get ITR Details#

Description#

Use Cases#

Technical Implementation#

Request Headers#

Path Parameters#

Query Parameters#

Response Parameters#

Income Object Parameters#

Example Successful Response#

Possible Error Responses#

Integration Best Practices#

Code Samples#

Request

Responses