{ "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.\n\nThe 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.\n\nHowever, staying TDS compliant can be a hassle for businesses, as they are required to :\n\n1. Deduct TDS from payments that are liable for TDS Deduction at an appropriate rate.\n \n2. Deposit TDS to Government before the due date.\n \n3. File TDS Returns on a Quarterly basis.\n \n4. Issue a TDS Certificate by the deductor to the deductee.\n \n\nOrganizations 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" }, "tags": [ { "name": "TDS Compliance Check" }, { "name": "Download CSI" }, { "name": "FVU Generation" }, { "name": "E-File TDS Return" }, { "name": "TDS" }, { "name": "TDS Certificate" }, { "name": "TRACES Credentials" } ], "paths": { "/tds/compliance/206ab/check": { "post": { "summary": "Section 206AB & 206CCA Compliance Check", "deprecated": false, "description": "", "tags": [ "TDS Compliance Check" ], "parameters": [ { "name": "authorization", "in": "header", "description": "JWT access token", "required": true, "example": "", "schema": { "type": "string" } }, { "name": "x-api-key", "in": "header", "description": "API key for identification", "required": true, "example": "", "schema": { "type": "string" } }, { "name": "x-api-version", "in": "header", "description": "API version", "required": false, "example": "", "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "@entity": { "type": "string", "enum": [ "in.co.sandbox.tds.compliance.206ab_check.request" ] }, "pan": { "description": "10-character alphanumeric unique identifier for an income tax-payer.", "pattern": "[A-Z]{3}[PCFTGHLABJ]{1}[A-Z]{1}[0-9]{4}[A-Z]{1}", "type": "string" }, "consent": { "type": "string" }, "reason": { "type": "string" } }, "required": [ "@entity", "pan", "consent", "reason" ] }, "examples": { "200 Specified person": { "value": { "@entity": "in.co.sandbox.tds.compliance.206ab_check.request", "pan": "XXXPX1234A", "consent": "y", "reason": "TDS compliance" }, "summary": "200 Specified person" }, "200 Specified person (2)": { "value": { "@entity": "in.co.sandbox.tds.compliance.206ab_check.request", "pan": "XXXPX1234L", "consent": "y", "reason": "TDS compliance" }, "summary": "200 Specified person (2)" }, "200 Specified person (3)": { "value": { "@entity": "in.co.sandbox.tds.compliance.206ab_check.request", "pan": "XXXPX1234L", "consent": "y", "reason": "TDS compliance" }, "summary": "200 Specified person (3)" }, "200 Specified person with inoperative pan": { "value": { "@entity": "in.co.sandbox.tds.compliance.206ab_check.request", "pan": "XXXPX1234H", "consent": "y", "reason": "TDS compliance" }, "summary": "200 Specified person with inoperative pan" }, "200 Specified person with inoperative pan (2)": { "value": { "@entity": "in.co.sandbox.tds.compliance.206ab_check.request", "pan": "XXXAX2345A", "consent": "y", "reason": "TDS compliance" }, "summary": "200 Specified person with inoperative pan (2)" }, "200 Not a specified person": { "value": { "@entity": "in.co.sandbox.tds.compliance.206ab_check.request", "pan": "XXXPX2345A", "consent": "y", "reason": "TDS complaince" }, "summary": "200 Not a specified person" }, "200 Not a specified person (2)": { "value": { "@entity": "in.co.sandbox.tds.compliance.206ab_check.request", "pan": "XXXBX3456B", "consent": "y", "reason": "TDS complaince" }, "summary": "200 Not a specified person (2)" }, "200 Not a specified person with inoperative pan": { "value": { "@entity": "in.co.sandbox.tds.compliance.206ab_check.request", "pan": "XXXPX1234O", "consent": "y", "reason": "TDS complaince" }, "summary": "200 Not a specified person with inoperative pan" }, "200 Not a specified person with inoperative pan (2)": { "value": { "@entity": "in.co.sandbox.tds.compliance.206ab_check.request", "pan": "XXXTX1234P", "consent": "y", "reason": "TDS complaince" }, "summary": "200 Not a specified person with inoperative pan (2)" }, "200 Invalid PAN": { "value": { "@entity": "in.co.sandbox.tds.compliance.206ab_check.request", "pan": "XXXPX1234C", "consent": "y", "reason": "TDS compliance" }, "summary": "200 Invalid PAN" }, "422 Invalid PAN pattern": { "value": { "@entity": "in.co.sandbox.tds.compliance.206ab_check.request", "pan": "XXXQX1234A", "consent": "y", "reason": "TDS compliance" }, "summary": "422 Invalid PAN pattern" } } } } }, "responses": { "200": { "description": "200 - OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "code": { "type": "integer" }, "timestamp": { "type": "integer" }, "transaction_id": { "type": "string" }, "data": { "type": "object", "properties": { "@entity": { "type": "string", "enum": [ "in.co.sandbox.tds.compliance.206ab_check.response" ] }, "pan": { "type": "string" }, "name": { "type": "string" }, "pan_allotment_date": { "type": "integer" }, "financial_year": { "type": "string" }, "specified_person_us_206ab_&_206cca": { "type": "string" }, "pan_status": { "type": "string" } } } } }, "examples": { "200 Specified person": { "summary": "200 Specified person", "value": { "code": 200, "timestamp": 1763362637000, "transaction_id": "e2b9145f-69d5-4bbe-a6de-be6fc08b426f", "data": { "@entity": "in.co.sandbox.tds.compliance.206ab_check.response", "pan": "XXXPX1234A", "name": "SXXXXJ MXXXXXXXXR", "pan_allotment_date": 1527100200000, "financial_year": "FY 2024-25", "specified_person_us_206ab_&_206cca": "y", "pan_status": "operative" } } }, "200 Specified person (2)": { "summary": "200 Specified person (2)", "value": { "code": 200, "timestamp": 1763362637000, "transaction_id": "e2b9145f-69d5-4bbe-a6de-be6fc08b426f", "data": { "@entity": "in.co.sandbox.tds.compliance.206ab_check.response", "pan": "XXXPX1234L", "name": "MXXXA PXXXL", "pan_allotment_date": 1527100200000, "financial_year": "FY 2024-25", "specified_person_us_206ab_&_206cca": "y", "pan_status": "operative" } } }, "200 Specified person (3)": { "summary": "200 Specified person (3)", "value": { "code": 200, "timestamp": 1763362637000, "transaction_id": "e2b9145f-69d5-4bbe-a6de-be6fc08b426f", "data": { "@entity": "in.co.sandbox.tds.compliance.206ab_check.response", "pan": "XXXCX1234B", "name": "IXXL CXXP", "pan_allotment_date": 1527100200000, "financial_year": "FY 2024-25", "specified_person_us_206ab_&_206cca": "y", "pan_status": "operative" } } }, "200 Specified person with inoperative pan": { "summary": "200 Specified person with inoperative pan", "value": { "code": 200, "timestamp": 1763362637000, "transaction_id": "e2b9145f-69d5-4bbe-a6de-be6fc08b426f", "data": { "@entity": "in.co.sandbox.tds.compliance.206ab_check.response", "pan": "XXXPX1234H", "name": "AXXXV KXXXA", "pan_allotment_date": 1527100200000, "financial_year": "FY 2024-25", "specified_person_us_206ab_&_206cca": "y", "pan_status": "inoperative" } } }, "200 Specified person with inoperative pan (2)": { "summary": "200 Specified person with inoperative pan (2)", "value": { "code": 200, "timestamp": 1763362637000, "transaction_id": "e2b9145f-69d5-4bbe-a6de-be6fc08b426f", "data": { "@entity": "in.co.sandbox.tds.compliance.206ab_check.response", "pan": "XXXAX2345A", "name": "MXXR SXXR", "pan_allotment_date": 1527100200000, "financial_year": "FY 2024-25", "specified_person_us_206ab_&_206cca": "y", "pan_status": "inoperative" } } }, "200 Not a specified person": { "summary": "200 Not a specified person", "value": { "code": 200, "timestamp": 1763362637000, "transaction_id": "e2b9145f-69d5-4bbe-a6de-be6fc08b426f", "data": { "@entity": "in.co.sandbox.tds.compliance.206ab_check.response", "pan": "XXXPX1234B", "name": "JXXXR MXXXXXXA", "pan_allotment_date": 1527100200000, "financial_year": "FY 2024-25", "specified_person_us_206ab_&_206cca": "n", "pan_status": "operative" } } }, "200 Not a specified person (2)": { "summary": "200 Not a specified person (2)", "value": { "code": 200, "timestamp": 1763362637000, "transaction_id": "e2b9145f-69d5-4bbe-a6de-be6fc08b426f", "data": { "@entity": "in.co.sandbox.tds.compliance.206ab_check.response", "pan": "XXXBX3456B", "name": "FXXD TXXXG", "pan_allotment_date": 1527100200000, "financial_year": "FY 2024-25", "specified_person_us_206ab_&_206cca": "n", "pan_status": "operative" } } }, "200 Not a specified person with inoperative pan": { "summary": "200 Not a specified person with inoperative pan", "value": { "code": 200, "timestamp": 1763362637000, "transaction_id": "e2b9145f-69d5-4bbe-a6de-be6fc08b426f", "data": { "@entity": "in.co.sandbox.tds.compliance.206ab_check.response", "pan": "XXXPX1234B", "name": "RXXXL SXXXH", "pan_allotment_date": 1527100200000, "financial_year": "FY 2024-25", "specified_person_us_206ab_&_206cca": "n", "pan_status": "inoperative" } } }, "200 Not a specified person with inoperative pan (2)": { "summary": "200 Not a specified person with inoperative pan (2)", "value": { "code": 200, "timestamp": 1763362637000, "transaction_id": "e2b9145f-69d5-4bbe-a6de-be6fc08b426f", "data": { "@entity": "in.co.sandbox.tds.compliance.206ab_check.response", "pan": "XXXTX1234P", "name": "EXXXN MXXL", "pan_allotment_date": 1527100200000, "financial_year": "FY 2024-25", "specified_person_us_206ab_&_206cca": "n", "pan_status": "inoperative" } } }, "200 Invalid PAN": { "summary": "200 Invalid PAN", "value": { "code": 200, "timestamp": 1763362637000, "transaction_id": "e2b9145f-69d5-4bbe-a6de-be6fc08b426f", "data": { "@entity": "in.co.sandbox.tds.compliance.206ab_check.response", "message": "Invalid PAN" } } } } } }, "headers": {} }, "422": { "description": "422 - Unprocessable Entity", "content": { "application/json": { "schema": { "type": "object", "properties": { "code": { "type": "integer" }, "timestamp": { "type": "integer" }, "transaction_id": { "type": "string" }, "message": { "type": "string" } } }, "examples": { "422 Invalid PAN pattern": { "summary": "422 Invalid PAN pattern", "value": { "code": 422, "timestamp": 1687348772740, "transaction_id": "780b2332-d96e-4ef5-b7bc-d7b40e59fa9e", "message": "Invalid Pan pattern" } } } } }, "headers": {} } }, "security": [] } }, "/tds/compliance/csi/otp": { "post": { "summary": "Generate OTP for CSI download", "deprecated": false, "description": "Send an OTP to the provided mobile number to request a CSI file.", "tags": [ "Download CSI" ], "parameters": [ { "name": "authorization", "in": "header", "description": "JWT access token", "required": true, "example": "{{access_token}}", "schema": { "type": "string" } }, { "name": "x-api-key", "in": "header", "description": "API key for identification", "required": true, "example": "{{api_key}}", "schema": { "type": "string" } }, { "name": "x-api-version", "in": "header", "description": "", "required": false, "example": "", "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "@entity": { "type": "string", "enum": [ "in.co.sandbox.tds.compliance.deductors.otp.request" ] }, "tan": { "description": "TAN of deductor/collector. Regular Expression: [A-Z]{4}[0-9]{5}[A-Z]{1}", "pattern": "[A-Z]{4}[0-9]{5}[A-Z]{1}", "type": "string" }, "mobile_number": { "description": "Mobile Number to send the OTP. Pattern: [1-9]{1}[0-9]{9}", "pattern": "[1-9]{1}[0-9]{9}", "type": "string" }, "from": { "description": "Date from which challan details are to be fetched. Value in EPOCH timestamp", "type": "integer" }, "to": { "description": "Date till which challan details are to be fetched. Value in EPOCH timestamp", "type": "integer" }, "consent": { "description": "Consent of the end-user to get their information. Possible values: Y or y", "type": "string" }, "reason": { "description": "Indicate the purpose. Min length: 20 characters", "type": "string" } }, "required": [ "@entity", "tan", "mobile_number", "from", "to", "consent", "reason" ] }, "examples": { "200 - Success": { "value": { "@entity": "in.co.sandbox.tds.compliance.deductors.otp.request", "tan": "AHMA09719B", "mobile_number": "1234567890", "from": 1722450600000, "to": 1730313000000, "consent": "Y", "reason": "Download CSI for TDS return filing" }, "summary": "200 - Success" }, "200 Invalid TAN": { "value": { "@entity": "in.co.sandbox.tds.compliance.deductors.otp.request", "tan": "AABC23456D", "mobile_number": "1234567890", "from": 1722450600000, "to": 1730313000000, "consent": "Y", "reason": "Download CSI for TDS return filing" }, "summary": "200 Invalid TAN" }, "200 OTP already generated": { "value": { "@entity": "in.co.sandbox.tds.compliance.deductors.otp.request", "tan": "PDES03028E", "mobile_number": "1234567890", "from": 1722450600000, "to": 1730313000000, "consent": "Y", "reason": "Download CSI for TDS return filing" }, "summary": "200 OTP already generated" }, "422 - Unprocessable Entity": { "value": { "@entity": "in.co.sandbox.tds.compliance.deductors.otp.request", "tan": "DABC2345DD", "mobile_number": "1234567890", "from": 1722450600000, "to": 1730313000000, "consent": "Y", "reason": "Download CSI for TDS return filing" }, "summary": "422 - Unprocessable Entity" } } } } }, "responses": { "200": { "description": "Check the response body for the result. HTTP 200 can also contain an application error in data.message.", "content": { "application/json": { "schema": { "type": "object", "properties": { "timestamp": { "type": "integer" }, "transaction_id": { "type": "string" }, "data": { "type": "object", "properties": { "@entity": { "type": "string" }, "tan": { "type": "string" }, "mobile_number": { "type": "string" }, "from": { "type": "integer" }, "to": { "type": "integer" }, "reference_id": { "type": "string", "description": "Reference ID for the OTP request. Pass this value with the received OTP to verify the request." }, "message": { "type": "string", "description": "Result of the OTP request, including any application error." } } }, "code": { "type": "integer" } } }, "examples": { "200 - Success": { "summary": "200 - Success", "value": { "timestamp": 1731669661517, "transaction_id": "166148b8-25e3-4ef2-b052-5a27098ebb0e", "data": { "@entity": "in.co.sandbox.tds.compliance.deductors.otp.response", "tan": "AHMA09719B", "mobile_number": "1234567890", "from": 1722450600000, "to": 1730313000000, "reference_id": "FOS005981930273", "message": "OTP sent successfully" }, "code": 200 } }, "200 Invalid TAN": { "summary": "200 Invalid TAN", "value": { "code": 200, "timestamp": 1763362637000, "transaction_id": "e2b9145f-69d5-4bbe-a6de-be6fc08b426f", "data": { "@entity": "in.co.sandbox.tds.compliance.deductors.csi.response", "message": "Invalid TAN" } } }, "200 OTP already generated": { "summary": "200 OTP already generated", "value": { "code": 200, "timestamp": 1763362637000, "transaction_id": "e2b9145f-69d5-4bbe-a6de-be6fc08b426f", "data": { "@entity": "in.co.sandbox.tds.compliance.deductors.csi.response", "message": "OTP generated for this TAN, please try after 30 seconds" } } } } } }, "headers": {} }, "422": { "description": "422 - Unprocessable Entity", "content": { "application/json": { "schema": { "type": "object", "properties": { "code": { "type": "integer" }, "timestamp": { "type": "integer" }, "transaction_id": { "type": "string" }, "message": { "type": "string" } } }, "examples": { "422 - Unprocessable Entity": { "summary": "422 - Unprocessable Entity", "value": { "code": 422, "timestamp": 1763362637000, "transaction_id": "e2b9145f-69d5-4bbe-a6de-be6fc08b426f", "message": "Invalid TAN pattern" } } } } }, "headers": {} } }, "security": [] } }, "/tds/compliance/csi/otp/verify": { "post": { "summary": "Verify OTP for CSI download", "deprecated": false, "description": "Verify the OTP to download the CSI file.", "tags": [ "Download CSI" ], "parameters": [ { "name": "authorization", "in": "header", "description": "JWT access token", "required": true, "example": "", "schema": { "type": "string" } }, { "name": "x-api-key", "in": "header", "description": "API key for identification", "required": true, "example": "", "schema": { "type": "string" } }, { "name": "x-api-version", "in": "header", "description": "", "required": false, "example": "", "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "@entity": { "type": "string", "enum": [ "in.co.sandbox.tds.compliance.deductors.csi.request" ] }, "reference_id": { "type": "string", "description": "The data.reference_id returned by Generate OTP for CSI download." }, "otp": { "type": "string", "description": "OTP sent to the mobile number provided in the generation request." } }, "required": [ "@entity", "reference_id", "otp" ] }, "examples": { "200 - Success": { "value": { "@entity": "in.co.sandbox.tds.compliance.deductors.csi.request", "reference_id": "FOS005981930273", "otp": "834201" }, "summary": "200 - Success" }, "200 Invalid OTP": { "value": { "@entity": "in.co.sandbox.tds.compliance.deductors.csi.request", "reference_id": "FOS101212121212121", "otp": "121212" }, "summary": "200 Invalid OTP" }, "200 OTP Expired": { "value": { "@entity": "in.co.sandbox.tds.compliance.deductors.csi.request", "reference_id": "FOS101212121212121", "otp": "121212" }, "summary": "200 OTP Expired" } } } } }, "responses": { "200": { "description": "Check the response body for the result. HTTP 200 can also contain an application error in data.message.", "content": { "application/json": { "schema": { "type": "object", "properties": { "timestamp": { "type": "integer" }, "transaction_id": { "type": "string" }, "data": { "type": "object", "properties": { "@entity": { "type": "string" }, "tan": { "type": "string" }, "from": { "type": "integer" }, "to": { "type": "integer" }, "reference_id": { "type": "string", "description": "Reference ID associated with the verified OTP request." }, "csi_url": { "type": "string", "description": "Download the CSI file from this URL after successful verification. The example URL is illustrative." }, "message": { "type": "string", "description": "Application error message when verification fails, such as an incorrect or expired OTP." } } }, "code": { "type": "integer" } } }, "examples": { "200 - Success": { "summary": "200 - Success", "value": { "timestamp": 1731669721578, "transaction_id": "8a0c097f-8e6d-4c11-8228-87d3c8cc44ce", "data": { "@entity": "in.co.sandbox.tds.compliance.deductors.csi.response", "tan": "AHMA09719B", "from": 1722450600000, "to": 1730313000000, "reference_id": "FOS005981930273", "csi_url": "https://example.com/challan.csi" }, "code": 200 } }, "200 Invalid OTP": { "summary": "200 Invalid OTP", "value": { "code": 200, "timestamp": 1763362637000, "transaction_id": "e2b9145f-69d5-4bbe-a6de-be6fc08b426f", "data": { "@entity": "in.co.sandbox.tds.compliance.deductors.csi", "message": "The OTP you have entered is incorrect." } } }, "200 OTP Expired": { "summary": "200 OTP Expired", "value": { "code": 200, "timestamp": 1763362637000, "transaction_id": "e2b9145f-69d5-4bbe-a6de-be6fc08b426f", "data": { "@entity": "in.co.sandbox.tds.compliance.deductors.csi", "message": "OTP expired" } } } } } }, "headers": {} } }, "security": [] } }, "/tds/compliance/fvu/generate": { "post": { "summary": "Create FVU generation job", "deprecated": false, "description": "Creates an FVU generation job for a TDS or TCS return. Upload the return text and CSI files to the returned URLs using HTTP PUT. For correction returns, the response also includes a consolidated file upload URL. Use `job_id` to check the validation result.", "tags": [ "FVU Generation" ], "parameters": [ { "name": "authorization", "in": "header", "description": "JWT authorization token", "required": true, "example": "{{access_token}}", "schema": { "type": "string" } }, { "name": "x-api-key", "in": "header", "description": "Public key required to authorize API access.", "required": true, "example": "{{api_key}}", "schema": { "type": "string" } }, { "name": "x-api-version", "in": "header", "description": "", "required": false, "example": "", "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "@entity": { "type": "string", "enum": [ "in.co.sandbox.tds.compliance.fvu.generate.request" ] }, "tax_year": { "description": "Tax Year (e.g. TY 2026-27)", "type": "string", "examples": [ "TY 2026-27" ], "pattern": "^TY [0-9]{4}-[0-9]{2}$" }, "quarter": { "enum": [ "Q1", "Q2", "Q3", "Q4" ], "type": "string", "examples": [ "Q1" ] }, "form": { "enum": [ "138", "140", "144", "143" ], "type": "string", "examples": [ "140" ], "description": "TDS/TCS return form. Use 138 for erstwhile 24Q, 140 for erstwhile 26Q, 144 for erstwhile 27Q, and 143 for erstwhile 27EQ." }, "tan": { "description": "TAN of deductor/collector. Regular Expression: [A-Z]{4}[0-9]{5}[A-Z]{1}", "pattern": "[A-Z]{4}[0-9]{5}[A-Z]{1}", "type": "string" }, "filing_type": { "description": "Type of TDS/TCS Return", "enum": [ "regular", "correction" ], "type": "string", "examples": [ "regular" ] } }, "required": [ "@entity", "tax_year", "tan", "form", "quarter", "filing_type" ] }, "examples": { "200 - Success": { "value": { "@entity": "in.co.sandbox.tds.compliance.fvu.generate.request", "tax_year": "TY 2026-27", "form": "138", "quarter": "Q1", "tan": "AHMQ00112A", "filing_type": "regular" }, "summary": "200 - Success" }, "200 Job created for Correction return": { "value": { "@entity": "in.co.sandbox.tds.compliance.fvu.generate.request", "tax_year": "TY 2026-27", "form": "138", "quarter": "Q4", "tan": "AHMA09719B", "filing_type": "correction" }, "summary": "200 Job created for Correction return" } } } } }, "responses": { "200": { "description": "200 - OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "code": { "type": "integer" }, "timestamp": { "type": "integer" }, "transaction_id": { "type": "string" }, "data": { "type": "object", "properties": { "@entity": { "type": "string" }, "job_id": { "type": "string", "description": "Job ID used to check status." }, "tan": { "type": "string" }, "tax_year": { "type": "string", "description": "Tax Year (e.g. TY 2026-27)", "examples": [ "TY 2026-27" ], "pattern": "^TY [0-9]{4}-[0-9]{2}$" }, "quarter": { "type": "string" }, "form": { "type": "string" }, "filing_type": { "type": "string" }, "status": { "type": "string" }, "created_at": { "type": "integer" }, "txt_file_upload_url": { "type": "string", "format": "uri", "description": "Pre-signed URL for uploading the return text file with HTTP PUT." }, "csi_file_upload_url": { "type": "string", "format": "uri", "description": "Pre-signed URL for uploading the CSI file with HTTP PUT." } } } } }, "examples": { "200 - Success": { "summary": "200 - Success", "value": { "code": 200, "timestamp": 1763362637000, "transaction_id": "e2b9145f-69d5-4bbe-a6de-be6fc08b426f", "data": { "@entity": "in.co.sandbox.tds.compliance.fvu.generate.job", "job_id": "4ef92975-aea8-4628-9eaa-18eb439c13d9", "tan": "AHMA09719B", "tax_year": "TY 2026-27", "quarter": "Q3", "form": "138", "filing_type": "regular", "status": "created", "created_at": 1763362637000, "txt_file_upload_url": "https://in-co-sandbox-tds-test-storage.s3.ap-south-1.amazonaws.com/upload/file", "csi_file_upload_url": "https://in-co-sandbox-tds-test-storage.s3.ap-south-1.amazonaws.com/upload/file" } } }, "200 Job created for Correction return": { "summary": "200 Job created for Correction return", "value": { "code": 200, "timestamp": 1763362637000, "transaction_id": "e2b9145f-69d5-4bbe-a6de-be6fc08b426f", "data": { "@entity": "in.co.sandbox.tds.compliance.fvu.generate.job", "job_id": "f845f37e-7f05-4de9-a282-a3b23b9d370a", "tan": "AHMA09719B", "tax_year": "TY 2026-27", "quarter": "Q4", "form": "138", "filing_type": "correction", "status": "created", "created_at": 1763362637000, "txt_file_upload_url": "https://in-co-sandbox-tds-test-storage.s3.ap-south-1.amazonaws.com/upload/file", "csi_file_upload_url": "https://in-co-sandbox-tds-test-storage.s3.ap-south-1.amazonaws.com/upload/file", "conso_file_upload_url": "https://in-co-sandbox-tds-test-storage.s3.ap-south-1.amazonaws.com/upload/file" } } } } } }, "headers": {} } }, "security": [] }, "get": { "summary": "Get FVU generation job status", "deprecated": false, "description": "Returns the FVU generation status for `job_id`. On success, download the ZIP from `data.fvu_zip_file_url`. On validation failure, check `data.validation_report_file_url`. HTTP 200 does not mean the job succeeded.", "tags": [ "FVU Generation" ], "parameters": [ { "name": "job_id", "in": "query", "description": "Job ID returned when the job was created.", "required": false, "example": "{{job_id}}", "schema": {} }, { "name": "authorization", "in": "header", "description": "JWT authorization token", "required": true, "example": "{{access_token}}", "schema": { "type": "string" } }, { "name": "x-api-key", "in": "header", "description": "Public key required to authorize API access.", "required": true, "example": "{{api_key}}", "schema": { "type": "string" } }, { "name": "x-api-version", "in": "header", "description": "", "required": false, "example": "", "schema": { "type": "string" } } ], "responses": { "200": { "description": "200 - OK", "content": { "application/json": { "schema": { "oneOf": [ { "title": "Job Queued", "type": "object", "properties": { "code": { "type": "integer" }, "timestamp": { "type": "integer" }, "transaction_id": { "type": "string" }, "data": { "type": "object", "properties": { "@entity": { "type": "string" }, "job_id": { "type": "string", "description": "Job ID used to check status." }, "tan": { "type": "string" }, "tax_year": { "type": "string", "description": "Tax Year (e.g. TY 2026-27)", "examples": [ "TY 2026-27" ], "pattern": "^TY [0-9]{4}-[0-9]{2}$" }, "quarter": { "type": "string" }, "form": { "type": "string" }, "filing_type": { "type": "string" }, "status": { "type": "string" }, "created_at": { "type": "integer" }, "updated_at": { "type": "integer" } } } } }, { "title": "Job Succeeded", "type": "object", "properties": { "code": { "type": "integer" }, "timestamp": { "type": "integer" }, "transaction_id": { "type": "string" }, "data": { "type": "object", "properties": { "@entity": { "type": "string" }, "job_id": { "type": "string", "description": "Job ID used to check status." }, "tan": { "type": "string" }, "tax_year": { "type": "string", "description": "Tax Year (e.g. TY 2026-27)", "examples": [ "TY 2026-27" ], "pattern": "^TY [0-9]{4}-[0-9]{2}$" }, "quarter": { "type": "string" }, "form": { "type": "string" }, "filing_type": { "type": "string" }, "status": { "type": "string" }, "created_at": { "type": "integer" }, "updated_at": { "type": "integer" }, "fvu_zip_file_url": { "type": "string", "format": "uri", "description": "Download URL for the FVU ZIP produced by a successful validation job." } } } } }, { "title": "Job Failed", "type": "object", "properties": { "code": { "type": "integer" }, "timestamp": { "type": "integer" }, "transaction_id": { "type": "string" }, "data": { "type": "object", "properties": { "@entity": { "type": "string" }, "job_id": { "type": "string", "description": "Job ID used to check status." }, "tan": { "type": "string" }, "tax_year": { "type": "string", "description": "Tax Year (e.g. TY 2026-27)", "examples": [ "TY 2026-27" ], "pattern": "^TY [0-9]{4}-[0-9]{2}$" }, "quarter": { "type": "string" }, "form": { "type": "string" }, "filing_type": { "type": "string" }, "status": { "type": "string" }, "created_at": { "type": "integer" }, "updated_at": { "type": "integer" }, "validation_report_file_url": { "type": "string", "format": "uri", "description": "Download URL for the report describing input validation failures." } } } } } ] }, "examples": { "200 - Job Success": { "summary": "200 - Job Success", "value": { "code": 200, "timestamp": 1763362637000, "transaction_id": "e2b9145f-69d5-4bbe-a6de-be6fc08b426f", "data": { "@entity": "in.co.sandbox.tds.compliance.fvu.generate.job", "job_id": "4ef92975-aea8-4628-9eaa-18eb439c13d9", "tan": "AHMA09719B", "tax_year": "TY 2026-27", "quarter": "Q3", "form": "138", "filing_type": "regular", "status": "succeeded", "created_at": 1763362637000, "updated_at": 1763362637000, "fvu_zip_file_url": "https://in-co-sandbox-tds-test-storage.s3.ap-south-1.amazonaws.com/AHMS45586C/FY+2025-26/Q3/140/4049c226-4988-4978-b5ad-d25705453da8/140.zip" } } }, "200 Job succeeded for Correction return": { "summary": "200 Job succeeded for Correction return", "value": { "code": 200, "timestamp": 1763362637000, "transaction_id": "e2b9145f-69d5-4bbe-a6de-be6fc08b426f", "data": { "@entity": "in.co.sandbox.tds.compliance.fvu.generate.job", "job_id": "445731fc-f785-4672-989a-6d332149e06f", "tan": "AHMA09719B", "tax_year": "TY 2026-27", "quarter": "Q3", "form": "138", "filing_type": "correction", "status": "succeeded", "created_at": 1763362637000, "updated_at": 1763362637000, "fvu_zip_file_url": "https://in-co-sandbox-tds-compliance-fvu-test.s3.ap-south-1.amazonaws.com/tan/tax_year/quarter/form/f845f37e-7f05-4de9-a282-a3b23b9d370a.zip" } } }, "200 - Job Failed": { "summary": "200 - Job Failed", "value": { "code": 200, "timestamp": 1763362637000, "transaction_id": "e2b9145f-69d5-4bbe-a6de-be6fc08b426f", "data": { "@entity": "in.co.sandbox.tds.compliance.fvu.generate.job", "job_id": "7a9176ef-1e59-4b8e-a1de-ee15b09963f8", "tan": "AHMA09719B", "tax_year": "TY 2026-27", "quarter": "Q3", "form": "138", "filing_type": "regular", "status": "failed", "created_at": 1763362637000, "updated_at": 1763362637000, "validation_report_file_url": "https://in-co-sandbox-cms-prod1.s3.ap-south-1.amazonaws.com/test-api-mock/tds/json.json" } } }, "200 Job Queued": { "summary": "200 Job Queued", "value": { "code": 200, "timestamp": 1763362637000, "transaction_id": "e2b9145f-69d5-4bbe-a6de-be6fc08b426f", "data": { "@entity": "in.co.sandbox.tds.compliance.fvu.generate.job", "job_id": "db544879-a592-466f-a948-83b5a11cd52d", "tan": "AHMA09719B", "tax_year": "TY 2026-27", "quarter": "Q3", "form": "138", "filing_type": "regular", "status": "queued", "created_at": 1763362637000, "updated_at": 1763362637000 } } }, "200 Job created": { "summary": "200 Job created", "value": { "code": 200, "timestamp": 1763362637000, "transaction_id": "e2b9145f-69d5-4bbe-a6de-be6fc08b426f", "data": { "@entity": "in.co.sandbox.tds.compliance.fvu.generate.job", "job_id": "a88ce705-e16f-4a44-9b56-273bfbc039d5", "tan": "AHMA09719B", "tax_year": "TY 2026-27", "quarter": "Q3", "form": "138", "filing_type": "regular", "status": "created", "created_at": 1763362637000 } } } } } }, "headers": {} }, "521": { "description": "521 - Data Not Found", "content": { "application/json": { "schema": { "type": "object", "properties": { "code": { "type": "integer" }, "timestamp": { "type": "integer" }, "transaction_id": { "type": "string" }, "message": { "type": "string", "description": "Reason for the job failure." } } }, "examples": { "521 Data not found": { "summary": "521 Data not found", "value": { "code": 521, "timestamp": 1763362637000, "transaction_id": "e2b9145f-69d5-4bbe-a6de-be6fc08b426f", "message": "Data not found" } } } } }, "headers": {} } }, "security": [] } }, "/tds/compliance/fvu/generate/search": { "post": { "summary": "Search FVU generation jobs", "deprecated": false, "description": "Finds FVU generation jobs by TAN, form, tax year, quarter, filing type, or creation date. Results appear in `data.items`. Set `page_size` to request up to 50 records. Use `last_evaluated_key` for pagination.", "tags": [ "FVU Generation" ], "parameters": [ { "name": "authorization", "in": "header", "description": "JWT authorization token", "required": true, "example": "{{access_token}}", "schema": { "type": "string" } }, { "name": "x-api-key", "in": "header", "description": "Public key required to authorize API access.", "required": true, "example": "{{api_key}}", "schema": { "type": "string" } }, { "name": "x-api-version", "in": "header", "description": "", "required": false, "example": "", "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "@entity": { "type": "string", "enum": [ "in.co.sandbox.tds.compliance.fvu.generate.search" ] }, "tax_year": { "description": "Tax Year (e.g. TY 2026-27)", "type": "string", "pattern": "^TY [0-9]{4}-[0-9]{2}$", "examples": [ "TY 2026-27" ] }, "form": { "description": "TDS return form", "type": "string" }, "quarter": { "description": "Quarter (e.g. Q2)", "type": "string" }, "tan": { "description": "TAN of deductor/collector. Regular Expression: [A-Z]{4}[0-9]{5}[A-Z]{1}", "type": "string" }, "filing_type": { "description": "Type of TDS/TCS Return", "type": "string" }, "from_date": { "description": "Start of the job creation-date range, expressed as an epoch timestamp.", "type": "integer" }, "to_date": { "description": "End of the job creation-date range, expressed as an epoch timestamp.", "type": "integer" }, "page_size": { "description": "Number of records in the API response. Maximum allowed size is 50", "type": "integer" }, "last_evaluated_key": { "description": "Base64 encoding of the stringified JSON object, which includes x-api-key, created_at, and job_id", "type": "string" } }, "required": [ "@entity" ] }, "examples": { "Search by TAN and tax period": { "summary": "Search by TAN and tax period", "value": { "@entity": "in.co.sandbox.tds.compliance.fvu.generate.search", "tan": "AHMA09719B", "tax_year": "TY 2026-27", "quarter": "Q1", "form": "140", "page_size": 10 } } } } } }, "responses": { "200": { "description": "200 - OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "code": { "type": "integer" }, "timestamp": { "type": "integer" }, "data": { "type": "object", "properties": { "@entity": { "type": "string", "enum": [ "in.co.sandbox.tds.compliance.fvu.generate.paginated_list" ] }, "items": { "type": "array", "items": { "type": "object", "properties": { "created_at": { "type": "integer" }, "@entity": { "type": "string" }, "job_id": { "type": "string", "description": "Job ID used to check status." }, "tan": { "type": "string" }, "tax_year": { "type": "string", "description": "Tax Year (e.g. TY 2026-27)", "examples": [ "TY 2026-27" ], "pattern": "^TY [0-9]{4}-[0-9]{2}$" }, "quarter": { "type": "string" }, "form": { "type": "string" }, "filing_type": { "type": "string" }, "status": { "type": "string" } } } } } }, "transaction_id": { "type": "string" } } }, "examples": { "200 job success": { "summary": "200 job success", "value": { "code": 200, "timestamp": 1763035746825, "data": { "@entity": "in.co.sandbox.tds.compliance.fvu.generate.paginated_list", "items": [ { "created_at": 1762511623903, "@entity": "in.co.sandbox.tds.compliance.fvu.generate.job", "job_id": "6622b26a-9601-4692-9c9c-a9b3a1ff8a6e", "tan": "AHMA44270C", "tax_year": "TY 2026-27", "quarter": "Q3", "form": "140", "filing_type": "regular", "status": "created" }, { "created_at": 1762238825579, "@entity": "in.co.sandbox.tds.compliance.fvu.generate.job", "job_id": "c4894d31-c59d-4955-b5a8-5c124e3e8072", "tan": "AHMA00000C", "tax_year": "TY 2026-27", "quarter": "Q2", "form": "140", "filing_type": "regular", "status": "created" }, { "created_at": 1762238798138, "@entity": "in.co.sandbox.tds.compliance.fvu.generate.job", "job_id": "83526ecf-9401-4472-9894-0dded05a5b2d", "tan": "AHMA00000C", "tax_year": "TY 2026-27", "quarter": "Q2", "form": "140", "filing_type": "regular", "status": "created" }, { "created_at": 1761819084423, "updated_at": 1761819130863, "@entity": "in.co.sandbox.tds.compliance.fvu.generate.job", "job_id": "6f006f8d-7680-47de-8982-950a6bba48c2", "tan": "AHMQ00112A", "tax_year": "TY 2026-27", "quarter": "Q2", "form": "140", "filing_type": "regular", "status": "succeeded" }, { "created_at": 1761818231823, "updated_at": 1761818280529, "@entity": "in.co.sandbox.tds.compliance.fvu.generate.job", "job_id": "98e92413-b1a1-4f15-9efc-84f0b617dd64", "tan": "AHMQ00112A", "tax_year": "TY 2026-27", "quarter": "Q2", "form": "140", "filing_type": "regular", "status": "failed" }, { "created_at": 1761738587585, "updated_at": 1761738622697, "@entity": "in.co.sandbox.tds.compliance.fvu.generate.job", "job_id": "183a31e4-fdc4-437b-8054-f87121af6dcc", "tan": "AHMQ00112A", "tax_year": "TY 2026-27", "quarter": "Q2", "form": "138", "filing_type": "regular", "status": "succeeded" }, { "created_at": 1761738584006, "@entity": "in.co.sandbox.tds.compliance.fvu.generate.job", "job_id": "e5142096-8182-46e7-8e19-b12159f8c965", "tan": "AHMQ00112A", "tax_year": "TY 2026-27", "quarter": "Q2", "form": "138", "filing_type": "regular", "status": "created" }, { "created_at": 1761737173402, "updated_at": 1761737219289, "@entity": "in.co.sandbox.tds.compliance.fvu.generate.job", "job_id": "1c8fce43-401e-4876-a78d-1043f81a7954", "tan": "AHMQ00112A", "tax_year": "TY 2026-27", "quarter": "Q2", "form": "138", "filing_type": "regular", "message": "Form mismatch", "status": "failed" }, { "created_at": 1761732724431, "updated_at": 1761732773453, "@entity": "in.co.sandbox.tds.compliance.fvu.generate.job", "job_id": "5c7dfb7d-7915-42e2-b0d5-7aa93449a648", "tan": "AHMS45586C", "tax_year": "TY 2026-27", "quarter": "Q2", "form": "140", "filing_type": "regular", "status": "succeeded" }, { "created_at": 1761659003619, "updated_at": 1761659086073, "@entity": "in.co.sandbox.tds.compliance.fvu.generate.job", "job_id": "2c35a44b-e61b-4a70-9a92-079354710133", "tan": "AHMS45586C", "tax_year": "TY 2026-27", "quarter": "Q2", "form": "138", "filing_type": "regular", "status": "succeeded" }, { "created_at": 1761634299914, "updated_at": 1761634345747, "@entity": "in.co.sandbox.tds.compliance.fvu.generate.job", "job_id": "56625794-b1a9-4d7d-a26d-7fcbd18632a7", "tan": "BLRR32170F", "tax_year": "TY 2026-27", "quarter": "Q2", "form": "144", "filing_type": "regular", "status": "succeeded" }, { "created_at": 1761571384235, "updated_at": 1761571434955, "@entity": "in.co.sandbox.tds.compliance.fvu.generate.job", "job_id": "e4f848a0-5bb6-448b-ba69-250a38455517", "tan": "DELG20840B", "tax_year": "TY 2026-27", "quarter": "Q2", "form": "144", "filing_type": "regular", "status": "succeeded" }, { "created_at": 1761570981608, "updated_at": 1761571018207, "@entity": "in.co.sandbox.tds.compliance.fvu.generate.job", "job_id": "6fe7be04-96db-4b18-90c3-0a8ea7692225", "tan": "DELG20840B", "tax_year": "TY 2026-27", "quarter": "Q2", "form": "144", "filing_type": "regular", "status": "failed" }, { "created_at": 1761557897110, "updated_at": 1761557936792, "@entity": "in.co.sandbox.tds.compliance.fvu.generate.job", "job_id": "d281be50-92c7-4b53-ac9f-1b4e61b20dbf", "tan": "BLRV26339F", "tax_year": "TY 2026-27", "quarter": "Q2", "form": "144", "filing_type": "regular", "status": "succeeded" }, { "created_at": 1761551312937, "updated_at": 1761551348037, "@entity": "in.co.sandbox.tds.compliance.fvu.generate.job", "job_id": "9b2349d4-a754-4fab-8e7f-320849436709", "tan": "MUMK37337G", "tax_year": "TY 2026-27", "quarter": "Q2", "form": "144", "filing_type": "regular", "status": "succeeded" }, { "created_at": 1760539426714, "updated_at": 1760539477220, "@entity": "in.co.sandbox.tds.compliance.fvu.generate.job", "job_id": "410c3dfb-86b1-4f17-bf5e-537485be3979", "tan": "MRTA26471E", "tax_year": "TY 2026-27", "quarter": "Q2", "form": "144", "filing_type": "regular", "status": "succeeded" }, { "created_at": 1760015060012, "updated_at": 1760015230331, "@entity": "in.co.sandbox.tds.compliance.fvu.generate.job", "job_id": "5264a512-fba0-408d-8c22-3b1e876248d3", "tan": "MUMP51255B", "tax_year": "TY 2026-27", "quarter": "Q2", "form": "144", "filing_type": "regular", "status": "succeeded" } ] }, "transaction_id": "c93b4b70-67e8-4853-9dd4-15d3ef50c5b2" } } } } }, "headers": {} } }, "security": [] } }, "/tds/compliance/e-file": { "post": { "summary": "Create TDS return e-filing job", "deprecated": false, "description": "Creates a TDS or TCS e-filing job. Upload a ZIP containing the FVU file and Form 27A to `data.fvu_upload_file_url` using HTTP PUT. Use `data.job_id` to check the filing result. Creating the job does not file the return.", "tags": [ "E-File TDS Return" ], "parameters": [ { "name": "authorization", "in": "header", "description": "JWT access token", "required": true, "example": "{{access_token}}", "schema": { "type": "string" } }, { "name": "x-api-key", "in": "header", "description": "API key for identification", "required": true, "example": "{{api_key}}", "schema": { "type": "string" } }, { "name": "x-api-version", "in": "header", "description": "API version", "required": false, "example": "", "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "@entity": { "type": "string", "enum": [ "in.co.sandbox.tds.compliance.e-file.request" ] }, "tax_year": { "description": "Tax Year (e.g. TY 2026-27)", "type": "string", "examples": [ "TY 2026-27" ], "pattern": "^TY [0-9]{4}-[0-9]{2}$" }, "form": { "description": "TDS/TCS return form. Use 138 for erstwhile 24Q, 140 for erstwhile 26Q, 144 for erstwhile 27Q, and 143 for erstwhile 27EQ.", "enum": [ "138", "140", "144", "143" ], "type": "string" }, "quarter": { "enum": [ "Q1", "Q2", "Q3", "Q4" ], "type": "string" }, "tan": { "description": "TAN of deductor/collector. Regular Expression: [A-Z]{4}[0-9]{5}[A-Z]{1}", "type": "string", "examples": [ "AHMA09719B" ] } }, "required": [ "@entity", "tax_year", "quarter", "tan", "form" ] }, "examples": { "200 Job created": { "value": { "@entity": "in.co.sandbox.tds.compliance.e-file.request", "tax_year": "TY 2026-27", "form": "140", "quarter": "Q1", "tan": "AHMS45586C" }, "summary": "200 Job created" }, "200 Job created: Statement furnished": { "value": { "@entity": "in.co.sandbox.tds.compliance.e-file.request", "tax_year": "TY 2026-27", "form": "140", "quarter": "Q2", "tan": "MUMR09719B" }, "summary": "200 Job created: Statement furnished" }, "200 Job created: Unacceptable fvu": { "value": { "@entity": "in.co.sandbox.tds.compliance.e-file.request", "tax_year": "TY 2026-27", "form": "144", "quarter": "Q2", "tan": "AABC23456D" }, "summary": "200 Job created: Unacceptable fvu" }, "200 Job created: invalid archive": { "value": { "@entity": "in.co.sandbox.tds.compliance.e-file.request", "tax_year": "TY 2026-27", "form": "140", "quarter": "Q4", "tan": "PDES03028E" }, "summary": "200 Job created: invalid archive" }, "200 Job created: Form type mismatch": { "value": { "@entity": "in.co.sandbox.tds.compliance.e-file.request", "tax_year": "TY 2026-27", "form": "138", "quarter": "Q4", "tan": "HYDC23456G" }, "summary": "200 Job created: Form type mismatch" }, "200 Job created: Quarter mismatch": { "value": { "@entity": "in.co.sandbox.tds.compliance.e-file.request", "tax_year": "TY 2026-27", "form": "140", "quarter": "Q2", "tan": "MUMC23456H" }, "summary": "200 Job created: Quarter mismatch" }, "200 Job created: Barcode mismatch": { "value": { "@entity": "in.co.sandbox.tds.compliance.e-file.request", "tax_year": "TY 2026-27", "form": "144", "quarter": "Q3", "tan": "DELC23456I" }, "summary": "200 Job created: Barcode mismatch" }, "200 Job created: Invalid entries": { "value": { "@entity": "in.co.sandbox.tds.compliance.e-file.request", "tax_year": "TY 2026-27", "form": "140", "quarter": "Q2", "tan": "BLRC23456F" }, "summary": "200 Job created: Invalid entries" }, "200 Job created: Tax year mismatch": { "value": { "@entity": "in.co.sandbox.tds.compliance.e-file.request", "tax_year": "TY 2026-27", "form": "138", "quarter": "Q4", "tan": "PUNC23456J" }, "summary": "200 Job created: Tax year mismatch" }, "200 Job created: TAN mismatch": { "value": { "@entity": "in.co.sandbox.tds.compliance.e-file.request", "tax_year": "TY 2026-27", "form": "138", "quarter": "Q2", "tan": "KOLT23456K" }, "summary": "200 Job created: TAN mismatch" }, "200 Job created: Form27A missing": { "value": { "@entity": "in.co.sandbox.tds.compliance.e-file.request", "tax_year": "TY 2026-27", "form": "144", "quarter": "Q3", "tan": "CABC23456M" }, "summary": "200 Job created: Form27A missing" }, "200 Job created: FVU missing": { "value": { "@entity": "in.co.sandbox.tds.compliance.e-file.request", "tax_year": "TY 2026-27", "form": "140", "quarter": "Q1", "tan": "BABC23456L" }, "summary": "200 Job created: FVU missing" }, "test csi file": { "value": { "@entity": "in.co.sandbox.tds.compliance.e-file.request", "tax_year": "TY 2026-27", "form": "140", "quarter": "Q2", "tan": "SRTH05889C" }, "summary": "test csi file" } } } } }, "responses": { "200": { "description": "200 - OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "code": { "type": "integer" }, "timestamp": { "type": "integer" }, "transaction_id": { "type": "string" }, "data": { "type": "object", "properties": { "@entity": { "type": "string" }, "job_id": { "type": "string", "description": "Job ID used to check status." }, "tan": { "type": "string" }, "tax_year": { "type": "string", "description": "Tax Year (e.g. TY 2026-27)", "examples": [ "TY 2026-27" ], "pattern": "^TY [0-9]{4}-[0-9]{2}$" }, "quarter": { "type": "string" }, "form": { "type": "string" }, "status": { "type": "string" }, "created_at": { "type": "integer" }, "fvu_upload_file_url": { "type": "string", "format": "uri", "description": "Pre-signed URL for uploading a ZIP containing the FVU file and Form 27A with HTTP PUT." } } } } }, "examples": { "200 Job created": { "summary": "200 Job created", "value": { "code": 200, "timestamp": 1763362637000, "transaction_id": "e2b9145f-69d5-4bbe-a6de-be6fc08b426f", "data": { "@entity": "in.co.sandbox.tds.compliance.e-file.job", "job_id": "f845f37e-7f05-4de9-a282-a3b23b9d370a", "tan": "AHMA09719B", "tax_year": "TY 2026-27", "quarter": "Q2", "form": "138", "status": "created", "created_at": 1763362637000, "fvu_upload_file_url": "https://in-co-sandbox-tds-test-storage.s3.ap-south-1.amazonaws.com/upload/file" } } }, "200 Job created: Statement furnished": { "summary": "200 Job created: Statement furnished", "value": { "code": 200, "timestamp": 1763362637000, "transaction_id": "e2b9145f-69d5-4bbe-a6de-be6fc08b426f", "data": { "@entity": "in.co.sandbox.tds.compliance.e-file.job", "job_id": "6e8d1908-c062-4846-a811-8f73054acd65", "tan": "MUMR09719B", "tax_year": "TY 2026-27", "quarter": "Q2", "form": "140", "status": "created", "created_at": 1763362637000, "fvu_upload_file_url": "https://in-co-sandbox-tds-test-storage.s3.ap-south-1.amazonaws.com/upload/file" } } }, "200 Job created: Unacceptable fvu": { "summary": "200 Job created: Unacceptable fvu", "value": { "code": 200, "timestamp": 1763362637000, "transaction_id": "e2b9145f-69d5-4bbe-a6de-be6fc08b426f", "data": { "@entity": "in.co.sandbox.tds.compliance.e-file.job", "job_id": "d75c3d26-4f81-451f-ab38-e217ea801ea1", "tan": "AABC23456D", "tax_year": "TY 2026-27", "quarter": "Q2", "form": "144", "status": "created", "created_at": 1763362637000, "fvu_upload_file_url": "https://in-co-sandbox-tds-test-storage.s3.ap-south-1.amazonaws.com/upload/file" } } }, "200 Job created: invalid archive": { "summary": "200 Job created: invalid archive", "value": { "code": 200, "timestamp": 1763362637000, "transaction_id": "e2b9145f-69d5-4bbe-a6de-be6fc08b426f", "data": { "@entity": "in.co.sandbox.tds.compliance.e-file.job", "job_id": "d1213059-ec22-4e10-b0c1-a91814377001", "tan": "PDES03028E", "tax_year": "TY 2026-27", "quarter": "Q4", "form": "140", "status": "created", "created_at": 1763362637000, "fvu_upload_file_url": "https://in-co-sandbox-tds-test-storage.s3.ap-south-1.amazonaws.com/upload/file" } } }, "200 Job created: Form type mismatch": { "summary": "200 Job created: Form type mismatch", "value": { "code": 200, "timestamp": 1763362637000, "transaction_id": "e2b9145f-69d5-4bbe-a6de-be6fc08b426f", "data": { "@entity": "in.co.sandbox.tds.compliance.e-file.job", "job_id": "d6f5b340-440b-400c-9b86-16e691e768b0", "tan": "HYDC23456G", "tax_year": "TY 2026-27", "quarter": "Q4", "form": "138", "status": "created", "created_at": 1763362637000, "fvu_upload_file_url": "https://in-co-sandbox-tds-test-storage.s3.ap-south-1.amazonaws.com/upload/file" } } }, "200 Job created: Quarter mismatch": { "summary": "200 Job created: Quarter mismatch", "value": { "code": 200, "timestamp": 1763362637000, "transaction_id": "e2b9145f-69d5-4bbe-a6de-be6fc08b426f", "data": { "@entity": "in.co.sandbox.tds.compliance.e-file.job", "job_id": "7a62876a-d638-430c-ad77-8fe33d9e63d5", "tan": "MUMC23456H", "tax_year": "TY 2026-27", "quarter": "Q2", "form": "140", "status": "created", "created_at": 1763362637000, "fvu_upload_file_url": "https://in-co-sandbox-tds-test-storage.s3.ap-south-1.amazonaws.com/upload/file" } } }, "200 Job created: Barcode mismatch": { "summary": "200 Job created: Barcode mismatch", "value": { "code": 200, "timestamp": 1763362637000, "transaction_id": "e2b9145f-69d5-4bbe-a6de-be6fc08b426f", "data": { "@entity": "in.co.sandbox.tds.compliance.e-file.job", "job_id": "6b11d176-b3c5-483c-9052-b533a6e92377", "tan": "DELC23456I", "tax_year": "TY 2026-27", "quarter": "Q3", "form": "144", "status": "created", "created_at": 1763362637000, "fvu_upload_file_url": "https://in-co-sandbox-tds-test-storage.s3.ap-south-1.amazonaws.com/upload/file" } } }, "200 Job created: Invalid entries": { "summary": "200 Job created: Invalid entries", "value": { "code": 200, "timestamp": 1763362637000, "transaction_id": "e2b9145f-69d5-4bbe-a6de-be6fc08b426f", "data": { "@entity": "in.co.sandbox.tds.compliance.e-file.job", "job_id": "3b979ce9-ef4e-4157-a4a3-51e8747e76d7", "tan": "BLRC23456F", "tax_year": "TY 2026-27", "quarter": "Q2", "form": "140", "status": "created", "created_at": 1763362637000, "fvu_upload_file_url": "https://in-co-sandbox-tds-test-storage.s3.ap-south-1.amazonaws.com/upload/file" } } }, "200 Job created: Tax year mismatch": { "summary": "200 Job created: Tax year mismatch", "value": { "code": 200, "timestamp": 1763362637000, "transaction_id": "e2b9145f-69d5-4bbe-a6de-be6fc08b426f", "data": { "@entity": "in.co.sandbox.tds.compliance.e-file.job", "job_id": "7928082e-34ca-474c-ba05-4ede9598b9b5", "tan": "PUNC23456J", "tax_year": "TY 2026-27", "quarter": "Q4", "form": "140", "status": "created", "created_at": 1763362637000, "fvu_upload_file_url": "https://in-co-sandbox-tds-test-storage.s3.ap-south-1.amazonaws.com/upload/file" } } }, "200 Job created: TAN mismatch": { "summary": "200 Job created: TAN mismatch", "value": { "code": 200, "timestamp": 1763362637000, "transaction_id": "e2b9145f-69d5-4bbe-a6de-be6fc08b426f", "data": { "@entity": "in.co.sandbox.tds.compliance.e-file.job", "job_id": "5fd2679f-040f-435c-a285-df5817a150b5", "tan": "KOLT23456K", "tax_year": "TY 2026-27", "quarter": "Q2", "form": "140", "status": "created", "created_at": 1763362637000, "fvu_upload_file_url": "https://in-co-sandbox-tds-test-storage.s3.ap-south-1.amazonaws.com/upload/file" } } }, "200 Job created: Form27A missing": { "summary": "200 Job created: Form27A missing", "value": { "code": 200, "timestamp": 1763362637000, "transaction_id": "e2b9145f-69d5-4bbe-a6de-be6fc08b426f", "data": { "@entity": "in.co.sandbox.tds.compliance.e-file.job", "job_id": "b411fbee-68e4-4da3-9f62-8de8ca09a74c", "tan": "CABC23456M", "tax_year": "TY 2026-27", "quarter": "Q3", "form": "140", "status": "created", "created_at": 1763362637000, "fvu_upload_file_url": "https://in-co-sandbox-tds-test-storage.s3.ap-south-1.amazonaws.com/upload/file" } } }, "200 Job created: FVU missing": { "summary": "200 Job created: FVU missing", "value": { "code": 200, "timestamp": 1763362637000, "transaction_id": "e2b9145f-69d5-4bbe-a6de-be6fc08b426f", "data": { "@entity": "in.co.sandbox.tds.compliance.e-file.job", "job_id": "9bf0b6f8-5957-484f-9aea-0d235054974c", "tan": "BABC23456L", "tax_year": "TY 2026-27", "quarter": "Q1", "form": "140", "status": "created", "created_at": 1763362637000, "fvu_upload_file_url": "https://in-co-sandbox-tds-test-storage.s3.ap-south-1.amazonaws.com/upload/file" } } }, "test csi file": { "summary": "test csi file", "value": "csi mock data" } } } }, "headers": {} } }, "security": [] }, "get": { "summary": "Get TDS return e-filing status", "deprecated": false, "description": "Returns the e-filing status for `job_id`. On success, `data` contains the receipt, FVU, and Form 27A download URLs. On failure, read `data.message`. HTTP 200 does not mean the job succeeded.", "tags": [ "E-File TDS Return" ], "parameters": [ { "name": "job_id", "in": "query", "description": "Job ID returned when the job was created.", "required": true, "example": "{{job_id}}", "schema": { "type": "string" } }, { "name": "authorization", "in": "header", "description": "JWT access token", "required": true, "example": "{{access_token}}", "schema": { "type": "string" } }, { "name": "x-api-key", "in": "header", "description": "API key for identification", "required": true, "example": "{{api_key}}", "schema": { "type": "string" } }, { "name": "x-api-version", "in": "header", "description": "API version", "required": false, "example": "", "schema": { "type": "string" } } ], "responses": { "200": { "description": "200 - OK", "content": { "application/json": { "schema": { "oneOf": [ { "title": "Job Queued", "type": "object", "properties": { "code": { "type": "integer" }, "timestamp": { "type": "integer" }, "transaction_id": { "type": "string" }, "data": { "type": "object", "properties": { "@entity": { "type": "string" }, "job_id": { "type": "string", "description": "Job ID used to check status." }, "tan": { "type": "string" }, "tax_year": { "type": "string", "description": "Tax Year (e.g. TY 2026-27)", "examples": [ "TY 2026-27" ], "pattern": "^TY [0-9]{4}-[0-9]{2}$" }, "quarter": { "type": "string" }, "form": { "type": "string" }, "filing_type": { "type": "string" }, "status": { "type": "string" }, "created_at": { "type": "integer" }, "updated_at": { "type": "integer" } } } } }, { "title": "Job Succeeded", "type": "object", "properties": { "code": { "type": "integer" }, "timestamp": { "type": "integer" }, "transaction_id": { "type": "string" }, "data": { "type": "object", "properties": { "@entity": { "type": "string" }, "job_id": { "type": "string", "description": "Job ID used to check status." }, "tan": { "type": "string" }, "tax_year": { "type": "string", "description": "Tax Year (e.g. TY 2026-27)", "examples": [ "TY 2026-27" ], "pattern": "^TY [0-9]{4}-[0-9]{2}$" }, "quarter": { "type": "string" }, "form": { "type": "string" }, "filing_type": { "type": "string" }, "status": { "type": "string" }, "receipt_number": { "type": "integer" }, "created_at": { "type": "integer" }, "updated_at": { "type": "integer" }, "receipt_file_url": { "type": "string", "format": "uri", "description": "Download URL for the filing receipt after the e-filing job succeeds." }, "fvu_file_url": { "type": "string", "format": "uri", "description": "Download URL for the FVU file associated with the filing." }, "form27a_file_url": { "type": "string", "format": "uri", "description": "Download URL for Form 27A associated with the filing." } } } } }, { "title": "Job Failed", "type": "object", "properties": { "code": { "type": "integer" }, "timestamp": { "type": "integer" }, "transaction_id": { "type": "string" }, "data": { "type": "object", "properties": { "@entity": { "type": "string" }, "job_id": { "type": "string", "description": "Job ID used to check status." }, "tan": { "type": "string" }, "tax_year": { "type": "string", "description": "Tax Year (e.g. TY 2026-27)", "examples": [ "TY 2026-27" ], "pattern": "^TY [0-9]{4}-[0-9]{2}$" }, "quarter": { "type": "string" }, "form": { "type": "string" }, "filing_type": { "type": "string" }, "status": { "type": "string" }, "message": { "type": "string", "description": "Reason for the job failure." }, "created_at": { "type": "integer" }, "updated_at": { "type": "integer" } } } } } ] }, "examples": { "200 Job Succeeded": { "summary": "200 Job Succeeded", "value": { "code": 200, "timestamp": 1763362637000, "transaction_id": "e2b9145f-69d5-4bbe-a6de-be6fc08b426f", "data": { "@entity": "in.co.sandbox.tds.compliance.e-file.job", "job_id": "f845f37e-7f05-4de9-a282-a3b23b9d370a", "tan": "AHMA09719B", "tax_year": "TY 2026-27", "quarter": "Q2", "form": "140", "filing_type": "regular", "status": "succeeded", "receipt_number": 123456789012345, "created_at": 1763362637000, "updated_at": 1763362637000, "receipt_file_url": "https://in-co-sandbox-tds-test-storage.s3.ap-south-1.amazonaws.com/AHMS45586C/FY+2025-26/Q3/140/4049c226-4988-4978-b5ad-d25705453da8/receipt.pdf", "fvu_file_url": "https://in-co-sandbox-tds-test-storage.s3.ap-south-1.amazonaws.com/AHMS45586C/FY+2025-26/Q3/140/4049c226-4988-4978-b5ad-d25705453da8/140.fvu", "form27a_file_url": "https://in-co-sandbox-tds-test-storage.s3.ap-south-1.amazonaws.com/AHMS45586C/FY+2025-26/Q3/140/4049c226-4988-4978-b5ad-d25705453da8/form27A_140.pdf" } } }, "200 Job Queued": { "summary": "200 Job Queued", "value": { "code": 200, "timestamp": 1763362637000, "transaction_id": "e2b9145f-69d5-4bbe-a6de-be6fc08b426f", "data": { "@entity": "in.co.sandbox.tds.compliance.e-file.job", "job_id": "2aa54d2b-68f6-4871-866a-4eba957a8672", "tan": "AHMA09719B", "tax_year": "TY 2026-27", "quarter": "Q2", "form": "140", "filing_type": "original", "status": "queued", "created_at": 1763362637000, "updated_at": 1763362637000 } } }, "200 Job Failed: Statement furnished": { "summary": "200 Job Failed: Statement furnished", "value": { "code": 200, "timestamp": 1763362637000, "transaction_id": "e2b9145f-69d5-4bbe-a6de-be6fc08b426f", "data": { "@entity": "in.co.sandbox.tds.compliance.e-file.job", "job_id": "6e8d1908-c062-4846-a811-8f73054acd65", "tan": "MUMR09719B", "tax_year": "TY 2026-27", "quarter": "Q2", "form": "140", "filing_type": "original", "status": "failed", "message": "Regular Statement with the same TAN, Tax Year, FORM and Quarter is already furnished", "created_at": 1763362637000, "updated_at": 1763362637000 } } }, "200 Job Failed: Unacceptable fvu": { "summary": "200 Job Failed: Unacceptable fvu", "value": { "code": 200, "timestamp": 1763362637000, "transaction_id": "e2b9145f-69d5-4bbe-a6de-be6fc08b426f", "data": { "@entity": "in.co.sandbox.tds.compliance.e-file.job", "job_id": "d75c3d26-4f81-451f-ab38-e217ea801ea1", "tan": "AABC23456D", "tax_year": "TY 2026-27", "quarter": "Q2", "form": "144", "filing_type": "original", "status": "failed", "message": "Unacceptable FVU", "created_at": 1763362637000, "updated_at": 1763362637000 } } }, "200 Job Failed: Invalid archive": { "summary": "200 Job Failed: Invalid archive", "value": { "code": 200, "timestamp": 1763362637000, "transaction_id": "e2b9145f-69d5-4bbe-a6de-be6fc08b426f", "data": { "@entity": "in.co.sandbox.tds.compliance.e-file.job", "job_id": "d1213059-ec22-4e10-b0c1-a91814377001", "tan": "PDES03028E", "tax_year": "TY 2026-27", "quarter": "Q4", "form": "140", "filing_type": "original", "status": "failed", "message": "Invalid Archive", "created_at": 1763362637000, "updated_at": 1763362637000 } } }, "200 Job Failed: Form type mismatch": { "summary": "200 Job Failed: Form type mismatch", "value": { "code": 200, "timestamp": 1763362637000, "transaction_id": "e2b9145f-69d5-4bbe-a6de-be6fc08b426f", "data": { "@entity": "in.co.sandbox.tds.compliance.e-file.job", "job_id": "d6f5b340-440b-400c-9b86-16e691e768b0", "tan": "HYDC23456G", "tax_year": "TY 2026-27", "quarter": "Q4", "form": "138", "filing_type": "original", "status": "failed", "message": "Form Type Mismatch", "created_at": 1763362637000, "updated_at": 1763362637000 } } }, "200 Job Failed: Quarter mismatch": { "summary": "200 Job Failed: Quarter mismatch", "value": { "code": 200, "timestamp": 1763362637000, "transaction_id": "e2b9145f-69d5-4bbe-a6de-be6fc08b426f", "data": { "@entity": "in.co.sandbox.tds.compliance.e-file.job", "job_id": "7a62876a-d638-430c-ad77-8fe33d9e63d5", "tan": "MUMC23456H", "tax_year": "TY 2026-27", "quarter": "Q2", "form": "140", "filing_type": "original", "status": "failed", "message": "Quarter mismatch", "created_at": 1763362637000, "updated_at": 1763362637000 } } }, "200 Job Failed: Barcode mismatch": { "summary": "200 Job Failed: Barcode mismatch", "value": { "code": 200, "timestamp": 1763362637000, "transaction_id": "e2b9145f-69d5-4bbe-a6de-be6fc08b426f", "data": { "@entity": "in.co.sandbox.tds.compliance.e-file.job", "job_id": "6b11d176-b3c5-483c-9052-b533a6e92377", "tan": "DELC23456I", "tax_year": "TY 2026-27", "quarter": "Q3", "form": "144", "filing_type": "original", "status": "failed", "message": "Barcode mismatch", "created_at": 1763362637000, "updated_at": 1763362637000 } } }, "200 Job Failed: Invalid number of entries in archive": { "summary": "200 Job Failed: Invalid number of entries in archive", "value": { "code": 200, "timestamp": 1763362637000, "transaction_id": "e2b9145f-69d5-4bbe-a6de-be6fc08b426f", "data": { "@entity": "in.co.sandbox.tds.compliance.e-file.job", "job_id": "3b979ce9-ef4e-4157-a4a3-51e8747e76d7", "tan": "BLRC23456F", "tax_year": "TY 2026-27", "quarter": "Q2", "form": "140", "filing_type": "original", "status": "failed", "message": "Invalid Number of entries in Archive: 1", "created_at": 1763362637000, "updated_at": 1763362637000 } } }, "200 Job Failed: Tax year mismatch": { "summary": "200 Job Failed: Tax year mismatch", "value": { "code": 200, "timestamp": 1763362637000, "transaction_id": "e2b9145f-69d5-4bbe-a6de-be6fc08b426f", "data": { "@entity": "in.co.sandbox.tds.compliance.e-file.job", "job_id": "7928082e-34ca-474c-ba05-4ede9598b9b5", "tan": "PUNC23456J", "tax_year": "TY 2026-27", "form": "138", "quarter": "Q4", "filing_type": "original", "status": "failed", "message": "Tax year mismatch", "created_at": 1763362637000, "updated_at": 1763362637000 } } }, "200 Job Failed: TAN mismatch": { "summary": "200 Job Failed: TAN mismatch", "value": { "code": 200, "timestamp": 1763362637000, "transaction_id": "e2b9145f-69d5-4bbe-a6de-be6fc08b426f", "data": { "@entity": "in.co.sandbox.tds.compliance.e-file.job", "job_id": "5fd2679f-040f-435c-a285-df5817a150b5", "tan": "KOLT23456K", "tax_year": "TY 2026-27", "quarter": "Q2", "form": "140", "filing_type": "original", "status": "failed", "message": "TAN mismatch", "created_at": 1763362637000, "updated_at": 1763362637000 } } }, "200 Job Failed: Form27A missing": { "summary": "200 Job Failed: Form27A missing", "value": { "code": 200, "timestamp": 1763362637000, "transaction_id": "e2b9145f-69d5-4bbe-a6de-be6fc08b426f", "data": { "@entity": "in.co.sandbox.tds.compliance.e-file.job", "job_id": "b411fbee-68e4-4da3-9f62-8de8ca09a74c", "tan": "CABC23456M", "tax_year": "TY 2026-27", "quarter": "Q3", "form": "140", "filing_type": "original", "status": "failed", "message": "Form 27A missing", "created_at": 1763362637000, "updated_at": 1763362637000 } } }, "200 Job Failed: FVU missing": { "summary": "200 Job Failed: FVU missing", "value": { "code": 200, "timestamp": 1763362637000, "transaction_id": "e2b9145f-69d5-4bbe-a6de-be6fc08b426f", "data": { "@entity": "in.co.sandbox.tds.compliance.e-file.job", "job_id": "9bf0b6f8-5957-484f-9aea-0d235054974c", "tan": "BABC23456L", "tax_year": "TY 2026-27", "quarter": "Q1", "form": "140", "filing_type": "original", "status": "failed", "message": "FVU missing", "created_at": 1763362637000, "updated_at": 1763362637000 } } } } } }, "headers": {} }, "521": { "description": "521 - Data Not Found", "content": { "application/json": { "schema": { "type": "object", "properties": { "code": { "type": "integer" }, "timestamp": { "type": "integer" }, "transaction_id": { "type": "string" }, "message": { "type": "string", "description": "Reason for the job failure." } } }, "examples": { "521 Data not found": { "summary": "521 Data not found", "value": { "code": 521, "timestamp": 1763362637000, "transaction_id": "e2b9145f-69d5-4bbe-a6de-be6fc08b426f", "message": "Data not found" } } } } }, "headers": {} } }, "security": [] } }, "/tds/compliance/e-file/search": { "post": { "summary": "Search TDS return e-filing jobs", "deprecated": false, "description": "Finds TDS and TCS e-filing jobs by TAN, form, tax year, quarter, or creation date. Results appear in `data.items`. Set `page_size` to request up to 50 records. Use `last_evaluated_key` for pagination.", "tags": [ "E-File TDS Return" ], "parameters": [ { "name": "authorization", "in": "header", "description": "JWT access token", "required": true, "example": "", "schema": { "type": "string" } }, { "name": "x-api-key", "in": "header", "description": "API key for identification", "required": true, "example": "", "schema": { "type": "string" } }, { "name": "x-api-version", "in": "header", "description": "", "required": false, "example": "", "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "@entity": { "enum": [ "in.co.sandbox.tds.compliance.e-file.search" ], "type": "string" }, "tan": { "description": "TAN of deductor/collector. Regular Expression: [A-Z]{4}[0-9]{5}[A-Z]{1}", "type": "string" }, "quarter": { "description": "Quarter (e.g. Q2)", "enum": [ "Q1", "Q2", "Q3", "Q4" ], "type": "string" }, "form": { "description": "TDS/TCS return form. Use 138 for erstwhile 24Q, 140 for erstwhile 26Q, 144 for erstwhile 27Q, and 143 for erstwhile 27EQ.", "enum": [ "138", "140", "144", "143" ], "type": "string" }, "tax_year": { "description": "Tax Year (e.g. TY 2026-27)", "type": "string", "pattern": "^TY [0-9]{4}-[0-9]{2}$", "examples": [ "TY 2026-27" ] }, "from_date": { "description": "Start of the job creation-date range, expressed as an epoch timestamp.", "type": "integer" }, "to_date": { "description": "End of the job creation-date range, expressed as an epoch timestamp.", "type": "integer" }, "page_size": { "description": "Number of records in the API response. Maximum allowed size is 50", "type": "integer" }, "last_evaluated_key": { "description": "Base64 encoding of the stringified JSON object, which includes x-api-key, created_at, and job_id", "type": "string" } }, "required": [ "@entity" ] }, "examples": { "Search by TAN and tax period": { "summary": "Search by TAN and tax period", "value": { "@entity": "in.co.sandbox.tds.compliance.e-file.search", "tan": "AHMA09719B", "tax_year": "TY 2026-27", "quarter": "Q1", "form": "140", "page_size": 10 } } } } } }, "responses": { "200": { "description": "200 - OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "code": { "type": "integer" }, "timestamp": { "type": "integer" }, "data": { "type": "object", "properties": { "@entity": { "type": "string" }, "items": { "type": "array", "items": { "type": "object", "properties": { "created_at": { "type": "integer" }, "@entity": { "type": "string" }, "job_id": { "type": "string", "description": "Job ID used to check status." }, "tan": { "type": "string" }, "tax_year": { "type": "string", "description": "Tax Year (e.g. TY 2026-27)", "examples": [ "TY 2026-27" ], "pattern": "^TY [0-9]{4}-[0-9]{2}$" }, "quarter": { "type": "string" }, "form": { "type": "string" }, "filing_type": { "type": "string" }, "status": { "type": "string" } } } } } }, "transaction_id": { "type": "string" } } }, "examples": { "200 Job succeeded": { "summary": "200 Job succeeded", "value": { "code": 200, "timestamp": 1763035357079, "data": { "@entity": "in.co.sandbox.tds.compliance.e-file.paginated_list", "items": [ { "created_at": 1763034775467, "@entity": "in.co.sandbox.tds.compliance.e-file.job", "job_id": "f139447f-07c0-4de1-9f35-0224e253aeec", "tan": "AHMA09719B", "tax_year": "TY 2026-27", "quarter": "Q2", "form": "138", "filing_type": "regular", "status": "created" }, { "created_at": 1763034374362, "@entity": "in.co.sandbox.tds.compliance.e-file.job", "job_id": "6cc8a10e-6c09-4c6f-9bfe-d10b6f6afbb0", "tan": "SRTH05889C", "tax_year": "TY 2026-27", "quarter": "Q2", "form": "140", "filing_type": "regular", "status": "created" }, { "created_at": 1745588854631, "updated_at": 1745588884436, "@entity": "in.co.sandbox.tds.compliance.e-file.job", "job_id": "8566e974-9f6f-49ca-96cb-c75680261405", "tan": "SRTH05889C", "tax_year": "TY 2026-27", "quarter": "Q2", "form": "140", "filing_type": "regular", "status": "succeeded" } ] }, "transaction_id": "a109f017-10ae-44aa-ade7-3902a8cddd6b" } } } } }, "headers": {} } }, "security": [] } }, "/tds/compliance/traces/deductors/forms/{certificate_type}": { "post": { "summary": "Create TDS or TCS certificate job", "deprecated": false, "description": "Create an asynchronous certificate generation job for the selected certificate type, tax year, quarter, and TAN. Use the returned job ID with the status endpoint to track the job.", "operationId": "SubmitCertificateJob", "tags": [ "TDS", "TDS Certificate" ], "parameters": [ { "name": "certificate_type", "in": "path", "description": "Certificate type. Use 130 for salary TDS, 131 for other TDS, or 133 for TCS.", "required": true, "example": "131", "schema": { "type": "string", "enum": [ "130", "131", "133" ] } }, { "name": "Authorization", "in": "header", "description": "JWT access token. For token-generation steps, refer to 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": "API key used to identify and authenticate the client.", "required": true, "example": "{{api_key}}", "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "@entity": { "type": "string", "description": "Request entity type.", "examples": [ "in.co.sandbox.tds.compliance.certificate.job.request" ] }, "quarter": { "type": "string", "description": "Quarter of the tax year.", "enum": [ "Q1", "Q2", "Q3", "Q4" ] }, "tax_year": { "type": "string", "description": "Tax year for the certificate request. Use the TY YYYY-YY format.", "examples": [ "TY 2026-27" ] }, "form": { "type": "string", "description": "Certificate form. Use 130 for salary TDS, 131 for other TDS, or 133 for TCS.", "enum": [ "130", "131", "133" ] }, "tan": { "type": "string", "description": "Tax Deduction and Collection Account Number (TAN).", "examples": [ "AHMS45586C" ] } }, "required": [ "@entity", "quarter", "tax_year", "form", "tan" ] }, "examples": { "Submit form 133 job": { "value": { "@entity": "in.co.sandbox.tds.compliance.certificate.job.request", "quarter": "Q1", "tax_year": "TY 2026-27", "form": "133", "tan": "AHMS45586C" }, "summary": "Submit form 133 job" }, "Submit form 131 job": { "value": { "@entity": "in.co.sandbox.tds.compliance.certificate.job.request", "quarter": "Q1", "tax_year": "TY 2026-27", "form": "131", "tan": "AHMS45586C" }, "summary": "Submit form 131 job" }, "Invalid Request Body": { "value": { "@entity": "in.co.sandbox.tds.compliance.certificate.job.request", "quarter": "Q1", "tax_year": "FY 2026-27", "form": "131", "tan": "AHMS45586C" }, "summary": "Invalid Request Body" } } } }, "required": true }, "responses": { "200": { "description": "Certificate generation job created.", "content": { "application/json": { "schema": { "type": "object", "properties": { "code": { "type": "integer" }, "timestamp": { "type": "integer" }, "data": { "type": "object", "properties": { "created_at": { "type": "integer", "description": "Unix timestamp when the job was created." }, "@entity": { "type": "string", "description": "Response entity type." }, "job_id": { "type": "string", "description": "Unique identifier for the certificate generation job." }, "tan": { "type": "string", "description": "Tax Deduction and Collection Account Number (TAN)." }, "tax_year": { "type": "string", "description": "Tax year for the certificate request." }, "quarter": { "type": "string", "description": "Quarter of the tax year." }, "form": { "type": "string", "description": "Certificate form used for the job.", "enum": [ "130", "131", "133" ] }, "status": { "type": "string", "description": "Current status of the certificate generation job.", "enum": [ "created", "queued", "in_progress", "succeeded", "failed" ] } }, "required": [ "created_at", "@entity", "job_id", "tan", "tax_year", "quarter", "form", "status" ] }, "transaction_id": { "type": "string", "description": "Unique identifier for the API transaction." } }, "required": [ "code", "timestamp", "data", "transaction_id" ] }, "examples": { "Submit form 133 job": { "summary": "Submit form 133 job", "value": { "code": 200, "timestamp": 1788770941235, "data": { "created_at": 1788770941288, "@entity": "in.co.sandbox.tds.compliance.certificate.job", "job_id": "e75e7d3d-0a44-4454-bfa5-3a2ce3caa2a0", "tan": "AHMS45586C", "tax_year": "TY 2026-27", "quarter": "Q1", "form": "133", "status": "created" }, "transaction_id": "e75e7d3d-0a44-4454-bfa5-3a2ce3caa2a0" } }, "Submit form 131 job": { "summary": "Submit form 131 job", "value": { "code": 200, "timestamp": 1788771381210, "data": { "created_at": 1788771384109, "@entity": "in.co.sandbox.tds.compliance.certificate.job", "job_id": "518bf6d5-be9d-4723-8fee-2382919fb605", "tan": "AHMS45586C", "tax_year": "TY 2026-27", "quarter": "Q1", "form": "131", "status": "created" }, "transaction_id": "518bf6d5-be9d-4723-8fee-2382919fb605" } } } } }, "headers": {} }, "400": { "description": "The request body or certificate parameters are invalid.", "content": { "application/json": { "schema": { "type": "object", "properties": { "code": { "type": "integer" }, "timestamp": { "type": "integer" }, "message": { "type": "string" }, "transaction_id": { "type": "string" } }, "required": [ "code", "timestamp", "message", "transaction_id" ] }, "examples": { "Invalid Request Body": { "summary": "Invalid Request Body", "value": { "code": 400, "timestamp": 1788771428630, "message": "Invalid request body", "transaction_id": "934e030b-e094-4533-84ad-8e68d234a6db" } } } } }, "headers": {} } }, "security": [] } }, "/tds/compliance/traces/deductors/forms/{certificate_type}/search": { "post": { "summary": "Search certificate jobs", "deprecated": false, "description": "Search certificate generation jobs by certificate type, TAN, tax year, quarter, form, and status. Use the returned pagination key to request the next page.", "operationId": "SearchCertificateJobs", "tags": [ "TDS", "TDS Certificate" ], "parameters": [ { "name": "certificate_type", "in": "path", "description": "Certificate type. Use 130 for salary TDS, 131 for other TDS, or 133 for TCS.", "required": true, "example": "131", "schema": { "type": "string", "enum": [ "130", "131", "133" ] } }, { "name": "x-api-version", "in": "header", "description": "API version for the request.", "required": false, "example": "{{api_version}}", "schema": { "type": "string" } }, { "name": "x-api-key", "in": "header", "description": "API key used to identify and authenticate the client.", "required": true, "example": "{{api_key}}", "schema": { "type": "string" } }, { "name": "Authorization", "in": "header", "description": "JWT access token. For token-generation steps, refer to the [Quickstart Guide](https://developer.sandbox.co.in/guides/get-started/quickstart).", "required": true, "example": "{{access_token}}", "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CertificateJobSearchRequest" }, "examples": { "Success": { "value": { "@entity": "in.co.sandbox.tds.compliance.certificate.job.search", "tan": "AHMS45586C", "tax_year": "TY 2026-27", "quarter": "Q1", "form": "131", "page_size": 5 }, "summary": "Success" }, "Success with Last evaluated key": { "value": { "@entity": "in.co.sandbox.tds.compliance.certificate.job.search", "tan": "AHMS45586C", "tax_year": "TY 2026-27", "quarter": "Q1", "form": "131", "page_size": 5, "last_evaluated_key": "eyJqb2JfaWQiOiI3NDVjZGU1Ny03YTZhLTQyZGItYjk0MC1lODNlZWE2YjgxN2IiLCJ3b3Jrc3BhY2VfaWQiOiJkYzQ5NTdlZC1kZTBlLTQyYzctODBkZC04MjIxY2VlOGNkYTAiLCJjcmVhdGVkX2F0IjoxNzg4NzYzNzI5OTEwfQ==" }, "summary": "Success with Last evaluated key" }, "Success without jobs": { "value": { "@entity": "in.co.sandbox.tds.compliance.certificate.job.search", "tan": "AHMS45586C", "tax_year": "TY 2026-27", "quarter": "Q1", "form": "130", "page_size": 5 }, "summary": "Success without jobs" }, "Failure Invalid Request Body": { "value": { "@entity": "in.co.sandbox.tds.compliance.certificate.job.search", "tan": "AHMS45586C", "tax_year": "FY 2026-27", "quarter": "Q1", "form": "130", "page_size": 5 }, "summary": "Failure Invalid Request Body" } } } }, "required": true }, "responses": { "200": { "description": "Certificate generation jobs returned.", "content": { "application/json": { "schema": { "type": "object", "properties": { "code": { "type": "integer" }, "timestamp": { "type": "integer" }, "transaction_id": { "type": "string" }, "data": { "type": "object", "properties": { "@entity": { "type": "string", "description": "Response entity type." }, "items": { "type": "array", "description": "Certificate jobs that match the search criteria.", "items": { "type": "object", "properties": { "@entity": { "type": "string", "description": "Certificate job entity type." }, "job_id": { "type": "string", "description": "Unique identifier for the certificate job." }, "tan": { "type": "string", "description": "Tax Deduction and Collection Account Number (TAN) associated with the certificate job." }, "tax_year": { "type": "string", "description": "Tax year for the certificate job." }, "quarter": { "type": "string", "description": "Quarter of the tax year." }, "form": { "type": "string", "description": "Certificate form used for the job.", "enum": [ "130", "131", "133" ] }, "created_at": { "type": "integer", "description": "Unix timestamp when the job was created." }, "updated_at": { "type": "integer", "description": "Unix timestamp when the job was last updated." }, "status": { "type": "string", "description": "Current status of the certificate generation job.", "enum": [ "created", "queued", "in_progress", "succeeded", "failed" ] }, "message": { "type": "string", "description": "Reason the certificate job failed, when applicable." } }, "required": [ "@entity", "job_id", "tan", "tax_year", "quarter", "form", "created_at", "updated_at", "status" ] } }, "last_evaluated_key": { "type": "string", "description": "Opaque pagination cursor. Send this value in the next search request to retrieve the next page." } }, "required": [ "@entity", "items" ] } }, "required": [ "code", "timestamp", "transaction_id", "data" ] }, "examples": { "Success": { "summary": "Success", "value": { "code": 200, "timestamp": 1788772736810, "data": { "@entity": "in.co.sandbox.tds.compliance.certificate.paginated_list", "last_evaluated_key": "eyJqb2JfaWQiOiI3NDVjZGU1Ny03YTZhLTQyZGItYjk0MC1lODNlZWE2YjgxN2IiLCJ3b3Jrc3BhY2VfaWQiOiJkYzQ5NTdlZC1kZTBlLTQyYzctODBkZC04MjIxY2VlOGNkYTAiLCJjcmVhdGVkX2F0IjoxNzg4NzYzNzI5OTEwfQ==", "items": [ { "created_at": 1788771384109, "updated_at": 1788771389188, "@entity": "in.co.sandbox.tds.compliance.certificate.job", "job_id": "518bf6d5-be9d-4723-8fee-2382919fb605", "tan": "AHMS45586C", "tax_year": "TY 2026-27", "quarter": "Q1", "form": "131", "message": "Invalid credentials", "status": "failed" }, { "created_at": 1788765755936, "updated_at": 1788765759820, "@entity": "in.co.sandbox.tds.compliance.certificate.job", "job_id": "70c7df85-8860-4d61-b168-4881cb48792f", "tan": "AHMS45586C", "tax_year": "TY 2026-27", "quarter": "Q1", "form": "131", "message": "Credentials not found", "status": "failed" }, { "created_at": 1788764647784, "updated_at": 1788764647806, "@entity": "in.co.sandbox.tds.compliance.certificate.job", "job_id": "55efc3fb-900c-4066-945e-a1b32d9f4d45", "tan": "AHMS45586C", "tax_year": "TY 2026-27", "quarter": "Q1", "form": "131", "status": "succeeded" }, { "created_at": 1788764478529, "updated_at": 1788764480520, "@entity": "in.co.sandbox.tds.compliance.certificate.job", "job_id": "26a67dd9-70a8-4ec6-be9a-869191cbd9bf", "tan": "AHMS45586C", "tax_year": "TY 2026-27", "quarter": "Q1", "form": "131", "status": "succeeded" }, { "created_at": 1788763729910, "updated_at": 1788763734899, "@entity": "in.co.sandbox.tds.compliance.certificate.job", "job_id": "745cde57-7a6a-42db-b940-e83eea6b817b", "tan": "AHMS45586C", "tax_year": "TY 2026-27", "quarter": "Q1", "form": "131", "status": "succeeded" } ] }, "transaction_id": "95380870-0b99-492f-8fb1-4580af105ad3" } }, "Success with Last evaluated key": { "summary": "Success with Last evaluated key", "value": { "code": 200, "timestamp": 1788772789304, "data": { "@entity": "in.co.sandbox.tds.compliance.certificate.paginated_list", "last_evaluated_key": "eyJ3b3Jrc3BhY2VfaWQiOiJkYzQ5NTdlZC1kZTBlLTQyYzctODBkZC04MjIxY2VlOGNkYTAiLCJjcmVhdGVkX2F0IjoxNzg4NzA0OTg0MjM0LCJqb2JfaWQiOiJhZDcxNGFkMy03Y2QyLTQ2YWEtYTNiMy1jZTY2Njg2MDMxN2YifQ==", "items": [ { "created_at": 1788762771957, "updated_at": 1788762775867, "@entity": "in.co.sandbox.tds.compliance.certificate.job", "job_id": "b88f494e-e60c-407c-aca4-09676d1c1f9b", "tan": "AHMS45586C", "tax_year": "TY 2026-27", "quarter": "Q1", "form": "131", "message": "Failed to submit the certificate job", "status": "failed" }, { "created_at": 1788761715040, "updated_at": 1788761718733, "@entity": "in.co.sandbox.tds.compliance.certificate.job", "job_id": "b2050206-7c13-4669-a82a-ce58b5622585", "tan": "AHMS45586C", "tax_year": "TY 2026-27", "quarter": "Q1", "form": "131", "status": "succeeded" }, { "created_at": 1788713969000, "updated_at": 1788713973336, "@entity": "in.co.sandbox.tds.compliance.certificate.job", "job_id": "94f0447c-62d4-4521-8af7-390de5c837d1", "tan": "AHMS45586C", "tax_year": "TY 2026-27", "quarter": "Q1", "form": "131", "status": "succeeded" }, { "created_at": 1788713289073, "updated_at": 1788713294413, "@entity": "in.co.sandbox.tds.compliance.certificate.job", "job_id": "5d3a9031-46c7-4fa9-b2f5-cac1fccf4d95", "tan": "AHMS45586C", "tax_year": "TY 2026-27", "quarter": "Q1", "form": "131", "message": "Failed to submit the certificate job", "status": "failed" }, { "created_at": 1788704984234, "updated_at": 1788704988663, "@entity": "in.co.sandbox.tds.compliance.certificate.job", "job_id": "ad714ad3-7cd2-46aa-a3b3-ce666860317f", "tan": "AHMS45586C", "tax_year": "TY 2026-27", "quarter": "Q1", "form": "131", "message": "Failed to submit the certificate job", "status": "failed" } ] }, "transaction_id": "d1ff4c62-8aa7-4ae6-8b4d-1c46727e58e2" } }, "Success without jobs": { "summary": "Success without jobs", "value": { "code": 200, "timestamp": 1788773983947, "data": { "@entity": "in.co.sandbox.tds.compliance.certificate.paginated_list", "items": [] }, "transaction_id": "04c20a08-c90c-495c-8404-4eeb827c766b" } } } } }, "headers": {} }, "400": { "description": "Invalid request body.", "content": { "application/json": { "schema": { "type": "object", "properties": { "code": { "type": "integer" }, "timestamp": { "type": "integer" }, "message": { "type": "string" }, "transaction_id": { "type": "string" } }, "required": [ "code", "timestamp", "message", "transaction_id" ] }, "examples": { "Failure Invalid Request Body": { "summary": "Failure Invalid Request Body", "value": { "code": 400, "timestamp": 1788774038411, "message": "Invalid request body", "transaction_id": "3d6295b8-901e-404c-950b-da09692f46e9" } } } } }, "headers": {} } }, "security": [] } }, "/tds/compliance/traces/deductors/forms/{certificate_type}/status": { "get": { "summary": "Get certificate job status", "deprecated": false, "description": "Return the current status of a certificate generation job. When the job succeeds, the response includes URLs for the generated certificate ZIP files.", "operationId": "CertificateJobStatus", "tags": [ "TDS", "TDS Certificate" ], "parameters": [ { "name": "certificate_type", "in": "path", "description": "Certificate type. Use 130 for salary TDS, 131 for other TDS, or 133 for TCS.", "required": true, "example": "131", "schema": { "type": "string", "enum": [ "130", "131", "133" ] } }, { "name": "job_id", "in": "query", "description": "Unique identifier returned when the certificate job was created.", "required": true, "example": "{{job_id}}", "schema": { "type": "string" } }, { "name": "x-api-version", "in": "header", "description": "API version for the request.", "required": true, "example": "{{api_version}}", "schema": { "type": "string" } }, { "name": "Authorization", "in": "header", "description": "JWT access token. For token-generation steps, refer to 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": "API key used to identify and authenticate the client.", "required": true, "example": "{{api_key}}", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Certificate job status returned.", "content": { "application/json": { "schema": { "type": "object", "properties": { "code": { "type": "integer" }, "timestamp": { "type": "integer" }, "data": { "type": "object", "properties": { "created_at": { "type": "integer", "description": "Unix timestamp when the job was created." }, "updated_at": { "type": "integer", "description": "Unix timestamp when the job was last updated." }, "@entity": { "type": "string", "description": "Response entity type." }, "job_id": { "type": "string", "description": "Unique identifier for the certificate generation job." }, "tan": { "type": "string", "description": "Tax Deduction and Collection Account Number (TAN)." }, "tax_year": { "type": "string", "description": "Tax year for the certificate job." }, "quarter": { "type": "string", "description": "Quarter of the tax year." }, "form": { "type": "string", "description": "Certificate form used for the job.", "enum": [ "130", "131", "133" ] }, "certificate_pdf_zip_urls": { "type": "array", "description": "URLs for the generated certificate ZIP files. Present when the job succeeds.", "items": { "type": "string", "format": "uri" } }, "message": { "type": "string", "description": "Reason the certificate job failed, when applicable." }, "status": { "type": "string", "description": "Current status of the certificate generation job.", "enum": [ "created", "queued", "in_progress", "succeeded", "failed" ] } }, "required": [ "created_at", "updated_at", "@entity", "job_id", "tan", "tax_year", "quarter", "form", "status" ] }, "transaction_id": { "type": "string", "description": "Unique identifier for the API transaction." } }, "required": [ "code", "timestamp", "data", "transaction_id" ] }, "examples": { "Failed to submit certificate job": { "summary": "Failed to submit certificate job", "value": { "code": 200, "timestamp": 1788762887353, "data": { "created_at": 1788762771957, "updated_at": 1788762775867, "@entity": "in.co.sandbox.tds.compliance.certificate.job", "job_id": "b88f494e-e60c-407c-aca4-09676d1c1f9b", "tan": "AHMS45586C", "tax_year": "TY 2026-27", "quarter": "Q1", "form": "131", "message": "Failed to submit the certificate job", "status": "failed" }, "transaction_id": "a0a12a28-82bb-4fab-bdb2-2b314c97deba" } }, "Certificate generated": { "summary": "Certificate generated", "value": { "code": 200, "timestamp": 1788764430169, "data": { "created_at": 1788763729910, "updated_at": 1788763734899, "@entity": "in.co.sandbox.tds.compliance.certificate.job", "job_id": "745cde57-7a6a-42db-b940-e83eea6b817b", "tan": "AHMS45586C", "tax_year": "TY 2026-27", "quarter": "Q1", "form": "131", "certificate_pdf_zip_urls": [ "{{certificate_pdf_zip_url}}" ], "status": "succeeded" }, "transaction_id": "cdb8d7a8-95d3-44c9-a28d-a69c5dd74588" } }, "Status Queued": { "summary": "Status Queued", "value": { "code": 200, "timestamp": 1788764483668, "data": { "created_at": 1788764478529, "updated_at": 1788764480520, "@entity": "in.co.sandbox.tds.compliance.certificate.job", "job_id": "26a67dd9-70a8-4ec6-be9a-869191cbd9bf", "tan": "AHMS45586C", "tax_year": "TY 2026-27", "quarter": "Q1", "form": "131", "status": "queued" }, "transaction_id": "4dd921f2-aa17-4f8e-9365-15fb1397f2bc" } }, "Status In progress": { "summary": "Status In progress", "value": { "code": 200, "timestamp": 1788764514931, "data": { "created_at": 1788764478529, "updated_at": 1788764480520, "@entity": "in.co.sandbox.tds.compliance.certificate.job", "job_id": "26a67dd9-70a8-4ec6-be9a-869191cbd9bf", "tan": "AHMS45586C", "tax_year": "TY 2026-27", "quarter": "Q1", "form": "131", "status": "in_progress" }, "transaction_id": "fb474b02-bc0e-419e-a506-57de18ee554e" } }, "Credentials not found": { "summary": "Credentials not found", "value": { "code": 200, "timestamp": 1788765768854, "data": { "created_at": 1788765755936, "updated_at": 1788765759820, "@entity": "in.co.sandbox.tds.compliance.certificate.job", "job_id": "70c7df85-8860-4d61-b168-4881cb48792f", "tan": "AHMS45586C", "tax_year": "TY 2026-27", "quarter": "Q1", "form": "131", "message": "Credentials not found", "status": "failed" }, "transaction_id": "a970bc6d-42b6-4f31-b1d8-257a574c7168" } }, "Certificate not available": { "summary": "Certificate not available", "value": { "code": 200, "timestamp": 1788770774783, "data": { "created_at": 1788770757399, "updated_at": 1788770762605, "@entity": "in.co.sandbox.tds.compliance.certificate.job", "job_id": "d09bba2a-3302-4469-a784-b72924e6bce2", "tan": "AHMS45586C", "tax_year": "TY 2026-27", "quarter": "Q1", "form": "131", "message": "No statement is available for the selected period. Please choose a valid period to generate the certificate.", "status": "failed" }, "transaction_id": "b6109848-9f6d-47d3-b47c-82b039935a86" } }, "Invalid Credentials": { "summary": "Invalid Credentials", "value": { "code": 200, "timestamp": 1788770965182, "data": { "created_at": 1788770941288, "updated_at": 1788770941436, "@entity": "in.co.sandbox.tds.compliance.certificate.job", "job_id": "e75e7d3d-0a44-4454-bfa5-3a2ce3caa2a0", "tan": "AHMS45586C", "tax_year": "TY 2026-27", "quarter": "Q1", "form": "131", "message": "Invalid credentials", "status": "failed" }, "transaction_id": "607e51d9-803e-4422-802d-9933c1388007" } } } } }, "headers": {} }, "521": { "description": "No certificate job data was found for the requested job ID.", "content": { "application/json": { "schema": { "type": "object", "properties": { "code": { "type": "integer" }, "timestamp": { "type": "integer" }, "message": { "type": "string" }, "transaction_id": { "type": "string" } }, "required": [ "code", "timestamp", "message", "transaction_id" ] }, "examples": { "Data Not Found": { "summary": "Data Not Found", "value": { "code": 521, "timestamp": 1788765830963, "message": "Data not found", "transaction_id": "6bc012e4-e16f-4814-a809-710479da3334" } } } } }, "headers": {} } }, "security": [] } }, "/tds/traces/deductors/credential": { "post": { "summary": "Add TRACES credentials", "deprecated": false, "description": "Add the TRACES login credentials for a TAN. APIs that require TRACES access use these credentials when processing requests for the TAN.", "operationId": "AddTracesCredentials", "tags": [ "TRACES Credentials" ], "parameters": [ { "name": "Authorization", "in": "header", "description": "JWT access token. For token-generation steps, refer to 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": "API key used to identify and authenticate the client.", "required": true, "example": "{{api_key}}", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "@entity": { "type": "string", "description": "Entity identifier for the request." }, "tan": { "type": "string", "description": "TAN for the TRACES account." }, "password": { "type": "string", "format": "password", "writeOnly": true, "description": "Password for the TRACES account." } }, "required": [ "@entity", "tan", "password" ] }, "examples": { "Success": { "value": { "@entity": "in.co.sandbox.tds.traces.deductor.credential.request", "tan": "AHMS45586C", "password": "{{password}}" }, "summary": "Success" }, "Failure: Invalid Request Body": { "value": { "@entity": "in.co.sandbox.tds.traces.deductor.credential.request", "tan": "AHMS45586C" }, "summary": "Failure: Invalid Request Body" }, "Failure: Credential already exists": { "value": { "@entity": "in.co.sandbox.tds.traces.deductor.credential.request", "tan": "AHMS45586C", "password": "{{password}}" }, "summary": "Failure: Credential already exists" } } } } }, "responses": { "200": { "description": "The TRACES credentials were added.", "content": { "application/json": { "schema": { "type": "object", "properties": { "code": { "type": "integer" }, "timestamp": { "type": "integer" }, "transaction_id": { "type": "string" } }, "required": [ "code", "timestamp", "transaction_id" ] }, "examples": { "Success": { "summary": "Success", "value": { "code": 200, "timestamp": 1788414642383, "transaction_id": "45a5d0e7-d428-47c3-906e-b039d0e4e157" } } } } }, "headers": {} }, "400": { "description": "The request body is invalid.", "content": { "application/json": { "schema": { "type": "object", "properties": { "code": { "type": "integer" }, "timestamp": { "type": "integer" }, "message": { "type": "string" }, "transaction_id": { "type": "string" } }, "required": [ "code", "timestamp", "message", "transaction_id" ] }, "examples": { "Failure: Invalid Request Body": { "summary": "Failure: Invalid Request Body", "value": { "code": 400, "timestamp": 1788414799493, "message": "Invalid request body", "transaction_id": "1113442c-0914-42d5-91e8-c372f67f902f" } } } } }, "headers": {} }, "409": { "description": "Credentials already exist for the TAN. Delete the existing credentials before you add new credentials.", "content": { "application/json": { "schema": { "type": "object", "properties": { "code": { "type": "integer" }, "timestamp": { "type": "integer" }, "message": { "type": "string" }, "transaction_id": { "type": "string" } }, "required": [ "code", "timestamp", "message", "transaction_id" ] }, "examples": { "Failure: Credential already exists": { "summary": "Failure: Credential already exists", "value": { "code": 409, "timestamp": 1788415156044, "message": "TRACES credential already exists", "transaction_id": "57e1ee72-71ae-4c5d-bc6b-eab44cccab3c" } } } } }, "headers": {} } }, "security": [] }, "delete": { "summary": "Delete TRACES credentials", "deprecated": false, "description": "Delete the TRACES login credentials for a TAN. Add the credentials again before you use an API that requires TRACES access for the TAN.", "operationId": "DeleteTracesCredentials", "tags": [ "TRACES Credentials" ], "parameters": [ { "name": "x-api-key", "in": "header", "description": "API key used to identify and authenticate the client.", "required": true, "example": "{{api_key}}", "schema": { "type": "string" } }, { "name": "Authorization", "in": "header", "description": "JWT access token. For token-generation steps, refer to the [Quickstart Guide](https://developer.sandbox.co.in/guides/get-started/quickstart).", "required": true, "example": "{{access_token}}", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "@entity": { "type": "string", "description": "Entity identifier for the request." }, "tan": { "type": "string", "description": "TAN for the TRACES account." } }, "required": [ "@entity", "tan" ] }, "examples": { "Success": { "value": { "@entity": "in.co.sandbox.tds.traces.deductor.credential.delete.request", "tan": "AHMS45586C" }, "summary": "Success" } } } } }, "responses": { "200": { "description": "The credentials were deleted or did not exist.", "content": { "application/json": { "schema": { "type": "object", "properties": { "code": { "type": "integer" }, "timestamp": { "type": "integer" }, "transaction_id": { "type": "string" } }, "required": [ "code", "timestamp", "transaction_id" ] }, "examples": { "Success": { "summary": "Success", "value": { "code": 200, "timestamp": 1788414871321, "transaction_id": "cc440798-8d60-4346-9622-527861e626ea" } } } } }, "headers": {} } }, "security": [] } } }, "webhooks": { "FVUGenerateJobStatus": { "post": { "summary": "FVU generation status webhook", "deprecated": false, "description": "Sandbox sends this webhook when an FVU generation job transitions to `succeeded` or `failed`, not for `created` or `queued` states. Configure your webhook URL in the Sandbox Console. See the [webhooks guide](https://developer.sandbox.co.in/guides/developer-resources/webhooks) for signature validation.", "operationId": "FVUGenerateJobStatus", "tags": [ "FVU Generation" ], "parameters": [], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "description": "Job details at the time of the status change.", "oneOf": [ { "title": "Job Succeeded", "type": "object", "required": [ "@entity", "job_id", "tan", "tax_year", "quarter", "form", "status", "created_at", "updated_at", "fvu_zip_file_url" ], "properties": { "@entity": { "type": "string", "description": "Entity type identifier" }, "job_id": { "type": "string", "description": "Unique identifier of the job" }, "tan": { "type": "string", "description": "Tax Deduction Account Number" }, "tax_year": { "type": "string", "description": "Tax year of the return (e.g. TY 2026-27)", "examples": [ "TY 2026-27" ], "pattern": "^TY [0-9]{4}-[0-9]{2}$" }, "quarter": { "type": "string", "description": "Quarter for which the return is filed (Q1–Q4)" }, "form": { "type": "string", "description": "TDS form type (138, 140, or 144)" }, "filing_type": { "type": "string", "description": "Filing type (regular or correction)" }, "status": { "type": "string", "description": "Job status", "enum": [ "succeeded" ] }, "created_at": { "type": "integer", "description": "Job creation time as a Unix timestamp in milliseconds" }, "updated_at": { "type": "integer", "description": "Last status update time as a Unix timestamp in milliseconds" }, "fvu_zip_file_url": { "type": "string", "format": "uri", "description": "Pre-signed URL to download the generated FVU ZIP file" } } }, { "title": "Job Failed", "type": "object", "required": [ "@entity", "job_id", "tan", "tax_year", "quarter", "form", "status", "created_at", "updated_at", "validation_report_file_url" ], "properties": { "@entity": { "type": "string", "description": "Entity type identifier" }, "job_id": { "type": "string", "description": "Unique identifier of the job" }, "tan": { "type": "string", "description": "Tax Deduction Account Number" }, "tax_year": { "type": "string", "description": "Tax year of the return (e.g. TY 2026-27)", "examples": [ "TY 2026-27" ], "pattern": "^TY [0-9]{4}-[0-9]{2}$" }, "quarter": { "type": "string", "description": "Quarter for which the return is filed (Q1–Q4)" }, "form": { "type": "string", "description": "TDS form type (138, 140, or 144)" }, "filing_type": { "type": "string", "description": "Filing type (regular or correction)" }, "status": { "type": "string", "description": "Job status", "enum": [ "failed" ] }, "created_at": { "type": "integer", "description": "Job creation time as a Unix timestamp in milliseconds" }, "updated_at": { "type": "integer", "description": "Last status update time as a Unix timestamp in milliseconds" }, "validation_report_file_url": { "type": "string", "format": "uri", "description": "Pre-signed URL to download the validation error report (JSON)" } } } ] } } }, "examples": { "Job Succeeded": { "value": { "data": { "@entity": "in.co.sandbox.tds.compliance.fvu.generate.job", "job_id": "4ef92975-aea8-4628-9eaa-18eb439c13d9", "tan": "AHMA09719B", "tax_year": "TY 2026-27", "quarter": "Q3", "form": "138", "filing_type": "regular", "status": "succeeded", "created_at": 1763362637000, "updated_at": 1763362650000, "fvu_zip_file_url": "https://in-co-sandbox-tds-compliance-fvu-test.s3.ap-south-1.amazonaws.com/tan/tax_year/quarter/form/4ef92975-aea8-4628-9eaa-18eb439c13d9.zip" } }, "summary": "Job Succeeded" }, "Job Failed": { "value": { "data": { "@entity": "in.co.sandbox.tds.compliance.fvu.generate.job", "job_id": "7a9176ef-1e59-4b8e-a1de-ee15b09963f8", "tan": "AHMA09719B", "tax_year": "TY 2026-27", "quarter": "Q3", "form": "138", "filing_type": "regular", "status": "failed", "created_at": 1763362637000, "updated_at": 1763362650000, "validation_report_file_url": "https://in-co-sandbox-tds-compliance-fvu-test.s3.ap-south-1.amazonaws.com/tan/tax_year/quarter/form/9693f3f9-e7dd-4a70-9390-0501ab7f4d27_error.json" } }, "summary": "Job Failed" } } } }, "required": true }, "responses": { "200": { "description": "Return any 2xx status to acknowledge receipt. Sandbox retries delivery on non-2xx responses.", "headers": {} } }, "security": [] } }, "EFileJobStatus": { "post": { "summary": "TDS return e-filing status webhook", "deprecated": false, "description": "Sandbox sends this webhook when an e-file job transitions to `succeeded` or `failed`, not for `created` or `queued` states. Configure your webhook URL in the Sandbox Console. See the [webhooks guide](https://developer.sandbox.co.in/guides/developer-resources/webhooks) for signature validation.", "operationId": "EFileJobStatus", "tags": [ "E-File TDS Return" ], "parameters": [], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "description": "Job details at the time of the status change.", "oneOf": [ { "title": "Job Succeeded", "type": "object", "required": [ "@entity", "job_id", "tan", "tax_year", "quarter", "form", "filing_type", "status", "receipt_number", "created_at", "updated_at", "receipt_file_url", "fvu_file_url", "form27a_file_url" ], "properties": { "@entity": { "type": "string", "description": "Entity type identifier" }, "job_id": { "type": "string", "description": "Unique identifier of the job" }, "tan": { "type": "string", "description": "Tax Deduction Account Number" }, "tax_year": { "type": "string", "description": "Tax year of the return (e.g. TY 2026-27)", "examples": [ "TY 2026-27" ], "pattern": "^TY [0-9]{4}-[0-9]{2}$" }, "quarter": { "type": "string", "description": "Quarter for which the return is filed (Q1–Q4)" }, "form": { "type": "string", "description": "TDS form type (138, 140, 144, or 143)" }, "filing_type": { "type": "string", "description": "Filing type (regular, original, or correction)" }, "status": { "type": "string", "description": "Job status", "enum": [ "succeeded" ] }, "receipt_number": { "type": "integer", "description": "Receipt number from the Income Tax Department confirming successful e-filing" }, "created_at": { "type": "integer", "description": "Job creation time as a Unix timestamp in milliseconds" }, "updated_at": { "type": "integer", "description": "Last status update time as a Unix timestamp in milliseconds" }, "receipt_file_url": { "type": "string", "format": "uri", "description": "Pre-signed URL to download the acknowledgement receipt PDF" }, "fvu_file_url": { "type": "string", "format": "uri", "description": "Pre-signed URL to download the FVU file" }, "form27a_file_url": { "type": "string", "format": "uri", "description": "Pre-signed URL to download the Form 27A PDF" } } }, { "title": "Job Failed", "type": "object", "required": [ "@entity", "job_id", "tan", "tax_year", "quarter", "form", "filing_type", "status", "message", "created_at", "updated_at" ], "properties": { "@entity": { "type": "string", "description": "Entity type identifier" }, "job_id": { "type": "string", "description": "Unique identifier of the job" }, "tan": { "type": "string", "description": "Tax Deduction Account Number" }, "tax_year": { "type": "string", "description": "Tax year of the return (e.g. TY 2026-27)", "examples": [ "TY 2026-27" ], "pattern": "^TY [0-9]{4}-[0-9]{2}$" }, "quarter": { "type": "string", "description": "Quarter for which the return is filed (Q1–Q4)" }, "form": { "type": "string", "description": "TDS form type (138, 140, 144, or 143)" }, "filing_type": { "type": "string", "description": "Filing type (regular, original, or correction)" }, "status": { "type": "string", "description": "Job status", "enum": [ "failed" ] }, "message": { "type": "string", "description": "Error message describing why the e-filing failed" }, "created_at": { "type": "integer", "description": "Job creation time as a Unix timestamp in milliseconds" }, "updated_at": { "type": "integer", "description": "Last status update time as a Unix timestamp in milliseconds" } } } ] } } }, "examples": { "Job Succeeded": { "value": { "data": { "@entity": "in.co.sandbox.tds.compliance.e-file.job", "job_id": "f845f37e-7f05-4de9-a282-a3b23b9d370a", "tan": "AHMA09719B", "tax_year": "TY 2026-27", "quarter": "Q2", "form": "140", "filing_type": "regular", "status": "succeeded", "receipt_number": 123456789012345, "created_at": 1763362637000, "updated_at": 1763362650000, "receipt_file_url": "https://in-co-sandbox-tds-test-storage.s3.ap-south-1.amazonaws.com/AHMS45586C/FY+2025-26/Q3/140/4049c226-4988-4978-b5ad-d25705453da8/receipt.pdf", "fvu_file_url": "https://in-co-sandbox-tds-test-storage.s3.ap-south-1.amazonaws.com/AHMS45586C/FY+2025-26/Q3/140/4049c226-4988-4978-b5ad-d25705453da8/140.fvu", "form27a_file_url": "https://in-co-sandbox-tds-test-storage.s3.ap-south-1.amazonaws.com/AHMS45586C/FY+2025-26/Q3/140/4049c226-4988-4978-b5ad-d25705453da8/form27A_140.pdf" } }, "summary": "Job Succeeded" }, "Job Failed": { "value": { "data": { "@entity": "in.co.sandbox.tds.compliance.e-file.job", "job_id": "6e8d1908-c062-4846-a811-8f73054acd65", "tan": "MUMR09719B", "tax_year": "TY 2026-27", "quarter": "Q2", "form": "140", "filing_type": "original", "status": "failed", "message": "Regular Statement with the same TAN, Tax Year, FORM and Quarter is already furnished", "created_at": 1763362637000, "updated_at": 1763362650000 } }, "summary": "Job Failed" } } } }, "required": true }, "responses": { "200": { "description": "Return any 2xx status to acknowledge receipt. Sandbox retries delivery on non-2xx responses.", "headers": {} } }, "security": [] } }, "CertificateJobStatus": { "post": { "summary": "Certificate job status", "deprecated": false, "description": "Sandbox sends this webhook when a Certificates job transitions to `succeeded` or `failed`, not for `created`, `queued`, or `in_progress` states. Configure your webhook URL in the Sandbox Console. See the [webhooks guide](https://docs.sandbox.co.in/guides/developer-resources/webhooks) for signature validation.", "operationId": "CertificateJobStatus", "tags": [ "TDS Certificate" ], "parameters": [], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "description": "Job details at the time of the status change.", "oneOf": [ { "title": "Job Succeeded", "type": "object", "required": [ "@entity", "job_id", "tan", "quarter", "form", "tax_year", "status", "created_at", "updated_at", "certificate_pdf_zip_urls" ], "properties": { "@entity": { "type": "string", "description": "Entity type identifier" }, "job_id": { "type": "string", "description": "Unique identifier of the job" }, "tan": { "type": "string", "description": "Tax Deduction Account Number" }, "quarter": { "type": "string", "description": "Quarter for which certificates are generated (Q1–Q4)" }, "form": { "type": "string", "description": "TDS form type (24Q or 26Q)" }, "tax_year": { "type": "string", "description": "Financial year of the return (e.g. FY 2023-24)" }, "status": { "type": "string", "description": "Job status", "enum": [ "succeeded" ] }, "created_at": { "type": "integer", "description": "Job creation time as a Unix timestamp in milliseconds" }, "updated_at": { "type": "integer", "description": "Last status update time as a Unix timestamp in milliseconds" }, "certificate_pdf_zip_urls": { "type": "array", "description": "Pre-signed URLs to download the certificate ZIP files", "items": { "type": "string", "format": "uri" } } } }, { "title": "Job Failed", "type": "object", "required": [ "@entity", "job_id", "tan", "quarter", "form", "tax_year", "status", "created_at", "updated_at", "message" ], "properties": { "@entity": { "type": "string", "description": "Entity type identifier" }, "job_id": { "type": "string", "description": "Unique identifier of the job" }, "tan": { "type": "string", "description": "Tax Deduction Account Number" }, "quarter": { "type": "string", "description": "Quarter for which certificates are generated (Q1–Q4)" }, "form": { "type": "string", "description": "TDS form type (24Q or 26Q)" }, "tax_year": { "type": "string", "description": "Financial year of the return (e.g. FY 2023-24)" }, "status": { "type": "string", "description": "Job status", "enum": [ "failed" ] }, "created_at": { "type": "integer", "description": "Job creation time as a Unix timestamp in milliseconds" }, "updated_at": { "type": "integer", "description": "Last status update time as a Unix timestamp in milliseconds" }, "message": { "type": "string", "description": "Error message describing why the certificate job failed" } } } ] } } }, "examples": { "Form 131 Job Succeeded": { "value": { "created_at": 1788782460848, "updated_at": 1788782462209, "@entity": "in.co.sandbox.tds.compliance.certificate.job", "job_id": "2b61a200-d225-48b5-a6a8-d29d9351c014", "tan": "AHMS45586C", "tax_year": "TY 2026-27", "quarter": "Q1", "form": "131", "certificate_pdf_zip_urls": [ "https://in-co-sandbox-tds-compliance-certificate-dev.s3.ap-south-1.amazonaws.com/b0ae5ad8-6d75-413d-9516-5773e62055f3/AHMS45586C/TY%202026-27/Q1/131/2b61a200-d225-48b5-a6a8-d29d9351c014/pdf/1_AHMxxxxx6C_FORM131_2026_Q1_251155230_1.zip?X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Content-Sha256=UNSIGNED-PAYLOAD&X-Amz-Credential=AKIAZG5IA3J4IHC65GYQ%2F20260907%2Fap-south-1%2Fs3%2Faws4_request&X-Amz-Date=20260907T120448Z&X-Amz-Expires=86400&X-Amz-Signature=5ae3fdc51be4da7786f3e118dea41c0ad2679197140931616c60271b5c3cc0d2&X-Amz-SignedHeaders=host&x-amz-checksum-mode=ENABLED&x-id=GetObject" ], "status": "succeeded" }, "summary": "Form 131 Job Succeeded" }, "Job Failed": { "value": { "data": { "created_at": 1788782950446, "updated_at": 1788782951671, "@entity": "in.co.sandbox.tds.compliance.certificate.job", "job_id": "a31097a4-6697-44ee-bbba-75d392f123db", "tan": "AHMS45586C", "tax_year": "TY 2026-27", "quarter": "Q1", "form": "131", "message": "Credentials not found", "status": "failed" } }, "summary": "Job Failed" } } } }, "required": true }, "responses": { "200": { "description": "Return any 2xx status to acknowledge receipt. Sandbox retries delivery on non-2xx responses.", "headers": {} } }, "security": [] } } }, "components": { "schemas": { "CertificateJobSearchRequest": { "type": "object", "description": "Filters used to search certificate generation jobs.", "properties": { "@entity": { "type": "string", "description": "Search request entity type.", "examples": [ "in.co.sandbox.tds.compliance.certificate.job.search" ] }, "tan": { "type": "string", "description": "Tax Deduction and Collection Account Number (TAN).", "examples": [ "AHMS45586C" ] }, "tax_year": { "type": "string", "description": "Tax year used to filter certificate jobs. Use the TY YYYY-YY format.", "examples": [ "TY 2026-27" ] }, "quarter": { "type": "string", "description": "Quarter used to filter certificate jobs.", "enum": [ "Q1", "Q2", "Q3", "Q4" ] }, "form": { "type": "string", "description": "Certificate form used to filter jobs. Use 130 for salary TDS, 131 for other TDS, or 133 for TCS.", "enum": [ "130", "131", "133" ] }, "status": { "type": "string", "description": "Job status used to filter results.", "enum": [ "created", "queued", "in_progress", "succeeded", "failed" ] }, "page_size": { "type": "integer", "description": "Maximum number of jobs to return.", "minimum": 1 }, "last_evaluated_key": { "type": "string", "description": "Pagination key returned by the previous search response." } }, "required": [ "@entity", "tan", "tax_year", "quarter", "form", "page_size" ] } }, "responses": {}, "securitySchemes": {} }, "servers": [ { "url": "https://test-api.sandbox.co.in" }, { "url": "https://api.sandbox.co.in" } ], "security": [] }