Feel free to reach techsupport@surepass.io for any technical support or guidance.
Download ITR
Production
https://kyc-api.surepass.app
Production
https://kyc-api.surepass.app
POST
https://kyc-api.surepass.app
Download ITR
Description
Key Benefits
Use Cases
Financial Services
Tax Consultancy
Wealth Management
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 Different authentication tokens are used for sandbox and production environments: Sandbox: Production:
1.
2.
3.
Authorization header as Bearer TOKEN.https://sandbox.surepass.iohttps://kyc-api.surepass.ioRequest Parameters
Request Headers
| Header | Required | Description |
|---|---|---|
| Authorization | Yes | Bearer token authentication using JWT |
| Content-Type | Yes | application/json |
Request Body
| Parameter | Type | Required | Description |
|---|---|---|---|
| client_id | String | Yes | Unique identifier of the client for whom ITR information is requested |
Example Request
{
"client_id": "itr_usrydGkBEqjfdsQMguMb"
}Process Response
Response Parameters
| Parameter | Type | Description |
|---|---|---|
| data | Object | Contains the requested ITR information |
| data.client_id | String | Unique identifier of the client |
| data.pan_no | String | PAN Number of the client |
| data.filed_itrs | Array | List of ITR filings for the client |
| data.filed_itrs[].itr_id | String | Unique identifier for the ITR filing |
| data.filed_itrs[].pan_no | String | PAN Number as per the filed ITR |
| data.filed_itrs[].filing_year | String | Assessment year for which ITR was filed |
| data.filed_itrs[].acknowledgement_no | String | Unique acknowledgement number for the ITR filing |
| data.filed_itrs[].itr_form | String | Type of ITR form used (ITR-1, ITR-2, ITR-3, etc.) |
| data.filed_itrs[].filing_type | String | Type of filing (Original, Rectification) |
| data.filed_itrs[].filing_section | String | Section under which ITR was filed (139(1), 139(4), etc.) |
| data.filed_itrs[].filing_date | String | Date when the ITR was filed (YYYY-MM-DD) |
| data.filed_itrs[].itr_status | Array | Chronological list of status updates for the ITR |
| data.filed_itrs[].itr_status[].status | String | Status description |
| data.filed_itrs[].itr_status[].date | String | Date of the status update (YYYY-MM-DD) |
| data.filed_itrs[].download_link | String | Temporary URL to download the ITR document |
| status_code | Integer | HTTP status code of the response |
| success | Boolean | Indicates if the request was successful |
| message | String | Human-readable description of the response |
| message_code | String | Code indicating the type of response |
Example Successful Response
{
"data": {
"client_id": "itr_LkksSlHrooCssgibbaol",
"pan_no": "AAPPL2222A",
"filed_itrs": [
{
"itr_id": "809",
"pan_no": "AAPPL2222A",
"filing_year": "2025-2027",
"acknowledgement_no": "123172820231222",
"itr_form": "ITR-3",
"filing_type": "Original",
"filing_section": "139()",
"filing_date": "2025-12-14",
"itr_status": [
{
"status": "Refund Paid",
"date": "2025-07-18"
},
{
"status": "No more in PFA, Return is in progress",
"date": "2025-12-14"
},
{
"status": "ITR TAKEN UP FOR PROCESSING",
"date": "2025-12-14"
},
{
"status": "Successfully e-verified",
"date": "2025-12-14"
},
{
"status": "Pending for e-verification",
"date": "2025-12-14"
},
{
"status": "ITR Filed",
"date": "2025-12-14"
}
],
"download_link": "https://aadhaar-kyc-docs.s3.amazonaws.com/itr/itr_LkksSlHruoCsxgigbaol/AAPPL2222A/.json?X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Credential=AKIAY5K3QRM5PAM3NMHW%2F20230728%2Fap-south-1%2Fs3%2Faws4_request&X-Amz-Date=20230728T104701Z&X-Amz-Expires=600&X-Amz-SignedHeaders=host"
}
]
},
"status_code": 200,
"success": true,
"message": "ITR downloaded successfully",
"message_code": "success"
}Possible Error Responses
Invalid Client ID
Authentication Error
{
"status_code": 400,
"success": false,
"message": "Invalid client_id provided",
"message_code": "invalid_client_id"
}Integration Best Practices
Security Recommendations
User Experience Guidelines
Code Samples
cURL
Python
Node.js
Related APIs
Compliance and Legal Considerations
Request Request Example
Shell
JavaScript
Java
Swift
curl --location --request POST 'https://kyc-api.surepass.app/api/v1/itr/download-itr' \
--header 'Content-Type: application/json' \
--data-raw '{
"client_id": "itr_usrydGkBEqjfdsQMguMb"
}'Response Response Example
{
"data": {
"client_id": "itr_LkksSlHrooCssgibbaol",
"pan_no": "AAPPL2222A",
"filed_itrs": [
{
"itr_id": "809",
"pan_no": "AAPPL2222A",
"filing_year": "2025-2027",
"acknowledgement_no": "123172820231222",
"itr_form": "ITR-3",
"filing_type": "Original",
"filing_section": "139()",
"filing_date": "2025-12-14",
"itr_status": [
{
"status": "Refund Paid",
"date": "2025-07-18"
},
{
"status": "No more in PFA, Return is in progress",
"date": "2025-12-14"
},
{
"status": "ITR TAKEN UP FOR PROCESSING",
"date": "2025-12-14"
},
{
"status": "Successfully e-verified",
"date": "2025-12-14"
},
{
"status": "Pending for e-verification",
"date": "2025-12-14"
},
{
"status": "ITR Filed",
"date": "2025-12-14"
}
],
"download_link": "https://aadhaar-kyc-docs.s3.amazonaws.com/itr/itr_LkksSlHruoCsxgigbaol/AAPPL2222A/.json?X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Credential=AKIAY5K3QRM5PAM3NMHW%2F20230728%2Fap-south-1%2Fs3%2Faws4_request&X-Amz-Date=20230728T104701Z&X-Amz-Expires=600&X-Amz-SignedHeaders=host"
},
{
"itr_id": "4080",
"pan_no": "AAPPL2222A",
"filing_year": "2025-2027",
"acknowledgement_no": "123472830241221",
"itr_form": "ITR-2",
"filing_type": "Original",
"filing_section": "139(1)",
"filing_date": "2025-12-24",
"itr_status": [
{
"status": "ITR processed demand determined",
"date": "2025-08-10"
},
{
"status": "No more in PFA, Return is in progress",
"date": "2025-01-19"
},
{
"status": "PREPAID TAXES MATCHING FAILED. REFER DETAILS OF MISMATCH",
"date": "2025-12-24"
},
{
"status": "ITR TAKEN UP FOR PROCESSING",
"date": "2025-12-24"
},
{
"status": "Successfully e-verified",
"date": "2025-12-24"
},
{
"status": "Pending for e-verification",
"date": "2025-12-24"
},
{
"status": "ITR Filed",
"date": "2025-12-24"
}
],
"download_link": "https://aadhaar-kyc-docs.s3.amazonaws.com/itr/itr_LkksSlHruoCsxgigbaol/AAPPL2222A/378472830241221_json-2023-07-28-104657973377.json?X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Credential=AKIAY5K3QRM5PAM3NMHW%2F20230728%2Fap-south-1%2Fs3%2Faws4_req"
},
{
"itr_id": "1005",
"pan_no": "AAPPL2222A",
"filing_year": "2025-2027",
"acknowledgement_no": "1236542460240523",
"itr_form": "ITR-2",
"filing_type": "Rectification",
"filing_section": null,
"filing_date": "2025-05-24",
"itr_status": [
{
"status": "Rectification processed no demand no refund",
"date": "2025-06-23"
},
{
"status": "No more in PFA, Return is in progress",
"date": "2025-05-24"
},
{
"status": "ITR TAKEN UP FOR PROCESSING",
"date": "2025-05-24"
},
{
"status": "Rectification request received",
"date": "2025-05-24"
}
],
"download_link": "https://aadhaar-kyc-docs.s3.amazonaws.com/itr/itr_LkksSlHruoCsxgigbaol/AAPPL2222A/166852460240523_json-2023-07-28-104658136714.json?X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Credential=AKIAY5K3QRM5PAM3NMHW%2F20230728%2Fap-south-1%2Fs3%2Faws4_request&X-Amz-Date=20230728T104701Z&X-Amz-Expires=600&X"
},
{
"itr_id": "1234",
"pan_no": "AAPPL2222A",
"filing_year": "2015-2027",
"acknowledgement_no": "123646550050121",
"itr_form": "ITR-1",
"filing_type": "Original",
"filing_section": "139(1)",
"filing_date": "2025-01-05",
"itr_status": [
{
"status": "ITR processed demand determined",
"date": "2025-01-07"
},
{
"status": "No more in PFA, Return is in progress",
"date": "2025-01-07"
},
{
"status": "ITR TAKEN UP FOR PROCESSING",
"date": "2025-01-07"
},
{
"status": "e-Verified",
"date": "2025-01-05"
}
],
"download_link": "https://aadhaar-kyc-docs.s3.amazonaws.com/itr/itr_LkksSlHruoCsxgigbaol/AAPPL2222A/106046550050121_xml-2023-07-28-104658272302.xml?X-Amz-Algorithm=AWS4X-Amz-Credential=AKIAY5K3QRM5PAM3NMHW%2F20230728%2Fap-south-1%2Fs3%2Faws4_request&X-Amz-Date=20230728T104701Z&X-Amz"
},
{
"itr_id": "114",
"pan_no": "AAPPL2222A",
"filing_year": "2015-2027",
"acknowledgement_no": "1236982870240523",
"itr_form": "ITR-1",
"filing_type": "Rectification",
"filing_section": null,
"filing_date": "2025-05-24",
"itr_status": [
{
"status": "Rectification request received",
"date": "2025-05-24"
}
],
"download_link": "https://aadhaar-kyc-docs.s3.amazonaws.com/itr/itr_LkksSlHruoCsxgigbaol/AAPPL2222A/166222870240523_xml-2023-07-28-104658656354.xml?X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Credential=AKIAY4_request&X-Amz-Date=20230728T104701Z&X-Amz-Expires=600&X-Amz-SignedHeaders=host&04eb025fe"
},
{
"itr_id": "1208",
"pan_no": "AAPPL2222A",
"filing_year": "2018-2019",
"acknowledgement_no": "023121890230819",
"itr_form": "ITR-1",
"filing_type": "Original",
"filing_section": "139(1)",
"filing_date": "2015-08-23",
"itr_status": [
{
"status": "ITR processed no demand no refund",
"date": "2015-10-14"
},
{
"status": "ITR TAKEN UP FOR PROCESSING",
"date": "2015-09-02"
},
{
"status": "EVC Accepted",
"date": "2015-08-30"
},
{
"status": "e-Verified",
"date": "2015-08-23"
}
],
"download_link": "https://aadhaar-kyc-docs.s3.amazonaws.com/itr/itr_LkksSlHruoCsxgigbaol/AAPPL2222A/864781890230819_xml-2023-07-28-104658935037.xml?X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Credential=AKIAY5K3QRM5PAM3NMHW%2F2023X1d17655dba0c09ca641bf95c81eee6becfdd30e22d88c674e1b4f0ad6b32fb2"
},
{
"itr_id": "2897",
"pan_no": "AAPPL2222A",
"filing_year": "2019-2018",
"acknowledgement_no": "185476180280818",
"itr_form": "ITR-2",
"filing_type": "Original",
"filing_section": "139(1)",
"filing_date": "2017-08-28",
"itr_status": [
{
"status": "ITR processed no demand no refund",
"date": "2019-02-05"
},
{
"status": "EVC Accepted",
"date": "2017-09-05"
},
{
"status": "e-Verified",
"date": "2019-08-28"
}
],
"download_link": "https://aadhaar-kyc-docs.s3.amazonaws.com/itr/itr_LkksSlHruoCsxgigbaol/AAPPL2222A/185476180280818_xml-2023-07-28-104659177365.xml?XAKIAY5K3QRM5PAM3NMHW%2F20230728%2Fap-south-1%2Fs3%2Faws4_request&X-Amz-Date=20230728T104701Z&X-Amz-Exfdbbc18647"
},
{
"itr_id": "6451",
"pan_no": "AAPPL2222A",
"filing_year": "2016-2017",
"acknowledgement_no": "123232260010817",
"itr_form": "ITR-1",
"filing_type": "Original",
"filing_section": "139(1)",
"filing_date": "2017-08-01",
"itr_status": [
{
"status": "ITR processed no demand no refund",
"date": "2018-08-19"
},
{
"status": "ITR TAKEN UP FOR PROCESSING",
"date": "2019-08-15"
},
{
"status": "EVC Accepted",
"date": "2020-08-03"
},
{
"status": "e-Verified",
"date": "2021-08-01"
}
],
"download_link": "https://aadhaar-kyc-docs.s3.amazonaws.com/itr/itr_LkksSlHruoCsxgigbaol/AAPPL2222A/102356260010817_xml-2023-07-28-104659377341.xml?X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-CredentialDate=20230728T104701Z&X-Amz-Expires=600&X-Amz-SignedHeaders=host&X-Amzc7f89a93"
},
{
"itr_id": "312",
"pan_no": "AAPPL2222A",
"filing_year": "2015-2016",
"acknowledgement_no": "526554320050816",
"itr_form": "ITR-2",
"filing_type": "Original",
"filing_section": "139(1)",
"filing_date": "2016-08-05",
"itr_status": [
{
"status": "ITR processed no demand no refund",
"date": "2016-10-08"
},
{
"status": "ITR TAKEN UP FOR PROCESSING",
"date": "2016-09-13"
},
{
"status": "ITRV Received",
"date": "2016-08-21"
}
],
"download_link": "https://aadhaar-kyc-docs.s3.amazonaws.com/itr/itr_LkksSlHruoCsxgigbaol/AAPPL2222A/391854320050816_xml-2023-07-28-104659594771.xml?X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Credential=AKIAY5K3QRM5PAM3NMHW%2F20230728%2Fap-south-1%2Fs3%2Faws4_request&X-Amz-Date=20230728T104701Z&X-Amz-Expires=600"
},
{
"itr_id": "482",
"pan_no": "AAPPL2222A",
"filing_year": "2014-2015",
"acknowledgement_no": "1265319080260815",
"itr_form": "ITR-2",
"filing_type": "Original",
"filing_section": "139(1)",
"filing_date": "2015-08-26",
"itr_status": [
{
"status": "ITR processed no demand no refund",
"date": "2015-10-15"
},
{
"status": "ITR TAKEN UP FOR PROCESSING",
"date": "2015-10-09"
},
{
"status": "ITRV Received",
"date": "2015-09-09"
}
],
"download_link": "https://aadhaar-kyc-docs.s3.amazonaws.com/itr/itr_LkksSlHruoCsxgigbaol712619080260815_xml-2023-07-28-104659866780.xml?X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Credential=AKIAY5K3QRM5PAM3NMHW%2F20230728%2Fap-south-1%2Fs3%2Faws4_request&X-Amz-Date=20230728T104701Z&X-Amz-Expires=600&X"
},
{
"itr_id": "43",
"pan_no": "AAPPL2222A",
"filing_year": "2013-2014",
"acknowledgement_no": "3018600000310714",
"itr_form": "ITR-1",
"filing_type": "Original",
"filing_section": "139(1)",
"filing_date": "2014-07-31",
"itr_status": [
{
"status": "ITR processed no demand no refund",
"date": "2014-11-01"
},
{
"status": "ITRV Received",
"date": "2014-09-18"
}
],
"download_link": "https://aadhaar-kyc-docs.s3.amazonaws.com/itr/itr_LkksSlHruoCsxgigbaol/AAPPL2222A/301865660310714_xml-2023-07-28-104700101736.xml?X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Credential=AKIAY5K3QRM5PAM3NMHW%2F20230728%2Fap-south-1%2Fs3%2FaX-Amz-Signature=ceec86a4fcd0990653655ba6b02545399ce43c2012210b5ae9d382dc684a6f7c"
},
{
"itr_id": "31",
"pan_no": "AAPPL2222A",
"filing_year": "2012-2013",
"acknowledgement_no": "15278965400050813",
"itr_form": "ITR-1",
"filing_type": "Original",
"filing_section": "139(1)",
"filing_date": "2013-08-05",
"itr_status": [
{
"status": "ITR processed no demand no refund",
"date": "2013-11-13"
},
{
"status": "ITRV Received",
"date": "2013-08-22"
}
],
"download_link": "https://aadhaar-kyc-docs.s3.amazonaws.com/itr/itr_LkksSlHruoCsxgigbaol/AAPPL2222A/736525700050813_xml-2023-07-28-104700230794.xml?X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Credential=AKIAY5K3QRM5PAM3NMHW%2F20230728%2Fap-south-1%2Fs3%X-Amz-Signature=d73111b0d48f162bb3380a22b51dc26709b093a063f1eb6a07d7210a2e89ac66"
},
{
"itr_id": "707",
"pan_no": "AAPPL2222A",
"filing_year": "2011-2012",
"acknowledgement_no": "60012356100313",
"itr_form": "ITR-1",
"filing_type": "Original",
"filing_section": "139(4)",
"filing_date": "2013-03-29",
"itr_status": [
{
"status": "ITR processed no demand no refund",
"date": "2013-07-09"
},
{
"status": "ITRV Received",
"date": "2013-07-04"
}
],
"download_link": "https://aadhaar-kyc-docs.s3.amazonaws.com/itr/itr_LkksSlHruoCsxgigbaol/AAPPL2222A/600341410290313_xml-2023-07-28-104700425690.xml?X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Credential=AKIAY5K3QRM5PAM3NMHW%2F20230728%2Fap-south-1%2Fs3%2Faws4_reqdc00f071a"
},
{
"itr_id": "374",
"pan_no": "AAPPL2222A",
"filing_year": "2010-2011",
"acknowledgement_no": "3675123456280312",
"itr_form": "ITR-1",
"filing_type": "Original",
"filing_section": "139(4)",
"filing_date": "2012-03-28",
"itr_status": [
{
"status": "ITR processed no demand no refund",
"date": "2012-07-08"
},
{
"status": "ITRV Received",
"date": "2012-06-21"
}
],
"download_link": "https://aadhaar-kyc-docs.s3.amazonaws.com/itr/itr_LkksSlHruoCsxgigbaol/AAPPL2222A/367563910280312_xml-2023-07-28-104700589972.xml?X-Amz-Algorithm=IAY5K3QRM5PAM3NMHW%2F20230728%2Fap-south-1%2Fs3%2Faws4_request&X-Amz-Date=20230728T104701Z&X-Amz-Expires=600&Xffc55a8b8"
},
{
"itr_id": "263",
"pan_no": "AAPPL2222A",
"filing_year": "2009-2010",
"acknowledgement_no": "123045640260311",
"itr_form": "ITR-2",
"filing_type": "Original",
"filing_section": "139(4)",
"filing_date": "2011-03-26",
"itr_status": [
{
"status": "Refund Paid",
"date": "2014-11-25"
},
{
"status": "Refund Failed at CPC",
"date": "2013-04-22"
},
{
"status": "Refund Failed at CPC",
"date": "2013-04-22"
},
{
"status": "Refund Unpaid",
"date": "2011-06-29"
},
{
"status": "ITR processed refund determined and sent out to Refund Banker",
"date": "2011-06-08"
},
{
"status": "ITRV Received",
"date": "2011-05-15"
}
],
"download_link": "https://aadhaar-kyc-docs.s3.amazonaws.com/itr/itr_LkksSlHruoCsxgigbaol/AAPPL2222A/203727640260311_xml-2023-07-28-104700799228.xml?X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Credential=AKIAY5K3QRM5PAM3NMHW%2F20230728%2Fap-south-1%2Fs3%2FawX-Amz-SignedHeaders=host&X-Amz-Signature=54fa6882d54c6be350c24f9004d1e9100aaa1cee164c53ea9124939091134dde"
},
{
"itr_id": "866",
"pan_no": "AAPPL2222A",
"filing_year": "2008-2009",
"acknowledgement_no": "1208421460318910",
"itr_form": "ITR-1",
"filing_type": "Original",
"filing_section": "139(4)",
"filing_date": "2010-03-31",
"itr_status": [
{
"status": "ITR processed no demand no refund",
"date": "2010-07-06"
},
{
"status": "ITRV Received",
"date": "2010-04-19"
}
],
"download_link": "https://aadhaar-kyc-docs.s3.amazonaws.com/itr/itr_LkksSlHruoCsxgigbaol/AAPPL2222A/119421460310310_xml-2023-07-28-104700985830.xml?X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Credential=AKIAY5K3QRM5PAM3NMHW%2F20230728%2Fap-south-1%2Fs3%2Faws4_request&X-Amz-SignedHeaders=host&X-Amz-Signature=edc31cc2aeb0c4097952121e0f2985b09c4b09ade8965f4bc3adae41c4a4349b"
}
]
},
"status_code": 200,
"success": true,
"message": "ITR downloaded successfully",
"message_code": "success"
}Request
Body Params application/json