(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

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

ParameterData TypeField ValidationsDescription

x-cleartax-auth-token

String

Cannot be empty.

Mandatory. User auth token.

tan

String

Cannot be empty

Mandatory. TAN of the taxpayer registered on CFC.

Content-Type

String

application/json

Request Path Params

ParameterData TypeField ValidationsDescription

templateType

String

Enum:

TDS

This will always be โ€œTDSโ€.

Request Query Params

There are no query parameters for this API.

Request Body

ParameterData TypeField ValidationDescription

userInputArgs

Object

NA

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

ParameterData TypeField ValidationDescription

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

ParameterData TypeField ValidationDescription

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

ParameterData TypeField ConstraintsDescription

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

ParameterData TypeField ConstraintsDescription

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

ParameterData TypeField ConstraintsDescription

recordIndex

Number

NA

Array index of the record in request jsonRecords. The index starts from 0.

recordErrors

Array

NA

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

ParameterData TypeField ConstraintsDescription

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

ParameterData TypeField ConstraintsDescription

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

HTTP Status CodeDescription

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

{
  "userInputArgs": {
    "templateId": "618a5623836651c01c1498ad",
    "metadata": {
      "financialYear": "2022",
      "quarter": "Q1",
      "formType": "Form26Q"
    }
  },
  "jsonRecords": [
    {
      "transactionId": "dc1e002c-d362-4d87-a8fb-6bf81af27370",
      "deducteePan": "ASDPF1234R",
      "deducteeName": "Kumar",
      "deducteeRefNumber": "0000012345",
      "sectionCode": "94C",
      "totalCreditedAmount": "100000",
      "creditDate": "12/08/2023",
      "deductionDate": "12/08/2023",
      "tdsAmount": "10000",
      "surchargeAmount": "1000",
      "educationCessAmount": "100",
      "totalTaxDepositedAmount": "111100",
      "lowerDeductionReason": "A",
      "certificateNumberUs197": "QWERTY2345",
      "cashWidthdrawnExcessOf1Cr194N": null,
      "cashWithdrawExcess20LAndLess1Cr194N": null,
      "cashWidthdrawnExcessOf1Cr194nNF": null,
      "externalId": "eb1e002c-d362-4d87-a8fb-6bf81af27370"
    }
  ]
}

Sample Response

Success - HTTP Status Code - 200

{
  "tanStats": [
    {
      "tan": "TANPF1234R",
      "totalDocumentCount": 1,
      "validRows": 1,
      "invalidRows": 0
    }
  ],
  "jsonRecordErrors": [...],
  "errors": null
}

Validation Error - HTTP Status Code - 200

{
  "tanStats": [
    {
      "tan": "TANPF1234R",
      "totalDocumentCount": 0,
      "validRows": 0,
      "invalidRows": 1
    }
  ],
  "jsonRecordErrors": [
    {
      "recordIndex": 0,
      "externalId": "eb1e002c-d362-4d87-a8fb-6bf81af27370",
      "recordErrors": [
        {
          "errorId": "SECTION_CODE_ERROR",
          "columnName": ["sectionCode"],
          "errorMessage": "1234 is not a valid section code."
        }
      ]
    }
  ],
  "errors": null
}

Non-Validation Error - HTTP Status Code - 401

{
  "tanStats": [],
  "jsonRecordErrors": [],
  "errors": [
    {
      "errorCode": "AUTHORIZATION_FAILED",
      "errorMessage": "Invalid Auth Token",
      "errorField": null,
      "errorValues": null,
      "errorResolution": null
    }
  ]
}

Non-Validation Error - HTTP Status Code - 500

{
  "tanStats": [],
  "jsonRecordErrors": [],
  "errors": [
    {
      "errorCode": "INTERNAL_ERROR",
      "errorMessage": "Internal Service Error",
      "errorField": null,
      "errorValues": null,
      "errorResolution": null
    }
  ]
}

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.

Last updated