Skip to main content
Before filing Form 24Q, it’s a good idea to validate your data for potential issues and generate a clean TXT file that will pass FVU validation. This recipe walks you through:
  • Checking for potential notices using TDS Analytics
  • Uploading salary data in Sheet JSON format
  • Generating the Form 24Q TXT file via TDS Reports
  • Getting ready to move into the FVU + e-filing flow
Before you begin, make sure you’ve:
  • Generated a Sandbox authorization token using the Authenticate endpoint.
  • Identified the correct tan, financial_year (for example, FY 2024-25), quarter (Q1–Q4), and form (24Q for salary TDS).
1

Check for Potential Notice

Start by checking whether your Form 24Q return is likely to trigger any notices. Use the TDS Analytics – Potential Notices API to create a job for the given TAN, financial year, quarter, and form.This returns a job_id and a json_url where you’ll later upload salary data in Sheet JSON format.

cURL Request – Create Potential Notice Job

curl --request POST \
  --url https://api.sandbox.co.in/tds/analytics/potential-notices \
  --header 'accept: application/json' \
  --header 'authorization: {sandbox-access-token}' \
  --header 'content-type: application/json' \
  --header 'x-api-key: xxxxxxxxxxxxxxxxxx' \
  --header 'x-api-version: 1.0.0' \
  --data '{
    "@entity": "in.co.sandbox.tds.analytics.potential_notice.request",
    "financial_year": "FY 2024-25",
    "form": "24Q",
    "quarter": "Q1",
    "tan": "AHMA09719B"
  }'
A successful response returns:
  • job_id – the Potential Notice job identifier
  • status – typically created or queued
  • json_url – a pre-signed S3 URL for uploading salary data in Sheet JSON format
You will use both job_id and json_url in the next steps.
2

Provide data (upload Sheet JSON for Potential Notices)

Next, upload the data required to detect potential notices.The json_url returned in Step 1 expects a Sheet JSON payload that represents the Form 24Q workbook (Deductor details, Employee master, Salary details, Challans, and mappings).You generate this Sheet JSON in your backend and then upload it with a PUT request.
The exact Sheet JSON structure for Form 24Q is documented in the TDS Sheet JSON / sample workbooks. Make sure your workbook name, sheet names, and columns match the specification for salary TDS.

cURL Request – Upload Sheet JSON to json_url

curl --request PUT \
  --url '{json_url-from-step-1}' \
  --header 'content-type: application/json' \
  --data '@form24q_potential_notice_sheet.json'
After a successful upload, Sandbox will process the workbook asynchronously and update the Potential Notice job with the analysis results.
3

Fetch Potential Notice details

Once the data is uploaded, poll the Potential Notice job to see whether any potential issues were identified.Use the Potential Notices GET endpoint with the job_id from Step 1.

cURL Request – Fetch Potential Notice Job

curl --request GET \
  --url 'https://api.sandbox.co.in/tds/analytics/potential-notices?job_id={job_id}' \
  --header 'accept: application/json' \
  --header 'authorization: {sandbox-access-token}' \
  --header 'x-api-key: xxxxxxxxxxxxxxxxxx' \
  --header 'x-api-version: 1.0.0'
When processing is complete, you’ll see:
  • status – for example, succeeded or failed
  • A link to a Potential Notice report (for example, an Excel or JSON report) summarising possible issues like missing challans, mismatches, or under-deductions
Review these findings and make any necessary corrections to your source data before moving ahead with TXT generation.
4

Generate TDS Report (create TXT job for Form 24Q)

After you’ve identified and understood potential issues, you can move on to preparing the TXT file using the TDS Reports – TXT API.This step creates a TXT generation job and returns a new job_id and json_url for uploading the final, corrected Form 24Q Sheet JSON workbook.

cURL Request – Create TXT Generation Job

curl --request POST \
  --url https://api.sandbox.co.in/tds/reports/txt \
  --header 'accept: application/json' \
  --header 'authorization: {sandbox-access-token}' \
  --header 'content-type: application/json' \
  --header 'x-api-key: xxxxxxxxxxxxxxxxxx' \
  --header 'x-api-version: 1.0.0' \
  --data '{
    "@entity": "in.co.sandbox.tds.reports.request",
    "financial_year": "FY 2024-25",
    "form": "24Q",
    "quarter": "Q1",
    "tan": "AHMA09719B",
    "previous_receipt_number": "123456789012345"
  }'
Notes:
  • Omit previous_receipt_number for an original (regular) return.
  • For a correction return, set previous_receipt_number to the earlier Form 24Q acknowledgement number.
The response includes:
  • job_id – the TXT generation job id
  • json_url – pre-signed S3 URL where you’ll upload the final quarter-wise Form 24Q Sheet JSON
5

Repeat the above steps after fixing issues

If the Potential Notice report (or later validation) indicates data problems, you should:
  • Correct your source data (salary, challans, employee master, etc.) in your system.
  • Regenerate the Sheet JSON workbook for Form 24Q.
  • Re-upload the updated Sheet JSON to the appropriate json_url.
  • If required, rerun the Potential Notice flow (Steps 1–3) until the report is clean.
This iterative process helps you catch issues early and ensures that the TXT generated in the next step is less likely to fail during FVU validation.
6

Provide quarterly details (upload Sheet JSON for TXT)

Now upload the final, quarter-specific Form 24Q Sheet JSON workbook to the json_url returned from the TXT job in Step 4.This workbook should contain all the data required for the Form 24Q return for the selected quarter:
  • Deductor details
  • Employee master and PAN details
  • Month-wise salary and TDS information
  • Challan / book-entry details and mappings

cURL Request – Upload Sheet JSON for TXT

curl --request PUT \
  --url '{json_url-from-step-4}' \
  --header 'content-type: application/json' \
  --data '@form24q_q1_final_sheet.json'
Once the upload succeeds, Sandbox processes this workbook to generate the Form 24Q TXT file in the background.
7

Fetch TXT file

After uploading the final Sheet JSON, poll the TXT job to track TXT generation status.

cURL Request – Fetch TXT Job Status

curl --request GET \
  --url 'https://api.sandbox.co.in/tds/reports/txt?job_id={job_id-from-step-4}' \
  --header 'accept: application/json' \
  --header 'authorization: {sandbox-access-token}' \
  --header 'x-api-key: xxxxxxxxxxxxxxxxxx' \
  --header 'x-api-version: 1.0.0'
When the job status is succeeded, the response will include:
  • A URL to download the generated Form 24Q TXT file
Save this TXT file securely. You will use it to generate FVU and then e-file the return (covered in the “File Form 24Q TDS Returns” recipe).
8

File Form 24Q TDS Return (next steps)

With a clean Form 24Q TXT in hand, you’re ready to move to the actual filing workflow:
  • Generate FVU using the TXT and CSI files with the TDS Compliance – FVU Generation APIs.
  • E-file the TDS return via the TDS Compliance – E-File APIs.
  • Download the filing receipts and, later, Form 16 certificates for employees.
For the full end-to-end filing steps, follow the File Form 24Q TDS Returns recipe, which builds on top of the TXT generated here.