TDS Reporting API

Overview

  • This endpoint allows you download TXT file which is required to file TDS Return by taking in `raw body that must contain payee, payer, payment, and challan details.

Problem

  • The TXT file is to be generated in a format that is to be consistent with the income tax department.

Solution

  • The API will automate the generation of the TXT file which is required to file quarterly TDS returns.

Endpoint

Sync API

HTTP Method

Resource

Description

POST

deductors/{tan}/tdsrs/{form}

Accepts a Raw body which contains the payee, payer, payment and challan details. Queues a JOB and returns a job id.

πŸ“˜ Note that the limit for JSON file size is 6mb compressed for the Sync API

Async API

HTTP MethodResourceDescription
POSTdeductors/{tan}/tdsrs/{form}/asyncAccepts a Raw body which contains the payee, payer, payment and challan details. Queues a JOB and returns a job id.
GETdeductors/{tan}/tdsrs/{form}Accepts job id and on JOBDONE returns TXT and on JOBFAILURE return validation report.

API EndpointAPI Endpoint

Request

Path Parameter

ParamTypeDescriptionExample
tanstringTAN of deductorPDES03028F
formenumTDS return form24Q, 26Q, 27Q

Query Parameter

ParamTypeDescriptionExample
financial_yearstringPattern : FY[0-9]{1,4}-[0-9]{1,2}FY 2022-23
quarterenumQ1, Q2, Q3, Q4
previous_rrr_numberstringPattern : [0-9]{15}
filing_typeenumOriginal Revised

Body

Payer

ParamTypeRequiredValidationDescription
namestringYesMax Length : 75Name of the Payer
tanstringYesPattern : [A-Z]{4}[0-9]{5}[A-Z]{1}TAN of the Payer
panstringYesPattern : [A-Z]{3}[PCFTGHLABJ]{1}[A-Z]{1}[0-9]{4}[A-Z]{1}PAN of the Payer
gstinstringNoPattern : [0-9]{2}[a-zA-Z]{5}[0-9]{4}[a-zA-Z]{1}[1-9A-Za-z]{1}[CZ]{1}[0-9a-zA-Z]{1}$|^[0-9]{4}[a-zA-Z]{3}[0-9]{5}[uUnN]{2}[0-9a-zA-Z]{1}GSTIN of the Payer
branchstringNoMax Length : 75Branch details of the Payer if multiple locations.
streetstringYesMax Length : 25Name of premise
areastringYesMax Length : 25Area of location
citystringYesMax Length : 25City of location
stateenumYesAnnexure - 1State of location
postal_codenumberYesPattern : [0-9]{6}Pincode of location
emailstringYesMax Length : 75Primary email for contact
mobilenumberYesPattern: [1-9]{1}[0-9]{9}Primary mobile number for contact

Responsible Person

ParamTypeRequiredValidationDescription
designationstringYesMax Length : 20Designation of the responsible person
namestringYesMax Length : 75Name of the responsible person
panstringYesPattern : [A-Z]{3}[PCFTGHLABJ]{1}[A-Z]{1}[0-9]{4}[A-Z]{1}PAN of the responsible person
streetstringYesMax Length : 25Name of the premise
areastringYesMax Length : 25Area of the location
citystringYesMax Length : 25City of location
stateenumYesAnnexure - 1State of location
postal_codenumberYesPattern : [0-9]{6}Pincode of location
emailstringYesMax Length : 75Primary email for contact
mobilenumberYesPattern: [1-9]{1}[0-9]{9}Primary mobile number for contact

Payee

Param

Type

Required

Validation

Description

sr_no

number

Yes

Serial Number

pan

string

Yes

Pattern : [A-Z]{3}[PCFTGHLABXYZ]{1}[A-Z]{1}[0-9]{4}[A-Z]{1}

PAN of the Payee. If payee doesn't have PAN then possible values are
PANNOTAVBL,PANAPPLIED, PANINVALID, PANNOTREQD

name

string

Yes

Max Length : 75

Name of the Payee

tax_identification
_number

string

Form 27Q - Yes

Max Length : 25

Tax Identification Number of Payee's jurisdication

street

string

Form 27Q - Yes

Max Length : 25

Name of premise of location

area

string

Form 27Q - Yes

Max Length : 25

Area of location

city

string

Form 27Q - Yes

Max Length : 25

City of location

state

string

Form 27Q - Yes

Max Length : 25

State of location

postal_code

string

Form 27Q - Yes

Max Length : 8

Pincode of location

country

enum

Form 27Q - Yes

Annexure - 4

Country of residance

email

string

Form 27Q - Yes

Max Length : 75

Primary email for contact

isd_code

number

Form 27Q - Yes

Max Length : 5

ISD code of country

mobile

number

Form 27Q - Yes

Pattern : [0-9]{10}

Primary mobile number for contact

Challan

ParamTypeRequiredValidationDescription
challan_serialstringYesPattern : [0-9]{5}Bank Challan No
bsr_codestringYesPattern : [0-9]{7}Bank-Branch Code/ Form 24G Receipt Number
paid_datenumberYesTimestamp of challan paid on date
minor_headenumYesAnnexure - 5Minor Head of challan
tds_amountnumberYesLength : 15,2Income Tax
surchargenumberYesLength : 15,2Surcharge on Income Tax
education_cessnumberYesLength : 15,2Education cess on Income Tax
interestnumberYesLength : 15,2Interest levied upon late deduction
late_filing_feesnumberYesLength : 15,2Penalty levied upon late filing
other_penaltynumberYesLength : 15,2Any Other Penalty

Payment

ParamTypeRequiredValidationDescription
payee_sr_nonumberYesPayee Serial Number
challan_serialstringYesPattern : [0-9]{5}Bank Challan No
bsr_codestringYesPattern : [0-9]{7}Bank-Branch Code/ Form 24G Receipt Number
sectionenumYesAnnexure -2TDS section of deduction
credit_amountnumberYesLength : 15,2Payment amount
credit_datenumberYesTime of Payment date
tds_amountnumberYesLength : 15,2Tax amount of deduction
surchargenumberYesLength : 15,2Surcharge on Tax amount
education_cessnumberYesLength : 15,2Eduction of Tax amount
deduction_datenumberYesTimestamp of Deduction date
reason_for_lower_deductionenumNoAnnexure -3Reason for non-deduction / lower deduction/ higher deduction/threshold
certificate_numberstringNoMax Length : 10Certificate number issued by the Assessing Officer u/s 197 for non-deduction/lower deduction.

Note : All the amount should be within 2 decimal places

Annexure - 1 State

State NameState Code
ANDAMAN AND NICOBAR ISLANDS1
ANDHRA PRADESH2
ARUNACHAL PRADESH3
ASSAM4
BIHAR5
CHANDIGARH6
DADRA & NAGAR HAVELI AND DAMAN & DIU7
DELHI9
GOA10
GUJARAT11
HARYANA12
HIMACHAL PRADESH13
JAMMU & KASHMIR14
KARNATAKA15
KERALA16
LAKSHWADEEP17
MADHYA PRADESH18
MAHARASHTRA19
MANIPUR20
MEGHALAYA21
MIZORAM22
NAGALAND23
ODISHA24
PONDICHERRY25
PUNJAB26
RAJASTHAN27
SIKKIM28
TAMIL NADU29
TRIPURA30
UTTAR PRADESH31
WEST BENGAL32
CHHATTISGARH33
UTTARAKHAND34
JHARKHAND35
TELANGANA36
LADAKH37

Annexure-2 Section

SectionCode
193 - Interest on Securities193
194 - Dividend194
194A - Other interest94A
194B - Lotteries / Puzzle / Game94B
194BB - Winnings from Horse Race4BB
194C - Contracts94C
194D - Insurance94D
194EE - NSS Deposit4EE
194F - UTI94F
194G - Commission on Sale of Lottery tickets94G
194H - Commission or Brokerage94H
194I(a) - Rent on Plant and Machinery4IA
194I(b) - Rent on Land & Building4IB
194J - Fees for Professional or Technical services94J
194LA - Acquisition of certain immovable properties94L
194LBA - Certain incomes from Units of Business Trust4BA
194DA - Payment in respect of life insurance policy4DA
192A - Payment of accumulated balance of provident fund, taxable in the hands of the employee2AA
194LBB - Investment fund paying an income to a unit holderLBB
194IA - TDS on sale of property9IA
194LBC - Income in respect of investment in securitization trustLBC
194IC - Payment under specified agreement4IC
194N - Payment of certain amount in cash94N
194K - Income from mutual fund units94K
194J(a) - Fees for technical services, royalty for sale, distribution or exhibition of cinematographic films and call centre4JA
194J(b) - Fee for professional service or royalty4JB
194LBA(a) - Certain income in the form of interest from units of a business trust to a residential unit holderBA1
194LBA(b) - Certain income in the form of dividend from units of a business trust to a resident unit holderBA2
194NF - Payment of certain amounts in cash to non-filers4NF
194O - TDS on E-commerce transactions94O
192 - Payment to Government Employees other than Union Government Employees92A
192 - Payment to Employees other than Government Employees92B
192 - Payments made to Union Government Employees92C
Lower deduction on account of certificate under section 197A
No deduction on account of certificate under section 197B
Deduction of tax at higher rate due to non-availability of PANC
194E - Payments to non-resident Sportsmen/Sport Associations94E
195 - Other sums payable to Non-Residents195
196A - Income in respect of Units of Non-Residents96A
196B - Payments in respect of Units to an Offshore Fund96B
196C - Income from Foreign Currency Bonds or Shares of Indian Company Payable to Non-Resident96C
196D - Income of Foreign institutional investors from securities96D
194LB - Income by way of interest from Infrastructure Debt fund4LB
194LC - Income by way of interest from Indian company engaged in certain Business4LC
194LD - Income by way of interest on certain bonds and Government Securities4LD
194LBA(c) - Income referred to in section 10 (23FCA) from units of a business trustBA3
194S - Payment of consideration for transfer of virtual digital asset by persons other than specified persons94S
194Q - Payment of certain sums for purchase of goods94Q

Annexure-3 Reason for non-deduction / lower deduction/ higher deduction/threshold

ReasonCode
Lower Deduction/No Deduction on account of Certificate u/s 197A
No Deduction on account of Certificate u/s 197AB
Deduction of Tax at higher rate due to Non availability of PANC
In case of Transporter transaction and valid PAN is providedT
Software acquired u/s 194JS
Transaction where Tax not been deducted as amount paid to vendor/party has not exceeded the thrashold limitY
No Deduction on account of payment u/s 197A (1F)Z
Software acquired u/s 195S
No Deduction upto Rs. 50,000 in respect of interest income from deposits held by Senior Citizen u/s 80TTB for section 194AR
No deduction on account of payment made to person referred to in clause (iii) or clause (iv) or on account of notification issued under clause (v) for section 194NN
No deduction or lower deduction on account of payment made to a persion or class of person on account of notification issued under sub-section (5) for section 194AD
No deduction as per the provisions of sub-section (2A) of section 194LBAO
No deduction or lower deduction on account of notification issued under second provision to section 194NM
No deduction on account of payment being made to a person referred to in board circular no. 3 of 2002 dated 28th june, 2002E
No deduction on account of payment being made to a person referred to in board circular no. 11 of 2002 dated 22nd november, 2002E
No deduction on account of payment being made to a person referred to in board circular no. 18 of 2017 dated 28th may, 2017E

Annexure - 4 Country

CountryCountry code
AFGHANISTAN01
AKROTIRI02
ALBANIA03
ALGERIA04
AMERICAN SAMOA05
ANDORRA06
ANGOLA07
ANGUILLA08
ANTARCTICA09
ANTIGUA AND BARBUDA10
ARGENTINA11
ARMENIA12
ARUBA13
ASHMORE AND CARTIER ISLANDS14
AUSTRALIA15
AUSTRIA16
AZERBAIJAN17
BAHRAIN18
BAILIWICK OF GUERNSEY19
BAILIWICK OF JERSEY20
BAKER ISLAND21
BANGLADESH22
BARBADOS23
BELARUS24
BELGIUM25
BELIZE26
BENIN PORTO27
BERMUDA28
BHUTAN29
BOLIVIA30
BOSNIAAND HERZEGOVINA31
BOTSWANA32
BOUVET ISLAND33
BRAZIL34
BRITISH INDIAN OCEAN TERRITORY35
BRUNEI36
BULGARIA37
BURKINA FASO38
BURUNDI39
CAMBODIA40
CAMEROON41
CANADA42
CAPE VERDE43
CAYMAN ISLANDS44
CENTRAL AFRICAN REPUBLIC45
CHAD46
CHILE47
CHINA48
CHRISTMAS ISLAND49
CLIPPERTON ISLAND50
COCOS (KEELING) ISLANDS51
COLOMBIA52
COMMONWEALTH OF PUERTO RICO53
COMMONWEALTH OF THE NORTHERN MARIANA ISLANDS54
COMOROS55
CONGO,DEMOCRATIC REPUBLIC OF THE56
CONGO,REPUBLIC OF THE57
COOK ISLANDS58
CORAL SEA ISLANDS59
CORAL SEA ISLANDS TERRITORY60
COSTA RICA61
COTE D'IVOIRE62
CROATIA63
CUBA64
CYPRUS65
CZECH REPUBLIC66
DENMARK67
DEPARTMENTAL COLLECTIVITY OF MAYOTTE68
DHEKELIA69
DJIBOUTI70
DOMINICA71
DOMINICAN REPUBLIC72
EAST TIMOR (TIMORLASTE)73
ECUADOR74
EGYPT75
ELSALVADOR76
EQUATORIAL GUINEA77
ERITREA78
ESTONIA79
ETHIOPIA80
FALKLAND ISLANDS (ISLAS MALVINAS)81
FAROE ISLANDS82
FIJI83
FINLAND84
FRANCE85
FRENCH GUIANA86
FRENCH POLYNESIA87
FRENCH SOUTHERN ISLANDS88
GABON89
GEORGIA90
GERMANY91
GEURNSEY92
GHANA93
GIBRALTAR94
GREECE95
GREENLAND96
GRENADA97
GUADELOUPE98
GUAM100
GUATEMALA101
GUERNSEY102
GUINEA103
GUINEABISSAU104
GUYANA105
HAITI106
HEARD ISLAND AND MCDONALD ISLANDS107
HONDURAS108
HONG KONG109
HOWLAND ISLAND110
HUNGARY111
ICELAND112
INDIA113
INDONESIA114
IRAN115
IRAQ116
IRELAND117
ISLE OF MAN118
ISRAEL119
ITALY120
JAMAICA121
JAN MAYEN122
JAPAN123
JARVIS ISLAND124
JERSEY125
JOHNSTON ATOLL126
JORDAN127
KAZAKHSTAN128
KENYA129
KINGMAN REEF130
KIRIBATI131
KOREA, NORTH132
KOREA, SOUTH133
KOSOVO134
KUWAIT135
KYRGYZSTAN136
LAOS137
LATVIA138
LEBANON139
LESOTHO140
LIBERIA141
LIBYA142
LIECHTENSTEIN143
LITHUANIA144
LUXEMBOURG145
MACAU146
MACEDONIA147
MADAGASCAR148
MALAWI149
MALAYSIA150
MALAYSIA (LABUAN)151
MALDIVES152
MALI153
MALTA154
MARSHALLISLANDS155
MARTINIQUE156
MAURITANIA157
MAURITIUS158
MAYOTTE159
UNITED MEXICAN STATES160
MICRONESIA, FEDERATED STATES OF161
MIDWAY ISLANDS162
MOLDOVA163
MONACO164
MONGOLIA165
MONTENEGRO166
MONTSERRAT167
MOROCCO168
MOZAMBIQUE169
MYANMAR (BURMA)170
NAMIBIA171
NAURU172
NAVASSA ISLAND173
NEPAL174
NETHERLANDS175
NETHERLANDS ANTILLES176
NEW CALEDONIA177
NEWZEALAND178
NICARAGUA179
NIGER180
NIGERIA181
NIUE182
NORFOLK ISLAND183
NORTHERN MARIANA ISLANDS184
NORWAY185
OMAN186
PAKISTAN187
PALAU188
PALMYRA ATOLL189
PANAMA190
PAPUA NEW GUINEA191
PARACEL ISLANDS192
PARAGUAY193
PERU194
PHILIPPINES195
PITCAIRN ISLANDS196
PITCAIRN, HENDERSON, DUCIE, AND OENO ISLANDS197
POLAND198
PORTUGAL199
PUERTO RICO200
QATAR201
REUNION202
ROMANIA203
RUSSIA204
RWANDA205
SAINT BARTHELEMY206
SAINT HELENA207
SAINT KITTS AND NEVIS208
SAINT LUCIA209
SAINT MARTIN210
SAINT PIERRE AND MIQUELON211
SAINT VINCENT AND THE GRENADINES212
SAMOA213
SANMARINO214
SAO TOME AND PRINCIPE215
SAUDI ARABIA216
SENEGAL217
SERBIA218
SEYCHELLES219
SIERRA LEONE220
SINGAPORE221
SLOVAKIA222
SLOVENIA223
SOLOMON ISLANDS224
SOMALIA225
SOUTH AFRICA226
SOUTH GEORGIA AND SOUTH SANDWICH ISLANDS227
SPRATLY ISLANDS228
SPAIN229
SRI LANKA230
ST. VINCENT & GRENADINES231
SUDAN232
SURINAME233
SVALBARD234
SWAZILAND235
SWEDEN236
SWITZERLAND237
SYRIA238
TAIWAN239
TAJIKISTAN240
TANZANIA241
TERRITORIAL COLLECTIVITY OF ST. PIERRE & MIQUELON242
TERRITORY OF AMERICAN SAMOA243
TERRITORY OF ASHMORE AND CARTIER ISLANDS244
TERRITORY OF CHRISTMAS ISLAND245
TERRITORY OF COCOS (KEELING) ISLANDS246
TERRITORY OF GUAM247
TERRITORY OF HEARD ISLAND & MCDONALD ISLANDS248
TERRITORY OF NORFOLK ISLAND249
THAILAND250
THE BAHAMAS251
THE GAMBIA252
TOGO253
TOKELAU254
TONGA255
TRINIDAD AND TOBAGO256
TUNISIA257
TURKEY258
TURKMENISTAN259
TURKS AND CAICOS ISLANDS260
TUVALU261
UGANDA262
UKRAINE263
UNITED ARAB EMIRATES264
UNITED KINGDOM265
UNITED STATES VIRGIN ISLANDS266
UNITED STATES OF AMERICA267
URUGUAY268
UZBEKISTAN269
VANUATU270
VATICAN CITY (HOLYSEE)271
VENEZUELA272
VIETNAM273
VIRGIN ISLANDS, BRITISH274
VIRGIN ISLANDS, U.S.275
WAKE ISLAND276
WALLIS AND FUTUNA277
WESTERN SAHARA278
YEMEN279
ZAMBIA280
ZIMBABWE281
COMBODIA282
CONGO283
IVORY COAST284
WEST INDIES285
BRITISH VIRGIN ISLANDS286

Annexure -5 Minor Head

Minor HeadCode
(200) TDS Payable by Tax Payer200
(400) TDS Regular Assessment (Raised by I.T. Dept.)400

Response

Param

Type

Description

code

number

HTTP response status code

transaction_id

string

Unique Transaction id to track the request

timestamp

number

Timestamp of the request

status

enum

Possbile values are :
JOBDONE, JOBQUEUED, JOBDONE

signed_url

string

JOBDONE : signed url of txt file
JOBFAILED : signed url of 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

Param

Type

Description

record_no

number

Row number

filed_name

string

Attribute name

level

enum

Possible values are :
ERROR, WARNING

issue_type

enum

Possible values are :
REQUIRED, PATTERN, ENUM, MIN, MAX, MIN_LENGTH, MAX_LENGTH, CUSTOM

message

string

Validation description message


Did this page help you?