TDS Reports API
TDS Reports is a job-based API that generates quarterly TDS/TCS statement TXT files (Forms 24Q, 26Q, 27Q) for Indian Income Tax. Use this API to generate TXT files from Sheet JSON workbooks, track job progress via polling or webhooks, and download TXT for FVU validation and e-filing.Key features
Async job-based workflow
Submit TXT generation jobs and track progress via polling or webhooks without blocking your application.
Multiple form support
Generate TXT files for Form 24Q (salary), 26Q (non-salary), and 27Q (NRI payments).
TCS statement support
Generate TCS TXT files using the same job-based pattern via dedicated endpoints.
Job search and audit
Search and list prior jobs for operations tracking and compliance audits.
How it works
Authenticate and get authorization token
Obtain a Sandbox authorization token from /api-reference/authenticate and your API key. Pass the token as
Authorization: <token> (without “Bearer”).Submit a TXT generation job
Call
POST /tds/reports/txt to create a job. The response includes a job_id and a json_url for uploading your Sheet JSON.Build and upload Sheet JSON
Construct your Sheet JSON using the correct schema for your form type and upload it to
json_url via PUT. Do not include Sandbox auth headers on the PUT request.Track job status
Monitor job progress by polling
GET /tds/reports/txt?job_id=... or by receiving webhook callbacks.Download the generated TXT
When status is
succeeded, download the TXT file from the provided URL for FVU validation and e-filing./tcs/reports/txt endpoints.
For detailed workflow patterns, see the job-based API workflow guide and Sheet JSON guide.
Recipes
Prepare Form 24Q
Step-by-step guide to prepare Form 24Q TDS statements for salary payments.
Prepare Form 26Q
Step-by-step guide to prepare Form 26Q TDS statements for non-salary payments.
API categories
TDS Reports endpoints
Submit, poll, and search TDS TXT generation jobs for Forms 24Q, 26Q, and 27Q.
TCS Reports endpoints
Submit, poll, and search TCS TXT generation jobs using the same job-based workflow.
TDS schemas
Sheet JSON schemas for Form 24Q, 26Q, and 27Q workbooks.
TCS schema
Sheet JSON schema for TCS payment workbooks.
TDS Reports endpoints
| API | Purpose |
|---|---|
| Submit job | Create a TXT generation job and get job_id + json_url |
| Poll job | Check job status and retrieve TXT download URL when complete |
| Search jobs | List and filter prior jobs for audit and operations |
TCS Reports endpoints
| API | Purpose |
|---|---|
| Submit job | Create a TCS TXT generation job and get job_id + json_url |
| Poll job | Check TCS job status and retrieve TXT download URL when complete |
| Search jobs | List and filter prior TCS jobs for audit and operations |
Sheet JSON schemas
| Schema | Form | Description |
|---|---|---|
| Salary payments | 24Q | TDS on salary payments to employees |
| Non-salary payments | 26Q | TDS on non-salary payments (vendors, contractors, rent) |
| NRI payments | 27Q | TDS on payments to non-residents |
| TCS payments | TCS | Tax collected at source statements |
Common use cases
Use the TDS Reports API when you need to:- Automate quarterly TDS return generation for Forms 24Q, 26Q, or 27Q from payroll or accounting systems
- Generate FVU-ready TXT files from structured payment data
- Process large volumes of deductee records using job-based workflows
- Integrate TDS return preparation into compliance workflows with webhook notifications
- Generate TCS (Tax Collected at Source) statements using the same job-based workflow
- Maintain audit trails of generation jobs for compliance and operations
Frequently asked questions
What is TDS Reports API?
What is TDS Reports API?
TDS Reports API is a job-based (asynchronous) API that generates TXT files required to prepare quarterly TDS returns for Forms 24Q, 26Q, and 27Q. TDS Reports API accepts Sheet JSON input containing deductee and payment data, processes it asynchronously, and produces TRACES-aligned TXT output for FVU validation and e-filing to the Income Tax portal.
How does the job-based workflow work?
How does the job-based workflow work?
TDS Reports API uses an async job-based workflow: you submit a job via
POST /tds/reports/txt and receive a job_id plus a json_url. Upload your Sheet JSON to json_url via PUT, then track progress by polling GET /tds/reports/txt?job_id=... or by receiving webhook callbacks. When status is succeeded, download the generated TXT file. See the job-based API workflow guide for details.What is Sheet JSON and where are the schemas?
What is Sheet JSON and where are the schemas?
Sheet JSON is a structured JSON format representing workbook data for TDS/TCS forms. TDS Reports API provides schemas for each form type: Form 24Q (salary), Form 26Q (non-salary), Form 27Q (NRI), and TCS. See the Sheet JSON guide for formatting details.
Do I need auth headers when uploading to json_url?
Do I need auth headers when uploading to json_url?
No. The
json_url returned by the Submit Job endpoint is a pre-signed URL. Upload your Sheet JSON via PUT without including Sandbox authorization headers—the URL itself contains the necessary credentials.When should I use webhooks vs polling?
When should I use webhooks vs polling?
Use polling when you need simple integration or want to check status on-demand. Use webhooks when you want real-time notifications without repeated API calls, especially for high-volume job processing. Webhooks reduce latency and API usage compared to polling.
Which forms are supported and how is TCS different?
Which forms are supported and how is TCS different?
TDS Reports API supports Form 24Q (salary TDS), Form 26Q (non-salary TDS), and Form 27Q (NRI TDS). TCS (Tax Collected at Source) statements use a separate set of endpoints at
/tcs/reports/txt but follow the same job-based workflow pattern. Each form type has its own Sheet JSON schema.What should I do if a job fails?
What should I do if a job fails?
When a TDS Reports API job fails, the poll response includes error details explaining the failure reason. Check your Sheet JSON for schema violations or missing required fields. Review the errors guide for common error codes and troubleshooting steps. You can resubmit a corrected job after fixing the issues.