API reference / Income (ITR)
ITR fetch
Filed income-tax returns pulled with the taxpayer's own income-tax portal login. The password is passed through, never stored or logged.
POST
/v1/tax/itr/fetch- Authentication
- Bearer token
- Scope
credit:read
Before you integrate
- At least one of password or session_id is required.
- The password is passed straight through to the income-tax portal. It is never stored, logged or returned in the reply.
Request body
| Field | Type | Required | Description |
|---|---|---|---|
username | string | Yes | The taxpayer's income-tax portal user ID, usually the PAN; 5 to 20 letters and digits, upper-cased for you. |
password | string | No | The taxpayer's income-tax portal password, up to 100 characters. Send this or session_id. |
session_id | string | No | A session ID from an earlier login, 6 to 300 characters. Send this or password. |
Sample code
Set your key in the GRAPPI_API_KEY environment variable. Sample values are placeholders.
curl -sS -X POST 'https://grappi.ai/v1/tax/itr/fetch' \
-H "Authorization: Bearer $GRAPPI_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"username": "ABCDE1234F",
"password": "taxpayer-portal-password"
}'Sample response
{
"request_id": "req_01HZY3K8M2",
"result": {
"2023-24": {
"form": "ITR-1",
"json": {
"itr": {}
}
},
"2022-23": {
"form": "ITR-1",
"json": {
"itr": {}
}
}
}
}Response fields
| Field | Type | Description |
|---|---|---|
{assessment_year} | object | One entry for each assessment year found, keyed by the year, for example 2023-24. |
{assessment_year}.form | string | The ITR form filed that year. |
{assessment_year}.json | object | The return as filed. |
{assessment_year}.json.itr | object | The return's contents as structured data. |
Errors
Every failure has the same shape. A call that fails on our side or at the data source is refunded to your wallet; a "no record found" answer is charged. See the error reference.