Skip to main content
Form 16 is the TDS certificate that employers must issue to employees after filing Form 24Q. This recipe shows how to:
  • Ensure Form 24Q is filed for the given TAN, year, and quarter
  • Trigger Form 16 generation via Sandbox TDS Compliance APIs
  • Fetch and download the generated Form 16 certificates
Before you begin, make sure you’ve:
  • Generated a Sandbox authorization token using the Authenticate endpoint.
  • Filed your Form 24Q TDS return for the relevant financial year and quarter (typically Q4 for Form 16).
  • TRACES credentials (username & password) for the employer TAN.
1

File Form 24Q TDS Return

Employers must finish filing their Form 24Q TDS return before generating Form 16. If this is already done via the File Form 24Q TDS Returns recipe, you can skip directly to Step 2.To programmatically confirm that a Form 24Q return has been filed (or is in progress), you can use the Search E-File TDS Return Jobs API for the given TAN, financial year, quarter, and form.

cURL Request – Search E-File TDS Return Jobs

curl --request POST \
  --url https://api.sandbox.co.in/tds/compliance/e-file/search \
  --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.compliance.e-file.search",
    "tan": "AHMA09719B",
    "quarter": "Q4",
    "form": "24Q",
    "financial_year": "FY 2024-25",
    "from_date": 1711929600000,
    "to_date": 1750463999000,
    "page_size": 20
  }'
Look for a job with:
  • form = 24Q
  • quarter = Q4
  • status = succeeded
This confirms that the Form 24Q return is filed and you can safely proceed to generating Form 16.
2

Generate Form 16

Once the Form 24Q return is filed, you can initiate Form 16 generation using the Download Form 16 – Submit Job API.This API logs into TRACES using the employer’s credentials, validates challan & return details, and creates a job to generate Form 16 (Part A and Part B) for the selected TAN, quarter, financial year, and form.
For Form 16, you must typically use form = 24Q and quarter = Q4, since Form 16 is issued for the full financial year’s salary TDS.

cURL Request – Submit Form 16 Download Job

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: xxxxxxxxxxxxxxxxxx' \
  --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",
      "provisional_receipt_number": "123456789012345",
      "challan_amount": 100000,
      "unique_pan_amount_combination_for_challan": [
        [
          "ABCDE1234F|50000"
        ],
        [
          "PQRSX9876Z|50000"
        ]
      ]
    },
    "remember_me": true
  }'
A successful response returns a certificate job:
  • job_id – identifier for the Form 16 generation job
  • tan, financial_year, quarter, form – job context
  • status – typically created or queued initially
  • remember_me – whether credentials are stored for easier polling
  • If remember_me is true, you can poll the job status without resending TRACES credentials on every request.
  • If remember_me is false, you’ll need to pass credentials again while polling (as per the Form 16 Remember Credentials behaviour).
3

Fetch Form 16 Certificates

After submitting the Form 16 job, you need to check when the certificates are generated and ready to download.There are two useful APIs here:
  • Poll Job – to check the status of a specific Form 16 job
  • Fetch Jobs – to list all jobs and their statuses for a TAN/period

​
3.1 Poll a specific Form 16 job

Use the Poll Job endpoint with the job_id from Step 2:

cURL Request – Poll Form 16 Job Status

curl --request POST \
  --url 'https://api.sandbox.co.in/tds/compliance/traces/deductors/forms/form16/status?job_id={job_id}' \
  --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.compliance.traces.credentials",
    "username": "traces-username",
    "password": "traces-password",
    "tan": "AHMA09719B"
  }'
When processing is complete, the job status will move to succeeded (or failed if there was an error such as invalid challan details or no Form 16 available for that period).

​
3.2 Fetch all Form 16 jobs and download certificates

To get a list of all Form 16 download jobs (and, depending on contract, the corresponding download URLs), use the Fetch Jobs endpoint:
curl --request POST \
  --url https://api.sandbox.co.in/tds/compliance/traces/deductors/forms/form16/search \
  --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.compliance.certificate.job.search",
    "tan": "AHMA09719B",
    "quarter": "Q4",
    "form": "24Q",
    "financial_year": "FY 2024-25",
    "from_date": 1711929600000,
    "to_date": 1750463999000,
    "page_size": 20
  }'
The response includes a list of jobs with their status:
  • status = “succeeded” – Form 16 certificates are generated and ready
  • status = “failed” – job failed (for example, wrong TRACES credentials or Form 16 not yet available)
For succeeded jobs, you can use the certificate download URLs provided in the job metadata (for example, a ZIP of all Form 16 PDFs for the specified TAN, year, and quarter). Download and store these PDFs in your system, and expose them to employees through your HR or payroll portal.
Form 16 for salary TDS is typically available only for Q4 Form 24Q returns. Make sure you request certificates with form = 24Q and quarter = Q4 for the relevant financial year.