(Deprecated) GST File Upload API Reference

IMPORTANT NOTICE

GST File Upload API is deprecated and will not be supported after 31-12-2020. If you want to integrate with ClearTax GST, please use JSON APIs instead.

Introduction

The File Upload API gives you the ability to upload your documents to ClearTax GST with staged validation checks.

Types of documents supported

With this API, you will be able to upload following types of documents from your local file system in CSV or Excel format:

  1. Sales Invoices or Outward Bills of Supply

  2. Purchase Invoices or Inward Bills of Supply

  3. Advance Receipts

  4. Advance Payments

  5. Outward Credit Debit Notes

  6. Inward Credit Debit Notes

Why File Upload API?

Using this API gets your documents staged in ClearTax database, removing the overhead of correcting validation errors at the time of sending the documents. This lets business user send documents faster and in more efficient manner. Once a file containing documents is uploaded, the File Upload API will return an activity_id that can be used for future requests to check upload status and validation errors.

Steps to upload a document

File Upload API is a set of requests that allow you to upload documents to ClearTax GST in CSV or Excel format in 3 easy steps:

  1. Upload the file with a POST request.

  2. Once uploaded, these files will be processed asynchronously and you can get the processing status with a subsequent GET request.

  3. Once the processing status is changed to PROCESSED, you can get the validation details with a subsequent GET request.

All requests require the user authentication token in the request headers. To learn more about how to generate user authentication token, click the below link.

(Deprecated) How to authenticate API requests?

Uploading a document

The request for uploading a document is slightly different for ClearTax template and Government template. In case of ClearTax Template, you will need to send custom_mapper_id whereas in case of Government Template, you will need to send vendor_type.

Uploading a document in ClearTax Template

The file containing documents in ClearTax Template, e-commerce template or custom template is sent by submitting a POST request to the Upload File API with the following request headers.

X-Cleartax-Auth-Token: <USER_AUTH_TOKEN>
Content-Type: multipart/form-data
Accept: application/json

URL query string:

https://api.clear.in/gst/api/v0.2/taxable_entities/{{TAXABLE_ENTITY_ID}}/transactions/upload?data_type={{DATA_TYPE}}&custom_mapper_id={{CUSTOM_MAPPER_ID}}

Request Parameters:

Parameter

Parameter type

Type

Description

custom_mapper_id

Query

String

Required. Cannot be sent with vendor_type. For supported types and more information, see below.

data_type

Query

String

Required. This is the identifier for the base document type. For supported types and more information, see below.

delimiter

Query

String

Optional. This is the character that separates values. Defaults to , (comma).

excelFile

formData

File

Required. This is the file in CSV or Excel format. In case of Excel, only the first sheet will be processed.

return_period

Query

String

Required. This is the return period of the documents in the file. Format MMYYYY. Eg: 082018 for August 2018

taxable_entity_id

Path

String

Required. This is the unique ID associated with the GSTIN in your account.

Supported values for parameters:

Template name

data_type

custom_mapper_id

Sales Invoice and Outward Bill of Supply

GSTR1_INVOICE

9b34f966-d78d-40a1-90c2-6acb1e1fcf42

Outward Credit Debit Note

GSTR1_CDN

44271028-4b8f-4228-9f99-9398ea5680ae

Advance Receipts

GSTR1_ADVANCE_PAYMENT

62f6f212-9d5e-44b4-8a7f-35ab0b765f38

Purchase Invoice and Inward Bill of Supply

GSTR2_PURCHASE_INVOICE

d541c80e-906e-49ed-9ee2-46c1d5497c4b

Inward Credit Debit Note

GSTR2_CDN

db48eb86-4e80-4814-894b-efe721ca789c

Advance Payments

GSTR2_ADVANCE_PAYMENT

fd2e71b9-94cc-48fb-a772-7a81fea46f27

Sample Request:

https://gst.cleartax.in/api/v0.2/taxable_entities/a4d61a08-64d8-404d-b375-14d8c466771e/transactions/upload?data_type=GSTR2_PURCHASE_INVOICE&custom_mapper_id=d541c80e-906e-49ed-9ee2-46c1d5497c4b&return_period=012019

Sample Response:

{
    "activity_id": "a2fe6607-b9ed-4e5c-9c19-9fbd951c0cb5",
    "error_response": null,
    "group_id": null,
    "other_activity_ids": null,
    "status": "UPLOADED",
    "queued_count": 1
}

Uploading a document in Government Template

The file containing documents in Government template is sent by submitting a POST request to the Upload File API with the following request headers.

X-Cleartax-Auth-Token: <USER_AUTH_TOKEN>
Content-Type: multipart/form-data
Accept: application/json

URL query string for Government template:

https://api.clear.in/gst/api/v0.2/taxable_entities/{{TAXABLE_ENTITY_ID}}/transactions/upload?data_type={{DATA_TYPE}}&vendor_type={{VENDOR_TYPE}}

Request Parameters:

Parameter

Parameter type

Type

Description

data_type

Query

String

Required. This is the identifier for the base document type. For supported types and more information, see below.

delimiter

Query

String

Optional. This is the character that separates values. Defaults to , (comma).

excelFile

formData

File

Required. This is the file in CSV or Excel format. In case of Excel, only the first sheet will be processed.

return_period

Query

String

Required. This is the return period of the documents in the file. Format MMYYYY. Eg: 082018 for August 2018

taxable_entity_id

Path

String

Required. This is the unique ID associated with the GSTIN in your account.

vendor_type

Query

String

Required. Cannot be sent with custom_mapper_id. For supported types and more information, see below.

Supported values for parameters:

Return

Sheet

data_type

vendor_type

GSTR1

B2B

GSTR1_INVOICE

GOVT_GSTR1_B2B_V1_2

GSTR1

B2CL

GSTR1_INVOICE

GOVT_GSTR1_B2CL_V1_2

GSTR1

B2CS

GSTR1_B2CS_AGG

GOVT_GSTR1_B2CS_V1_2

GSTR1

EXP

GSTR1_INVOICE

GOVT_GSTR1_EXP_V1_2

GSTR1

CDNR

GSTR1_CDN

GOVT_GSTR1_CDNR_V1_2

GSTR1

CDNUR

GSTR1_CDN

GOVT_GSTR1_CDNUR_V1_2

GSTR1

AT

GSTR1_ADVANCE_AGG

GOVT_GSTR1_AT_V1_2

GSTR1

ATADJ

GSTR1_ADVANCE_ADJ_AGG

GOVT_GSTR1_ATADJ_V1_2

GSTR1

EXEMP

GSTR1_EXEMPTION_AGG

GOVT_GSTR1_EXEMP_V1_2

GSTR1

HSN

GSTR1_HSN_AGG

GOVT_GSTR1_HSN_V1_2

GSTR1

DOC

GSTR1_DOCS_AGG

GOVT_GSTR1_DOCS_V1_2

GSTR2

B2B

GSTR2_PURCHASE_INVOICE

GOVT_GSTR2_B2B_V1_0

GSTR2

B2CL

GSTR2_PURCHASE_INVOICE

GOVT_GSTR2_B2BUR_V1_0

GSTR2

IMPS

GSTR2_PURCHASE_INVOICE

GOVT_GSTR2_IMPS_V1_0

GSTR2

IMPG

GSTR2_PURCHASE_INVOICE

GOVT_GSTR2_IMPG_V1_0

GSTR2

CDNR

GSTR2_CDN

GOVT_GSTR2_CDNR_V1_0

GSTR2

CDNUR

GSTR2_CDN

GOVT_GSTR2_CDNUR_V1_0

GSTR2

AT

GSTR2_ADVANCE_AGG

GOVT_GSTR2_AT_V1_0

GSTR2

ATADJ

GSTR2_ADVANCE_ADJ_AGG

GOVT_GSTR2_ATADJ_V1_0

GSTR2

HSN

GSTR2_HSN_AGG

GOVT_GSTR2_HSNSUM_V1_0

GSTR2

EXEMP

GSTR2_EXEMPTION_AGG

GOVT_GSTR2_EXEMP_V1_0

GSTR2

ITCR

GSTR2_ITCR_AGG

GOVT_GSTR2_ITCR_V1_0

GSTR3B

GSTR-3B

GSTR3B_GOVT

GSTR4

4B(B2B)

GSTR2_PURCHASE_INVOICE

GOVT_GSTR4_B2B_V1_0

GSTR4

4C(B2BUR)

GSTR2_PURCHASE_INVOICE

GOVT_GSTR4_B2BUR_V1_0

GSTR4

4D(IMPS)

GSTR2_PURCHASE_INVOICE

GOVT_GSTR4_IMPS_V1_0

GSTR4

5B(CDNR)

GSTR2_PURCHASE_INVOICE

GOVT_GSTR4_CDNR_V1_0

GSTR4

5B(CDNUR)

GSTR2_PURCHASE_INVOICE

GOVT_GSTR4_CDNUR_V1_0

GSTR4

6(TXOS)

GSTR2_PURCHASE_INVOICE

GOVT_GSTR4_TXOS_V1_0

GSTR4

8A(AT)

GSTR2_PURCHASE_INVOICE

GOVT_GSTR4_AT_V1_0

GSTR4

8B(ATADJ)

GSTR2_PURCHASE_INVOICE

GOVT_GSTR4_ATADJ_V1_0

Sample Request:

https://api.clear.in/gst/api/v0.2/taxable_entities/a4d61a08-64d8-404d-b375-14d8c466771e/transactions/upload?data_type=GSTR1_INVOICE&vendor_type=GOVT_GSTR1_B2B_V1_2

Sample Response:

200
{
    "activity_id": "a2fe6607-b9ed-4e5c-9c19-9fbd951c0cb5",
    "error_response": null,
    "group_id": null,
    "other_activity_ids": null,
    "status": "UPLOADED",
    "queued_count": 1
}

Getting upload status

You can get the status of an upload activity by submitting a GET request to the Upload File API with following request headers.

X-Cleartax-Auth-Token: <USER_AUTH_TOKEN>

URL query string:

https://api.clear.in/gst/api/v0.2/taxable_entities/{{TAXABLE_ENTITY_ID}}/upload_activity/{{ACTIVITY_ID}}/status

Request Parameters:

Parameters

Parameter Type

Type

Description

taxable_entity_id

Path

String

Required. This is the unique ID associated with the GSTIN in your account.

activity_id

Path

String

Required. This is the activity ID received in response to the Upload API.

Sample Request:

https://api.clear.in/gst/api/v0.2/taxable_entities/a4d61a08-64d8-404d-b375-14d8c466771e/upload_activity/a2fe6607-b9ed-4e5c-9c19-9fbd951c0cb5/status

Sample Response:

{
    "activityId": "a2fe6607-b9ed-4e5c-9c19-9fbd951c0cb5",
    "status": "PROCESSED",
    "errorMessage": null,
    "queuedCount": 0,
    "hasHeaderError": false,
    "headerStatus": "SUCCESS"
}

In the response, status can be either QUEUED, PROCESSING, ABORTED or PROCESSED.

Getting upload validation

If the upload activity status as seen above is PROCESSED, you can get the validation details of the upload activity by submitting a GET request to the Upload File API with following request headers.

X-Cleartax-Auth-Token: <USER_AUTH_TOKEN>

URL query string:

https://api.clear.in/gst/api/v0.2/taxable_entities/<TAXABLE_ENTITY_ID>/upload_activity/<ACTIVITY_ID>

Request Parameters:

Parameters

Parameter Type

Type

Description

taxable_entity_id

Path

String

Required. This is the unique ID associated with the GSTIN in your account.

activity_id

Path

String

Required. This is the activity ID received in response to the Upload API.

Sample Request:

https://api.clear.in/gst/api/v0.2/taxable_entities/a4d61a08-64d8-404d-b375-14d8c466771e/upload_activity/a2fe6607-b9ed-4e5c-9c19-9fbd951c0cb5

Sample Response:

{
    "activity_id": "a2fe6607-b9ed-4e5c-9c19-9fbd951c0cb5",
    "status": "PROCESSED",
    "total_rows_processed": 1,
    "valid_invoice_summary": {
        "totalInvoices": 1,
        "totalValue": null,
        "totalTax": null
    },
    "invalid_invoice_summary": {
        "totalInvoices": 0,
        "totalValue": null,
        "totalTax": null
    },
    "error_messages": [],
    "warning_messages": [],
    ...
}

Only the response fields relevant for integration are mentioned above. Actual response will have other fields which may not be relevant here.

Getting upload history

You can get the list of all upload activities by submitting a GET request to the Upload File API with following request headers.

X-Cleartax-Auth-Token: <USER_AUTH_TOKEN>

URL query string:

https://api.clear.in/gst/api/v0.1/business/{{BUSINESS_ID}}/upload_activity

Request Parameters:

Parameters

Parameter Type

Type

Description

business_id

Path

String

Required. This is the unique ID associated with the Business in your account.

For this particular endpoint, you need to use Business ID instead of Taxable Entity ID.

Sample Request:

https://api.clear.in/gst/api/v0.1/business/4657-e4a629ee-056954c4f3fb0123-b104/upload_activity

Sample Response:

[
​ ​ ​{
​ ​ ​ ​ ​"activity_id":​ ​Excel​ ​Upload​ ​Activity​ ​ID,
​ ​ ​ ​ ​"owner_taxable_entity_id":​ ​Taxable​ ​Entity​ ​ID,
​ ​ ​ ​ ​"owner_gstin":​ ​Taxable​ ​Entity​ ​GSTIN,​ ​for​ ​which​ ​file​ ​was​ ​uploaded,
​ ​ ​ ​ ​"owner_taxable_entity_name":​ ​Taxable​ ​Entity​ ​Name​ ​in​ ​Cleartax,
​ ​ ​ ​ ​"status":​ ​Status​ ​of​ ​the​ ​file​ ​(​QUEUED​,​PROCESSING​,​PROCESSED​,​ABORTED)​,
​ ​ ​ ​ ​"total_rows_processed":​ ​Number​ ​of​ ​rows​ ​processed,
​ ​ ​ ​ ​"valid_invoice_summary":​ ​{
​ ​ ​ ​ ​ ​ ​"totalInvoices":​ ​Number​ ​of​ ​valid​ ​invoices​ ​created,
​ ​ ​ ​ ​ ​ ​"totalValue":​ ​Total​ ​Invoice​ ​value​ ​of​ ​created​ ​invoices,
​ ​ ​ ​ ​ ​ ​"totalTax":​ ​Total​ ​tax​ ​value​ ​of​ ​created​ ​invoices,
​ ​ ​ ​ ​},
​ ​ ​ ​ ​​"invalid_invoice_summary":​ {
​ ​ ​ ​ ​ ​ ​"totalInvoices":​ ​Number​ ​of​ ​failed​ ​invoices
​ ​ ​ ​ ​},
​ ​ ​ ​ ​"upload_data_type":​ ​Type​ ​of​ ​data,
​ ​ ​ ​ ​"created_at":​ ​Activity​ ​created​ ​datetime,
​ ​ ​ ​ ​"excel_processing_exception":​ ​Reason​ ​for​ ​aborts,​ ​if​ ​unknown​ ​exception​ ​happens,
​ ​ ​ ​ ​"file_name":​ ​Attached​ ​file​ ​name​ ​for​ ​activity
​ ​ ​ ​},
...
]

Only the response fields relevant for integration are mentioned above. Actual response will have other fields which may not be relevant here.

Rate Limiting

Currently, there is no rate limit. You are requested to apply judicial discretion while using ClearTax APIs to ensure overall level of service on our API server for all users.

Best Practices

  1. Upload only 1 file at a time.

  2. Space out multiple requests evenly to reduce load on our server.

  3. Limit file size to 3 Mb to ensure faster processing and validation.

  4. While there is practically no limitation on the number of rows or documents per file, for the purpose of optimization, we have a maximum limit of 5000 line items per document in a file.

Last updated