(Deprecated) Ingest Deductions via JSON
This API is deprecated and no more supported due to scaling issues.
Upload a deduction for TDS filing with JSON payload. The same API works for 24Q, 26Q, 27Q and 27EQ. Currently we support only 26Q.
A maximum of 100 deduction line item objects can be ingested in one request.
Request Method
POST
Request URL
Replace the {{BASE_URL}}
with the one mentioned here based on whether you are using sandbox or production.
Request Headers
tan
String
Cannot be empty
Mandatory. TAN of the taxpayer registered on CFC.
Content-Type
String
application/json
Request Path Params
templateType
String
Enum:
TDS
This will always be “TDS”.
Request Query Params
There are no query parameters for this API.
Request Body
jsonRecords
Array
MaxLength: 100
Mandatory. An array of Deduction objects based on templateType
used in the path param and the formType
used in UserInputArgs.
User Input Arguments Object
templateId
String
NA
Mandatory. The template ID will be different for each TDS form. For a “Form26Q” deduction document, the system template ID is "62de5622813e5b2d2d2a2f90". For now, we do not support custom template.
metadata
Object
NA
Mandatory. Metadata of the records to be uploaded.
groupId
String
NA
Optional. Unique ID across the TAN to group a set of documents as a single record on the Clear Import History page.
Default: Autogenerated random ID.
Metadata Object
financialYear
String
YYYY
Mandatory. The starting year of the financial year for which the records are to be uploaded. If the financial year is 2023-24, then this will be “2023”. Even if the financial quarter is “Q4”, in this case, the financial year will be “2023” only.
financialQuarter
String
Enum: Q1, Q2, Q3, Q4
Mandatory. The financial quarter for which the records are to be uploaded.
Q1 - Apr to Jun Q2 - Jul to Sep Q3 - Oct to Dec Q4 - Jan to Mar
formType
String
Enum: Form24Q, Form26Q, Form27Q, Form27EQ
Mandatory. Form type for filing TDS returns.
Form24Q - Salary Form26Q - Non salary domestic Form27Q - Non salary foreign Form27EQ - TCS (Tax collection at source)
Response Schema
tanStats
Array
NA
Upload statistics aggregated at the TAN level. An array of TAN 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 ([]).
TAN Stats Object
tan
String
NA
Deductor TAN 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
recordIndex
Number
NA
Array index of the record in request jsonRecords. The index starts from 0.
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.
Record Error Details Object
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
errorCode
String
NA
Error code
errorMessage
String
NA
Error message.
errorField
NA
Error field.
errorValues
NA
Error values.
errorResolution
NA
Error resolution.
Response Status Codes
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.
Sample Request
Deduction document
Sample Response
Success - HTTP Status Code - 200
Validation Error - HTTP Status Code - 200
Non-Validation Error - HTTP Status Code - 401
Non-Validation Error - HTTP Status Code - 500
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
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.
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.
Last updated