ClearTax Docs
Subscribe for Updates
  • Introduction to ClearTax APIs
  • ☁️Clear Finance Cloud
    • Introduction to Clear Finance Cloud
    • Learn Clear Finance Cloud Basics
      • API client
      • Access token
      • FTP client
      • How to get Custom Upload Template ID?
    • CFC API Reference
      • Resources and Masters
        • Sale Document Line Object
        • Purchase Document Line Object
      • Generate Access Token API
      • Ingestion API
        • Ingest Documents via File
          • Get Pre-signed URL
          • Upload File to Storage
          • Trigger File Ingestion
          • Get File Ingestion Status
        • (Deprecated) Ingest Documents via JSON
    • Notifications
  • 🇮🇳GLS API
    • GLS API Reference
      • Resources and Masters
      • Advanced Ingestion API Reference
        • Get Pre-signed URL
        • Upload File to Storage
        • Create Ingestion Activity
        • Get Ingestion Activity Status
  • 🇮🇳GST API
    • Introduction to GST API
    • GST 2.0 API Reference
      • Upload Documents
    • GST FTP Magnet
  • 🇮🇳Max ITC API
    • Introduction to Max ITC API
    • Getting Started with Max ITC API
    • Max ITC API Reference
      • Resources and Masters
        • Input and output templates
        • Error Code Master
        • Learn Max ITC API Architecture
      • Max ITC APIs
        • Fetch Max ITC Configuration
        • Upload Purchase Documents
          • Ingest PR via File
          • (Deprecated) Ingest PR via JSON
        • Trigger Max ITC Workflow
        • Get Max ITC Results
        • Postman Collection
    • Max ITC FTP Magnet
  • 🇮🇳TDS API
    • Introduction to TDS API
    • TDS API Reference
      • Resources and Masters
        • Deduction Document Line Objects
        • Output Template(Error)
      • TDS APIs
        • Upload Deductions
          • Ingest Deductions via File
            • Get Pre-signed URL
            • Upload File to Storage
            • Trigger File Ingestion
            • Get File Ingestion Status
          • (Deprecated) Ingest Deductions via JSON
  • 🇮🇳E-Invoicing API
    • Introduction to E-Invoicing API
    • Learn E-Invoicing API Basics
      • How to get E-Invoicing User Auth Token?
      • How to scan the E-Invoice QR code?
      • How to add GSTIN to E-Invoicing?
        • Clear IRP API Credentials
    • Learn E-waybill API Basics
    • E-Invoicing API Reference
      • Setting up your account
      • Clear Schema
        • Generate IRN
        • Cancel IRN
        • Get E-Invoice PDF
        • Get E-Invoice by IRN
        • Generate E-Waybill by IRN
        • Generate E-Waybill for Non-IRN documents
        • Bulk Generate E-Waybill for Non-IRN documents
        • Cancel E-Waybill
        • Get E-Waybill PDF
        • Update E-Waybill Transporter ID
        • Update E-Waybill Part-B
        • Extend E-Waybill Validity
        • Generate/Regenerate Consolidated EWB
        • Get Consolidated EWB PDF
        • Initiate Multi-Vehicle E-Waybills
        • Update EWB Status from NIC
        • Download E-waybills by Others
        • Get E-Waybill Download Status
        • Get E-Waybills
        • Get latest E-Waybill status from Government
        • Generate B2C Payment QR Code
          • Generate B2C Payment QR Code (Lite)
        • Get Signed PDF
        • Sign PDF API Base 64 Encoded
        • Send an E-Invoice via Email
        • Get Invoice Details
      • Government Schema
        • Generate IRN
        • Cancel IRN
        • Get Invoice by IRN
        • Generate E-Waybill by IRN
      • Resources and Masters
        • E-Invoice Object
        • Country Code Master
        • State Code Master
        • Pincode Master
        • Pincode State Mapping Pattern
        • Port Code Master
        • Currency Code Master
        • UQC Master
        • Tax Rates
        • Error Codes
    • E-Invoicing FTP Magnet
  • 🇮🇳Invoicing API
    • Invoicing API Reference
      • Create an Invoice
      • Create Document (Non-Sale)
      • Download PDF of a Document
      • Get Document details
      • Resources and Master
        • Country Master
        • State Master
        • Pincode Master
        • Port Master
        • Currency Master
        • Unit Master
        • Document Types
        • Supply Types
  • 🇲🇾E-INVOICING MALAYSIA API
    • E-Invoicing Malaysia API Reference
      • Resources and Masters
        • Error resolution guide
        • Frequently asked questions (FAQs)
        • E-Invoice Object
      • Generate Access Token API
      • Malaysia E-Invoicing APIs
        • Generate E-Invoice for a Document
        • Status Check for Submitted E-Invoice
        • Cancel E-Invoice
        • Upload E-Invoice
        • Get Documents
        • Get E-Invoice PDF
        • Get Document via UUID
        • Delete Invoice
        • Send Bulk Email
        • Search Taxpayer Tin API
  • E-Invoicing FTP Magnet (XML)
  • E-Invoicing FTP Magnet (Excel)
  • 🇸🇦E-Invoicing KSA API
    • Introduction to E-Invoicing KSA API
    • Learn E-Invoicing KSA API Basics
      • How to get E-Invoicing KSA Auth Token?
      • How to add a VAT number to KSA E-Invoicing Account?
      • How to add Branch for existing Vat to KSA E-Invoicing Account ?
      • How to register a device for a VAT?
      • How to generate OTP on ERAD Portal?
      • How to get Print Template ID?
      • KSA E-Invoicing Integration Architecture
    • E-Invoicing KSA API Reference
      • Resources and Masters
        • E-Invoice Object
        • Error Details Object
        • Data Types
        • Code Lists
        • Common Errors and Resolution
      • Authentication
      • Generate Access Token API
      • KSA E-Invoicing APIs
        • Generate E-Invoice
          • Additional Standard (B2B) E-Invoice Examples
          • Additional Simplified (B2C) E-Invoice Examples
        • Generate E-Invoice Async
        • Generate E-Invoice via XML
        • Send Signed E-Invoice XML To ZATCA
        • Get Bulk Invoice Lite
        • Get Invoice
        • Get E-Invoice PDF
        • Get E-Invoice PDF/A-3 with PDF API
        • Register Device
        • Get PCSID Generation Status
        • Renew PCSID
        • Generate E-Invoice (Phase I)
        • Generate QR Code (Phase I)
        • Generate Device ID
        • Generate CSID and PCSID
        • Send E-Invoice via Email
        • Add Business units API
    • E-Invoicing KSA FTP Magnet
    • E-Invoicing KSA XML reporting FTP Magnet
  • 🧩Add-ons and Extensions
    • SAP Add-on
      • SAP Connectivity Checklist
        • Steps to import SSL/TLS certificates in SAP
        • Steps to check ICM settings in SAP
        • Steps to test connectivity in SAP
        • Steps to troubleshoot connectivity issues in SAP
    • Tally Add-on
  • Microsoft Dynamics 365(F&O)
  • General
    • Go-Live Cutover Activity Checklist
    • How to check DNS resolution?
    • How to check hostname reachability?
    • How to check if hostname is trusted?
    • How to get the SSL certificate of a host?
  • ⭐GST GSP API
    • Introduction to GST GSP API
    • Getting Started with GST GSP API
    • GST GSP API Reference
      • Sample API
    • Migrating from Karvy GST GSP
  • ⭐E-Waybill GSP API
    • Introduction to E-Waybill GSP API
    • Getting Started with EWB GSP API
      • How to register EWB GSP on NIC?
      • Sandbox GSTIN for EWB GSP
    • E-Waybill GSP API Reference
      • Sample API
    • Migrating from Karvy EWB GSP
  • ⭐E-Invoicing GSP API
    • Introduction to E-Invoicing GSP API
    • Getting Started with EINV GSP API
      • How to register EINV GSP on IRP?
      • Sandbox GSTIN for EINV GSP
    • E-Invoicing GSP API Reference
      • Sample API
  • Subscribe for Updates
  • 🚫(Deprecated) GST 1.0 API
    • (Deprecated) Introduction to GST API
    • (Deprecated) Learn GST API Basics
    • (Deprecated) Getting Started with GST API
      • (Deprecated) How to set up ClearTax account?
      • (Deprecated) How to authenticate API requests?
      • (Deprecated) How to upload an invoice from File?
      • (Deprecated) How to create custom import template?
    • (Deprecated) GST 1.0 API Reference
      • Taxpayer Information
      • (Deprecated) Invoices
      • (Deprecated) Bills of Supply
      • (Deprecated) Credit Debit Notes (CDN)
      • (Deprecated) Advances
      • (Deprecated) Resources and Masters
        • (Deprecated) How to read GST error response
        • (Deprecated) Unit of Measurement master
        • (Deprecated) State master
        • (Deprecated) Document Classification/Section Name master
      • (Deprecated) Items
      • (Deprecated) Contacts
      • (Deprecated) GST File Upload API Reference
  • 🚫Deprecated E-Waybill API
    • (Deprecated) Introduction to E-Waybill API
    • (Deprecated) Learn E-Waybill API Basics
    • (Deprecated) Getting Started with E-Waybill API
    • (Deprecated) E-Waybill API Reference
      • (Deprecated) Resources and Masters
        • (Deprecated) Unit Master
        • (Deprecated) State Master
        • (Deprecated) Error Master
      • (Deprecated) E-Waybill JSON API Reference
        • (Deprecated) Generating E-Waybill
        • (Deprecated) Getting E-Waybill
        • (Deprecated) Updating E-Waybill
        • (Deprecated) Extending Validity of E-Waybill
        • (Deprecated) Multi-vehicle E-Waybill
        • (Deprecated) Printing E-Waybill
        • (Deprecated) Cancelling E-Waybill
        • (Deprecated) Generating Consolidated E-Waybill
        • (Deprecated) Getting Consolidated E-Waybill
        • (Deprecated) Regenerating Consolidated E-Waybill
        • (Deprecated) Printing Consolidated E-Waybill
      • (Deprecated) E-Waybill File Upload API Reference
        • (Deprecated) Creating or Updating Documents
        • (Deprecated) Getting Upload Status
        • (Deprecated) Getting Upload Validation
        • (Deprecated) Getting Upload History
        • (Deprecated) Rate Limiting & Best Practices
    • (Deprecated) E-Waybill FTP Magnet
Powered by GitBook
On this page
  • Request Method
  • Request URL
  • Request Headers
  • Request Path Params
  • Request Query Params
  • Request Body
  • Response Schema
  • Response Status Codes
  • Sample Request
  • Sample Response
  • API Validations
  • API Constraints

Was this helpful?

  1. TDS API
  2. TDS API Reference
  3. TDS APIs
  4. Upload Deductions

(Deprecated) Ingest Deductions via JSON

PreviousGet File Ingestion StatusNextIntroduction to E-Invoicing API

Last updated 1 year ago

Was this helpful?

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

tan

String

Cannot be empty

Mandatory. TAN of the taxpayer registered on CFC.

Content-Type

String

application/json

Request Path Params

Parameter
Data Type
Field Validations
Description

templateType

String

Enum:

TDS

This will always be “TDS”.

Request Query Params

There are no query parameters for this API.

Request Body

Parameter
Data Type
Field Validation
Description

userInputArgs

Object

NA

jsonRecords

Array

MaxLength: 100

User Input Arguments Object

Parameter
Data Type
Field Validation
Description

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

Parameter
Data Type
Field Validation
Description

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

Parameter
Data Type
Field Constraints
Description

tanStats

Array

NA

jsonRecordErrors

Array

NA

errors

Array

NA

TAN Stats Object

Parameter
Data Type
Field Constraints
Description

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

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

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

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.

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.

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.

Mandatory. .

Mandatory. .

Mandatory. An array of based on templateType used in the path param and the formType used in UserInputArgs.

Upload statistics aggregated at the TAN level. An array of . In case of non-validation errors, this will be an empty Array ([]).

Validation Errors. An array of . In case there are no errors, this will be an empty Array ([]).

Non-Validation Errors. An array of . In case there are no errors, this will be an empty Array ([]).

Array of .

🇮🇳
here
User auth token
Deduction objects
User Input Arguments Object
TAN stats object
JSON record error details objects
non-validation error details objects
record error details objects