API reference / Income (ITR)
ITR-V verification
Checks filed returns for the last 1 to 5 years (years, default 3) with the taxpayer's password or a session_id.
POST
/v1/tax/itr/verify- 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 and never stored, logged or returned.
- result is a list, not an object; the field names above are for each item in it.
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. |
years | integer | No | How many recent years to check, 1 to 5. Defaults to 3. |
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/verify' \
-H "Authorization: Bearer $GRAPPI_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"username": "ABCDE1234F",
"session_id": "sess_123456"
}'Sample response
{
"request_id": "req_01HZY3K8M2",
"result": [
{
"assessment_year": "2023-24",
"filing_year": "2023",
"pan_number": "ABCDE1234F",
"acknowledgement_number": "123456789012345",
"filing_type": "Original"
}
]
}Response fields
| Field | Type | Description |
|---|---|---|
[] | array | One entry per return filed in the years checked. |
[].assessment_year | string | Assessment year of the return. |
[].filing_year | string | Year the return was filed. |
[].pan_number | string | PAN the return was filed under. |
[].acknowledgement_number | string | Acknowledgement number of the filing. |
[].filing_type | string | How the return was filed, for example original or revised. |
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.