TDS Return Job Status

Confirm the job status of the Prepare TDS Return API and download the TXT file.

Overview

API takes job_id and gives back job status and tds_return URL to download the generated TXT file.

Problem

  • After posting a job using Prepare TDS return API, businesses will require generated TXT file for TDS Filing.

Solution

  • API that provides the status of your TXT file generation.
  • Upon successful completion, you will be provided with a tds_url to download the TXT file.

Endpoint

HTTP MethodResource
GET/tds-reporting/deductors/{tan}/tdsrs/{form}/async

API Endpoint  Contact Us  Free Trial

Request

Follow the below guidelines to pass the Job ID to check the status of your TXT generation.

Path Parameter

ParamTypeDescriptionExample
tanstringTAN of deductorPDES03028F
formstringTDS Return Form26Q

Query Parameters

ParamTypeDescriptionExample
job_idstringJob ID obtained from the previous step.1546372e-6fc5-45bb-a2d9-b18d0c662427
financial_yearstringPattern : FY[0-9]{1,4}-[0-9]{1,2}FY 2022-23
quarterenumQuarter.
Possible values: Q1, Q2, Q3, Q4
Q3

Sample CURL request

curl --request GET \
     --url 'https://api.sandbox.co.in/tds-reporting/deductors/PDES03028F/tdsrs/26Q/async?job_id=1546372e-6fc5-45bb-a2d9-b18d0c662427&financial_year=FY%202022-23&quarter=Q3' \
     --header 'Accept: application/json' \
     --header 'Authorization: xxxxxxxxxxxxxxxxxxxxxxxxx' \
     --header 'x-api-key: xxxxxxxxxxxxxxxxx' \
     --header 'x-api-version: 1.0'

Response

ParamTypeDescriptionExample
job_idstringThe Job ID of the particular JOB. 1546372e-6fc5-45bb-a2d9-b18d0c662427
statusstringJob Status. Possible Values:
JOBQUEUED
JOBDONE
JOBFAILED
JOBQUEUED
tds_returnstringLink from where you can download the generated TXT file. Will be provided when the status is JOBDONEhttps://.

..

Sample TXT and Validation Report

1^FH^NS1^R^30082022^1^D^AHMD00000A^1^Protean RPU 4.3^^^^^^^^
2^BH^1^1^26Q^^^^391119600483411^^^^AHMD00000A^^XYZPG0000N^202324^202223^Q1^JOHN^NA^FLAT NO^BUILDING^ROAD^AREA^CITY^36^500081^[email protected]^91^8100000000^N^Q^JOHN^SELF^FLAT NO^BUILDING^ROAD^AREA^CITY^36^500081^[email protected]^8100000000^^^N^10000.00^^^^N^Y^^^^^^^XYZPG0000N^^^^^^^^^^^^^
3^CD^1^1^1^N^^^^^^00949^^^^6390340^^01062022^^^^10000.00^0.00^0.00^0.00^0.00^10000.00^^10000.00^10000.00^0.00^0.00^10000.00^0.00^0.00^^N^^0.00^200^
4^DD^1^1^1^O^^2^^ABCPE1234F^^^WILLIAM^10000.00^0.00^0.00^10000.00^^10000.00^^^100000.00^31052022^31052022^^10.0000^^^^^^^94A^^^^^^^^^^^^^^^

{
    "sheets": [
        {
            "name": "TDS Return",
            "blocks": [
                {
                    "name": "Metadata",
                    "@entity": "table",
                    "header": [
                        "field_name",
                        "level",
                        "issue_type",
                        "message"
                    ]
                }
            ]
        },
        {
            "name": "Payer",
            "blocks": [
                {
                    "name": "Payer",
                    "@entity": "table",
                    "header": [
                        "field_name",
                        "level",
                        "issue_type",
                        "message"
                    ],
                    "rows": [
                        [
                            "tan",
                            "ERROR",
                            "REQUIRED",
                            "TAN is required"
                        ],
                        [
                            "street",
                            "ERROR",
                            "MAX_LENGTH",
                            "Street can not be more than 25 charcters"
                        ]
                    ]
                },
                {
                    "name": "Responsible Person",
                    "@entity": "table",
                    "header": [
                        "field_name",
                        "level",
                        "issue_type",
                        "message"
                    ],
                    "rows": [
                        [
                            "pan",
                            "ERROR",
                            "REQUIRED",
                            "PAN is required"
                        ],
                        [
                            "designation",
                            "ERROR",
                            "REQUIRED",
                            "Designation is required"
                        ]
                    ]
                }
            ]
        },
        {
            "name": "Payee",
            "blocks": [
                {
                    "name": "Payee",
                    "@entity": "table",
                    "header": [
                        [
                            "record_no",
                            "field_name",
                            "level",
                            "issue_type",
                            "message"
                        ]
                    ],
                    "rows": [
                        [
                            1,
                            "pan",
                            "ERROR",
                            "PATTERN",
                            "Invalid PAN"
                        ]
                    ]
                }
            ]
        },
        {
            "name": "Challan",
            "blocks": [
                {
                    "name": "Challan",
                    "@entity": "table",
                    "header": [
                        [
                            "record_no",
                            "field_name",
                            "level",
                            "issue_type",
                            "message"
                        ]
                    ],
                    "rows": [
                        [
                            1,
                            "bsr_code",
                            "ERROR",
                            "PATTERN",
                            "Invalid BSR Code"
                        ],
                        [
                            1,
                            "paid_date",
                            "ERROR",
                            "CUSTOM",
                            "Paid on date doesn't fall within the period"
                        ]
                    ]
                }
            ]
        },
        {
            "name": "Payment",
            "blocks": [
                {
                    "name": "Payment",
                    "@entity": "table",
                    "header": [
                        [
                            "record_no",
                            "field_name",
                            "level",
                            "issue_type",
                            "message"
                        ]
                    ],
                    "rows": [
                        [
                            1,
                            "bsr_code",
                            "ERROR",
                            "CUSTOM",
                            "Invalid BSR Code"
                        ],
                        [
                            1,
                            "section",
                            "ERROR",
                            "ENUM",
                            "Invalid Section"
                        ]
                    ]
                }
            ]
        }
    ]
}

Validation Attribute

ParamTypeDescription
record_nonumberRow number
filed_namestringAttribute name
levelenumPossible values are :
ERROR, WARNING
issue_typeenumPossible values are :
REQUIRED, PATTERN, ENUM, MIN, MAX, MIN_LENGTH, MAX_LENGTH, CUSTOM
messagestringValidation description message

Response Caching

Response caching is not available for this API. Learn more about our response caching mechanism here

Wallet Charges

Since TDS Return Job Status API is not a Paid API, no wallet charge will take place.

Versioning

This API is currently in major version 1.0. Refer to our versioning policies here