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

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

FieldTypeDescription
[]arrayOne entry per return filed in the years checked.
[].assessment_yearstringAssessment year of the return.
[].filing_yearstringYear the return was filed.
[].pan_numberstringPAN the return was filed under.
[].acknowledgement_numberstringAcknowledgement number of the filing.
[].filing_typestringHow 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.