# Taxpayer Information

ClearTax provides APIs to verify if a GSTIN number is valid as per the Government.

* Never have a wrong GSTIN for your Vendor/Customer in your ERP.
* System/Product On-boarding Avoid GST Compliance errors.
* Improve overall efficiency by reducing back and forth due to mistakes in GSTINs.
* Get additional details related to the GSTIN you already have.

## Get Taxpayer Profile

You can verify the GSTIN number and avoid any mistakes in invoice preparation, tax payments.

You can get the taxpayer profile of a GSTIN by submitting a **GET** request to the GST API with the following request headers.

#### URL query String:

```
GET: {{host}}/gst/api/v0.2/taxable_entities/{{TAXABLE_ENTITY_ID}}/gstin_verification?gstin={{GSTIN_NUMBER_HERE}}
```

#### Request parameters:

| Parameters            | Parameter Type | Type   | Description                                                                |
| --------------------- | -------------- | ------ | -------------------------------------------------------------------------- |
| X-Cleartax-Auth-Token | Header         | String | Mandatory. The auth token generated from ClearTax user id and password.    |
| taxable\_entity\_id   | Path           | String | Required. This is the unique ID associated with the GSTIN in your account. |
| gstin                 | query          | String | Required. GSTIN number you wanted to validate                              |

#### Sample Request:

```
https://api.clear.in/gst/api/v0.2/taxable_entities/249ba4-7392-4fa2-b3a0-685c6c7ad87e/gstin_verification?gstin=29AAFCD5862R1ZR
```

#### Sample Response:

{% tabs %}
{% tab title="200" %}

```javascript
{
    "gstin": "29AAFCD5862R1ZR",
    "lgnm": "DEFMACRO SOFTWARE PRIVATE LIMITED",
    "stj": "LVO 015 A - BENGALURU",
    "ctj": "RANGE-ASD7",
    "rgdt": "01/07/2017",
    "ctb": "Private Limited Company",
    "dty": "Regular",
    "nba": [
        "Leasing Business",
        "Supplier of Services",
        "Recipient of Goods or Services",
        "Import",
        "Office / Sale Office"
    ],
    "sts": "Active",
    "cxdt": "",
    "tradeNam": "DEFMACRO SOFTWARE PRIVATE LIMITED",
    "stjCd": "KA004",
    "ctjCd": "YV0701",
    "pradr": {
        "addr": {
            "bnm": "Block 1",
            "st": "HOSUR MAIN ROAD",
            "loc": "BANGALORE",
            "bno": "23, 24 AMR TECH PARK",
            "stcd": "Karnataka",
            "flno": "First Floor",
            "lt": "",
            "lg": "",
            "dst": "Bengaluru (Bangalore) Urban",
            "city": "",
            "pncd": "560068"
        },
        "ntr": "Leasing Business, Supplier of Services, Recipient of Goods or Services, Import"
    },
    "adadr": [
        {
            "addr": {
                "bnm": "DSI Innovation Campus, AWFIS",
                "st": "Gharebhavipalya",
                "loc": "Bangalore",
                "bno": "Block A",
                "stcd": "Karnataka",
                "flno": "2nd Floor",
                "lt": "",
                "lg": "",
                "dst": "Bengaluru (Bangalore) Urban",
                "city": "",
                "pncd": "560068"
            },
            "ntr": "Office / Sale Office"
        },
        {
            "addr": {
                "bnm": "AMR Tech Park, Treebo",
                "st": "Hosur Main Road , Bommanahalli",
                "loc": "Bangalore",
                "bno": "Block 1, 23 and 24",
                "stcd": "Karnataka",
                "flno": "First Floor",
                "lt": "",
                "lg": "",
                "dst": "Bengaluru (Bangalore) Urban",
                "city": "",
                "pncd": "560068"
            },
            "ntr": "Office / Sale Office"
        }
    ],
    "filingFreq": "MONTHLY",
    "lastUpdated": "21/Sep/2020"
}
```

{% endtab %}

{% tab title="400" %}

```javascript
{
    "success": false,
    "message": "Invalid GSTIN format. Please enter a valid Format"
}
```

{% endtab %}
{% endtabs %}

#### Taxpayer API Objects

| Key   | Type   | Description |
| ----- | ------ | ----------- |
| stjCd | String | <p>         |

</p><p>State Jurisdiction Code
</p>       |
| lgnm     | String             | Legal Name of Business                        |
| stj      | String             | &#xD;State Jurisdiction&#xD;                  |
| dty      | String             | Taxpayer type                                 |
| adadr    | Array              | &#xD;Additional Place of Business Fields&#xD; |
| cxdt     | Date \[DD/MM/YYYY] | &#xD;Date Of Cancellation&#xD;                |
| gstin    | String             | GSTIN of the Tax Payer                        |
| nba      | Array              | Nature of Business Activity                   |
| lstupdt  | Date \[DD/MM/YYYY] | Last Updated Date                             |
| rgdt     | Date \[DD/MM/YYYY] | Date of Registration                          |
| ctb      | String             | Constitution of Business                      |
| pradr    | Object             | Principal Place of Business objects.          |
| tradeNam | String             | Trade Name                                    |
| sts      | String             | GSTIN Status                                  |
| ctjCd    | String             | &#xD;Centre Jurisdiction Code&#xD;            |
| ctj      | String             | &#xD;Centre Jurisdiction&#xD;                 |

#### Principal Place of Business object & fields

| Key         | Type    | Description                                        |
| ----------- | ------- | -------------------------------------------------- |
| bnm         | String  | Building Name                                      |
| st          | String  | Street                                             |
| loc         | String  | Location                                           |
| bno         | String  | Door Number                                        |
| stcd        | String  | State Name                                         |
| dst         | String  | District                                           |
| city        | String  | City                                               |
| flno        | String  | Floor Number                                       |
| lt          | String  | Latitude                                           |
| pncd        | Integer | Pin Code                                           |
| lg          | String  | Longitude                                          |
| ntr         | String  | Nature of principle place of business              |
| filingFreq  | String  | Filing frequency                                   |
| lastUpdated | String  | Date in which the provided GSTIN was last updated. |

## Get Taxpayer Compliance

#### URL query String:

```
GET: {{host}}/gst/api/v0.2/taxable_entities/{{TAXABLE_ENTITY_ID}}/returns_filing_status?gstin={{GSTIN_NUMBER_HERE}}
```

#### Request parameters:

| Parameters            | Parameter Type | Type   | Description                                                                |
| --------------------- | -------------- | ------ | -------------------------------------------------------------------------- |
| X-Cleartax-Auth-Token | Header         | String | Mandatory. The auth token generated from ClearTax user id and password.    |
| taxable\_entity\_id   | Path           | String | Required. This is the unique ID associated with the GSTIN in your account. |
| gstin                 | Query          | String | Required. GSTIN number you wanted to validate                              |

#### Sample Request:

```
https://api.clear.in/gst/api/v0.2/taxable_entities/249f74-7392-4fa2-b3a0-685c6c7ad87e/returns_filing_status?gstin=29AAFCD5862R1ZR
```

#### Sample Response:

{% tabs %}
{% tab title="200" %}

```
[
  {
      "EFiledlist": [
          {
              "arn": "AA2702188342463",
              "ret_prd": "022018",
              "mof": "ONLINE",
              "dof": "20-03-2018",
              "rtntype": "GSTR3B",
              "status": "Filed",
              "valid": "Y",
              "is_filed_through_ct": false,
              "filedThroughCT": false
          }
      ]
  },
  {
      "EFiledlist": [
          {
              "arn": "AB270219056196Y",
              "ret_prd": "022019",
              "mof": "ONLINE",
              "dof": "20-03-2019",
              "rtntype": "GSTR3B",
              "status": "Filed",
              "valid": "Y",
              "is_filed_through_ct": false,
              "filedThroughCT": false
          }
      ]
  },
  {
      "EFiledlist": [
          {
              "arn": "AB270220282959T",
              "ret_prd": "022020",
              "mof": "ONLINE",
              "dof": "20-03-2020",
              "rtntype": "GSTR3B",
              "status": "Filed",
              "valid": "Y",
              "is_filed_through_ct": false,
              "filedThroughCT": false
          }
      ]
  }
]
```

{% endtab %}

{% tab title="400" %}

```
{
    "success": false,
    "message": "Invalid GSTIN format. Please enter a valid Format"
}
```

{% endtab %}
{% endtabs %}

#### Filed list object & fields

| Key                    | Type    | Description                    |
| ---------------------- | ------- | ------------------------------ |
| arn                    | String  | GSTIN number                   |
| ret\_prd               | String  | Return period                  |
| mof                    | String  | Mode of filing                 |
| dof                    | String  | Date of filing                 |
| rtntype                | String  | Return type                    |
| status                 | String  | Filing status                  |
| valid                  | Boolean | Validity                       |
| is\_filed\_through\_ct | String  | If it's filed through ClearTax |


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.cleartax.in/cleartax-docs/gst-api-1/gst-api-reference/taxpayer-information.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.