> ## Documentation Index
> Fetch the complete documentation index at: https://sandboxfinancialtechnologiesprivatelimited.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# File Form 140 TDS returns

> Validate and e-file Form 140 TDS returns with Sandbox's APIs, then download the filing receipt.

This guide covers filing a regular non-salary TDS return for payments to residents using a prepared Form 140 text file. Form 140 replaces Form 26Q. See the [Income Tax Department's Form 140 FAQs](https://www.incometaxindia.gov.in/documents/d/guest/form-140-faqs) for the form's requirements.

## Before you start

* Get a Sandbox API key and access token using the [Quickstart guide](https://sandboxfinancialtechnologiesprivatelimited.mintlify.site/guides/get-started/quickstart.md).
* Prepare the Form 140 TXT file for your TAN, tax year, and quarter. You can use the [TDS Reports API](https://sandboxfinancialtechnologiesprivatelimited.mintlify.site/api-reference/tds/reports/tds-reports/endpoints/submit_job.md) to generate it.
* Keep the TAN and a mobile number for CSI OTP verification ready. Obtain the user's consent before requesting the OTP.

The examples use Q1 of TY 2026-27. Replace the sample TAN and placeholders with your own values. Use the same TAN and return period throughout.

Already have the CSI file? Start at [Create an FVU job](#generate-fvu). If you have a validated ZIP containing the FVU file and Form 27A, start at [Create an e-filing job](#e-file-tds-return).

## File the return

### 1. Request the CSI OTP

Call [Generate CSI OTP](https://sandboxfinancialtechnologiesprivatelimited.mintlify.site/api-reference/tds/compliance/download-csi/endpoints/generate_otp.md) with the TAN, mobile number, and challan date range.

The example covers 1 April to 31 July 2026 in IST. The timestamps are in milliseconds. Adjust the range to include all challans needed for the return.

```bash theme={null}
curl --request POST \
  --url 'https://api.sandbox.co.in/tds/compliance/csi/otp' \
  --header 'Authorization: {sandbox-access-token}' \
  --header 'x-api-key: {sandbox-api-key}' \
  --header 'Content-Type: application/json' \
  --data '{
    "@entity": "in.co.sandbox.tds.compliance.deductors.otp.request",
    "tan": "AHMA09719B",
    "mobile_number": "{mobile-number}",
    "from": 1774981800000,
    "to": 1785522599000,
    "consent": "Y",
    "reason": "Download challan details for TDS return validation"
  }'
```

Save `data.reference_id` for OTP verification. If the response has no reference ID, check its message before continuing.

### 2. Verify the OTP and download CSI

Call [Verify CSI OTP](https://sandboxfinancialtechnologiesprivatelimited.mintlify.site/api-reference/tds/compliance/download-csi/endpoints/verify_otp.md) with the reference ID and the OTP received.

```bash theme={null}
curl --request POST \
  --url 'https://api.sandbox.co.in/tds/compliance/csi/otp/verify' \
  --header 'Authorization: {sandbox-access-token}' \
  --header 'x-api-key: {sandbox-api-key}' \
  --header 'Content-Type: application/json' \
  --data '{
    "@entity": "in.co.sandbox.tds.compliance.deductors.csi.request",
    "reference_id": "{reference-id}",
    "otp": "{otp}"
  }'
```

Use `data.csi_url` to download the file. If verification fails, resolve the error before continuing.

```bash theme={null}
curl --request GET \
  --url '{csi-url}' \
  --output challan.csi
```

### 3. Create an FVU job

Call [Generate FVU](https://sandboxfinancialtechnologiesprivatelimited.mintlify.site/api-reference/tds/compliance/generate-fvu/endpoints/submit_job.md) with the return details. This guide uses `"regular"` as the filing type.

```bash theme={null}
curl --request POST \
  --url 'https://api.sandbox.co.in/tds/compliance/fvu/generate' \
  --header 'Authorization: {sandbox-access-token}' \
  --header 'x-api-key: {sandbox-api-key}' \
  --header 'Content-Type: application/json' \
  --data '{
    "@entity": "in.co.sandbox.tds.compliance.fvu.generate.request",
    "tax_year": "TY 2026-27",
    "quarter": "Q1",
    "form": "140",
    "tan": "AHMA09719B",
    "filing_type": "regular"
  }'
```

Save `data.job_id` as your FVU job ID. The response also provides `data.txt_file_upload_url` and `data.csi_file_upload_url` for the next step.

### 4. Upload the TXT and CSI files

Upload both files to the URLs returned by the FVU job. Use the signed upload URLs directly.

```bash theme={null}
curl --request PUT \
  --url '{txt-file-upload-url}' \
  --header 'Content-Type: text/plain' \
  --data-binary '@form-140.txt'
```

```bash theme={null}
curl --request PUT \
  --url '{csi-file-upload-url}' \
  --header 'Content-Type: application/octet-stream' \
  --data-binary '@challan.csi'
```

Confirm that both uploads succeed before checking the job.

### 5. Check validation and download the FVU ZIP

Call [Get FVU job status](https://sandboxfinancialtechnologiesprivatelimited.mintlify.site/api-reference/tds/compliance/generate-fvu/endpoints/poll_job.md) with the FVU job ID.

```bash theme={null}
curl --request GET \
  --url 'https://api.sandbox.co.in/tds/compliance/fvu/generate?job_id={fvu-job-id}' \
  --header 'Authorization: {sandbox-access-token}' \
  --header 'x-api-key: {sandbox-api-key}'
```

Check `data.status`; an HTTP `200` response alone does not mean validation succeeded. Poll until the job reaches `succeeded` or `failed`.

If it fails, review the validation report at `data.validation_report_file_url` when provided. Correct the return and create a new FVU job.

When it succeeds, download `data.fvu_zip_file_url`. Check that the ZIP contains the FVU file and Form 27A.

```bash theme={null}
curl --request GET \
  --url '{fvu-zip-file-url}' \
  --output form-140-fvu.zip
```

### 6. Create an e-filing job

Call [E-file TDS return](https://sandboxfinancialtechnologiesprivatelimited.mintlify.site/api-reference/tds/compliance/e-file/endpoints/submit_job.md) using the same TAN, tax year, quarter, and form as the validated return.

```bash theme={null}
curl --request POST \
  --url 'https://api.sandbox.co.in/tds/compliance/e-file' \
  --header 'Authorization: {sandbox-access-token}' \
  --header 'x-api-key: {sandbox-api-key}' \
  --header 'Content-Type: application/json' \
  --data '{
    "@entity": "in.co.sandbox.tds.compliance.e-file.request",
    "tax_year": "TY 2026-27",
    "quarter": "Q1",
    "form": "140",
    "tan": "AHMA09719B"
  }'
```

Save the new `data.job_id` as your e-filing job ID. It is separate from the FVU job ID. Use `data.fvu_upload_file_url` for the upload.

### 7. Upload the FVU ZIP

Upload the ZIP containing the validated FVU file and Form 27A.

```bash theme={null}
curl --request PUT \
  --url '{fvu-upload-file-url}' \
  --header 'Content-Type: application/zip' \
  --data-binary '@form-140-fvu.zip'
```

Creating a job does not complete the filing. After the upload succeeds, check the e-filing status.

### 8. Check filing status and download the receipt

Call [Get TDS e-filing status](https://sandboxfinancialtechnologiesprivatelimited.mintlify.site/api-reference/tds/compliance/e-file/endpoints/poll_job.md) with the e-filing job ID.

```bash theme={null}
curl --request GET \
  --url 'https://api.sandbox.co.in/tds/compliance/e-file?job_id={efile-job-id}' \
  --header 'Authorization: {sandbox-access-token}' \
  --header 'x-api-key: {sandbox-api-key}'
```

Poll until `data.status` is `succeeded` or `failed`. If the job fails, read `data.message` and resolve the error.

When it succeeds, save `data.receipt_number` and download the receipt from `data.receipt_file_url`.

```bash theme={null}
curl --request GET \
  --url '{receipt-file-url}' \
  --output form-140-receipt.pdf
```

## After filing

After TRACES processes the Form 140 statement and makes the certificates available, follow the [Form 131 certificate guide](https://sandboxfinancialtechnologiesprivatelimited.mintlify.site/recipes/tds/form-131/generate-form-131-certificates.md).

## Related guides

* [FVU webhooks](https://sandboxfinancialtechnologiesprivatelimited.mintlify.site/api-reference/tds/compliance/generate-fvu/endpoints/webhook.md) and [e-filing webhooks](https://sandboxfinancialtechnologiesprivatelimited.mintlify.site/api-reference/tds/compliance/e-file/endpoints/webhook.md): Receive job completion updates instead of polling.
* [Job-based API workflow](https://sandboxfinancialtechnologiesprivatelimited.mintlify.site/guides/developer-resources/job_based_apis.md): Learn how file uploads and background jobs work.
* [TDS compliance API overview](https://sandboxfinancialtechnologiesprivatelimited.mintlify.site/api-reference/tds/compliance/overview.md): Explore CSI download, return validation, e-filing, and TDS certificates.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.