TDS Compliance API
TDS (Tax Deducted at Source) compliance is the set of processes used by a deductor to prepare, validate, and submit quarterly e-TDS returns and generate TDS certificates in India. Use these APIs to download CSI (Challan Status Inquiry) files, generate FVU (File Validation Utility) packages, e-file quarterly TDS returns, and create Form 16/16A certificates using a job-based async workflow with optional webhooks.Key features
CSI download
Retrieve Challan Status Inquiry files from TRACES to reconcile tax payments before preparing quarterly returns.
FVU generation
Validate and package TDS return data into FVU-ready ZIP files for upload to the income tax portal.
E-file returns
Submit quarterly TDS returns electronically and download acknowledgement receipts and Form 27A artifacts.
Form 16/16A certificates
Generate salary (Form 16) and non-salary (Form 16A) TDS certificates from TRACES for distribution to deductees.
Job-based async workflow
Submit long-running compliance tasks as jobs and poll for status or receive webhook callbacks when complete.
Webhook notifications
Receive real-time status updates for job completion instead of polling, enabling event-driven integrations.
How it works
Authenticate to get an access token
Call the authentication endpoint to obtain a bearer token for subsequent API requests.
Download CSI file
Generate an OTP and verify it to retrieve the CSI file URL for challan reconciliation.
Generate FVU package
Submit a job with return data, upload additional inputs if needed, then poll or await a webhook to download the validated FVU ZIP.
E-file the quarterly return
Submit the FVU for e-filing, then poll or await a webhook to download the acknowledgement receipt and Form 27A.
Recipes
File Form 24Q
E-file Form 24Q with CSI download, FVU generation, and receipt downloads.
File Form 26Q
E-file Form 26Q (non-salary TDS) with CSI download, FVU generation, and receipts.
Generate Form 16 certificates
Download Form 16 salary certificates after Form 24Q filing.
Generate Form 16A certificates
Download Form 16A certificates after Form 26Q or 27Q filing.
API categories
Download CSI
Generate and verify OTP to retrieve Challan Status Inquiry files.
Generate FVU
Submit, poll, and search FVU generation jobs.
E-file returns
Submit, poll, and search e-filing jobs for quarterly returns.
Form 16/16A certificates
Submit, poll, and fetch certificate generation jobs.
CSI download APIs
| API | Purpose |
|---|---|
| Generate OTP | Request an OTP to initiate CSI file download from TRACES |
| Verify OTP | Verify OTP and retrieve the CSI file download URL |
FVU generation APIs
| API | Purpose |
|---|---|
| Submit job | Create a new FVU generation job with return data |
| Poll job | Check job status and download FVU ZIP when complete |
| Search job | List and filter previously submitted FVU jobs |
E-file APIs
| API | Purpose |
|---|---|
| Submit job | Submit FVU for e-filing to the income tax portal |
| Poll job | Check filing status and download receipt/Form 27A |
| Search job | List and filter previously submitted e-filing jobs |
Form 16/16A certificate APIs
| API | Purpose |
|---|---|
| Submit job | Create a certificate generation job for Form 16 or Form 16A |
| Credentials | Reference for TRACES credentials required for certificate generation |
| Poll job | Check job status and retrieve certificate outputs |
| Fetch job | Retrieve details of a specific certificate generation job |
Common use cases
Use the TDS Compliance API when you need to:- Build a payroll platform that validates quarterly TDS return files by generating FVU packages automatically
- Help finance teams e-file quarterly TDS returns programmatically and store acknowledgements and receipts
- Generate and distribute Form 16/16A certificates to employees and vendors after returns are processed
- Automate CSI retrieval for challan reconciliation before preparing the quarterly return
- Run asynchronous compliance workflows at scale using webhooks instead of polling
Frequently asked questions
What is TDS compliance?
What is TDS compliance?
TDS (Tax Deducted at Source) compliance refers to the processes a deductor follows to withhold tax at source, file quarterly returns with the Income Tax Department, and issue TDS certificates to deductees. The TDS Compliance API automates these workflows including CSI download, FVU generation, e-filing, and certificate creation.
What is a CSI file and why do I need it?
What is a CSI file and why do I need it?
CSI (Challan Status Inquiry) is a file downloaded from TRACES (TDS Reconciliation Analysis and Correction Enabling System) that contains challan payment details. You need the CSI file to reconcile tax payments before preparing your quarterly TDS return. Use the Download CSI APIs to retrieve this file programmatically.
What is FVU and how does it work?
What is FVU and how does it work?
FVU (File Validation Utility) is a tool provided by the Income Tax Department to validate TDS return files before submission. The TDS Compliance API generates FVU-validated ZIP packages from your return data. Submit a job with your return data, then poll or receive a webhook to download the validated FVU package ready for e-filing.
How do job-based APIs work?
How do job-based APIs work?
Job-based APIs handle long-running operations asynchronously. You submit a job with input data, receive a job ID, then either poll the job status endpoint or configure webhooks to receive a callback when the job completes. See the job-based API workflow guide for implementation details.
Can I receive notifications instead of polling?
Can I receive notifications instead of polling?
The TDS Compliance API supports webhooks for all job-based endpoints. Configure a webhook URL to receive notifications when jobs complete instead of polling. See the webhooks guide.
What credentials do I need for Form 16/16A generation?
What credentials do I need for Form 16/16A generation?
You need valid TRACES credentials (TAN-based login) to generate Form 16 and Form 16A certificates. See the credentials reference for required fields and setup before submitting jobs.
What forms does the TDS Compliance API support?
What forms does the TDS Compliance API support?
The TDS Compliance API supports quarterly TDS returns filed by deductors, including Form 24Q (salary payments), Form 26Q (non-salary payments), and Form 27Q (payments to non-residents). Certificate generation supports both Form 16 (salary) and Form 16A (non-salary) TDS certificates.
How do I handle errors during compliance workflows?
How do I handle errors during compliance workflows?
The TDS Compliance API returns structured error responses with codes and messages. Common errors include invalid credentials, validation failures, and job timeouts. Check the errors guide for error code reference and troubleshooting steps.