> ## 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.

# Search TDS challans

> Search TDS challans on TRACES for a TAN and deposit date range. Use optional pagination to retrieve the matching challan records.

<Note>
  Before you search TDS challans, [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.
</Note>

To look up a challan with its payment details, use [Fetch TDS challan details](/api-reference/tds/compliance/challans/endpoints/fetch_challan).

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/search
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/search:
    post:
      tags:
        - TRACES/Challans
        - TRACES
        - Challans
      summary: Search challans
      description: >-
        Searches a deductor's TDS challans by deposit-date range and returns one
        page of results from TRACES.


        Provide the deductor's TAN, from_date_epoch, and to_date_epoch. Both
        dates are required and use epoch milliseconds. The calendar dates are
        interpreted in Asia/Kolkata.


        page_number starts at 0. page_size specifies the number of challans
        requested per page. Both fields are optional.


        The response includes the challans in data and the pagination totals
        totalPages and totalElements. A page with no challans returns HTTP 200
        with an empty data list.


        Requires registered TRACES deductor credentials for the requested TAN
        and Sandbox authentication.
      operationId: searchChallans
      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/ChallanSearchRequest'
            examples:
              Challans found within the date range:
                value:
                  '@entity': in.co.sandbox.tds.compliance.challan.search
                  tan: AHMA12345A
                  from_date_epoch: 1782844200000
                  to_date_epoch: 1785436200000
                  page_number: 0
                  page_size: 10
                summary: Challans found within the date range
              No challans found within date range:
                value:
                  '@entity': in.co.sandbox.tds.compliance.challan.search
                  tan: AHMA12345A
                  from_date_epoch: 1785522600000
                  to_date_epoch: 1788114600000
                  page_number: 0
                  page_size: 10
                summary: No challans found within date range
              Challans found on the next page:
                value:
                  '@entity': in.co.sandbox.tds.compliance.challan.search
                  tan: AHMA12345A
                  from_date_epoch: 1788201000000
                  to_date_epoch: 1790706600000
                  page_number: 1
                  page_size: 1
                summary: Challans found on the next page
        required: true
      responses:
        '200':
          description: >-
            One page of challans with pagination totals. The data list is empty
            when the page contains no challans.
          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/ChallanSearchResponse'
                required:
                  - code
                  - timestamp
                  - transaction_id
                  - data
                additionalProperties: false
                x-apidog-ignore-properties: []
                x-apidog-orders:
                  - code
                  - timestamp
                  - transaction_id
                  - data
              examples:
                Challans found within the date range:
                  summary: Challans found within the date range
                  description: Fictional example data.
                  value:
                    code: 200
                    timestamp: 1791829800000
                    transaction_id: 87c1b4f6-1632-4d8b-a2f9-05f291c00a42
                    data:
                      '@entity': in.co.sandbox.tds.compliance.challan.search.response
                      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
                      totalPages: 1
                      totalElements: 1
                No challans found within date range:
                  summary: No challans found within date range
                  description: Fictional example data.
                  value:
                    code: 200
                    timestamp: 1791829800000
                    transaction_id: 87c1b4f6-1632-4d8b-a2f9-05f291c00a42
                    data:
                      '@entity': in.co.sandbox.tds.compliance.challan.search.response
                      data: []
                      totalPages: 0
                      totalElements: 0
                Challans found on the next page:
                  summary: Challans found on the next page
                  description: Fictional example data.
                  value:
                    code: 200
                    timestamp: 1791829800000
                    transaction_id: 87c1b4f6-1632-4d8b-a2f9-05f291c00a42
                    data:
                      '@entity': in.co.sandbox.tds.compliance.challan.search.response
                      data:
                        - '@entity': in.co.sandbox.tds.compliance.challan.response
                          tan: AHMA12345A
                          bsr_code: '0123456'
                          challan_serial: '00043'
                          paid_date_epoch: 1789497000000
                          challan_identification_number: '01234561609202600043'
                          receipt_number: '9000000002'
                          financial_year: FY 2026-27
                          major_head: '0021'
                          minor_head: '200'
                          total_amount: 2000
                          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: 2000
                              surcharge: 0
                              cess: 0
                              total_amount: 2000
                          consumption_details: null
                      totalPages: 2
                      totalElements: 2
          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'
          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'
          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: >-
            No TRACES credentials are stored for the deductor TAN in the
            workspace.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          headers: {}
          x-apidog-name: Credentials not found
          x-apidog-ordering: 7
      deprecated: false
      security: []
      servers:
        - url: https://api.sandbox.co.in
components:
  schemas:
    ChallanSearchRequest:
      title: ChallanSearchRequest
      description: >-
        Deposit-date filters for a deductor's challan search. Both dates are
        required. Pagination is optional.
      type: object
      additionalProperties: false
      properties:
        '@entity':
          type: string
          default: in.co.sandbox.tds.compliance.challan.search
          enum:
            - in.co.sandbox.tds.compliance.challan.search
          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.
        from_date_epoch:
          type: integer
          minimum: 0
          description: >-
            Start of the deposit-date range in epoch milliseconds, interpreted
            in Asia/Kolkata.
        to_date_epoch:
          type: integer
          minimum: 0
          description: >-
            End of the deposit-date range in epoch milliseconds, interpreted in
            Asia/Kolkata.
        page_number:
          type: integer
          minimum: 0
          description: >-
            Zero-based page number. 0 requests the first page. Omit to use the
            default page.
        page_size:
          type: integer
          minimum: 1
          description: >-
            Number of challans requested per page. Omit to use the default page
            size.
      required:
        - '@entity'
        - tan
        - from_date_epoch
        - to_date_epoch
      x-apidog-ignore-properties: []
      x-apidog-orders:
        - '@entity'
        - id
        - description
        - created_at
        - updated_at
        - tan
        - from_date_epoch
        - to_date_epoch
        - page_number
        - page_size
      x-apidog-folder: ''
    ChallanSearchResponse:
      title: ChallanSearchResponse
      type: object
      additionalProperties: false
      properties:
        '@entity':
          type: string
          default: in.co.sandbox.tds.compliance.challan.search.response
          enum:
            - in.co.sandbox.tds.compliance.challan.search.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.
        data:
          type: array
          items:
            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
          description: >-
            Challans in the requested page. An empty list means no challans were
            returned for that page.
        totalPages:
          type: integer
          minimum: 0
          description: Total number of result pages reported by TRACES.
        totalElements:
          type: integer
          minimum: 0
          description: Total number of matching challans reported by TRACES.
      required:
        - '@entity'
        - data
        - totalPages
        - totalElements
      description: One page of challans with pagination totals reported by TRACES.
      x-apidog-ignore-properties: []
      x-apidog-orders:
        - '@entity'
        - id
        - description
        - created_at
        - updated_at
        - data
        - totalPages
        - totalElements
      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.