> ## Documentation Index
> Fetch the complete documentation index at: https://developer.sandbox.co.in/llms.txt
> Use this file to discover all available pages before exploring further.

# Overview

> Generate TDS TXT files for Forms 138, 140, and 144, plus TCS TXT files, with a job-based workflow for Indian Income Tax compliance.

# 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

<CardGroup cols={2}>
  <Card title="Async job-based workflow" icon="server">
    Submit TXT generation jobs and track progress via polling or webhooks without blocking your application.
  </Card>

  <Card title="Multiple form support" icon="folder">
    Generate TXT files for Form 138 (salary), Form 140 (non-salary), and Form 144 (NRI payments).
  </Card>

  <Card title="TCS statement support" icon="file-invoice">
    Generate TCS TXT files through dedicated endpoints that use the same job-based workflow.
  </Card>

  <Card title="Job search and audit" icon="database">
    Search past jobs for operations tracking and compliance audits.
  </Card>
</CardGroup>

## How it works

<Steps>
  <Step title="Authenticate and get authorization token">
    Obtain a Sandbox authorization token from [/api-reference/authenticate](/api-reference/authenticate) and your API key. Pass the token as `Authorization: <token>` (without "Bearer").
  </Step>

  <Step title="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.
  </Step>

  <Step title="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.
  </Step>

  <Step title="Track job status">
    Monitor job progress by polling `GET /tds/reports/txt?job_id=...` or by receiving [webhook callbacks](/guides/developer-resources/webhooks#webhooks).
  </Step>

  <Step title="Download the generated TXT">
    When status is `succeeded`, download the TXT file from the provided URL for FVU validation and e-filing.
  </Step>

  <Step title="Search prior jobs (optional)">
    Use `POST /tds/reports/txt/search` to list and audit previous jobs for operations or compliance purposes.
  </Step>
</Steps>

TCS TXT generation uses the same workflow through the `/tcs/reports/txt` endpoints.

For the full workflow, see the [job-based API workflow guide](/guides/developer-resources/job_based_apis#job-based-api-workflow) and the [Sheet JSON guide](/guides/developer-resources/sheet_json).

## Form workbooks

<CardGroup cols={3}>
  <Card title="Form 138 salary workbook" icon="file-lines" href="/api-reference/tds/reports/tds-reports/salary_payments">
    Workbook schema and sample payload for salary payments under Form 138.
  </Card>

  <Card title="Form 140 non-salary workbook" icon="file-invoice" href="/api-reference/tds/reports/tds-reports/non_salary_payments">
    Workbook schema and sample payload for non-salary payments under Form 140.
  </Card>

  <Card title="Form 144 NRI workbook" icon="globe" href="/api-reference/tds/reports/tds-reports/nri_payments">
    Workbook schema and sample payload for non-resident payments under Form 144.
  </Card>
</CardGroup>

## API categories

<CardGroup cols={2}>
  <Card title="TDS Reports endpoints" icon="server" href="/api-reference/tds/reports/tds-reports/endpoints/submit_job">
    Submit, poll, and search TDS TXT generation jobs for Forms 138, 140, and 144.
  </Card>

  <Card title="TCS Reports endpoints" icon="server" href="/api-reference/tds/reports/tcs-reports/endpoints/submit_job">
    Submit, poll, and search TCS TXT generation jobs using the same job-based workflow.
  </Card>

  <Card title="TDS schemas" icon="file-lines" href="/api-reference/tds/reports/tds-reports/salary_payments">
    Sheet JSON schemas for Form 138, 140, and 144 workbooks.
  </Card>

  <Card title="TCS schema" icon="file-lines" href="/api-reference/tds/reports/tcs-reports/tcs_payments">
    Sheet JSON schema for TCS payment workbooks.
  </Card>
</CardGroup>

## TDS Reports endpoints

| API                                                                            | Purpose                                                      |
| :----------------------------------------------------------------------------- | :----------------------------------------------------------- |
| [Submit job](/api-reference/tds/reports/tds-reports/endpoints/submit_job)      | Create a TXT generation job and get `job_id` + `json_url`    |
| [Poll job](/api-reference/tds/reports/tds-reports/endpoints/poll_job)          | Check job status and retrieve TXT download URL when complete |
| [Job status webhook](/api-reference/tds/reports/tds-reports/endpoints/webhook) | Receive notification when a job succeeds or fails            |
| [Search jobs](/api-reference/tds/reports/tds-reports/endpoints/fetch_jobs)     | List and filter prior jobs for audit and operations          |

## TCS Reports endpoints

| API                                                                            | Purpose                                                          |
| :----------------------------------------------------------------------------- | :--------------------------------------------------------------- |
| [Submit job](/api-reference/tds/reports/tcs-reports/endpoints/submit_job)      | Create a TCS TXT generation job and get `job_id` + `json_url`    |
| [Poll job](/api-reference/tds/reports/tcs-reports/endpoints/poll_job)          | Check TCS job status and retrieve TXT download URL when complete |
| [Job status webhook](/api-reference/tds/reports/tcs-reports/endpoints/webhook) | Receive notification when a TCS job succeeds or fails            |
| [Search jobs](/api-reference/tds/reports/tcs-reports/endpoints/fetch_jobs)     | List and filter prior TCS jobs for audit and operations          |

## Sheet JSON schemas

| Schema                                                                            | Form | Description                                      |
| :-------------------------------------------------------------------------------- | :--- | :----------------------------------------------- |
| [Salary payments](/api-reference/tds/reports/tds-reports/salary_payments)         | 138  | TDS on salary payments to employees for Q1 to Q3 |
| [Non-salary payments](/api-reference/tds/reports/tds-reports/non_salary_payments) | 140  | TDS on resident non-salary payments              |
| [NRI payments](/api-reference/tds/reports/tds-reports/nri_payments)               | 144  | TDS on payments to non-residents                 |
| [TCS payments](/api-reference/tds/reports/tcs-reports/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 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

<AccordionGroup>
  <Accordion title="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.
  </Accordion>

  <Accordion title="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](/guides/developer-resources/webhooks#webhooks). When the job succeeds, download the TXT file. See the [job-based API workflow guide](/guides/developer-resources/job_based_apis#job-based-api-workflow) for details.
  </Accordion>

  <Accordion title="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)](/api-reference/tds/reports/tds-reports/salary_payments), [Form 140 (non-salary)](/api-reference/tds/reports/tds-reports/non_salary_payments), [Form 144 (NRI)](/api-reference/tds/reports/tds-reports/nri_payments), and [TCS](/api-reference/tds/reports/tcs-reports/tcs_payments). See the [Sheet JSON guide](/guides/developer-resources/sheet_json) for formatting details.
  </Accordion>

  <Accordion title="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.
  </Accordion>

  <Accordion title="When should I use webhooks vs polling?">
    Use polling when you want to check status on demand. Use [webhooks](/guides/developer-resources/webhooks#webhooks) when you want real-time notifications without repeated API calls, especially for high-volume job processing.
  </Accordion>

  <Accordion title="Which forms are supported and how is TCS different?">
    TDS Reports API supports [Form 138](/api-reference/tds/reports/tds-reports/salary_payments) for salary TDS, [Form 140](/api-reference/tds/reports/tds-reports/non_salary_payments) for resident non-salary TDS, and [Form 144](/api-reference/tds/reports/tds-reports/nri_payments) for non-resident TDS. TCS (Tax Collected at Source) statements use separate `/tcs/reports/txt` endpoints and a dedicated [TCS workbook schema](/api-reference/tds/reports/tcs-reports/tcs_payments), but the job flow is the same.
  </Accordion>

  <Accordion title="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](/guides/developer-resources/errors) for troubleshooting steps. You can resubmit the job after you fix the issue.
  </Accordion>
</AccordionGroup>