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

FieldTypeRequiredDescription
usernamestringYesThe taxpayer's income-tax portal user ID, usually the PAN; 5 to 20 letters and digits, upper-cased for you.
passwordstringNoThe taxpayer's income-tax portal password, up to 100 characters. Send this or session_id.
session_idstringNoA 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

FieldTypeDescription
{assessment_year}objectOne entry for each assessment year found, keyed by the year, for example 2023-24.
{assessment_year}.formstringThe ITR form filed that year.
{assessment_year}.jsonobjectThe return as filed.
{assessment_year}.json.itrobjectThe 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.