ITR eProceeding Notice

Endpoint Overview

POST /api/v1/itr/eproceeding-notice

Description

The ITR eProceeding Notice API retrieves all e-proceeding notices issued by the Income Tax Department of India against a taxpayer, organized by assessment year. This is a secondary endpoint that requires a client_id obtained from a prior ITR (Income Tax Return) verification API call.

E-proceeding notices are official communications issued by the Income Tax Department under various sections of the Income Tax Act (e.g., Section 143, 148, 154, etc.) during assessments, reassessments, rectifications, or inquiries. These notices are critical legal documents that indicate the department's scrutiny actions against a taxpayer. This API returns downloadable PDF links for each notice, grouped by assessment year, providing a complete audit trail of all departmental proceedings.

By programmatically accessing these notices, businesses can automate tax compliance monitoring, perform thorough financial due diligence, and proactively identify taxpayers who are under active scrutiny — all without requiring manual login to the Income Tax e-Filing portal.

Key Benefits

Comprehensive Notice Retrieval: Fetches all e-proceeding notices across multiple assessment years in a single API call, providing a complete view of a taxpayer's scrutiny history.

Downloadable PDF Documents: Returns pre-signed, time-limited URLs for each notice PDF, enabling direct document download and archival without manual portal access.

Assessment Year Grouping: Notices are systematically organized by assessment year, making it easy to correlate proceedings with specific financial years.

Automated Compliance Monitoring: Eliminates the need for manual e-Filing portal checks, enabling real-time or scheduled monitoring of departmental actions against taxpayers.

Use Cases

Banking & Financial Services

Legal & Compliance

Enterprise & Corporate

Loan Underwriting Due Diligence: Before sanctioning large loans, banks can verify whether a borrower has any pending income tax proceedings or scrutiny notices, which may indicate potential financial risk or undisclosed liabilities.

Credit Risk Assessment: NBFCs and fintech lenders can incorporate e-proceeding notice data into credit scoring models to flag applicants who are under active tax scrutiny.

Portfolio Monitoring: Continuously monitor existing borrowers for new tax proceedings that could impact their repayment capacity or financial stability.

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

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

Request Parameters

Request Headers

Header	Required	Description
`Authorization`	Yes	Bearer token for authentication. Format: `Bearer <JWT_TOKEN>`. Use the appropriate token for sandbox or production environment.
`Content-Type`	Yes	Must be set to `application/json`.

Request Body

Parameter	Type	Required	Description
`client_id`	string	Yes	The unique client identifier returned from a prior ITR verification API call.

Example Request

{
  "client_id": "itr_FWhvWleUwutGOAzxXtnk"
}

Process Response

Response Parameters

Parameter	Type	Description
`data`	object	The root data object containing the e-proceeding notice information.
`data.client_id`	string	The unique client identifier associated with this request.
`data.eproceeding_notice_data`	array	An array of objects, each representing e-proceeding notices for a specific assessment year.
`data.eproceeding_notice_data[].assessment_year`	string	The assessment year for which the notices were issued (e.g., `"2015"`).
`data.eproceeding_notice_data[].notice_pdf_list`	array	An array of pre-signed S3 URLs pointing to downloadable PDF files of each individual notice issued for this assessment year. These URLs are time-limited and expire after a short duration.
`status_code`	integer	HTTP status code of the response (e.g., `200` for success).
`success`	boolean	Indicates whether the API call was successful (`true` or `false`).
`message`	string/null	A human-readable message providing additional context. `null` on success.
`message_code`	string	A machine-readable code indicating the result status (e.g., `"success"`).

Example Successful Response

{
  "data": {
    "client_id": "itr_UIkvMTidupyhokiQbrft",
    "eproceeding_notice_data": [
      {
        "assessment_year": "2015",
        "notice_pdf_list": [
          "https://aadhaar-kyc-docs.s3.amazonaws.com/eproceedings_notice/AAACA1547M/itr_UIkvMTidupyhokiQbrft/1401823/216407333/147335552-2026-02-27-064312364661.pdf?X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Credential=AKIAY5K3QRM5KVPBYKKE%2F20260227%2Fap-south-1%2Fs3%2Faws4_request&X-Amz-Date=20260227T064526Z&X-Amz-Expires=600&X-Amz-SignedHeaders=host&X-Amz-Signature=50fdcff7ece00b5b56069a08bba5766df37a8e50c12a1adw0677dee5e7fba32e",
          "https://aadhaar-kyc-docs.s3.amazonaws.com/eproceedings_notice/AAACA1547M/itr_UIkvMTidupyhokiQbrft/1401823/215076592/118066035-2026-02-27-064313080830.pdf?X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Credential=AKIAY5K3QRM5KVPBYKKE%2F20260227%2Fap-south-1%2Fs3%2Faws4_request&X-Amz-Date=20260227T064526Z&X-Amz-Expires=600&X-Amz-SignedHeaders=host&X-Amz-Signature=788cbfb9649f9d120f6330d1f8079ce6dabd9f5a8e91a542115d6e1626588cdd",
          "https://aadhaar-kyc-docs.s3.amazonaws.com/eproceedings_notice/AAACA1547M/itr_UIkvMTidupyhokiQbrft/1401823/102386461/43947490-2026-02-27-064313639831.pdf?X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Credential=AKIAY5K3QRM5KVPBYKKE%2F20260227%2Fap-south-1%2Fs3%2Faws4_request&X-Amz-Date=20260227T064526Z&X-Amz-Expires=600&X-Amz-SignedHeaders=host&X-Amz-Signature=09b454d123459e6d1e72ea903027237fcc0a674cb51213099dc1c1d5dc0ffc4a"
        ]
      }
    ]
  },
  "status_code": 200,
  "success": true,
  "message": null,
  "message_code": "success"
}

Possible Error Responses

401 Unauthorized

422 E-proceedings Notice Not Found

500 Internal Server Error

{
    "data": null,
    "error": null,
    "message": "Your access token is not valid for this API/Scope. Please contact support for help.",
    "status_code": 401,
    "success": false,
    "message_code": "invalid_token"
}

This error occurs when the JWT Bearer token is missing, expired, or invalid. Generate a new token and ensure it is correctly included in the Authorization header.

Integration Best Practices

Security Recommendations

Download PDFs Promptly: The pre-signed S3 URLs in the notice_pdf_list are time-limited (typically 10 minutes). Download and store the notice PDFs in your own secure storage immediately upon receiving the response.

Secure Token Storage: Never hardcode JWT tokens in client-side code or version control systems. Use environment variables or a secure secrets manager.

Encrypt Stored Documents: E-proceeding notices contain sensitive taxpayer information. Ensure all downloaded PDFs are encrypted at rest and access-controlled within your systems.

Implement Access Logging: Log all API calls and document downloads with user identifiers and timestamps to maintain a complete audit trail for compliance purposes.

User Experience Guidelines

Prerequisite Guidance: Clearly communicate to users that a valid client_id from a prior ITR verification is required before they can access e-proceeding notices. Guide them through the prerequisite step if the ID is unavailable.

Assessment Year Organization: Display notices grouped by assessment year in a clear, chronological layout (e.g., accordion or tabbed interface) so users can quickly locate notices for a specific financial period.

Download Status Indicators: Provide visual feedback (progress bars, spinners) when downloading notice PDFs, and clearly indicate success or failure for each document.

Expiry Warnings: Inform users that PDF download links are temporary. If links have expired, provide a clear option to re-trigger the API call to obtain fresh URLs.

Code Samples

cURL

Python

Node.js

Related APIs

ITR Verification API: The primary ITR verification endpoint that returns the client_id required as input for this eProceeding Notice API. Must be called first to establish the taxpayer context.

ITR eProceeding Response API: Retrieves the taxpayer's responses to e-proceeding notices, complementing this API by providing the other side of the proceeding communication.

ITR Demand Details API: Fetches outstanding tax demand details raised by the Income Tax Department, often associated with the same proceedings whose notices are retrieved by this API.

ITR Compliance Check API: Provides a broader compliance overview of the taxpayer, of which active e-proceedings are a key component.

Compliance and Legal Considerations

Data Sensitivity: E-proceeding notices contain highly sensitive taxpayer information including PAN, assessment details, and tax department observations. Handle this data in strict compliance with India's Information Technology Act, 2000, and applicable data protection regulations.

Consent Requirement: Ensure you have explicit, documented consent from the taxpayer or their authorized representative before accessing their e-proceeding notice data. Unauthorized access may constitute a violation of privacy laws.

PDF URL Expiry: The pre-signed S3 URLs have a limited validity period (typically 600 seconds / 10 minutes). Do not store or share these URLs beyond their expiry. Instead, download and securely store the PDF documents within your own infrastructure.

Retention Policies: Establish and follow clear data retention policies for downloaded notice documents. Income tax records in India are generally required to be maintained for a minimum of 6–8 years from the end of the relevant assessment year, depending on the nature of the case.

Audit Trail: Maintain a comprehensive log of who accessed which notices and when, to ensure accountability and compliance with regulatory audit requirements.

Provide your bearer token in the

Authorization

header when making requests to protected resources.

Example:

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

curl --location --request POST 'https://kyc-api.surepass.app/api/v1/itr/eproceeding-notice' \ --header 'Authorization: Bearer <token>' \ --header 'Content-Type: application/json' \ --data-raw '{ "client_id": "itr_FWhvWleUojtGOAzxltnk" }'

{ "data": { "client_id": "itr_UIkvMTidupyhokiQbrft", "eproceeding_notice_data": [ { "assessment_year": "2015", "notice_pdf_list": [ "https://aadhaar-kyc-docs.s3.amazonaws.com/eproceedings_notice/AAACA1547M/itr_UIkvMTidupyhokiQbrft/1401823/216407333/147335552-2026-02-27-064312364661.pdf?X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Credential=AKIAY5K3QRM5KVPBYKKE%2F20260227%2Fap-south-1%2Fs3%2Faws4_request&X-Amz-Date=20260227T064526Z&X-Amz-Expires=600&X-Amz-SignedHeaders=host&X-Amz-Signature=50fdcff7ece00b5b56069a08bba5766df37a8e50c12a1adw0677dee5e7fba32e", "https://aadhaar-kyc-docs.s3.amazonaws.com/eproceedings_notice/AAACA1547M/itr_UIkvMTidupyhokiQbrft/1401823/215076592/118066035-2026-02-27-064313080830.pdf?X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Credential=AKIAY5K3QRM5KVPBYKKE%2F20260227%2Fap-south-1%2Fs3%2Faws4_request&X-Amz-Date=20260227T064526Z&X-Amz-Expires=600&X-Amz-SignedHeaders=host&X-Amz-Signature=788cbfb9649f9d120f6330d1f8079ce6dabd9f5a8e91a542115d6e1626588cdd", "https://aadhaar-kyc-docs.s3.amazonaws.com/eproceedings_notice/AAACA1547M/itr_UIkvMTidupyhokiQbrft/1401823/102386461/43947490-2026-02-27-064313639831.pdf?X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Credential=AKIAY5K3QRM5KVPBYKKE%2F20260227%2Fap-south-1%2Fs3%2Faws4_request&X-Amz-Date=20260227T064526Z&X-Amz-Expires=600&X-Amz-SignedHeaders=host&X-Amz-Signature=09b454d123459e6d1e72ea903027237fcc0a674cb51213099dc1c1d5dc0ffc4a" ] } ] }, "status_code": 200, "success": true, "message": null, "message_code": "success" }

Download EProceeding Notice

ITR eProceeding Notice#

Description#

Use Cases#

Technical Implementation#

Request Headers#

Request Body#

Example Request#

Response Parameters#

Example Successful Response#

Possible Error Responses#

Integration Best Practices#

Code Samples#

Request

Responses