Skip to main content
This recipe walks you through filing Form 24Q TDS returns after generating the TXT file.
It covers CSI download (OTP-based), FVU generation, e-filing, and post-filing steps.
Before you begin:
  • You must have generated the Form 24Q TXT file using the TDS Reports API.
  • You must have a valid Sandbox authorization token.
  • You must know the correct TAN, financial_year, and quarter.
1

Prepare TDS Return (Generate TXT)

Ensure that you have generated the Form 24Q TXT file using the TDS Reports APIs.If you’ve already completed the Prepare Form 24Q TDS Return recipe, you can reuse the TXT file and continue to the next step.
2

Generate OTP for CSI Download

To fetch the CSI file, you must first generate an OTP.
This OTP is sent by TRACES to the TAN’s registered email/mobile.Endpoint:
POST /tds/compliance/download-csi/generate_otp

cURL Request – Generate CSI OTP

curl --request POST \
  --url https://api.sandbox.co.in/tds/compliance/download-csi/generate_otp \
  --header 'authorization: {sandbox-access-token}' \
  --header 'content-type: application/json' \
  --header 'x-api-key: xxxxxxxxxxxxx' \
  --header 'x-api-version: 1.0.0' \
  --data '{
    "tan": "AHMA09719B",
    "financial_year": "FY 2024-25"
  }'
This step only triggers OTP delivery.
No CSI file or download URL is returned here.
3

Verify OTP and Get CSI Download URL

Verify the OTP received to obtain a signed CSI download URL.Endpoint:
POST /tds/compliance/download-csi/verify_otp

cURL Request – Verify CSI OTP

curl --request POST \
  --url https://api.sandbox.co.in/tds/compliance/download-csi/verify_otp \
  --header 'authorization: {sandbox-access-token}' \
  --header 'content-type: application/json' \
  --header 'x-api-key: xxxxxxxxxxxxx' \
  --header 'x-api-version: 1.0.0' \
  --data '{
    "tan": "AHMA09719B",
    "financial_year": "FY 2024-25",
    "otp": "123456"
  }'
A successful response includes:
  • csi_download_url (signed, time-limited)
Download the CSI file using this URL. You will upload it during FVU generation.
4

Generate FVU

With the TXT and CSI files ready, create an FVU generation job.

cURL Request – Create FVU Job

curl --request POST \
  --url https://api.sandbox.co.in/tds/compliance/fvu/generate \
  --header 'authorization: {sandbox-access-token}' \
  --header 'content-type: application/json' \
  --header 'x-api-key: xxxxxxxxxxxxx' \
  --header 'x-api-version: 1.0.0' \
  --data '{
    "@entity": "in.co.sandbox.tds.compliance.fvu.generate.request",
    "financial_year": "FY 2024-25",
    "quarter": "Q1",
    "form": "24Q",
    "tan": "AHMA09719B"
  }'
The response returns:
  • txt_file_upload_url
  • csi_file_upload_url
5

Provide TXT & CSI Files

Upload the TXT and CSI files using the signed URLs.
curl --request PUT \
  --url '{txt_file_upload_url}' \
  --header 'Content-Type: text/plain' \
  --data-binary '@/form24q.txt'

curl --request PUT \
  --url '{csi_file_upload_url}' \
  --header 'Content-Type: application/octet-stream' \
  --data-binary '@/challan.csi'
6

Fetch FVU Generation Status

Poll the FVU job until it completes.

cURL – Fetch FVU Status

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: xxxxxxxxxxxxx' \
  --header 'x-api-version: 1.0.0'
When the job status is succeeded, download:
  • fvu_zip_file_url
7

E-file TDS Return

Create an e-file job for Form 24Q.

cURL – Create E-file Job

curl --request POST \
  --url https://api.sandbox.co.in/tds/compliance/e-file \
  --header 'authorization: {sandbox-access-token}' \
  --header 'content-type: application/json' \
  --header 'x-api-key: xxxxxxxxxxxxx' \
  --header 'x-api-version: 1.0.0' \
  --data '{
    "@entity": "in.co.sandbox.tds.compliance.e-file.request",
    "financial_year": "FY 2024-25",
    "quarter": "Q1",
    "form": "24Q",
    "tan": "AHMA09719B"
  }'
The response contains fvu_upload_file_url.
8

Provide FVU ZIP

Upload the ZIP containing the FVU file and Form 27A.
curl --request PUT \
  --url '{fvu_upload_file_url}' \
  --header 'Content-Type: application/zip' \
  --data-binary '@/fvu_and_form27a.zip'
9

Fetch TDS Return Status

Poll the e-file job to confirm filing completion.

cURL – Fetch E-file Status

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: xxxxxxxxxxxxx' \
  --header 'x-api-version: 1.0.0'
On success, the response includes:
  • receipt_number
  • receipt_file_url
  • form27a_file_url
10

Generate Form 16 (Optional)

After filing Form 24Q, you can generate Form 16 certificates.Ensure that the request includes at least 3 PAN–amount combinations.
curl --request POST \
  --url https://api.sandbox.co.in/tds/compliance/traces/deductors/forms/form16 \
  --header 'authorization: {sandbox-access-token}' \
  --header 'content-type: application/json' \
  --header 'x-api-key: xxxxxxxxxxxxx' \
  --header 'x-api-version: 1.0.0' \
  --data '{
    "@entity": "in.co.sandbox.tds.compliance.traces.credentials",
    "username": "traces-username",
    "password": "traces-password",
    "tan": "AHMA09719B",
    "security_captcha": {
      "@entity": "in.co.sandbox.tds.compliance.traces.credentials.security_captcha",
      "quarter": "Q4",
      "financial_year": "FY 2024-25",
      "form": "24Q",
      "bsr_code": "0510001",
      "challan_date": 1711929600000,
      "challan_serial_no": "00001",
      "challan_amount": 150000,
      "unique_pan_amount_combination_for_challan": [
        ["ABCDE1234F|50000"],
        ["PQRSX9876Z|50000"],
        ["LMNOP4321Q|50000"]
      ]
    },
    "remember_me": true
  }'