File Form 138 TDS returns

Start with your prepared TXT file and follow the steps to validate the return, file it, and download the receipt.

Before you start

Get a Sandbox API key and access token using the Quickstart guide.
Prepare the Form 138 TXT file for your TAN, tax year, and quarter. You can use the TDS Reports API to generate it.

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. If you have a validated ZIP containing the FVU file and Form 27A, start at Create an e-filing job.

File the return

Request the CSI OTP

Obtain the user’s consent, then call Generate CSI OTP 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.

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.

Verify the OTP and download CSI

Call Verify CSI OTP with the reference ID and the OTP received.

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.

curl --request GET \
  --url '{csi-url}' \
  --output challan.csi

Create an FVU job

Call Generate FVU with the return details. This guide uses "regular" as the filing type.

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": "138",
    "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.

Upload the TXT and CSI files

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

curl --request PUT \
  --url '{txt-file-upload-url}' \
  --header 'Content-Type: text/plain' \
  --data-binary '@form-138.txt'

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.

Check validation and download the FVU ZIP

Call Get FVU job status with the FVU job ID.

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.

curl --request GET \
  --url '{fvu-zip-file-url}' \
  --output form-138-fvu.zip

Create an e-filing job

Call E-file TDS return using the same TAN, tax year, quarter, and form as the validated return.

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": "138",
    "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.

Upload the FVU ZIP

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

curl --request PUT \
  --url '{fvu-upload-file-url}' \
  --header 'Content-Type: application/zip' \
  --data-binary '@form-138-fvu.zip'

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

Check filing status and download the receipt

Call Get TDS e-filing status with the e-filing job ID.

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.

curl --request GET \
  --url '{receipt-file-url}' \
  --output form-138-receipt.pdf

After filing

Form 130 is an annual certificate. After the tax year ends and TRACES processes the relevant statement, check Form 130 certificate availability.

FVU webhooks and e-filing webhooks: Receive job completion updates instead of polling.
Job-based API workflow: Learn how file uploads and background jobs work.
TDS compliance API overview: Explore CSI download, return validation, e-filing, and TDS certificates.

Form 24Q

Return filing

TDS certificates

File Form 138 TDS returns

Before you start

File the return

Request the CSI OTP

Verify the OTP and download CSI

Create an FVU job

Upload the TXT and CSI files

Check validation and download the FVU ZIP

Create an e-filing job

Upload the FVU ZIP

Check filing status and download the receipt

After filing

​Before you start

​File the return

Request the CSI OTP

Verify the OTP and download CSI

Create an FVU job

Upload the TXT and CSI files

Check validation and download the FVU ZIP

Create an e-filing job

Upload the FVU ZIP

Check filing status and download the receipt

​After filing

​Related guides

Before you start

File the return

After filing

Related guides