Company ITR And Gross Revenue Details By PAN Number API
GET COMPANY ITR FILING DETAILS AND GROSS TURNOVER BY PAN NUMBER
Description
This API provides instant access to the latest details of Income Tax Return (ITR) filings and the gross revenue of a company based on the provided business PAN number. It's especially useful for conducting real-time analysis of company/vendor credit risks for lending, onboarding, and compliance purposes.
Please be aware that this functionality is exclusively available for businesses (Companies and MSMEs) that submit income tax returns (ITR) using one of the following forms: ITR-3, ITR-4, ITR-5, and ITR-6. Individuals, HUFs, or other entities using ITR-1, ITR-2, or ITR-7 are not compatible.
API Details
Request
| Type | URL | Current / LTS Version | Min Version | Max Version |
|---|---|---|---|---|
| POST | https://api.attestr.com/api/{version}/public/corpx/itr | v2 | v2 |
Request Body Parameters
| Type | Name | Description | Optional (default) | Min Version | Max Version |
|---|---|---|---|---|---|
| String | pan | Business PAN Number | Required | v2 | |
| Date | birthOrIncorporatedDate | Date of incorporation of the company in DD/MM/YYYY format | Required | v2 | |
| String | name | Registered legal name as per PAN | Required | v2 |
If in case you don't have the company incorporation date and registered legal name information for a given company PAN number, consider using our Comprehensive PAN Verification API to retrieve the same and pass the values to this API to fetch ITR and gross revenue details.
Request Header Parameters
| Type | Name | Value / Description | Optional | Min Version | Max Version |
|---|---|---|---|---|---|
| String | Content-Type | application/json | Required | v2 | |
| String | Authorization | Basic {authToken} | Required | v2 |
If you do not have the authentication token, please refer to Register App to generate one.
Sample Request
{ "pan": "AAXXX3063A", "birthOrIncorporatedDate": "26/11/2011", "name": "Acme Solutions Private Limited"}Response
HTTP status code 200
| Key | Description | Type | Min Version | Max Version |
|---|---|---|---|---|
| valid | True | false indicating if the provided PAN details are a valid registered business. | Boolean | v2 | |
| panStatus | Status of the provided PAN details. Possible values are as follows. VALID_DETAILS_MATCHED Provided details match. VALID_DETAILS_NOT_MATCHED Provided details do not match INVALID Provided PAN does not exist MAX_LIMIT_EXCEEDED Maximum daily attempts exceeded for the provided PAN | String | v2 | |
| fy | Previous financial year for which the ITR details are furnished in this API response | String | v2 | |
| itrFiled | Whether ITR has been filed in the indicated financial year. Only ITR - 3,4,5,6 types are supported. | Boolean | v2 | |
| itrType | Type of the ITR filed in the financial year indicated. Possible values are as follows. ITR_3_5_6 : For ITR-3, ITR-5, ITR-6 ITR_4 : For ITR-4 | String | v2 | |
| grossTurnover | Gross turnover of the company in the indicated financial year | String | v2 | |
| grossTurnoverFormatted | Indian currency formatted representation of the gross turnover. | String | v2 | |
| exportTurnover | Export turnover of the company in the indicated financial year, if any. | String | v2 | |
| exportTurnoverFormatted | Indian currency formatted representation of the export turnover. | String | v2 | |
| message | Message if the provided PAN details are invalid or details are not available | String | v2 |
Sample Response
Sample successful response for valid PAN details
{ "valid": true, "message": null, "panStatus": "VALID_DETAILS_MATCHED", "fy": "2022-23", "itrFiled": true, "itrType": "ITR_3_5_6", "grossTurnover": "19243457", "grossTurnoverFormatted": "₹1,92,43,457.00", "exportTurnover": "78320", "exportTurnoverFormatted": "₹78,320.00"}Sample response for invalid PAN number
{ "valid": false, "message": "Provided PAN details are invalid / not active", "panStatus": "INVALID"}Sample response for a particular PAN number daily limit exceeded
{ "valid": false, "message": "Max attempts exceeded for the provided PAN", "panStatus": "MAX_LIMIT_EXCEEDED"}Sample response for Individual / Unsupported ITR Type
{ "valid": false, "message": "ITR not filed or unsupported ITR type (ITR-1, ITR-2 or ITR-7)", "panStatus": "VALID_DETAILS_MATCHED"}Error Response
| Parameter | Type | Description |
|---|---|---|
| code | Number | Unique error codes for different errors. Always available. |
| message | String | Error message describing the error. Always Available. |
| details | String | Detail error message. Available only for certain types of errors. |
Error Codes
| HTTP Status | Error Code | Error Message |
|---|---|---|
| 400 | 4001 | Malformed data or missing required parameter values |
| 400 | 4005 | Operation could not be performed due to low credits balance |
| 401 | 4016 | Invalid client authorization |
| 403 | 4031 | Unauthorized access |
| 403 | 4035 | Requested service is not provisioned for your account |
| 403 | 4039 | Client's IP address is not whitelisted |
| 403 | 4035 | Requested service is not provisioned for your account |
| 429 | 4291 | Maximum account rate limit exceeded |
| 429 | 4292 | Maximum API rate limit exceeded |
| 429 | 4293 | Maximum account daily limit exceeded |
| 429 | 4294 | Maximum API daily limit exceeded |
| 500 | 5001 | Request could not be processed |
Sample Error Response
{ "code": 4001, "message": "Malformed data or missing required parameter values"}