TDS annexures

Use this page to reference request and response payloads for TDS APIs.

Compliance API

Search TAN

Field	Type	Description	Example
nameOrgn	string	Name of the TAN Entity	RON DOE PRIVATE LIMITED
nameLast	string	Last Name of TAN Entity if Individual	DOE
nameFirst	string	First Name of TAN Entity if Individual	JOHN
nameMid	string	Middle Name of TAN Entity if Individual	RON
addLine1	string	Address Line 1	1, ABC Tower,
addLine2	string	Address Line 2	Nr. ABC Tower
addLine3	string	Address Line 3	Opp. XYZ
addLine4	string	Address Line 4	ABCLMN Lane
addLine5	string	Address Line 5	Ahmedabad, India-380015
stateCd	number	State	9
pin	number	PIN Code of the address	380015
phoneNum	string	Phone Number of the TAN Entity	99xxxxxx83
dtTanAllotment	number	Date of TAN Allotment	1499324427000
emailId1	string	Email ID corresponding to TAN Entity	[e-mail]
emailId2	string	Alternate Email ID corresponding to TAN Entity	[e-mail]

Section 206AB & 206CCA

Key	Type	Description	Example
pan	string	10-character alphanumeric unique identifier for an income taxpayer	XXXPX1234A
name	string	Name of Taxpayer (masked)	SXXXXJ MXXXXXXXXR
pan_allotment_date	number	PAN allotment date	1527100200000
financial_year	string	The financial year for which compliance check u/s 206AB & 206CCA is done. It will return the current financial year.	FY 2023-24
specified_person_us_206ab_&_206cca	string	Flag for compliance check. Possible values: y n If y, then a higher TDS/TCS rate is to be applied for specified persons u/s 206AB & 206CCA.	y
pan_status	string	Possible values: operative inoperative na	operative

TDS Return (TXT & CSI)

Submit Job

Key	Type	Description	Example
job_id	string	The ID of this job. It will be used later on to check the status.	f24cd229-42c8-43de-af79-8ce2d3c4c3db
status	string	status of the job	created
created_at	number	EPOCH timestamp of when job was created	1701250588000
txt_url	string	Pre-signed URL where you need to upload txt file	https://… .
csi_url	string	Pre signed URL where you need to upload csi file	https://… .
tan	string	TAN of the deductor for which the TDS return is being filed	AHMJ01234A
form	string	TDS return form type	26Q
financial_year	string	Financial Year	FY 2023-24
quarter	string	Quarter	Q4

Poll Job

Key	Type	Description	Example
job_id	string	ID of the particular txt and csi uploaded.	f24cd229-42c8-43de-af79-8ce2d3c4c3db
status	string	Status of the fvu upload. Possible values: created queued failed succeeded	succeeded
tan	string	TAN of the deductor for which the TDS return is being filed	AHMJ01234A
form	string	TDS return form type	26Q
financial_year	string	Financial Year	FY 2023-24
quarter	string	Quarter	Q4
filing_type	string	TDSR Filing Type.	original
receipt_number	number	TDSR filing receipt number	123456789012345
receipt_url	string	URL to download the TDS return acknowledgment. Present only when the status is succeeded	https://s3.ap-south-1.amazonaws.com/efile.tds-compliance.sandbox.co.in/receipt.pdf
fvu_url	string	URL to download the TDS return FVU file. Present only when the status is succeeded	https://…
form27a_url	string	URL to download Form 27A for the TDS return. Present only when the status is succeeded	https://…
validation_url	string	URL to download the validation report if FVU generation fails. Present only when the status is failed	https://…
message	string	Reason the TDS return was not e-filed. Present only when the status is failed For possible values, refer to the TIN-FC error codes and messages	Regular Statement with the same TAN, Financial Year, FORM, and Quarter is already furnished
created_at	number	EPOCH timestamp of when job was created	1701250588000
updated_at	number	EPOCH timestamp of when job was last updated	1701250698000

TDS return (FVU and Form 27A)

Submit Job

Key	Type	Description	Example
job_id	string	The ID of this job. It will be used later on to check the status.	f24cd229-42c8-43de-af79-8ce2d3c4c3db
status	string	status of the job	created
created_at	number	EPOCH timestamp of when the job was created	1701250588000
fvu_url	string	Pre-signed URL where you upload the ZIP file for FVU and Form 27A	https://… .
tan	string	TAN of the deductor for which the TDS return is being filed	AHMJ01234A
form	string	TDS return form type	26Q
financial_year	string	Financial Year	FY 2023-24
quarter	string	Quarter	Q4

Poll Job

Key	Type	Description	Example
job_id	string	ID of the particular txt and csi uploaded.	f24cd229-42c8-43de-af79-8ce2d3c4c3db
status	string	Status of the fvu upload. Possible values: created queued failed succeeded	succeeded
tan	string	TAN of the deductor for which the TDS return is being filed	AHMJ01234A
form	string	TDS return form type	26Q
financial_year	string	Financial Year	FY 2023-24
quarter	string	Quarter	Q4
filing_type	string	TDSR Filing Type.	original
receipt_number	number	TDSR filing receipt number	123456789012345
receipt_url	string	URL to download the TDS return acknowledgment. Present only when the status is succeeded	pdf format
fvu_url	string	URL to download the TDS return FVU file. Present only when the status is succeeded	https://…
form27a_url	string	URL to download Form 27A for the TDS return. Present only when the status is succeeded	https://…
message	string	Reason the TDS return was not e-filed. Present only when the status is failed For possible values, refer to the TIN-FC error codes and messages	Regular Statement with the same TAN, Financial Year, FORM, and Quarter is already furnished
created_at	number	EPOCH timestamp of when job was created	1701250588000
updated_at	number	EPOCH timestamp of when job was last updated	1701250698000

Download Form 16

Submit Job

Param	Type	Description	Example
job_id	string	Unique identifier of the job	f24cd229-42c8-43de-af79-8ce2d3c4c3db
tan	string	TAN of deductor	MUMR09719B
financial_year	string	Financial Year	FY 2023-24
quarter	string	Quarter	Q1
status	string	The status of the job submitted.	created
form	string	TDS return form type	26Q
created_at	number	EPOCH timestamp of when the job was created	1701250588000
remember_me	boolean	Whether to remember the credentials	true

Poll Job API

Param	Type	Description	Example
job_id	string	Unique identifier of the job	f24cd229-42c8-43de-af79-8ce2d3c4c3db
tan	string	TAN of deductor	MUMR09719B
quarter	string	Quarter	Q1
financial_year	string	Financial Year	FY 2023-24
form	string	TDS return form type	26Q
created_at	number	EPOCH timestamp of when the job was created	1701250588000
updated_at	number	EPOCH timestamp of when the job was last updated	1701250598000
remember_me	boolean	Whether to remember the credentials	true
status	string	Status of the job. Possible values: created queued in_progress failed succeeded	queued
form16a_url	string	URL to download the ZIP file that contains Form 16A PDFs. Present only when the status is succeeded	https://. ..
form16_url	string	URL to download the ZIP file that contains Form 16 PDFs. Present only when the status is succeeded	https://. ..
message	string	Reason for not generating TDS certificates. Will be visible only when the status is failed	Invalid security captcha

Report API

TDS Report

TDS Report Submit Job API

Key	Type	Description
job_id	string	Unique Job ID to track the request
tan	string	TAN of Deductor
quarter	string	Quarter for which TDS is being filed. Form 138 currently supports Q1 to Q3 only
tax_year	string	Tax Year for which TDS is being filed
form	string	TDS Return Form. Supported values: 138, 140, 144
previous_receipt_number	string	Receipt Number of previously filed TDS Return
status	string	Status of the job
json_url	string	S3 URL to make the PUT request
created_at	number	EPOCH timestamp of when the job was created

TDS Report Poll Job API

Key	Type	Description
job_id	string	Unique Job ID to track the request
tan	string	TAN of Deductor
quarter	string	Quarter for which TDS is being filed
form	string	TDS Return Form. Possible values: 138, 140, 144
tax_year	string	Tax Year for which TDS is being filed
previous_receipt_number	string	Receipt Number of previously filed TDS Return
status	string	Status of the job. Possible values: created, queued, succeeded, failed
txt_url	string	Link from where you can download the generated TXT file. Will be provided when the status is succeeded
validation_report_url	string	Link from where you can download the validation report. Will be provided when the status is failed
created_at	number	EPOCH timestamp of when the job was created
updated_at	number	EPOCH timestamp of when the job was last updated

TCS Report

TCS Report Submit Job API

Key	Type	Description
job_id	string	Unique Job ID to track the request
tan	string	TAN of collectee
quarter	string	Quarter for which TCS is being filed
financial_year	string	Financial Year for which TCS is being filed
previous_receipt_number	string	Receipt Number of previously filed TCS Return
status	string	Status of the job
json_url	string	S3 URL to make the PUT request
created_at	number	EPOCH timestamp of when the job was created

TCS Report Poll Job API

Key	Type	Description
job_id	string	Unique Job ID to track the request
tan	string	TAN of collectee
quarter	string	Quarter for which TCS is being filed
financial_year	string	Financial Year for which TCS is being filed
previous_receipt_number	string	Receipt Number of previously filed TCS Return
status	string	Status of the job. Possible values: created, queued, succeeded, failed
txt_url	string	Link from where you can download the generated TXT file. Will be provided when the status is succeeded
validation_report_url	string	Link from where you can download the validation report. Will be provided when the status is failed
created_at	number	EPOCH timestamp of when the job was created
updated_at	number	EPOCH timestamp of when the job was last updated

Calculator API

Non-Salary Payments

Key	Type	Description	Example
deductee_type	string	Type of Deductee	company
is_pan_available	boolean	Returns PAN status	false
is_206ab_applicable	boolean	Returns 206AB status	false
is_pan_operative	boolean	Returns PAN operative	false
residential_status	string	Residential Status of the deductee	resident
section	string	Section under which the tax is to be deducted	194C
code	string	Code under which the tax is to be deducted	94C
category	string	Category under which tax is to be deducted	contractual_payment
nature_of_payment	string	The kind of payment being made. View applicable Nature of Payments	tender_fees
credit_amount	number	Payment amount (in INR)	90500
credit_date	number	Date of payment in EPOCH Timestamp	1685577600000
deduction_rate	number	Applicable TDS rate	20
threshold_amount	number	The threshold amount after which TDS is applicable	100000
due_date	number	Due date of depositing TDS in EPOCH Timestamp	1688688000000
deduction_amount	number	TDS amount to be deducted	0

TCS Payments

Key	Type	Description	Example
deductee_type	string	Type of Deductee	individual
is_pan_available	boolean	Returns PAN status	false
is_206cca_applicable	boolean	Returns 206AB status	false
is_pan_operative	boolean	Returns PAN operative	false
residential_status	string	Residential Status of the deductee	resident
section	string	Section under which the tax is to be collected	206C(1)
code	string	The code under which the tax is to be collected	6CO
category	string	Category under which tax is to be collected	overseas_tour_program_package
nature_of_payment	string	The kind of payment being made. View applicable Nature of Payments	foreign_flight_tickets
payment_amount	number	Payment amount (in INR)	695000
payment_date	number	Payment date in EPOCH	1685577600000
collection_rate	number	Applicable TCS rate	5
threshold_amount	number	The threshold amount after which TCS is applicable	0
due_date	number	Due date of depositing TCS in EPOCH Timestamp	1688688000000
collection_amount	number	TCS amount to be collected	34750

Analytics API

TDS potential notice

Submit Job

Key	Type	Description	Example
tan	string	TAN of deductor	AHMA09719B
quarter	string	Quarter	Q4
financial_year	string	Financial Year	FY 2023-24
form	string	TDS Return Form	26Q
job_id	string	Unique identifier of the job	1c1e4905-d07e-4c51-b8c5-1163050ded7f
status	string	Status of the job	created
created_at	number	EPOCH timestamp of when the job was created	1716515767000
json_url	string	Pre-signed URL where the payload is to be submitted	https://…

Poll Job

Key	Type	Description	Example
tan	string	TAN of deductor	AHMA09719B
quarter	string	Quarter	Q4
financial_year	string	Financial Year	FY 2023-24
form	string	TDS Return Form	26Q
job_id	string	Unique identifier of the job	1c1e4905-d07e-4c51-b8c5-1163050ded7f
status	string	Status of the job. Possible values: created, queued, succeeded, failed	created
created_at	number	EPOCH timestamp when the job was created	1716515767000
updated_at	number	EPOCH timestamp when the job was last updated. Present only when the status is queued, succeeded, or failed	1716515787000
potential_notice_report_url	string	Pre-signed URL to download the potential notice report in XLSX format. Present only when the status is succeeded	https://…
message	string	Error message. Present only when the status is failed	Validation Error
validation_report_url	string	Pre-signed URL to download the validation report in XLSX format. Present only when the status is failed	https://…

TCS potential notice

Submit Job

Key	Type	Description	Example
tan	string	TAN of collector	AHMA09719B
quarter	string	Quarter	Q4
financial_year	string	Financial Year	FY 2023-24
job_id	string	Unique identifier of the job	1c1e4905-d07e-4c51-b8c5-1163050ded7f
status	string	Status of the job	created
created_at	number	EPOCH timestamp of when the job was created	1716515767000
json_url	string	Pre-signed URL where the payload is to be submitted	https://…

Poll Job

Key	Type	Description	Example
tan	string	TAN of collector	AHMA09719B
quarter	string	Quarter	Q4
financial_year	string	Financial Year	FY 2023-24
job_id	string	Unique identifier of the job	1c1e4905-d07e-4c51-b8c5-1163050ded7f
status	string	Status of the job. Possible values: created, queued, succeeded, failed	created
created_at	number	EPOCH timestamp when the job was created	1716515767000
updated_at	number	EPOCH timestamp when the job was last updated. Present only when the status is queued, succeeded, or failed	1716515787000
potential_notice_report_url	string	Pre-signed URL to download the potential notice report in XLSX format. Present only when the status is succeeded	https://…
message	string	Error message. Present only when the status is failed	Validation Error
validation_report_url	string	Pre-signed URL to download the validation report in XLSX format. Present only when the status is failed	https://…

Workbooks

TDS Reports workbook support now uses the Income-tax Act 2025 forms:

• 138 for salary payments
• 140 for resident non-salary payments
• 144 for non-resident payments

TDS report jobs use tax_year. Form 138 currently supports Q1 to Q3 only.

Form 138

View Schema

View Sample

• payer_sheet / payer_list: name, tan, pan, country, flat_door_block_number, post_office, road_street_block_sector, area_locality, district, state, postal_code, email, contact_country_code, contact_number, deductor_type, government_state_code, ministry_code, ministry_name_other, account_office_identification_number, gstin
• payer_sheet / responsible_person_list: name, designation, pan, flat_door_block_number, post_office, road_street_block_sector, area_locality, district, state, postal_code, email, country, contact_country_code, contact_number
• payee_sheet / payee_table: sr_no, pan, name
• challan_sheet / challan_table: bank_challan_number_or_ddo_serial_number, bsr_code_or_form_24g_receipt_number, bank_challan_or_transfer_voucher_date_epoch, minor_head, mode_of_payment, nil_challan_indicator, total_tax_deducted, total_interest, total_fee, total_penalty, total_tax_deposited
• payment_sheet / payment_table: payee_sr_no, bank_challan_number_or_ddo_serial_number, bsr_code_or_form_24g_receipt_number, nature_of_payment, payment_amount, payment_date_epoch, total_tax_deducted, deduction_date_epoch, total_tax_deposited, deposit_date_epoch, reason_for_lower_deduction, certificate_number

Form 140

View Schema

View Sample

• payer_sheet / payer_list: tan, pan, name, street, area, city, state, postal_code, email, mobile, gstin, country, country_code, deductor_type
• payer_sheet / responsible_person_list: designation, name, pan, street, area, city, state, postal_code, email, mobile, country, country_code
• payee_sheet / payee_table: sr_no, pan, name
• challan_sheet / challan_table: challan_serial, bsr_code, paid_date_epoch, minor_head, total_tax_deducted, interest, late_filing_fees, other_penalty
• payment_sheet / payment_table: payee_sr_no, challan_serial, bsr_code, nature_of_payment, payment_amount, payment_date_epoch, total_tax_deducted, total_tax_deposited, deduction_date_epoch, reason_for_lower_deduction, certificate_number, unique_identification_number_form_121, amount_of_cash_withdrawal_more_than_1_crore_under_section_393_3, amount_of_cash_withdrawal_more_than_3_crore_for_cooperative_societies_under_section_393_3

Form 144

View Schema

View Sample

• payer_sheet / payer_list: name, tan, pan, country, flat_door_block_number, post_office, road_street_block_sector, area_locality, district, state, postal_code, email, contact_country_code, contact_number, deductor_type, government_state_code, ministry_code, ministry_name_other, account_office_identification_number, gstin
• payer_sheet / responsible_person_list: name, designation, pan, flat_door_block_number, post_office, road_street_block_sector, area_locality, district, state, postal_code, email, country, contact_country_code, contact_number
• payee_sheet / payee_table: sr_no, pan, name, opting_out_of_taxation_regime_under_section_202_1, country, address_in_country_of_residence, email, isd_code, mobile, tax_identification_number
• challan_sheet / challan_table: bank_challan_number_or_ddo_serial_number, bsr_code_or_form_24g_receipt_number, bank_challan_or_transfer_voucher_date_epoch, minor_head, mode_of_payment, nil_challan_indicator, total_tax_deducted, total_interest, total_fee, total_penalty, total_tax_deposited
• payment_sheet / payment_table: payee_sr_no, bank_challan_number_or_ddo_serial_number, bsr_code_or_form_24g_receipt_number, nature_of_payment, nature_of_remittance, payment_amount, payment_date_epoch, total_tax_deducted, deduction_date_epoch, total_tax_deposited, grossed_up_under_section_393_10, applicability_of_tds_rate_under_dtaa, unique_identification_number_form_121, reason_for_lower_deduction, certificate_number, amount_of_cash_withdrawal_more_than_1_crore_under_section_393_3, amount_of_cash_withdrawal_more_than_3_crore_for_cooperative_societies_under_section_393_3

Potential notice report

summary_of_potential_notices_table

Key	Type	Description
type_of_default	string	Possible default type for the TDS or TCS return. Values include: short_payment, short_deduction, late_payment, late_deduction, late_filing_fee_u/s_234E
is_applicable	string	Whether the default applies to the return. Possible values: Y or N

penalty_summary_table

Key	Type	Description
particular	string	Default type for the TDS or TCS return. Values include: short_payment, short_deduction, late_payment, late_deduction, late_filing_fee_u/s_234E
rate	string	The rate of penalty for a given notice
amount	number	Amount of penalty payable for a given notice

interest_summary_table

Key	Type	Description
particular	string	Value is interest_amount
actual	number	The total amount of interest paid as per the return. Excludes Late filing fees.
required	number	The required amount of interest payable for this return. Excludes Late filing fees.
difference	number	Balance amount between actual and required.

deduction_summary_table

Key	Type	Description
particular	string	Value is deduction_amount
actual	number	The total amount of deduction/collection as per the return.
required	number	The required amount of deduction/collection required for this return.
difference	number	Balance amount between actual and required.

challan_summary_table

Key	Type	Description
particular	string	Value is challan_amount
actual	number	The total amount deposited as per the return.
required	number	The required amount to be deposited for this return.
difference	number	Balance amount between actual and required.

challan_utilization_summary_table

Key	Type	Description
particular	string	Value is challan_amount
actual	number	The total challan amount utilized for this return
required	number	The required challan amount to be utilized for this return
difference	number	Balance amount between actual and required.

challan_table

Param	Type	Description
challan_serial	string	Bank Challan No
bsr_code	string	Bank-Branch Code/ Form 24G Receipt Number
paid_date_epoch	number	EPOCH timestamp of the challan paid date
minor_head	enumeration	Minor head for the challan
tds_amount	number	Income Tax
surcharge	number	Surcharge on Income Tax
health_and_education_cess	number	Education cess on Income Tax
interest	number	Interest levied upon late deduction
late_filing_fees	number	Penalty levied upon late filing
other_penalty	number	Any Other Penalty
utilized_amount	number	Total challan amount used in previous returns
notice	string	Type of notice applicable from this challan. Possible values: short_payment, late_payment, short_&_late_payment
notice_reason	string	Reason for the applicable notice
challan_available	number	Challan amount available for this return after deducting the utilized amount.
utilized_amount_in_payments	number	Challan amount utilized in the payment_sheet
short_payment	number	The amount that exceeds the available challan for this return.
challan_due_date	number	The date at which the challan should be deposited.
interest_payable	number	Penalty interest payable due to the notice
additional_tds_to_be_deposited	number	Additional amount to be paid, which is the sum of the short_payment and interest_payable.

payment_table

Param	Type	Description
payee_sr_no	number	Payee Serial Number
challan_serial	string	Bank Challan No
bsr_code	string	Bank-Branch Code/ Form 24G Receipt Number
nature_of_payment	enumeration	TDS section of deduction
payment_amount	number	Payment amount
payment_date_epoch	number	EPOCH timestamp of Payment date
tds_amount	number	Tax amount of deduction
surcharge	number	Surcharge on Tax amount
health_and_education_cess	number	Health and education cess on the Tax amount
deduction_date_epoch	number	EPOCH timestamp of Deduction date
reason_for_lower_deduction	enumeration	Reason for non-deduction / lower deduction/ higher deduction/threshold
certificate_number	string	Certificate number issued by the Assessing Officer u/s 197 for non-deduction/lower deduction.
notice	string	Type of notice applicable from this challan. Possible values: short_deduction, late_deduction, short_&_late_deduction
notice_reason	string	Reason for the applicable notice
tds_rate	number	The rate at which tax is deducted in this return
tds_rate_as_per_it_act	number	The rate at which tax is to be deducted according to the Income Tax Act
tds_amount_payable_as_per_it_act	number	Amount of TDS/TCS to be deducted/collected as per the Income Tax Act
additional_tds_to_be_deducted	number	Additional TDS amount to be deducted for the mentioned payment
interest_payable	number	Penalty interest payable due to the notice