(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 GST 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.

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.
1
X-Cleartax-Auth-Token: <USER_AUTH_TOKEN>
2
Content-Type: multipart/form-data
3
Accept: application/json
Copied!
URL query string:
1
https://gst.cleartax.in/api/v0.2/taxable_entities/{{TAXABLE_ENTITY_ID}}/transactions/upload?data_type={{DATA_TYPE}}&custom_mapper_id={{CUSTOM_MAPPER_ID}}
Copied!
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:
1
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
Copied!
Sample Response:
1
{
2
"activity_id": "a2fe6607-b9ed-4e5c-9c19-9fbd951c0cb5",
3
"error_response": null,
4
"group_id": null,
5
"other_activity_ids": null,
6
"status": "UPLOADED",
7
"queued_count": 1
8
}
Copied!

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.
1
X-Cleartax-Auth-Token: <USER_AUTH_TOKEN>
2
Content-Type: multipart/form-data
3
Accept: application/json
Copied!
URL query string for Government template:
1
https://gst.cleartax.in/api/v0.2/taxable_entities/{{TAXABLE_ENTITY_ID}}/transactions/upload?data_type={{DATA_TYPE}}&vendor_type={{VENDOR_TYPE}}
Copied!
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:
1
https://gst.cleartax.in/api/v0.2/taxable_entities/a4d61a08-64d8-404d-b375-14d8c466771e/transactions/upload?data_type=GSTR1_INVOICE&vendor_type=GOVT_GSTR1_B2B_V1_2
Copied!
Sample Response:
200
1
{
2
"activity_id": "a2fe6607-b9ed-4e5c-9c19-9fbd951c0cb5",
3
"error_response": null,
4
"group_id": null,
5
"other_activity_ids": null,
6
"status": "UPLOADED",
7
"queued_count": 1
8
}
Copied!

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.
1
X-Cleartax-Auth-Token: <USER_AUTH_TOKEN>
Copied!
URL query string:
1
https://gst.cleartax.in/api/v0.2/taxable_entities/{{TAXABLE_ENTITY_ID}}/upload_activity/{{ACTIVITY_ID}}/status
Copied!
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:
1
https://gst.cleartax.in/api/v0.2/taxable_entities/a4d61a08-64d8-404d-b375-14d8c466771e/upload_activity/a2fe6607-b9ed-4e5c-9c19-9fbd951c0cb5/status
Copied!
Sample Response:
1
{
2
"activityId": "a2fe6607-b9ed-4e5c-9c19-9fbd951c0cb5",
3
"status": "PROCESSED",
4
"errorMessage": null,
5
"queuedCount": 0,
6
"hasHeaderError": false,
7
"headerStatus": "SUCCESS"
8
}
Copied!
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.
1
X-Cleartax-Auth-Token: <USER_AUTH_TOKEN>
Copied!
URL query string:
1
https://gst.cleartax.in/api/v0.2/taxable_entities/<TAXABLE_ENTITY_ID>/upload_activity/<ACTIVITY_ID>
Copied!
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:
1
https://gst.cleartax.in/api/v0.2/taxable_entities/a4d61a08-64d8-404d-b375-14d8c466771e/upload_activity/a2fe6607-b9ed-4e5c-9c19-9fbd951c0cb5
Copied!
Sample Response:
1
{
2
"activity_id": "a2fe6607-b9ed-4e5c-9c19-9fbd951c0cb5",
3
"status": "PROCESSED",
4
"total_rows_processed": 1,
5
"valid_invoice_summary": {
6
"totalInvoices": 1,
7
"totalValue": null,
8
"totalTax": null
9
},
10
"invalid_invoice_summary": {
11
"totalInvoices": 0,
12
"totalValue": null,
13
"totalTax": null
14
},
15
"error_messages": [],
16
"warning_messages": [],
17
...
18
}
Copied!
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.
1
X-Cleartax-Auth-Token: <USER_AUTH_TOKEN>
Copied!
URL query string:
1
https://gst.cleartax.in/api/v0.1/business/{{BUSINESS_ID}}/upload_activity
Copied!
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:
1
https://gst.cleartax.in/api/v0.1/business/4657-e4a629ee-056954c4f3fb0123-b104/upload_activity
Copied!
Sample Response:
1
[
2
​ ​ ​{
3
​ ​ ​ ​ ​"activity_id":​ ​Excel​ ​Upload​ ​Activity​ ​ID,
4
​ ​ ​ ​ ​"owner_taxable_entity_id":​ ​Taxable​ ​Entity​ ​ID,
5
​ ​ ​ ​ ​"owner_gstin":​ ​Taxable​ ​Entity​ ​GSTIN,​ ​for​ ​which​ ​file​ ​was​ ​uploaded,
6
​ ​ ​ ​ ​"owner_taxable_entity_name":​ ​Taxable​ ​Entity​ ​Name​ ​in​ ​Cleartax,
7
​ ​ ​ ​ ​"status":​ ​Status​ ​of​ ​the​ ​file​ ​(​QUEUED​,​PROCESSING​,​PROCESSED​,​ABORTED)​,
8
​ ​ ​ ​ ​"total_rows_processed":​ ​Number​ ​of​ ​rows​ ​processed,
9
​ ​ ​ ​ ​"valid_invoice_summary":​ ​{
10
​ ​ ​ ​ ​ ​ ​"totalInvoices":​ ​Number​ ​of​ ​valid​ ​invoices​ ​created,
11
​ ​ ​ ​ ​ ​ ​"totalValue":​ ​Total​ ​Invoice​ ​value​ ​of​ ​created​ ​invoices,
12
​ ​ ​ ​ ​ ​ ​"totalTax":​ ​Total​ ​tax​ ​value​ ​of​ ​created​ ​invoices,
13
​ ​ ​ ​ ​},
14
​ ​ ​ ​ ​​"invalid_invoice_summary":​ {
15
​ ​ ​ ​ ​ ​ ​"totalInvoices":​ ​Number​ ​of​ ​failed​ ​invoices
16
​ ​ ​ ​ ​},
17
​ ​ ​ ​ ​"upload_data_type":​ ​Type​ ​of​ ​data,
18
​ ​ ​ ​ ​"created_at":​ ​Activity​ ​created​ ​datetime,
19
​ ​ ​ ​ ​"excel_processing_exception":​ ​Reason​ ​for​ ​aborts,​ ​if​ ​unknown​ ​exception​ ​happens,
20
​ ​ ​ ​ ​"file_name":​ ​Attached​ ​file​ ​name​ ​for​ ​activity
21
​ ​ ​ ​},
22
...
23
]
Copied!
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 modified 9mo ago