> ## Documentation Index > Fetch the complete documentation index at: https://developer.sandbox.co.in/llms.txt > Use this file to discover all available pages before exploring further. # Fetch TDS challan details > Fetch TDS challan details from TRACES for a TAN using the challan's BSR code, deposit date, and serial number. Before you fetch TDS challan details, [add the TRACES credentials](/api-reference/tds/compliance/traces-credentials/endpoints/save_credential) for the TAN. If the credentials already exist, you do not need to add them again. To find challans by deposit date, use [Search TDS challans](/api-reference/tds/compliance/challans/endpoints/search_challans). See [Check TDS challans](/recipes/tds/challans/check-tds-challans) for credential setup and cURL examples. ## OpenAPI ````yaml api-reference/tds/compliance/openapi.json POST /tds/compliance/traces/deductors/challans openapi: 3.1.0 info: title: compliance description: >- Tax Deducted at Source (TDS) is an indirect method of collecting Income Tax. TDS is based on the principle of “Pay as you earn” which is beneficial for both the Government and the taxpayer. It is where a person making a payment of specified nature is liable to deduct tax at a prescribed rate. This ensures continuous revenue for the Government by way of Tax Deducted at the Source. The Payer making a payment is also responsible to deposit TDS with the Income Tax Department within a specified date and file a TDS Return. Once filed, the deposited amount will be shown in the Payee's Form 26AS which they can then use to claim tax credits when filing ITR. However, staying TDS compliant can be a hassle for businesses, as they are required to : 1. Deduct TDS from payments that are liable for TDS Deduction at an appropriate rate. 2. Deposit TDS to Government before the due date. 3. File TDS Returns on a Quarterly basis. 4. Issue a TDS Certificate by the deductor to the deductee. Organizations deducting TDS have to remain compliant with each of the steps. Failure to do so results in TDS Penalties by Authorities. Sandbox provides TDS Compliance APIs to help you automate end-to-end TDS compliance. version: 1.0.0 servers: [] security: [] tags: - name: TDS Compliance Check - name: Download CSI - name: FVU Generation - name: E-File TDS Return - name: TRACES - name: TRACES/TDS Certificate - name: TRACES/Credentials - name: TRACES/Challans - name: TDS - name: TDS Certificate - name: TRACES Credentials - name: Challans paths: /tds/compliance/traces/deductors/challans: post: tags: - TRACES/Challans - TRACES - Challans summary: Get challan description: >- Retrieves a TDS challan and its tax and available consumption details from TRACES. Identify the challan using the deductor's TAN, BSR code, deposit date, and challan serial number. The deposit date uses epoch milliseconds and the Asia/Kolkata calendar date. Requires registered TRACES deductor credentials for the requested TAN and Sandbox authentication. Returns HTTP 521 when no challan matches the supplied particulars. A null consumption_details value means utilization details are unavailable; it does not indicate an unused challan. operationId: getChallan parameters: - name: Authorization in: header description: >- JWT access token. For token-generation steps, refer to the [Quickstart Guide](https://developer.sandbox.co.in/guides/get-started/quickstart). required: true example: '{{access_token}}' schema: type: string - name: x-api-key in: header description: API key used to identify and authenticate the client. required: true example: '{{api_key}}' schema: type: string - name: Content-Type in: header description: Request body format. required: true example: application/json schema: type: string requestBody: content: application/json: schema: $ref: '#/components/schemas/ChallanLookupRequest' examples: Challan found: value: '@entity': in.co.sandbox.tds.compliance.challan.request tan: AHMA12345A bsr_code: '0123456' challan_serial: '00042' paid_date_epoch: 1784053800000 summary: Challan found TRACES credentials not stored: value: '@entity': in.co.sandbox.tds.compliance.challan.request tan: AHMA12345A bsr_code: '0123456' challan_serial: '00042' paid_date_epoch: 1784053800000 summary: TRACES credentials not stored Incorrect TRACES credentials: value: '@entity': in.co.sandbox.tds.compliance.challan.request tan: AHMA12345A bsr_code: '0123456' challan_serial: '00042' paid_date_epoch: 1784053800000 summary: Incorrect TRACES credentials TRACES login unavailable: value: '@entity': in.co.sandbox.tds.compliance.challan.request tan: AHMA12345A bsr_code: '0123456' challan_serial: '00042' paid_date_epoch: 1784053800000 summary: TRACES login unavailable required: true responses: '200': description: The matching challan with its tax and available consumption details. content: application/json: schema: type: object properties: code: type: integer const: 200 description: HTTP status code. timestamp: type: integer description: Response timestamp in epoch milliseconds. transaction_id: type: string description: Unique identifier for this API request. data: $ref: '#/components/schemas/Challan' required: - code - timestamp - transaction_id - data additionalProperties: false x-apidog-ignore-properties: [] x-apidog-orders: - code - timestamp - transaction_id - data examples: Challan found: summary: Challan found description: Fictional example data. value: code: 200 timestamp: 1791829800000 transaction_id: 87c1b4f6-1632-4d8b-a2f9-05f291c00a42 data: '@entity': in.co.sandbox.tds.compliance.challan.response tan: AHMA12345A bsr_code: '0123456' challan_serial: '00042' paid_date_epoch: 1784053800000 challan_identification_number: '01234561507202600042' receipt_number: '9000000001' financial_year: FY 2026-27 major_head: '0021' minor_head: '200' total_amount: 1500 status: CLAIMED section_code: 94D residency_status: R tax_breakdown: - '@entity': in.co.sandbox.tds.compliance.challan.tax_breakdown section: '393(1) [Table: Sl. No. 1(i)]' tax_amount: 1500 surcharge: 0 cess: 0 total_amount: 1500 consumption_details: null headers: {} x-apidog-name: Success x-apidog-ordering: 0 '400': description: The request body is malformed or does not match the request schema. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' headers: {} x-apidog-name: Invalid request body x-apidog-ordering: 1 '401': description: >- Sandbox authorization is missing or invalid, or the stored TRACES credentials are incorrect. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' examples: Incorrect TRACES credentials: summary: Incorrect TRACES credentials description: Fictional example data. value: code: 401 timestamp: 1791829800000 transaction_id: 87c1b4f6-1632-4d8b-a2f9-05f291c00a42 message: Invalid credentials headers: {} x-apidog-name: Unauthorized x-apidog-ordering: 2 '403': description: Access is denied for this request. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' headers: {} x-apidog-name: Forbidden x-apidog-ordering: 3 '429': description: The request rate limit has been exceeded. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' headers: {} x-apidog-name: Too Many Requests x-apidog-ordering: 4 '500': description: The challan request could not be completed. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' examples: TRACES login unavailable: summary: TRACES login unavailable description: Fictional example data. value: code: 500 timestamp: 1791829800000 transaction_id: 87c1b4f6-1632-4d8b-a2f9-05f291c00a42 message: Failed to log in to TRACES headers: {} x-apidog-name: Failed to fetch TRACES challans x-apidog-ordering: 5 '503': description: TRACES is temporarily unavailable. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' headers: {} x-apidog-name: Source Unavailable x-apidog-ordering: 6 '521': description: >- TRACES credentials are not stored for this TAN, or no challan matches the supplied payment details. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' examples: TRACES credentials not stored: summary: TRACES credentials not stored description: Fictional example data. value: code: 521 timestamp: 1791829800000 transaction_id: 87c1b4f6-1632-4d8b-a2f9-05f291c00a42 message: Credentials not found headers: {} x-apidog-name: Challan not found x-apidog-ordering: 7 deprecated: false security: [] servers: - url: https://api.sandbox.co.in components: schemas: ChallanLookupRequest: title: ChallanLookupRequest type: object additionalProperties: false properties: '@entity': type: string default: in.co.sandbox.tds.compliance.challan.request enum: - in.co.sandbox.tds.compliance.challan.request description: Identifies the type of this object. id: type: string description: Object identifier, when available. description: type: string description: Additional information about the object, when available. created_at: type: string description: Creation timestamp, when available. updated_at: type: string description: Last update timestamp, when available. tan: type: string pattern: ^[A-Z]{4}[0-9]{5}[A-Z]$ description: Tax Deduction and Collection Account Number (TAN) of the deductor. bsr_code: type: string pattern: ^[0-9]{7}$ description: >- Basic Statistical Return (BSR) code of the bank branch where the challan was deposited. challan_serial: type: string pattern: ^[0-9]{5}$ description: Five-digit challan serial number, including leading zeroes. paid_date_epoch: type: integer minimum: 0 description: >- Deposit date in epoch milliseconds. The calendar date is interpreted in Asia/Kolkata. required: - '@entity' - tan - bsr_code - challan_serial - paid_date_epoch description: Particulars that identify a TDS challan for a deductor. x-apidog-ignore-properties: [] x-apidog-orders: - '@entity' - id - description - created_at - updated_at - tan - bsr_code - challan_serial - paid_date_epoch x-apidog-folder: '' Challan: title: Challan type: object additionalProperties: false properties: '@entity': type: string default: in.co.sandbox.tds.compliance.challan.response enum: - in.co.sandbox.tds.compliance.challan.response description: Identifies the type of this object. id: type: string description: Object identifier, when available. description: type: string description: Additional information about the object, when available. created_at: type: string description: Creation timestamp, when available. updated_at: type: string description: Last update timestamp, when available. tan: type: string description: Tax Deduction and Collection Account Number (TAN) of the deductor. bsr_code: type: string description: >- Basic Statistical Return (BSR) code of the bank branch where the challan was deposited. challan_serial: type: string description: Five-digit challan serial number, including leading zeroes. paid_date_epoch: type: integer description: >- Deposit date in epoch milliseconds. The calendar date is interpreted in Asia/Kolkata. challan_identification_number: type: string description: Challan Identification Number (CIN) reported by TRACES. receipt_number: type: string description: Receipt number reported by TRACES. financial_year: type: string description: >- Financial year reported by TRACES in FY YYYY-YY format. This year can differ from the financial year of the deposit date. major_head: type: string description: Major head of tax, including leading zeroes, such as 0021. minor_head: type: string description: Minor head of payment, such as 200. total_amount: type: number description: Total amount in INR. status: type: string description: Challan matching status reported by TRACES. section_code: type: - string - 'null' description: >- Legacy section code reported by TRACES, or null if unavailable. This code can be present even when tax_breakdown is empty. residency_status: type: - string - 'null' description: Residency status code reported by TRACES, or null if unavailable. tax_breakdown: type: array items: title: ChallanTaxBreakdown type: object additionalProperties: false properties: '@entity': type: string default: in.co.sandbox.tds.compliance.challan.tax_breakdown enum: - in.co.sandbox.tds.compliance.challan.tax_breakdown description: Identifies the type of this object. id: type: string description: Object identifier, when available. description: type: string description: Additional information about the object, when available. created_at: type: string description: Creation timestamp, when available. updated_at: type: string description: Last update timestamp, when available. section: type: string description: TDS section reported by TRACES for this tax breakdown. tax_amount: type: number description: Base tax amount in INR, excluding surcharge and cess. surcharge: type: number description: Surcharge amount in INR. cess: type: number description: Cess amount in INR. total_amount: type: number description: Total amount in INR. required: - '@entity' - section - tax_amount - surcharge - cess - total_amount description: >- Tax, surcharge, and cess for a section reported against the challan. All amounts are in INR. x-apidog-ignore-properties: [] x-apidog-orders: - '@entity' - id - description - created_at - updated_at - section - tax_amount - surcharge - cess - total_amount description: >- Section-wise tax breakdown in INR. An empty list means no breakdown is available. consumption_details: title: ChallanConsumptionDetails description: >- Statement utilization reported by TRACES. null means utilization details are unavailable and does not indicate an unused challan. type: - object - 'null' additionalProperties: false properties: '@entity': type: string default: in.co.sandbox.tds.compliance.challan.consumption_details enum: - in.co.sandbox.tds.compliance.challan.consumption_details description: Identifies the type of this object. id: type: string description: Object identifier, when available. description: type: string description: Additional information about the object, when available. created_at: type: string description: Creation timestamp, when available. updated_at: type: string description: Last update timestamp, when available. statement_token_number: type: string description: >- Token number of the statement against which the challan was claimed. financial_year: type: string pattern: ^FY [0-9]{4}-[0-9]{2}$ description: >- Financial year of the reported TDS statement in FY YYYY-YY format. quarter: type: string description: Quarter of the TDS statement, from Q1 to Q4. form: type: string description: TDS statement form code reported by TRACES. status: type: string description: Consumption status of the challan in the reported statement. claimed_amount: type: number description: >- Amount claimed against the challan in the reported statement, in INR. excess_claimed_amount: type: number description: Excess claimed amount reported by TRACES, in INR. available_amount: type: number description: Available challan amount reported by TRACES, in INR. required: - '@entity' - statement_token_number - financial_year - quarter - form - status - claimed_amount - excess_claimed_amount - available_amount x-apidog-ignore-properties: [] x-apidog-orders: - '@entity' - id - description - created_at - updated_at - statement_token_number - financial_year - quarter - form - status - claimed_amount - excess_claimed_amount - available_amount required: - '@entity' - tan - bsr_code - challan_serial - paid_date_epoch - challan_identification_number - receipt_number - financial_year - major_head - minor_head - total_amount - status - section_code - residency_status - tax_breakdown - consumption_details description: >- A TDS challan with its tax breakdown and available utilization details from TRACES. All amounts are in INR. x-apidog-ignore-properties: [] x-apidog-orders: - '@entity' - id - description - created_at - updated_at - tan - bsr_code - challan_serial - paid_date_epoch - challan_identification_number - receipt_number - financial_year - major_head - minor_head - total_amount - status - section_code - residency_status - tax_breakdown - consumption_details x-apidog-folder: '' ErrorResponse: type: object additionalProperties: false required: - code - timestamp - transaction_id - message properties: code: type: integer description: HTTP status code. timestamp: type: integer format: int64 description: Response timestamp in epoch milliseconds. transaction_id: type: string description: Transaction identifier used to trace the API request. message: type: string description: Error message. x-apidog-orders: - code - timestamp - transaction_id - message x-apidog-ignore-properties: [] x-apidog-folder: '' ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.