# 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 |