Ingest Documents via JSON

Upload a sale or purchase document with JSON payload.
A maximum of 100 invoice line item objects can be ingested in one request.
Request Method
POST
Request URL
{{BASE_URL}}/integration/v2/ingest/json/{{templateType}}
Replace the {{BASE_URL}} with the one mentioned here based on whether you are using sandbox or production.
Request Headers
Parameter
Data Type
Field Validations
Description
x-cleartax-auth-token
String
Cannot be empty.
Mandatory. User auth token.
x-cleartax-gstin
String
Cannot be empty
Mandatory. GSTIN of the taxpayer registered on CFC.
Content-Type
String
​
application/json
Request Path Params
Parameter
Data Type
Field Validations
Description
templateType
String
Enum: 
sales,
purchase
Type of document. sales - Sales document.
purchase- Purchase document.
​
Request Query Params
There are no query parameters for this API.
Request Body
Parameter
Data Type
Field Validation
Description
userInputArgs
String
NA
Mandatory. User Input Arguments Object.
jsonRecords
Array
MaxLength: 100
Mandatory. An array of Sale Document Line Objects or Purchase Document Line Objects based on templateType used in the path param.
User Input Arguments Object
Parameter
Data Type
Field Validation
Description
templateId
String
NA
Mandatory. For a sale document, the system template ID is "618a5623836651c01c1498ad". For a purchase document, the system template ID is "60e5613ff71f4a7aeca4336b". For custom upload templates, use the custom upload template ID.
groupId
String
NA
Unique ID across the PAN to group a set of documents as a single record on the Clear Import History page.
Default: Autogenerated random ID.
settings
Object
NA
Optional. Settings Object.
Settings Object
Parameter
Data Type
Field Validation
Description
ignoreHsnValidation
Boolean
NA
Optional. Indicates if HSN validation has to be ignored or not. 
true - HSN validation error will be ignored.
false - HSN validation error will not be ignored.
Default: false
Sample Request
Sales document
1
{
2
    "userInputArgs": {
3
        "templateId": "618a5623836651c01c1498ad", 
4
        "groupId": "TEST123",
5
        "settings": {
6
            "ignoreHsnValidation": true
7
        }
8
    }, 
9
    "jsonRecords": [
10
        {
11
            "documentType": "Invoice", 
12
            "documentDate": "2022-11-29", 
13
            "documentNumber": "Inv-123", 
14
            
15
            "erpSource": "Tally", 
16
            "voucherNumber": "Inv-123", 
17
            "voucherDate": "2022-11-29", 
18
            
19
            "isBillOfSupply": "N", 
20
            "isReverseCharge": "N", 
21
            "isDocumentCancelled": "N", 
22
​
23
            "supplierName": "Defmacro Software Private Limited", 
24
            "supplierGstin": "29AAFCD5862R1ZR", 
25
​
26
            "customerName": "Clearsharp Technology Private Limited", 
27
            "customerAddress": "Cust1 Mst Addr1, Cust1 Mst Addr2, Cust1 Mst Addr3", 
28
            "customerState": "Karnataka", 
29
            "customerGstin": "29AAECC3822D1ZY", 
30
            "placeOfSupply": "Karnataka", 
31
​
32
            "itemDescription": "Item1", 
33
            "itemCategory": "G", 
34
            "hsnSacCode": "48", 
35
            "itemQuantity": 500, 
36
            "itemUnitCode": "PCS", 
37
            "itemUnitPrice": 250, 
38
            "itemDiscount": 0, 
39
            "itemTaxableAmount": 125000, 
40
            "cgstRate": 9, 
41
            "cgstAmount": 11250, 
42
            "sgstRate": 9, 
43
            "sgstAmount": 11250, 
44
            "igstRate": 0, 
45
            "igstAmount": 0, 
46
            "cessRate": 0, 
47
            "cessAmount": 0, 
48
​
49
            "documentTotalAmount": 147500
50
        }
51
    ]
52
}
Purchase document
1
{
2
    "userInputArgs": {
3
        "templateId": "60e5613ff71f4a7aeca4336b", 
4
        "settings": {
5
            "ignoreHsnValidation": true
6
        }
7
    }, 
8
    "jsonRecords": [
9
        {
10
            "documentType": "Invoice", 
11
            "documentDate": "2022-11-29", 
12
            "documentNumber": "Inv-123", 
13
            
14
            "erpSource": "Tally", 
15
            "voucherNumber": "Inv-123", 
16
            "voucherDate": "2022-11-29", 
17
            
18
            "isBillOfSupply": "N", 
19
            "isReverseCharge": "N", 
20
            "isDocumentCancelled": "N", 
21
​
22
            "supplierGstin": "29AAECC3822D1ZY", 
23
            "supplierName": "Clearsharp Technology Private Limited", 
24
            "supplierAddress": "Cust1 Mst Addr1, Cust1 Mst Addr2, Cust1 Mst Addr3", 
25
            "supplierState": "Karnataka", 
26
            
27
            "customerGstin": "29AAFCD5862R1ZR", 
28
​
29
            "placeOfSupply": "Karnataka", 
30
​
31
            "itemDescription": "Item1", 
32
            "itemCategory": "G", 
33
            "hsnSacCode": "48", 
34
            "itemQuantity": 500, 
35
            "itemUnitCode": "PCS", 
36
            "itemUnitPrice": 250, 
37
            "itemDiscount": 0, 
38
            "itemTaxableAmount": 125000, 
39
            "cgstRate": 9, 
40
            "cgstAmount": 11250, 
41
            "sgstRate": 9, 
42
            "sgstAmount": 11250, 
43
            "igstRate": 0, 
44
            "igstAmount": 0, 
45
            "cessRate": 0, 
46
            "cessAmount": 0, 
47
​
48
            "documentTotalAmount": 147500
49
        }
50
    ]
51
}
Response Status Codes
HTTP Status Code
Description
200
For a successfully processed request (may be a success or validation error).
400
If the request schema is not valid.
401
If the user is not authenticated for the operation.
403
If the user is not authorized for the operation.
500
If there are any unhandled exceptions on Clear side.
Response Schema
Parameter
Data Type
Field Constraints
Description
gstinStats
Array
NA
Upload statistics aggregated at the GSTIN level. An array of GSTIN stats object. In case of non-validation errors, this will be an empty Array ([]).
jsonRecordErrors
Array
NA
Validation Errors. An array of JSON record error details objects. In case there are no errors, this will be an empty Array ([]).
errors
Array
NA
Non-Validation Errors. An array of non-validation error details objects. In case there are no errors, this will be an empty Array ([]).
GSTIN Stats Object
Parameter
Data Type
Field Constraints
Description
gstin
String
NA
Seller GSTIN that these stats belong to.
totalDocumentCount
Number
NA
Total count of documents parsed successfully.
validRows
Number
NA
Total count of valid document line objects.
invalidRows
Number
NA
Total count of invalid document line objects.
JSON Record Error Details Object
Parameter
Data Type
Field Constraints
Description
recordIndex
Number
NA
Array index of the record in request jsonRecords. The index starts from 0.
recordErrors
Array
NA
Array of record error details objects.
externalId
String
NA
External ID that was sent in the request to identify the document, if any. In case an external ID was not sent, this field will not exist.
externalLineItemId
String
NA
External ID that was sent in the request to identify the document line item, if any. In case an external ID was not sent, this field will not exist.
Record Error Details Object
Parameter
Data Type
Field Constraints
Description
errorId
String
NA
Error ID
columnName
Array
NA
Array of strings representing field keys in the jsonRecords of the request that has an error.
errorMessage
String
NA
User friendly error message.
Non-Validation Error Details Object
Parameter
Data Type
Field Constraints
Description
errorCode
String
NA
Error code
errorMessage
String
NA
Error message.
errorField
​
NA
Error field.
errorValues
​
NA
Error values.
errorResolution
​
NA
Error resolution.
Sample Response
Success - HTTP Status Code - 200
1
{
2
  "gstinStats": [
3
    {
4
      "gstin": "29AAFCD5862R1ZR",
5
      "totalDocumentCount": 1,
6
      "validRows": 1,
7
      "invalidRows": 0
8
    }
9
  ],
10
  "jsonRecordErrors": [...],
11
  "errors": null
12
}
Validation Error - HTTP Status Code - 200
1
{
2
  "gstinStats": [
3
    {
4
      "gstin": "29AAFCD5862R1ZR",
5
      "totalDocumentCount": 0,
6
      "validRows": 0,
7
      "invalidRows": 1
8
    }
9
  ],
10
  "jsonRecordErrors": [
11
    {
12
      "recordIndex": 0,
13
      "externalId": "INVOICE_maxitc123_06ADECO9084R5Z4_29AAFCD5862R000_2022_0",
14
      "externalLineItemId": "INVOICE_maxitc123_06ADECO9084R5Z4_29AAFCD5862R000_2022_0",
15
      "recordErrors": [
16
        {
17
          "errorId": "HSN_OR_SAC_TYPE_ERROR",
18
          "columnName": ["hsnSacCode"],
19
          "errorMessage": "1234 is not a valid HSN "
20
        }
21
      ]
22
    }
23
  ],
24
  "errors": null
25
}
Non-Validation Error - HTTP Status Code - 401
1
{
2
  "gstinStats": [],
3
  "jsonRecordErrors": [],
4
  "errors": [
5
    {
6
      "errorCode": "AUTHORIZATION_FAILED",
7
      "errorMessage": "Invalid Auth Token",
8
      "errorField": null,
9
      "errorValues": null,
10
      "errorResolution": null
11
    }
12
  ]
13
}
Non-Validation Error - HTTP Status Code - 500
1
{
2
  "gstinStats": [],
3
  "jsonRecordErrors": [],
4
  "errors": [
5
    {
6
      "errorCode": "INTERNAL_ERROR",
7
      "errorMessage": "Internal Service Error",
8
      "errorField": null,
9
      "errorValues": null,
10
      "errorResolution": null
11
    }
12
  ]
13
}
API Validations
There are more than 200 field validations as well as business validations on the Clear API side. For data validation errors, the validation error message will be sent back in the `jsonRecordErrors` field in the response.
API Constraints
1.This API needs to be authenticated with a valid user authentication token. If the auth token is not present or is invalid, the API will return HTTP Status Code 401.
2.If the auth token is valid, but the user does not have the authorization, then the API will return HTTP Status Code 403. The user, whose auth token is used, should have permission to create a document.
Integrating for MaxITC?
If you are integrating with Max ITC, once the documents are uploaded, trigger the reconciliation using the Trigger MaxITC Workflow API.

Parameter	Data Type	Field Validations	Description
x-cleartax-auth-token	String	Cannot be empty.	Mandatory. User auth token.
x-cleartax-gstin	String	Cannot be empty	Mandatory. GSTIN of the taxpayer registered on CFC.
Content-Type	String		application/json

Parameter	Data Type	Field Validations	Description
templateType	String	Enum: sales, purchase	Type of document. sales - Sales document. purchase- Purchase document.

Parameter	Data Type	Field Validation	Description
userInputArgs	String	NA	Mandatory. User Input Arguments Object.
jsonRecords	Array	MaxLength: 100	Mandatory. An array of Sale Document Line Objects or Purchase Document Line Objects based on `templateType` used in the path param.

Parameter	Data Type	Field Validation	Description
templateId	String	NA	Mandatory. For a sale document, the system template ID is "618a5623836651c01c1498ad". For a purchase document, the system template ID is "60e5613ff71f4a7aeca4336b". For custom upload templates, use the custom upload template ID.
groupId	String	NA	Unique ID across the PAN to group a set of documents as a single record on the Clear Import History page. Default: Autogenerated random ID.
settings	Object	NA	Optional. Settings Object.

Parameter	Data Type	Field Validation	Description
ignoreHsnValidation	Boolean	NA	Optional. Indicates if HSN validation has to be ignored or not. true - HSN validation error will be ignored. false - HSN validation error will not be ignored. Default: false

HTTP Status Code	Description
200	For a successfully processed request (may be a success or validation error).
400	If the request schema is not valid.
401	If the user is not authenticated for the operation.
403	If the user is not authorized for the operation.
500	If there are any unhandled exceptions on Clear side.

Parameter	Data Type	Field Constraints	Description
gstinStats	Array	NA	Upload statistics aggregated at the GSTIN level. An array of GSTIN stats object. In case of non-validation errors, this will be an empty Array ([]).
jsonRecordErrors	Array	NA	Validation Errors. An array of JSON record error details objects. In case there are no errors, this will be an empty Array ([]).
errors	Array	NA	Non-Validation Errors. An array of non-validation error details objects. In case there are no errors, this will be an empty Array ([]).

Parameter	Data Type	Field Constraints	Description
gstin	String	NA	Seller GSTIN that these stats belong to.
totalDocumentCount	Number	NA	Total count of documents parsed successfully.
validRows	Number	NA	Total count of valid document line objects.
invalidRows	Number	NA	Total count of invalid document line objects.

Parameter	Data Type	Field Constraints	Description
recordIndex	Number	NA	Array index of the record in request jsonRecords. The index starts from 0.
recordErrors	Array	NA	Array of record error details objects.
externalId	String	NA	External ID that was sent in the request to identify the document, if any. In case an external ID was not sent, this field will not exist.
externalLineItemId	String	NA	External ID that was sent in the request to identify the document line item, if any. In case an external ID was not sent, this field will not exist.

Parameter	Data Type	Field Constraints	Description
errorId	String	NA	Error ID
columnName	Array	NA	Array of strings representing field keys in the jsonRecords of the request that has an error.
errorMessage	String	NA	User friendly error message.

Parameter	Data Type	Field Constraints	Description
errorCode	String	NA	Error code
errorMessage	String	NA	Error message.
errorField		NA	Error field.
errorValues		NA	Error values.
errorResolution		NA	Error resolution.

Last modified 23h ago