Skip to main content
Generate Form 131 TDS or Form 133 TCS certificates from TRACES with a deductor access token. You manage the deductor session and continue polling until the certificate job succeeds or fails.

​
Before you start

  • Obtain a Sandbox API key and access token using the Quickstart guide.
  • Keep the deductor’s TAN and TRACES password ready.
  • Confirm that TRACES has processed the relevant statement and made the certificates available for the requested period.
The example generates Form 131 certificates for TY 2026-27, Q1. Replace the sample TAN, period, and placeholders with your own values.

​
Generate Form 131 certificates

1

Authenticate the deductor

Call Authenticate a TRACES deductor with your Sandbox access token in the Authorization header.

Deductor authentication request

Save data.access_token as your deductor access token and data.refresh_token as your deductor refresh token. Use the deductor access token in the Authorization header for certificate requests.
2

Create the certificate job

Call Create a certificate job with a deductor token with 131 in the path. The token identifies the TAN. Send only @entity, tax_year, and quarter in the body.

Certificate job request

Save data.job_id from the response. The job starts with data.status set to in_progress.
3

Check the certificate job status

Call Get certificate job status with a deductor token with the returned job_id and the same certificate type.

Certificate status request

Continue polling while data.status is in_progress, including while TRACES prepares the certificate files. When data.status is failed, stop polling and read data.message for the reason. A failed job still returns HTTP 200.
4

Download the certificate ZIP files

When data.status is succeeded, the response includes one or more signed URLs in data.certificate_pdf_zip_urls.Response excerpt:
Download each ZIP file, which contains certificate PDFs.

Certificate ZIP download request

​
Generate Form 133 TCS certificates

Replace 131 with 133 in both the create and status URLs. Use the same request body fields and deductor authentication flow.

​
Resume after token expiry

If a status request returns HTTP 403 because the deductor access token expired, call Refresh a TRACES deductor session. Send the deductor refresh token in Authorization.
Replace both saved deductor tokens with the returned data.access_token and data.refresh_token. Retry the status request with the new access token and the same job_id. If the refresh token has expired or is rejected, authenticate the same deductor again. Resume polling the existing job_id with the new deductor access token.