ITR Fetch guide
How to fetch a taxpayer's filed income tax returns with POST /api/v1/itr/requests, and what to expect back.
ITR Fetch logs in to the income tax e-filing portal with the taxpayer's own user ID and password, and returns their latest filed returns with the full ITR JSON. The endpoints are in the ITR Verification reference.
Three ways to get the result
The same result body comes back in all three, so you can treat whichever you see first as the answer and ignore the rest. On webhooks, deduplicate on event_id.
How a request runs
Submit
POST /api/v1/itr/requests with userName, password, consent, consent_text and a webhook_url. Add your own reference_id so a retry is safe, and range (1 to 5, default 3) for how many years you want.
Wait up to 25 seconds
The call stays open. Most failures, such as a wrong password, come back here at once with their own HTTP status and an error_code.
Otherwise, collect it later
If there is no outcome yet, you get 202 Accepted and a request_id. The result arrives on your webhook, or you poll the status API after 30 seconds, 1 minute and 5 minutes, then every 15 minutes.
What you can get back
| Outcome | Where you see it | What to do |
|---|---|---|
COMPLETED | 200, webhook, status API | Read result, keyed by financial year. years_missing lists any year that could not be delivered. |
FAILED | The failure's HTTP status, webhook, status API | Read error_code. The full list with what to do is in ITR Fetch errors. |
PROCESSING with a notice | 202, status API | Nothing. The portal is temporarily refusing logins and the request is retried automatically. retry_at says when. |
| Refused before it starts | 400, 402, 403, 429, 503 | Nothing was queued or charged. 429 and 503 carry data.retry_at, the time a new request is accepted. |
Good to know
| Topic | How it works |
|---|---|
| Duplicates | Sending the same reference_id again returns the original request (duplicate: true), with no second fetch or charge. |
| Years | range is 1 to 5. If fewer returns are filed, the request still completes with the years that exist. The latest filing wins when a year has an original and a revised return. |
| Charges | One charge for each request that completes with at least one return. Failed, timed-out, refused and delayed requests, and status reads, are free. The response's isBillable is always false, even on COMPLETED, because the charge is made separately when the result arrives. |
| Webhook retries | A failed delivery is retried after 30 seconds, 2 minutes and 10 minutes. webhook_status and webhook_attempts on the status API show what happened. |
| Retention | Results stay readable for 7 days. |
| Privacy | The password is encrypted on arrival and never stored in readable form or logged. |
A wrong password is not tried again, because repeated attempts can lock the taxpayer's account. If the portal rejected a password recently, a new request for the same taxpayer is refused with 429 CREDENTIALS_RECENTLY_REJECTED until the time in retry_at. Ask the taxpayer to check the password on the portal, then submit again with a new reference_id. The portal also ends the taxpayer's other session when the fetch logs in.