TDS Reports API
TDS Reports API is a job-based API for generating quarterly TDS statement TXT files for Forms 138, 140, and 144. Use this API to upload Sheet JSON workbooks, track processing with polling or webhooks, and download TXT files for FVU validation and e-filing. TCS statements use the same workflow through separate/tcs/reports/txt endpoints.
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 138 (salary), Form 140 (non-salary), and Form 144 (NRI payments).
TCS statement support
Generate TCS TXT files through dedicated endpoints that use the same job-based workflow.
Job search and audit
Search past jobs for operations tracking and compliance audits.
How it works
1
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”).2
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.3
Build and upload Sheet JSON
Build the Sheet JSON with the schema for your form type, then upload it to
json_url with a PUT request. Do not include Sandbox auth headers in the PUT request.4
Track job status
Monitor job progress by polling
GET /tds/reports/txt?job_id=... or by receiving webhook callbacks.5
Download the generated TXT
When status is
succeeded, download the TXT file from the provided URL for FVU validation and e-filing.6
Search prior jobs (optional)
Use
POST /tds/reports/txt/search to list and audit previous jobs for operations or compliance purposes./tcs/reports/txt endpoints.
For the full workflow, see the job-based API workflow guide and the Sheet JSON guide.
Form workbooks
Form 138 salary workbook
Workbook schema and sample payload for salary payments under Form 138.
Form 140 non-salary workbook
Workbook schema and sample payload for non-salary payments under Form 140.
Form 144 NRI workbook
Workbook schema and sample payload for non-resident payments under Form 144.
API categories
TDS Reports endpoints
Submit, poll, and search TDS TXT generation jobs for Forms 138, 140, and 144.
TCS Reports endpoints
Submit, poll, and search TCS TXT generation jobs using the same job-based workflow.
TDS schemas
Sheet JSON schemas for Form 138, 140, and 144 workbooks.
TCS schema
Sheet JSON schema for TCS payment workbooks.
TDS Reports endpoints
TCS Reports endpoints
Sheet JSON schemas
Common use cases
Use the TDS Reports API when you need to:- Automate quarterly TDS return generation for Forms 138, 140, or 144 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 an asynchronous API that generates TXT files for quarterly TDS returns for Forms 138, 140, and 144. It accepts Sheet JSON input with deductee and payment data and returns TRACES-aligned TXT output for FVU validation and e-filing on 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 workflow. Submit a job with
POST /tds/reports/txt, upload your Sheet JSON to the returned json_url with a PUT request, then track the job by polling GET /tds/reports/txt?job_id=... or receiving webhook callbacks. When the job succeeds, download the 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 for workbook data used in TDS and TCS forms. TDS Reports API provides schemas for Form 138 (salary), Form 140 (non-salary), Form 144 (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 want to check status on demand. Use webhooks when you want real-time notifications without repeated API calls, especially for high-volume job processing.
Which forms are supported and how is TCS different?
Which forms are supported and how is TCS different?
TDS Reports API supports Form 138 for salary TDS, Form 140 for resident non-salary TDS, and Form 144 for non-resident TDS. TCS (Tax Collected at Source) statements use separate
/tcs/reports/txt endpoints and a dedicated TCS workbook schema, but the job flow is the same.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 for the failure. Check your Sheet JSON for schema violations or missing required fields, then review the errors guide for troubleshooting steps. You can resubmit the job after you fix the issue.