Skip to main content
Before filing Form 26Q, 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 non-salary data in Sheet JSON format
  • Generating the Form 26Q 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 (26Q for non-salary TDS).
1

Check for potential notice

Start by checking whether your Form 26Q 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 non-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": "26Q",
    "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 non-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 26Q workbook (Deductor details, Deductee master, payment details, challans, and mappings).You generate this Sheet JSON in your backend and then upload it with a PUT request.
The Sheet JSON structure for Form 26Q is documented in the non-salary payments schema and the Sheet JSON guide. Make sure your workbook name, sheet names, and columns match the specification for non-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 '@form26q_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) summarizing 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 26Q)

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 26Q 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": "26Q",
    "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 26Q 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 26Q 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 (deductees, payments, challans, etc.) in your system.
  • Regenerate the Sheet JSON workbook for Form 26Q.
  • 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 26Q 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 26Q return for the selected quarter:
  • Deductor details
  • Deductee master and PAN details
  • Vendor/contractor payments and TDS information
  • Challan or 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 '@form26q_q1_final_sheet.json'
Once the upload succeeds, Sandbox processes this workbook to generate the Form 26Q 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 26Q 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 26Q TDS Returns” recipe).
8

File Form 26Q TDS return (next steps)

With a clean Form 26Q 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 16A certificates for deductees.
For the full end-to-end filing steps, follow the File Form 26Q TDS Returns recipe, which builds on top of the TXT generated here.