The Basics

Host URLs

Please find below the distinct host URLs for our production and test environments.

EnvironmentHost URL
Testtest-api.sandbox.co.in
Productionapi.sandbox.co.in

Request & Response Structure

Sandbox API requests will take JSON-encoded payloads, query, and path parameters and provide standard JSON-encoded responses. All GET and DELETE API requests take path and/or query parameters. Meanwhile, POST API request accepts JSON-encoded body. Please note that there might be some exceptions which will be informed in the API doc and reference.

In some APIs, the JSON body will be in a sheet structure format.

Headers

Below are the headers that need to be present in Sandbox API requests

HeaderTypeDescriptionExample
x-api-keyStringYour API Keykey_live_SIethxxxxxxxxxxxxx
AuthorizationStringJWT TokeneyJhbGcxxxxx.eyJhdJxxxx.Si29xxxxx
x-api-versionStringAPI version. Default is the latest stable version1.0
Content-TypeStringThe content type being sent in the request. Mandatory in case of JSON body in POST API requestapplication/json
x-sourceStringSpecify the source. Default is primarysecondary

Sheet Structure

APIs with volumetric data will either require or respond back in the form of a sheet structure. A sheet structure mimics an Excel or Google Sheet. This allows API users to send/receive more data in a smaller JSON format. The sheet will be divided into multiple blocks, which will have data either in a table or list format.

Click on the button below to see an example workbook for TDS Form 24Q.

View Workbook

In the above workbook, there are four separate sheets, each containing different types of data. The same data represented in a JSON format would look like below.

{
    "name": "Form 26Q",  
    "sheets": [
        {
            "name": "Payer",
            "blocks": [
                {
                    "name": "Payer",
                    "@entity": "list",
                    "items": [
                        [
                            "name",
                            "Acme Pvt Ltd"
                        ],
                        [
                            "tan",
                            "AHMA09719B"
                        ],
                        [
                            "pan",
                            "AAACA1234Z"
                        ],
                        [
                            "branch",
                            "HQ"
                        ],
                        [
                            "gstin",
                            "24AAACA1234Z1ZP"
                        ],
                        [
                            "street",
                            "A-901, Stark Tower"
                        ],
                        [
                            "area",
                            "Relief Road"
                        ],
                        [
                            "city",
                            "Ahmedabad"
                        ],
                        [
                            "state",
                            "GUJARAT"
                        ],
                        [
                            "postal_code",
                            "380001"
                        ],
                        [
                            "email",
                            "[email protected]"
                        ],
                        [
                            "mobile",
                            "9876543210"
                        ]
                    ]
                },
                {
                    "name": "Responsible Person",
                    "@entity": "list",
                    "items": [
                        [
                            "designation",
                            "Finance Manager"
                        ],
                        [
                            "name",
                            "Tony Stark"
                        ],
                        [
                            "pan",
                            "DKLPT3483J"
                        ],
                        [
                            "street",
                            "A-901, Stark Tower"
                        ],
                        [
                            "area",
                            "Relief Road"
                        ],
                        [
                            "city",
                            "Ahmedabad"
                        ],
                        [
                            "state",
                            "GUJARAT"
                        ],
                        [
                            "postal_code",
                            "380001"
                        ],
                        [
                            "email",
                            "[email protected]"
                        ],
                        [
                            "mobile",
                            "9876543210"
                        ]
                    ]
                }
            ]
        },
        {
            "name": "Payee",
            "blocks": [
                {
                    "name": "Payee",
                    "@entity": "table",
                    "header": [
                        "sr_no",
                        "pan",
                        "name"
                    ],
                    "rows": [
                        [
                            1,
                            "COWPR1618C",
                            "Aarya Stark"
                        ],
                        [
                            2,
                            "PANNOTAVBL",
                            "Marya Stark"
                        ],
                        [
                            3,
                            "PANAPPLIED",
                            "Karya Stark"
                        ],
                        [
                            4,
                            "PANINVALID",
                            "Barya Stark"
                        ],
                        [
                            5,
                            "PANNOTAVBL",
                            "Sarya Stark"
                        ]
                    ]
                }
            ]
        },
        {
            "name": "Challan",
            "blocks": [
                {
                    "name": "Challan",
                    "@entity": "table",
                    "header": [
                        "challan_serial",
                        "bsr_code",
                        "paid_date",
                        "minor_head",
                        "tds_amount",
                        "surcharge",
                        "health_and_education_cess",
                        "interest",
                        "late_filing_fees",
                        "other_penalty"
                    ],
                    "rows": [
                        [
                            "12345",
                            "1234567",
                            1656547200000,
                            "(200) TDS Payable by Tax Payer",
                            20000,
                            0,
                            800,
                            80,
                            0,
                            0
                        ]
                    ]
                }
            ]
        },
        {
            "name": "Payment",
            "blocks": [
                {
                    "name": "Payment",
                    "@entity": "table",
                    "header": [
                        "payee_sr_no",
                        "challan_serial",
                        "bsr_code",
                        "section",
                        "credit_amount",
                        "credit_date",
                        "tds_amount",
                        "surcharge",
                        "health_and_education_cess",
                        "deduction_date",
                        "reason_for_lower_deduction",
                        "certificate_number",
                        "amount_of_cash_withdrawal_more_than_1_crore_us_194N",
                        "amount_of_cash_withdrawal_between_20_lakhs_and_1_crore_us_194N_for_non_filers",
                        "amount_of_cash_withdrawal_more_than_1_crore_us_194N_for_non_filers",
                      	"amount_of_cash_withdrawal_more_than_3_crore_us_194N_for_co-operative_societies",
                      	"amount_of_cash_withdrawal_between_20_lakhs_and_3_crore_us_194N_for_non_filers",
                      	"amount_of_cash_withdrawal_more_than_3_crore_us_194N_for_non_filers"
                    ],
                    "rows": [
                        [
                            1,
                            "12345",
                            "1234567",
                            "194 - Dividend",
                            20000,
                            1680245287000,
                            900,
                            0,
                            36,
                            1680245287000
                        ]
                    ]
                }
            ]
        }
    ]
}