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

# Create a bulk PAN verification job

> Create a TRACES bulk PAN verification job for a TAN and receive a signed URL to upload the JSON payee workbook.

Save the [TRACES credentials](/api-reference/tds/compliance/traces-credentials/endpoints/save_credential) for the TAN in your Sandbox workspace. Sandbox manages TRACES authentication during processing.

After creating the job, upload the [JSON payee workbook](/api-reference/tds/compliance/pan-verification/payee_workbook) to `data.json_url` with HTTP PUT. Then use `data.job_id` to [check the job status](/api-reference/tds/compliance/pan-verification/endpoints/poll_job).

<Note>
  Credential checks happen after the workbook upload. Missing or incorrect TRACES credentials appear as a `failed` job with a `message` in the status response.
</Note>

For cURL examples covering the complete workflow, see [Verify PANs in bulk](/recipes/tds/pan-verification/verify-pans-in-bulk).


## OpenAPI

````yaml api-reference/tds/compliance/openapi.json POST /tds/compliance/enriched/traces/deductors/pan/verify
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:
  - url: https://test-api.sandbox.co.in
    description: test
  - url: https://api.sandbox.co.in
    description: prod
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/enriched/traces/deductors/pan/verify:
    post:
      tags:
        - TDS
        - TRACES
        - PAN Verification
      summary: Create bulk PAN verification job
      description: >-
        Creates an enriched bulk PAN verification job for the supplied TAN.
        Sandbox manages TRACES authentication using your stored credentials. The
        response contains a job ID and a signed URL for the input JSON workbook.
        Upload the workbook with HTTP PUT and Content-Type application/json.


        Save the [TRACES
        credentials](https://developer.sandbox.co.in/api-reference/tds/compliance/traces-credentials/endpoints/save_credential)
        for the TAN before processing. Credential checks happen after the
        workbook upload. Missing or incorrect credentials appear as a failed job
        when you retrieve its status.


        The uploaded JSON file must be at most 5,000,000 bytes. The workbook
        contains payee_sheet and payee_table with the header ["sr_no", "pan"].
        PAN values are submitted to TRACES as provided. For repeated PANs,
        verification keeps the first row and ignores later rows.


        Retrieve the job with the returned job_id to check progress and obtain
        the output download URL.


        Input workbook example:


        ```json

        {
          "@entity": "workbook",
          "name": "payee_workbook",
          "sheets": [
            {
              "@entity": "sheet",
              "name": "payee_sheet",
              "blocks": [
                {
                  "@entity": "table",
                  "name": "payee_table",
                  "header": [
                    "sr_no",
                    "pan"
                  ],
                  "rows": [
                    [
                      1,
                      "ABCPD1234E"
                    ],
                    [
                      2,
                      "XYZPK5678L"
                    ],
                    [
                      3,
                      "ABCPD1234E"
                    ],
                    [
                      4,
                      "AAAAA1111A"
                    ]
                  ]
                }
              ]
            }
          ]
        }

        ```
      operationId: SubmitPanVerificationJob
      parameters:
        - name: Authorization
          in: header
          description: >-
            Sandbox JWT access token. See 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: Sandbox API key for the request.
          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/PanVerificationRequest'
            examples:
              Job created:
                value:
                  '@entity': in.co.sandbox.tds.compliance.pan.verification.request
                  tan: AHMA12345A
                summary: Job created
                description: >-
                  Create a job and receive a signed URL to upload the payee
                  workbook.
              Missing TAN:
                value:
                  '@entity': in.co.sandbox.tds.compliance.pan.verification.request
                summary: Missing TAN
                description: The request does not include tan.
              Invalid TAN format:
                value:
                  '@entity': in.co.sandbox.tds.compliance.pan.verification.request
                  tan: '12345'
                summary: Invalid TAN format
                description: The TAN does not match the required format.
              Missing authorization:
                value:
                  '@entity': in.co.sandbox.tds.compliance.pan.verification.request
                  tan: AHMA12345A
                summary: Missing authorization
                description: The request does not include the Authorization header.
              Missing API key:
                value:
                  '@entity': in.co.sandbox.tds.compliance.pan.verification.request
                  tan: AHMA12345A
                summary: Missing API key
                description: The request does not include the x-api-key header.
        required: true
      responses:
        '200':
          description: The job is created and ready for the input workbook upload.
          content:
            application/json:
              schema:
                type: object
                properties:
                  code:
                    type: integer
                    enum:
                      - 200
                    description: HTTP status code.
                  timestamp:
                    type: integer
                    format: int64
                    description: Response timestamp in epoch milliseconds.
                  transaction_id:
                    type: string
                    format: uuid
                    description: Unique identifier for this API transaction.
                  data:
                    allOf:
                      - $ref: '#/components/schemas/PanVerificationJob'
                      - type: object
                        properties:
                          status:
                            type: string
                            enum:
                              - created
                required:
                  - code
                  - timestamp
                  - transaction_id
                  - data
              examples:
                Job created:
                  summary: Job created
                  value:
                    code: 200
                    timestamp: 1792136869079
                    data:
                      created_at: 1792136873733
                      '@entity': in.co.sandbox.tds.compliance.pan.verification.job
                      job_id: b5084575-7bdf-4a40-a8db-e19c93d34ec4
                      tan: AHMA12345A
                      status: created
                      json_url: >-
                        https://sandbox-example.s3.ap-south-1.amazonaws.com/example-workspace/b5084575-7bdf-4a40-a8db-e19c93d34ec4/payee.json?X-Amz-Signature=example
                    transaction_id: 6ead62b9-35c9-4c1c-8625-4e0bfdc025d5
          headers: {}
        '400':
          description: The request body or query parameters are invalid.
          content:
            application/json:
              schema:
                type: object
                properties:
                  code:
                    type: integer
                    enum:
                      - 400
                    description: HTTP status code.
                  timestamp:
                    type: integer
                    format: int64
                    description: Response timestamp in epoch milliseconds.
                  transaction_id:
                    type: string
                    format: uuid
                    description: Unique identifier for this API transaction.
                  message:
                    type: string
                    description: Reason the request could not be completed.
                required:
                  - code
                  - timestamp
                  - transaction_id
                  - message
              examples:
                Missing TAN:
                  summary: Missing TAN
                  value:
                    code: 400
                    timestamp: 1792136874200
                    message: Invalid request body
                    transaction_id: 6b31ee70-abdf-4428-8678-67c75d42712a
                Invalid TAN format:
                  summary: Invalid TAN format
                  value:
                    code: 400
                    timestamp: 1792136874678
                    message: Invalid request body
                    transaction_id: 330b6df2-a419-4942-be5d-8ffd1073ada8
          headers: {}
        '401':
          description: Sandbox authorization is missing, invalid, or expired.
          content:
            application/json:
              schema:
                type: object
                properties:
                  code:
                    type: integer
                    enum:
                      - 401
                    description: HTTP status code.
                  timestamp:
                    type: integer
                    format: int64
                    description: Response timestamp in epoch milliseconds.
                  transaction_id:
                    type: string
                    format: uuid
                    description: Unique identifier for this API transaction.
                  message:
                    type: string
                    description: Reason the request could not be completed.
                required:
                  - code
                  - timestamp
                  - transaction_id
                  - message
              examples:
                Missing authorization:
                  summary: Missing authorization
                  value:
                    code: 401
                    message: Unauthorized
                    timestamp: 1792136874846
                    transaction_id: b0b82447-fe6a-4852-a320-405f6744ce08
          headers: {}
        '403':
          description: Access to this API is denied.
          content:
            application/json:
              schema:
                type: object
                properties:
                  code:
                    type: integer
                    enum:
                      - 403
                    description: HTTP status code.
                  timestamp:
                    type: integer
                    format: int64
                    description: Response timestamp in epoch milliseconds.
                  transaction_id:
                    type: string
                    format: uuid
                    description: Unique identifier for this API transaction.
                  message:
                    type: string
                    description: Reason the request could not be completed.
                required:
                  - code
                  - timestamp
                  - transaction_id
                  - message
              examples:
                Missing API key:
                  summary: Missing API key
                  value:
                    code: 403
                    message: Forbidden
                    timestamp: 1792136874924
                    transaction_id: 90caaf62-2271-4172-b711-c5f5a5cc07d2
          headers: {}
        '500':
          description: The API request could not be completed.
          content:
            application/json:
              schema:
                type: object
                properties:
                  code:
                    type: integer
                    enum:
                      - 500
                    description: HTTP status code.
                  timestamp:
                    type: integer
                    format: int64
                    description: Response timestamp in epoch milliseconds.
                  transaction_id:
                    type: string
                    format: uuid
                    description: Unique identifier for this API transaction.
                  message:
                    type: string
                    description: Reason the request could not be completed.
                required:
                  - code
                  - timestamp
                  - transaction_id
                  - message
          headers: {}
      deprecated: false
      security: []
components:
  schemas:
    PanVerificationRequest:
      type: object
      description: >-
        Creates a bulk PAN verification job for a TAN. The payee workbook is
        uploaded separately to the returned signed URL.
      properties:
        '@entity':
          type: string
          enum:
            - in.co.sandbox.tds.compliance.pan.verification.request
          description: Request entity type.
        tan:
          type: string
          pattern: ^[A-Z]{4}[0-9]{5}[A-Z]$
          description: >-
            Tax Deduction and Collection Account Number associated with the
            saved TRACES credentials.
          examples:
            - AHMA12345A
      required:
        - '@entity'
        - tan
      additionalProperties: false
    PanVerificationJob:
      type: object
      description: >-
        A bulk PAN verification job. Upload the input through json_url. A
        succeeded job provides output_json_url. A failed job provides message.
      properties:
        '@entity':
          type: string
          enum:
            - in.co.sandbox.tds.compliance.pan.verification.job
          description: Job entity type.
        job_id:
          type: string
          format: uuid
          description: Unique identifier returned when the job is created.
        tan:
          type: string
          pattern: ^[A-Z]{4}[0-9]{5}[A-Z]$
          description: TAN associated with the verification job.
        status:
          type: string
          enum:
            - created
            - queued
            - in_progress
            - succeeded
            - failed
          description: >-
            Current job status. created waits for the workbook upload. queued
            waits to start processing. in_progress covers workbook validation,
            TRACES authentication and verification, and output workbook
            generation. succeeded means the output JSON workbook is saved.
            failed means processing did not complete.
        created_at:
          type: integer
          format: int64
          description: Job creation timestamp in epoch milliseconds.
        updated_at:
          type: integer
          format: int64
          description: >-
            Last job update timestamp in epoch milliseconds. Omitted from the
            job creation response.
        json_url:
          type: string
          format: uri
          description: >-
            Signed URL for uploading the input JSON workbook with HTTP PUT. The
            input limit is 5,000,000 bytes.
        output_json_url:
          type: string
          format: uri
          description: >-
            Signed URL for downloading the completed output JSON workbook with
            HTTP GET. Available when status is succeeded.
        message:
          type: string
          description: Reason the job failed. Present when status is failed.
      required:
        - '@entity'
        - job_id
        - tan
        - status
        - created_at
      additionalProperties: false
      oneOf:
        - properties:
            status:
              enum:
                - created
                - queued
                - in_progress
          type: object
        - properties:
            status:
              enum:
                - succeeded
          type: object
        - properties:
            status:
              enum:
                - failed
          type: object

````

This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.