# (Deprecated) Ingest Deductions via JSON

<mark style="color:red;">**This API is deprecated and no more supported due to scaling issues.**</mark>

Upload a deduction for TDS filing with JSON payload. The same API works for 24Q, 26Q, 27Q and 27EQ. Currently we support only 26Q.

{% hint style="warning" %}
A maximum of 100 deduction line item objects can be ingested in one request.
{% endhint %}

### Request Method

POST

### Request URL

```
{{BASE_URL}}/integration/v2/ingest/json/{{templateType}}
```

{% hint style="info" %}
Replace the `{{BASE_URL}}` with the one mentioned [here](https://docs.cleartax.in/cleartax-docs/clear-finance-cloud/cfc-api-reference) based on whether you are using sandbox or production.
{% endhint %}

### Request Headers

<table><thead><tr><th width="183">Parameter</th><th width="129">Data Type</th><th>Field Validations</th><th>Description</th></tr></thead><tbody><tr><td>x-cleartax-auth-token</td><td>String</td><td>Cannot be empty.</td><td>Mandatory. <a href="../../../../clear-finance-cloud/learn-clear-finance-cloud-basics/access-token">User auth token</a>.</td></tr><tr><td>tan</td><td>String</td><td>Cannot be empty</td><td>Mandatory. TAN of the taxpayer registered on CFC.</td></tr><tr><td>Content-Type</td><td>String</td><td></td><td>application/json</td></tr></tbody></table>

### Request Path Params

<table><thead><tr><th width="184">Parameter</th><th width="132">Data Type</th><th width="166">Field Validations</th><th>Description</th></tr></thead><tbody><tr><td>templateType</td><td>String</td><td><p>Enum: </p><p>TDS</p></td><td><p>This will always be “TDS”.</p><p></p></td></tr></tbody></table>

### Request Query Params

There are no query parameters for this API.

### Request Body

<table><thead><tr><th width="182">Parameter</th><th width="112.88562596599695">Data Type</th><th width="123">Field Validation</th><th>Description</th></tr></thead><tbody><tr><td>userInputArgs</td><td>Object</td><td>NA</td><td>Mandatory. <a href="#user-input-arguments-object">User Input Arguments Object</a>.</td></tr><tr><td>jsonRecords</td><td>Array</td><td>MaxLength: 100</td><td>Mandatory. An array of <a href="../../resources-and-masters/deduction-document-line-objects">Deduction objects</a> based on <code>templateType</code> used in the path param and the <code>formType</code> used in UserInputArgs.</td></tr></tbody></table>

#### User Input Arguments Object

<table><thead><tr><th width="163">Parameter</th><th width="129.88562596599695">Data Type</th><th width="130">Field Validation</th><th>Description</th></tr></thead><tbody><tr><td>templateId</td><td>String</td><td>NA</td><td>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.</td></tr><tr><td>metadata</td><td>Object</td><td>NA</td><td>Mandatory. Metadata of the records to be uploaded.</td></tr><tr><td>groupId</td><td>String</td><td>NA</td><td><p>Optional. Unique ID across the TAN to group a set of documents as a single record on the Clear Import History page.</p><p>Default: Autogenerated random ID.</p></td></tr></tbody></table>

#### Metadata Object

<table><thead><tr><th width="178">Parameter</th><th width="129.88562596599695">Data Type</th><th width="130">Field Validation</th><th>Description</th></tr></thead><tbody><tr><td>financialYear</td><td>String</td><td>YYYY</td><td>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.</td></tr><tr><td>financialQuarter</td><td>String</td><td>Enum: Q1, Q2, Q3, Q4</td><td><p>Mandatory. The financial quarter for which the records are to be uploaded.</p><p>Q1 - Apr to Jun Q2 - Jul to Sep Q3 - Oct to Dec Q4 - Jan to Mar</p></td></tr><tr><td>formType</td><td>String</td><td>Enum: Form24Q, Form26Q, Form27Q, Form27EQ</td><td><p>Mandatory. Form type for filing TDS returns.</p><p>Form24Q - Salary Form26Q - Non salary domestic Form27Q - Non salary foreign Form27EQ - TCS (Tax collection at source)</p></td></tr></tbody></table>

### Response Schema

<table><thead><tr><th width="184">Parameter</th><th width="113">Data Type</th><th width="97">Field Constraints</th><th>Description</th></tr></thead><tbody><tr><td>tanStats</td><td>Array</td><td>NA</td><td>Upload statistics aggregated at the TAN level. An array of <a href="#gstin-stats-object">TAN stats object</a>. In case of non-validation errors, this will be an empty Array ([]).</td></tr><tr><td>jsonRecordErrors</td><td>Array</td><td>NA</td><td>Validation Errors. An array of <a href="#json-record-error-details-object">JSON record error details objects</a>. In case there are no errors, this will be an empty Array ([]).</td></tr><tr><td>errors</td><td>Array</td><td>NA</td><td>Non-Validation Errors. An array of <a href="#non-validation-error-details-object">non-validation error details objects</a>. In case there are no errors, this will be an empty Array ([]).</td></tr></tbody></table>

#### TAN Stats Object

<table><thead><tr><th width="184">Parameter</th><th width="113">Data Type</th><th width="106">Field Constraints</th><th>Description</th></tr></thead><tbody><tr><td>tan</td><td>String</td><td>NA</td><td>Deductor TAN that these stats belong to.</td></tr><tr><td>totalDocumentCount</td><td>Number</td><td>NA</td><td>Total count of documents parsed successfully.</td></tr><tr><td>validRows</td><td>Number</td><td>NA</td><td>Total count of valid document line objects.</td></tr><tr><td>invalidRows</td><td>Number</td><td>NA</td><td>Total count of invalid document line objects.</td></tr></tbody></table>

#### JSON Record Error Details Object

<table><thead><tr><th width="184">Parameter</th><th width="113">Data Type</th><th width="130">Field Constraints</th><th>Description</th></tr></thead><tbody><tr><td>recordIndex</td><td>Number</td><td>NA</td><td>Array index of the record in request jsonRecords. The index starts from 0.</td></tr><tr><td>recordErrors</td><td>Array</td><td>NA</td><td>Array of <a href="#record-error-details-object">record error details objects</a>.</td></tr><tr><td>externalId</td><td>String</td><td>NA</td><td>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.</td></tr></tbody></table>

#### Record Error Details Object

<table><thead><tr><th width="184">Parameter</th><th width="113">Data Type</th><th width="130">Field Constraints</th><th>Description</th></tr></thead><tbody><tr><td>errorId</td><td>String</td><td>NA</td><td>Error ID</td></tr><tr><td>columnName</td><td>Array</td><td>NA</td><td>Array of strings representing field keys in the jsonRecords of the request that has an error.</td></tr><tr><td>errorMessage</td><td>String</td><td>NA</td><td>User friendly error message.</td></tr></tbody></table>

#### Non-Validation Error Details Object

<table><thead><tr><th width="173">Parameter</th><th width="113">Data Type</th><th width="130">Field Constraints</th><th>Description</th></tr></thead><tbody><tr><td>errorCode</td><td>String</td><td>NA</td><td>Error code</td></tr><tr><td>errorMessage</td><td>String</td><td>NA</td><td>Error message.</td></tr><tr><td>errorField</td><td></td><td>NA</td><td>Error field.</td></tr><tr><td>errorValues</td><td></td><td>NA</td><td>Error values.</td></tr><tr><td>errorResolution</td><td></td><td>NA</td><td>Error resolution.</td></tr></tbody></table>

### Response Status Codes

<table><thead><tr><th width="192">HTTP Status Code</th><th>Description</th></tr></thead><tbody><tr><td>200</td><td>For a successfully processed request (may be a success or validation error).</td></tr><tr><td>400</td><td>If the request schema is not valid.</td></tr><tr><td>401</td><td>If the user is not authenticated for the operation.</td></tr><tr><td>403</td><td>If the user is not authorized for the operation.</td></tr><tr><td>500</td><td>If there are any unhandled exceptions on Clear side.</td></tr></tbody></table>

### Sample Request

#### Deduction document

{% code lineNumbers="true" %}

```json
{
  "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"
    }
  ]
}
```

{% endcode %}

### Sample Response

Success - HTTP Status Code - 200

{% code lineNumbers="true" %}

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

{% endcode %}

Validation Error - HTTP Status Code - 200

{% code lineNumbers="true" %}

```json
{
  "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
}
```

{% endcode %}

Non-Validation Error - HTTP Status Code - 401

{% code lineNumbers="true" %}

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

{% endcode %}

Non-Validation Error - HTTP Status Code - 500

{% code lineNumbers="true" %}

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

{% endcode %}

### 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.