{ "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": "TRACES" }, { "name": "TRACES/TDS Certificate" }, { "name": "TRACES/Credentials" }, { "name": "TRACES/Challans" }, { "name": "TDS" }, { "name": "TDS Certificate" }, { "name": "TRACES Credentials" }, { "name": "Challans" } ], "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" ], "x-apidog-orders": [ "@entity", "pan", "consent", "reason" ], "x-apidog-ignore-properties": [] }, "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" } }, "x-apidog-orders": [ "@entity", "pan", "name", "pan_allotment_date", "financial_year", "specified_person_us_206ab_&_206cca", "pan_status" ], "x-apidog-ignore-properties": [] } }, "x-apidog-orders": [ "code", "timestamp", "transaction_id", "data" ], "x-apidog-ignore-properties": [] }, "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": {}, "x-apidog-ordering": 0 }, "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" } }, "x-apidog-orders": [ "code", "timestamp", "transaction_id", "message" ], "x-apidog-ignore-properties": [] }, "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": {}, "x-apidog-ordering": 1 } }, "security": [], "x-apidog-folder": "TDS Compliance Check", "x-apidog-status": "released", "x-run-in-apidog": "https://app.apidog.com/web/project/1186657/apis/api-34524273-run" } }, "/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" ], "x-apidog-orders": [ "@entity", "tan", "mobile_number", "from", "to", "consent", "reason" ], "x-apidog-ignore-properties": [] }, "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." } }, "x-apidog-orders": [ "@entity", "tan", "mobile_number", "from", "to", "reference_id", "message" ], "x-apidog-ignore-properties": [] }, "code": { "type": "integer" } }, "x-apidog-orders": [ "timestamp", "transaction_id", "data", "code" ], "x-apidog-ignore-properties": [] }, "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": {}, "x-apidog-ordering": 0 }, "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" } }, "x-apidog-orders": [ "code", "timestamp", "transaction_id", "message" ], "x-apidog-ignore-properties": [] }, "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": {}, "x-apidog-ordering": 1 } }, "security": [], "x-apidog-folder": "Download CSI", "x-apidog-status": "released", "x-run-in-apidog": "https://app.apidog.com/web/project/1186657/apis/api-34524274-run" } }, "/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" ], "x-apidog-orders": [ "@entity", "reference_id", "otp" ], "x-apidog-ignore-properties": [] }, "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." } }, "x-apidog-orders": [ "@entity", "tan", "from", "to", "reference_id", "csi_url", "message" ], "x-apidog-ignore-properties": [] }, "code": { "type": "integer" } }, "x-apidog-orders": [ "timestamp", "transaction_id", "data", "code" ], "x-apidog-ignore-properties": [] }, "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": {}, "x-apidog-ordering": 0 } }, "security": [], "x-apidog-folder": "Download CSI", "x-apidog-status": "released", "x-run-in-apidog": "https://app.apidog.com/web/project/1186657/apis/api-34524275-run" } }, "/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", "pattern": "^TY [0-9]{4}-[0-9]{2}$", "example": "TY 2026-27" }, "quarter": { "enum": [ "Q1", "Q2", "Q3", "Q4" ], "type": "string", "example": "Q1" }, "form": { "enum": [ "138", "140", "144", "143" ], "type": "string", "description": "TDS/TCS return form. Use 138 for erstwhile 24Q, 140 for erstwhile 26Q, 144 for erstwhile 27Q, and 143 for erstwhile 27EQ.", "example": "140" }, "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", "example": "regular" } }, "required": [ "@entity", "tax_year", "tan", "form", "quarter", "filing_type" ], "x-apidog-orders": [ "@entity", "tax_year", "quarter", "form", "tan", "filing_type" ], "x-apidog-ignore-properties": [] }, "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)", "pattern": "^TY [0-9]{4}-[0-9]{2}$", "example": "TY 2026-27" }, "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." } }, "x-apidog-orders": [ "@entity", "job_id", "tan", "tax_year", "quarter", "form", "filing_type", "status", "created_at", "txt_file_upload_url", "csi_file_upload_url" ], "x-apidog-ignore-properties": [] } }, "x-apidog-orders": [ "code", "timestamp", "transaction_id", "data" ], "x-apidog-ignore-properties": [] }, "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": {}, "x-apidog-ordering": 0 } }, "security": [], "x-apidog-folder": "FVU Generation", "x-apidog-status": "released", "x-run-in-apidog": "https://app.apidog.com/web/project/1186657/apis/api-34524276-run" }, "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)", "pattern": "^TY [0-9]{4}-[0-9]{2}$", "example": "TY 2026-27" }, "quarter": { "type": "string" }, "form": { "type": "string" }, "filing_type": { "type": "string" }, "status": { "type": "string" }, "created_at": { "type": "integer" }, "updated_at": { "type": "integer" } }, "x-apidog-orders": [ "@entity", "job_id", "tan", "tax_year", "quarter", "form", "filing_type", "status", "created_at", "updated_at" ], "x-apidog-ignore-properties": [] } }, "x-apidog-orders": [ "code", "timestamp", "transaction_id", "data" ], "x-apidog-ignore-properties": [] }, { "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)", "pattern": "^TY [0-9]{4}-[0-9]{2}$", "example": "TY 2026-27" }, "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." } }, "x-apidog-orders": [ "@entity", "job_id", "tan", "tax_year", "quarter", "form", "filing_type", "status", "created_at", "updated_at", "fvu_zip_file_url" ], "x-apidog-ignore-properties": [] } }, "x-apidog-orders": [ "code", "timestamp", "transaction_id", "data" ], "x-apidog-ignore-properties": [] }, { "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)", "pattern": "^TY [0-9]{4}-[0-9]{2}$", "example": "TY 2026-27" }, "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." } }, "x-apidog-orders": [ "@entity", "job_id", "tan", "tax_year", "quarter", "form", "filing_type", "status", "created_at", "updated_at", "validation_report_file_url" ], "x-apidog-ignore-properties": [] } }, "x-apidog-orders": [ "code", "timestamp", "transaction_id", "data" ], "x-apidog-ignore-properties": [] } ] }, "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": {}, "x-apidog-ordering": 0 }, "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." } }, "x-apidog-orders": [ "code", "timestamp", "transaction_id", "message" ], "x-apidog-ignore-properties": [] }, "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": {}, "x-apidog-ordering": 1 } }, "security": [], "x-apidog-folder": "FVU Generation", "x-apidog-status": "released", "x-run-in-apidog": "https://app.apidog.com/web/project/1186657/apis/api-34524277-run" } }, "/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}$", "example": "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" ], "x-apidog-orders": [ "@entity", "tax_year", "form", "quarter", "tan", "filing_type", "from_date", "to_date", "page_size", "last_evaluated_key" ], "x-apidog-ignore-properties": [] }, "examples": { "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 }, "summary": "Search by TAN and tax period" } } } } }, "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)", "pattern": "^TY [0-9]{4}-[0-9]{2}$", "example": "TY 2026-27" }, "quarter": { "type": "string" }, "form": { "type": "string" }, "filing_type": { "type": "string" }, "status": { "type": "string" } }, "x-apidog-orders": [ "created_at", "@entity", "job_id", "tan", "tax_year", "quarter", "form", "filing_type", "status" ], "x-apidog-ignore-properties": [] } } }, "x-apidog-orders": [ "@entity", "items" ], "x-apidog-ignore-properties": [] }, "transaction_id": { "type": "string" } }, "x-apidog-orders": [ "code", "timestamp", "data", "transaction_id" ], "x-apidog-ignore-properties": [] }, "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": {}, "x-apidog-ordering": 0 } }, "security": [], "x-apidog-folder": "FVU Generation", "x-apidog-status": "released", "x-run-in-apidog": "https://app.apidog.com/web/project/1186657/apis/api-34524278-run" } }, "/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", "pattern": "^TY [0-9]{4}-[0-9]{2}$", "example": "TY 2026-27" }, "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", "example": "AHMA09719B" } }, "required": [ "@entity", "tax_year", "quarter", "tan", "form" ], "x-apidog-orders": [ "@entity", "tax_year", "form", "quarter", "tan" ], "x-apidog-ignore-properties": [] }, "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)", "pattern": "^TY [0-9]{4}-[0-9]{2}$", "example": "TY 2026-27" }, "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." } }, "x-apidog-orders": [ "@entity", "job_id", "tan", "tax_year", "quarter", "form", "status", "created_at", "fvu_upload_file_url" ], "x-apidog-ignore-properties": [] } }, "x-apidog-orders": [ "code", "timestamp", "transaction_id", "data" ], "x-apidog-ignore-properties": [] }, "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": {}, "x-apidog-ordering": 0 } }, "security": [], "x-apidog-folder": "E-File TDS Return", "x-apidog-status": "released", "x-run-in-apidog": "https://app.apidog.com/web/project/1186657/apis/api-34524279-run" }, "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)", "pattern": "^TY [0-9]{4}-[0-9]{2}$", "example": "TY 2026-27" }, "quarter": { "type": "string" }, "form": { "type": "string" }, "filing_type": { "type": "string" }, "status": { "type": "string" }, "created_at": { "type": "integer" }, "updated_at": { "type": "integer" } }, "x-apidog-orders": [ "@entity", "job_id", "tan", "tax_year", "quarter", "form", "filing_type", "status", "created_at", "updated_at" ], "x-apidog-ignore-properties": [] } }, "x-apidog-orders": [ "code", "timestamp", "transaction_id", "data" ], "x-apidog-ignore-properties": [] }, { "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)", "pattern": "^TY [0-9]{4}-[0-9]{2}$", "example": "TY 2026-27" }, "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." } }, "x-apidog-orders": [ "@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" ], "x-apidog-ignore-properties": [] } }, "x-apidog-orders": [ "code", "timestamp", "transaction_id", "data" ], "x-apidog-ignore-properties": [] }, { "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)", "pattern": "^TY [0-9]{4}-[0-9]{2}$", "example": "TY 2026-27" }, "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" } }, "x-apidog-orders": [ "@entity", "job_id", "tan", "tax_year", "quarter", "form", "filing_type", "status", "message", "created_at", "updated_at" ], "x-apidog-ignore-properties": [] } }, "x-apidog-orders": [ "code", "timestamp", "transaction_id", "data" ], "x-apidog-ignore-properties": [] } ] }, "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": {}, "x-apidog-ordering": 0 }, "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." } }, "x-apidog-orders": [ "code", "timestamp", "transaction_id", "message" ], "x-apidog-ignore-properties": [] }, "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": {}, "x-apidog-ordering": 1 } }, "security": [], "x-apidog-folder": "E-File TDS Return", "x-apidog-status": "released", "x-run-in-apidog": "https://app.apidog.com/web/project/1186657/apis/api-34524280-run" } }, "/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}$", "example": "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" ], "x-apidog-orders": [ "@entity", "tan", "quarter", "form", "tax_year", "from_date", "to_date", "page_size", "last_evaluated_key" ], "x-apidog-ignore-properties": [] }, "examples": { "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 }, "summary": "Search by TAN and tax period" } } } } }, "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)", "pattern": "^TY [0-9]{4}-[0-9]{2}$", "example": "TY 2026-27" }, "quarter": { "type": "string" }, "form": { "type": "string" }, "filing_type": { "type": "string" }, "status": { "type": "string" } }, "x-apidog-orders": [ "created_at", "@entity", "job_id", "tan", "tax_year", "quarter", "form", "filing_type", "status" ], "x-apidog-ignore-properties": [] } } }, "x-apidog-orders": [ "@entity", "items" ], "x-apidog-ignore-properties": [] }, "transaction_id": { "type": "string" } }, "x-apidog-orders": [ "code", "timestamp", "data", "transaction_id" ], "x-apidog-ignore-properties": [] }, "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": {}, "x-apidog-ordering": 0 } }, "security": [], "x-apidog-folder": "E-File TDS Return", "x-apidog-status": "released", "x-run-in-apidog": "https://app.apidog.com/web/project/1186657/apis/api-34524281-run" } }, "/tds/compliance/traces/deductors/forms/{certificate_type}/status": { "get": { "summary": "Get certificate job status", "deprecated": false, "description": "", "tags": [ "TRACES/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" } }, { "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": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "code": { "type": "integer" }, "timestamp": { "type": "integer" }, "data": { "type": "object", "properties": { "created_at": { "type": "integer" }, "updated_at": { "type": "integer" }, "@entity": { "type": "string" }, "job_id": { "type": "string" }, "tan": { "type": "string" }, "tax_year": { "type": "string" }, "quarter": { "type": "string" }, "form": { "type": "string" }, "message": { "type": "string" }, "status": { "type": "string" } }, "required": [ "created_at", "updated_at", "@entity", "job_id", "tan", "tax_year", "quarter", "form", "message", "status" ], "x-apidog-orders": [ "created_at", "updated_at", "@entity", "job_id", "tan", "tax_year", "quarter", "form", "message", "status" ], "x-apidog-ignore-properties": [] }, "transaction_id": { "type": "string" } }, "required": [ "code", "timestamp", "data", "transaction_id" ], "x-apidog-orders": [ "code", "timestamp", "data", "transaction_id" ], "x-apidog-ignore-properties": [] }, "example": { "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" } } }, "x-apidog-ordering": 0 }, "521": { "description": "", "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" ], "x-apidog-orders": [ "code", "timestamp", "message", "transaction_id" ], "x-apidog-ignore-properties": [] }, "example": { "code": 521, "timestamp": 1788765830963, "message": "Data not found", "transaction_id": "6bc012e4-e16f-4814-a809-710479da3334" } } }, "x-apidog-ordering": 1 }, "x-apidog-additional-responses": [ { "statusCode": 200, "description": "", "content": { "application/octet-stream": { "schema": { "type": "object", "properties": {}, "x-apidog-orders": [], "x-apidog-ignore-properties": [] } } }, "x-apidog-ordering": 2 } ] }, "security": [], "x-apidog-folder": "TRACES/TDS Certificate", "x-apidog-status": "released", "x-run-in-apidog": "https://app.apidog.com/web/project/1186657/apis/api-43150998-run" } }, "/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": [ "TRACES/TDS Certificate", "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" } }, { "name": "Content-Type", "in": "header", "description": "Request body format.", "required": true, "example": "application/json", "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "@entity": { "type": "string", "description": "Request entity type.", "example": "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.", "example": "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).", "example": "AHMS45586C" } }, "required": [ "@entity", "quarter", "tax_year", "form", "tan" ], "x-apidog-orders": [ "@entity", "quarter", "tax_year", "form", "tan" ], "x-apidog-ignore-properties": [] }, "examples": { "Submit form 133 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 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" ], "x-apidog-orders": [ "created_at", "@entity", "job_id", "tan", "tax_year", "quarter", "form", "status" ], "x-apidog-ignore-properties": [] }, "transaction_id": { "type": "string", "description": "Unique identifier for the API transaction." } }, "required": [ "code", "timestamp", "data", "transaction_id" ], "x-apidog-orders": [ "code", "timestamp", "data", "transaction_id" ], "x-apidog-ignore-properties": [] }, "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": {}, "x-apidog-ordering": 0 }, "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" ], "x-apidog-orders": [ "code", "timestamp", "message", "transaction_id" ], "x-apidog-ignore-properties": [] }, "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": {}, "x-apidog-ordering": 1 } }, "security": [], "x-apidog-folder": "TRACES/TDS Certificate", "x-apidog-status": "released", "x-run-in-apidog": "https://app.apidog.com/web/project/1186657/apis/api-43150997-run" } }, "/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": [ "TRACES/TDS Certificate", "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" } }, { "name": "Content-Type", "in": "header", "description": "Request body format.", "required": true, "example": "application/json", "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" ], "x-apidog-orders": [ "@entity", "job_id", "tan", "tax_year", "quarter", "form", "created_at", "updated_at", "status", "message" ], "x-apidog-ignore-properties": [] } }, "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" ], "x-apidog-orders": [ "@entity", "items", "last_evaluated_key" ], "x-apidog-ignore-properties": [] } }, "required": [ "code", "timestamp", "transaction_id", "data" ], "x-apidog-orders": [ "code", "timestamp", "transaction_id", "data" ], "x-apidog-ignore-properties": [] }, "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": {}, "x-apidog-ordering": 0 }, "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" ], "x-apidog-orders": [ "code", "timestamp", "message", "transaction_id" ], "x-apidog-ignore-properties": [] }, "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": {}, "x-apidog-ordering": 1 } }, "security": [], "x-apidog-folder": "TRACES/TDS Certificate", "x-apidog-status": "released", "x-run-in-apidog": "https://app.apidog.com/web/project/1186657/apis/api-43150999-run" } }, "/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", "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" } }, { "name": "Content-Type", "in": "header", "description": "Request body format.", "required": true, "example": "application/json", "schema": { "type": "string" } } ], "requestBody": { "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" ], "x-apidog-orders": [ "@entity", "tan", "password" ], "x-apidog-ignore-properties": [] }, "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" } } } }, "required": true }, "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" ], "x-apidog-orders": [ "code", "timestamp", "transaction_id" ], "x-apidog-ignore-properties": [] }, "examples": { "Success": { "summary": "Success", "value": { "code": 200, "timestamp": 1788414642383, "transaction_id": "45a5d0e7-d428-47c3-906e-b039d0e4e157" } } } } }, "headers": {}, "x-apidog-ordering": 0 }, "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" ], "x-apidog-orders": [ "code", "timestamp", "message", "transaction_id" ], "x-apidog-ignore-properties": [] }, "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": {}, "x-apidog-ordering": 1 }, "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" ], "x-apidog-orders": [ "code", "timestamp", "message", "transaction_id" ], "x-apidog-ignore-properties": [] }, "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": {}, "x-apidog-ordering": 2 } }, "security": [], "x-apidog-folder": "TRACES/Credentials", "x-apidog-status": "released", "x-run-in-apidog": "https://app.apidog.com/web/project/1186657/apis/api-43151000-run" }, "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", "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": { "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" ], "x-apidog-orders": [ "@entity", "tan" ], "x-apidog-ignore-properties": [] }, "examples": { "Success": { "value": { "@entity": "in.co.sandbox.tds.traces.deductor.credential.delete.request", "tan": "AHMS45586C" }, "summary": "Success" } } } }, "required": true }, "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" ], "x-apidog-orders": [ "code", "timestamp", "transaction_id" ], "x-apidog-ignore-properties": [] }, "examples": { "Success": { "summary": "Success", "value": { "code": 200, "timestamp": 1788414871321, "transaction_id": "cc440798-8d60-4346-9622-527861e626ea" } } } } }, "headers": {}, "x-apidog-ordering": 0 } }, "security": [], "x-apidog-folder": "TRACES/Credentials", "x-apidog-status": "released", "x-run-in-apidog": "https://app.apidog.com/web/project/1186657/apis/api-43151001-run" } }, "/tds/compliance/traces/deductors/challans": { "post": { "summary": "Get challan", "deprecated": false, "description": "Retrieves a TDS challan and its tax and available consumption details from TRACES.\n\nIdentify the challan using the deductor's TAN, BSR code, deposit date, and challan serial number. The deposit date uses epoch milliseconds and the Asia/Kolkata calendar date.\n\nRequires registered TRACES deductor credentials for the requested TAN and Sandbox authentication.\n\nReturns HTTP 521 when no challan matches the supplied particulars. A null consumption_details value means utilization details are unavailable; it does not indicate an unused challan.", "operationId": "getChallan", "tags": [ "TRACES/Challans", "TRACES", "Challans" ], "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" } }, { "name": "Content-Type", "in": "header", "description": "Request body format.", "required": true, "example": "application/json", "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ChallanLookupRequest" }, "examples": { "Challan found": { "value": { "@entity": "in.co.sandbox.tds.compliance.challan.request", "tan": "AHMA12345A", "bsr_code": "0123456", "challan_serial": "00042", "paid_date_epoch": 1784053800000 }, "summary": "Challan found" }, "TRACES credentials not stored": { "value": { "@entity": "in.co.sandbox.tds.compliance.challan.request", "tan": "AHMA12345A", "bsr_code": "0123456", "challan_serial": "00042", "paid_date_epoch": 1784053800000 }, "summary": "TRACES credentials not stored" }, "Incorrect TRACES credentials": { "value": { "@entity": "in.co.sandbox.tds.compliance.challan.request", "tan": "AHMA12345A", "bsr_code": "0123456", "challan_serial": "00042", "paid_date_epoch": 1784053800000 }, "summary": "Incorrect TRACES credentials" }, "TRACES login unavailable": { "value": { "@entity": "in.co.sandbox.tds.compliance.challan.request", "tan": "AHMA12345A", "bsr_code": "0123456", "challan_serial": "00042", "paid_date_epoch": 1784053800000 }, "summary": "TRACES login unavailable" } } } }, "required": true }, "responses": { "200": { "description": "The matching challan with its tax and available consumption details.", "content": { "application/json": { "schema": { "type": "object", "properties": { "code": { "type": "integer", "const": 200, "description": "HTTP status code." }, "timestamp": { "type": "integer", "description": "Response timestamp in epoch milliseconds." }, "transaction_id": { "type": "string", "description": "Unique identifier for this API request." }, "data": { "$ref": "#/components/schemas/Challan" } }, "required": [ "code", "timestamp", "transaction_id", "data" ], "additionalProperties": false, "x-apidog-ignore-properties": [], "x-apidog-orders": [ "code", "timestamp", "transaction_id", "data" ] }, "examples": { "Challan found": { "summary": "Challan found", "description": "Fictional example data.", "value": { "code": 200, "timestamp": 1791829800000, "transaction_id": "87c1b4f6-1632-4d8b-a2f9-05f291c00a42", "data": { "@entity": "in.co.sandbox.tds.compliance.challan.response", "tan": "AHMA12345A", "bsr_code": "0123456", "challan_serial": "00042", "paid_date_epoch": 1784053800000, "challan_identification_number": "01234561507202600042", "receipt_number": "9000000001", "financial_year": "FY 2026-27", "major_head": "0021", "minor_head": "200", "total_amount": 1500, "status": "CLAIMED", "section_code": "94D", "residency_status": "R", "tax_breakdown": [ { "@entity": "in.co.sandbox.tds.compliance.challan.tax_breakdown", "section": "393(1) [Table: Sl. No. 1(i)]", "tax_amount": 1500, "surcharge": 0, "cess": 0, "total_amount": 1500 } ], "consumption_details": null } } } } } }, "headers": {}, "x-apidog-name": "Success", "x-apidog-ordering": 0 }, "400": { "description": "The request body is malformed or does not match the request schema.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "headers": {}, "x-apidog-name": "Invalid request body", "x-apidog-ordering": 1 }, "401": { "description": "Sandbox authorization is missing or invalid, or the stored TRACES credentials are incorrect.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "Incorrect TRACES credentials": { "summary": "Incorrect TRACES credentials", "description": "Fictional example data.", "value": { "code": 401, "timestamp": 1791829800000, "transaction_id": "87c1b4f6-1632-4d8b-a2f9-05f291c00a42", "message": "Invalid credentials" } } } } }, "headers": {}, "x-apidog-name": "Unauthorized", "x-apidog-ordering": 2 }, "403": { "description": "Access is denied for this request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "headers": {}, "x-apidog-name": "Forbidden", "x-apidog-ordering": 3 }, "429": { "description": "The request rate limit has been exceeded.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "headers": {}, "x-apidog-name": "Too Many Requests", "x-apidog-ordering": 4 }, "500": { "description": "The challan request could not be completed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "TRACES login unavailable": { "summary": "TRACES login unavailable", "description": "Fictional example data.", "value": { "code": 500, "timestamp": 1791829800000, "transaction_id": "87c1b4f6-1632-4d8b-a2f9-05f291c00a42", "message": "Failed to log in to TRACES" } } } } }, "headers": {}, "x-apidog-name": "Failed to fetch TRACES challans", "x-apidog-ordering": 5 }, "503": { "description": "TRACES is temporarily unavailable.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "headers": {}, "x-apidog-name": "Source Unavailable", "x-apidog-ordering": 6 }, "521": { "description": "TRACES credentials are not stored for this TAN, or no challan matches the supplied payment details.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "TRACES credentials not stored": { "summary": "TRACES credentials not stored", "description": "Fictional example data.", "value": { "code": 521, "timestamp": 1791829800000, "transaction_id": "87c1b4f6-1632-4d8b-a2f9-05f291c00a42", "message": "Credentials not found" } } } } }, "headers": {}, "x-apidog-name": "Challan not found", "x-apidog-ordering": 7 } }, "security": [], "x-apidog-folder": "TRACES/Challans", "x-apidog-status": "released", "x-run-in-apidog": "https://app.apidog.com/web/project/1186657/apis/api-45162941-run", "servers": [ { "url": "https://api.sandbox.co.in" } ] } }, "/tds/compliance/traces/deductors/challans/search": { "post": { "summary": "Search challans", "deprecated": false, "description": "Searches a deductor's TDS challans by deposit-date range and returns one page of results from TRACES.\n\nProvide the deductor's TAN, from_date_epoch, and to_date_epoch. Both dates are required and use epoch milliseconds. The calendar dates are interpreted in Asia/Kolkata.\n\npage_number starts at 0. page_size specifies the number of challans requested per page. Both fields are optional.\n\nThe response includes the challans in data and the pagination totals totalPages and totalElements. A page with no challans returns HTTP 200 with an empty data list.\n\nRequires registered TRACES deductor credentials for the requested TAN and Sandbox authentication.", "operationId": "searchChallans", "tags": [ "TRACES/Challans", "TRACES", "Challans" ], "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" } }, { "name": "Content-Type", "in": "header", "description": "Request body format.", "required": true, "example": "application/json", "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ChallanSearchRequest" }, "examples": { "Challans found within the date range": { "value": { "@entity": "in.co.sandbox.tds.compliance.challan.search", "tan": "AHMA12345A", "from_date_epoch": 1782844200000, "to_date_epoch": 1785436200000, "page_number": 0, "page_size": 10 }, "summary": "Challans found within the date range" }, "No challans found within date range": { "value": { "@entity": "in.co.sandbox.tds.compliance.challan.search", "tan": "AHMA12345A", "from_date_epoch": 1785522600000, "to_date_epoch": 1788114600000, "page_number": 0, "page_size": 10 }, "summary": "No challans found within date range" }, "Challans found on the next page": { "value": { "@entity": "in.co.sandbox.tds.compliance.challan.search", "tan": "AHMA12345A", "from_date_epoch": 1788201000000, "to_date_epoch": 1790706600000, "page_number": 1, "page_size": 1 }, "summary": "Challans found on the next page" } } } }, "required": true }, "responses": { "200": { "description": "One page of challans with pagination totals. The data list is empty when the page contains no challans.", "content": { "application/json": { "schema": { "type": "object", "properties": { "code": { "type": "integer", "const": 200, "description": "HTTP status code." }, "timestamp": { "type": "integer", "description": "Response timestamp in epoch milliseconds." }, "transaction_id": { "type": "string", "description": "Unique identifier for this API request." }, "data": { "$ref": "#/components/schemas/ChallanSearchResponse" } }, "required": [ "code", "timestamp", "transaction_id", "data" ], "additionalProperties": false, "x-apidog-ignore-properties": [], "x-apidog-orders": [ "code", "timestamp", "transaction_id", "data" ] }, "examples": { "Challans found within the date range": { "summary": "Challans found within the date range", "description": "Fictional example data.", "value": { "code": 200, "timestamp": 1791829800000, "transaction_id": "87c1b4f6-1632-4d8b-a2f9-05f291c00a42", "data": { "@entity": "in.co.sandbox.tds.compliance.challan.search.response", "data": [ { "@entity": "in.co.sandbox.tds.compliance.challan.response", "tan": "AHMA12345A", "bsr_code": "0123456", "challan_serial": "00042", "paid_date_epoch": 1784053800000, "challan_identification_number": "01234561507202600042", "receipt_number": "9000000001", "financial_year": "FY 2026-27", "major_head": "0021", "minor_head": "200", "total_amount": 1500, "status": "CLAIMED", "section_code": "94D", "residency_status": "R", "tax_breakdown": [ { "@entity": "in.co.sandbox.tds.compliance.challan.tax_breakdown", "section": "393(1) [Table: Sl. No. 1(i)]", "tax_amount": 1500, "surcharge": 0, "cess": 0, "total_amount": 1500 } ], "consumption_details": null } ], "totalPages": 1, "totalElements": 1 } } }, "No challans found within date range": { "summary": "No challans found within date range", "description": "Fictional example data.", "value": { "code": 200, "timestamp": 1791829800000, "transaction_id": "87c1b4f6-1632-4d8b-a2f9-05f291c00a42", "data": { "@entity": "in.co.sandbox.tds.compliance.challan.search.response", "data": [], "totalPages": 0, "totalElements": 0 } } }, "Challans found on the next page": { "summary": "Challans found on the next page", "description": "Fictional example data.", "value": { "code": 200, "timestamp": 1791829800000, "transaction_id": "87c1b4f6-1632-4d8b-a2f9-05f291c00a42", "data": { "@entity": "in.co.sandbox.tds.compliance.challan.search.response", "data": [ { "@entity": "in.co.sandbox.tds.compliance.challan.response", "tan": "AHMA12345A", "bsr_code": "0123456", "challan_serial": "00043", "paid_date_epoch": 1789497000000, "challan_identification_number": "01234561609202600043", "receipt_number": "9000000002", "financial_year": "FY 2026-27", "major_head": "0021", "minor_head": "200", "total_amount": 2000, "status": "CLAIMED", "section_code": "94D", "residency_status": "R", "tax_breakdown": [ { "@entity": "in.co.sandbox.tds.compliance.challan.tax_breakdown", "section": "393(1) [Table: Sl. No. 1(i)]", "tax_amount": 2000, "surcharge": 0, "cess": 0, "total_amount": 2000 } ], "consumption_details": null } ], "totalPages": 2, "totalElements": 2 } } } } } }, "headers": {}, "x-apidog-name": "Success", "x-apidog-ordering": 0 }, "400": { "description": "The request body is malformed or does not match the request schema.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "headers": {}, "x-apidog-name": "Invalid request body", "x-apidog-ordering": 1 }, "401": { "description": "Sandbox authorization is missing or invalid, or the stored TRACES credentials are incorrect.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "headers": {}, "x-apidog-name": "Unauthorized", "x-apidog-ordering": 2 }, "403": { "description": "Access is denied for this request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "headers": {}, "x-apidog-name": "Forbidden", "x-apidog-ordering": 3 }, "429": { "description": "The request rate limit has been exceeded.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "headers": {}, "x-apidog-name": "Too Many Requests", "x-apidog-ordering": 4 }, "500": { "description": "The challan request could not be completed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "headers": {}, "x-apidog-name": "Failed to fetch TRACES challans", "x-apidog-ordering": 5 }, "503": { "description": "TRACES is temporarily unavailable.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "headers": {}, "x-apidog-name": "Source Unavailable", "x-apidog-ordering": 6 }, "521": { "description": "No TRACES credentials are stored for the deductor TAN in the workspace.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "headers": {}, "x-apidog-name": "Credentials not found", "x-apidog-ordering": 7 } }, "security": [], "x-apidog-folder": "TRACES/Challans", "x-apidog-status": "released", "x-run-in-apidog": "https://app.apidog.com/web/project/1186657/apis/api-45162942-run", "servers": [ { "url": "https://api.sandbox.co.in" } ] } }, "/tds/compliance/enriched/traces/deductors/pan/verify": { "post": { "summary": "Create bulk PAN verification job", "deprecated": false, "description": "Creates an enriched bulk PAN verification job for the supplied TAN. Sandbox manages TRACES authentication using your stored credentials. The response contains a job ID and a signed URL for the input JSON workbook. Upload the workbook with HTTP PUT and Content-Type application/json.\n\nSave the [TRACES credentials](https://developer.sandbox.co.in/api-reference/tds/compliance/traces-credentials/endpoints/save_credential) for the TAN before processing. Credential checks happen after the workbook upload. Missing or incorrect credentials appear as a failed job when you retrieve its status.\n\nThe uploaded JSON file must be at most 5,000,000 bytes. The workbook contains payee_sheet and payee_table with the header [\"sr_no\", \"pan\"]. PAN values are submitted to TRACES as provided. For repeated PANs, verification keeps the first row and ignores later rows.\n\nRetrieve the job with the returned job_id to check progress and obtain the output download URL.\n\nInput workbook example:\n\n```json\n{\n \"@entity\": \"workbook\",\n \"name\": \"payee_workbook\",\n \"sheets\": [\n {\n \"@entity\": \"sheet\",\n \"name\": \"payee_sheet\",\n \"blocks\": [\n {\n \"@entity\": \"table\",\n \"name\": \"payee_table\",\n \"header\": [\n \"sr_no\",\n \"pan\"\n ],\n \"rows\": [\n [\n 1,\n \"ABCPD1234E\"\n ],\n [\n 2,\n \"XYZPK5678L\"\n ],\n [\n 3,\n \"ABCPD1234E\"\n ],\n [\n 4,\n \"AAAAA1111A\"\n ]\n ]\n }\n ]\n }\n ]\n}\n```", "operationId": "SubmitPanVerificationJob", "tags": [ "TDS", "TRACES", "PAN Verification" ], "parameters": [ { "name": "Authorization", "in": "header", "description": "Sandbox JWT access token. See 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": "Sandbox API key for the request.", "required": true, "example": "{{api_key}}", "schema": { "type": "string" } }, { "name": "Content-Type", "in": "header", "description": "Request body format.", "required": true, "example": "application/json", "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PanVerificationRequest" }, "examples": { "Job created": { "value": { "@entity": "in.co.sandbox.tds.compliance.pan.verification.request", "tan": "AHMA12345A" }, "summary": "Job created", "description": "Create a job and receive a signed URL to upload the payee workbook." }, "Missing TAN": { "value": { "@entity": "in.co.sandbox.tds.compliance.pan.verification.request" }, "summary": "Missing TAN", "description": "The request does not include tan." }, "Invalid TAN format": { "value": { "@entity": "in.co.sandbox.tds.compliance.pan.verification.request", "tan": "12345" }, "summary": "Invalid TAN format", "description": "The TAN does not match the required format." }, "Missing authorization": { "value": { "@entity": "in.co.sandbox.tds.compliance.pan.verification.request", "tan": "AHMA12345A" }, "summary": "Missing authorization", "description": "The request does not include the Authorization header." }, "Missing API key": { "value": { "@entity": "in.co.sandbox.tds.compliance.pan.verification.request", "tan": "AHMA12345A" }, "summary": "Missing API key", "description": "The request does not include the x-api-key header." } } } }, "required": true }, "responses": { "200": { "description": "The job is created and ready for the input workbook upload.", "content": { "application/json": { "schema": { "type": "object", "properties": { "code": { "type": "integer", "enum": [ 200 ], "description": "HTTP status code." }, "timestamp": { "type": "integer", "format": "int64", "description": "Response timestamp in epoch milliseconds." }, "transaction_id": { "type": "string", "format": "uuid", "description": "Unique identifier for this API transaction." }, "data": { "allOf": [ { "$ref": "#/components/schemas/PanVerificationJob" }, { "type": "object", "properties": { "status": { "type": "string", "enum": [ "created" ] } } } ] } }, "required": [ "code", "timestamp", "transaction_id", "data" ] }, "examples": { "Job created": { "summary": "Job created", "value": { "code": 200, "timestamp": 1792136869079, "data": { "created_at": 1792136873733, "@entity": "in.co.sandbox.tds.compliance.pan.verification.job", "job_id": "b5084575-7bdf-4a40-a8db-e19c93d34ec4", "tan": "AHMA12345A", "status": "created", "json_url": "https://sandbox-example.s3.ap-south-1.amazonaws.com/example-workspace/b5084575-7bdf-4a40-a8db-e19c93d34ec4/payee.json?X-Amz-Signature=example" }, "transaction_id": "6ead62b9-35c9-4c1c-8625-4e0bfdc025d5" } } } } }, "headers": {} }, "400": { "description": "The request body or query parameters are invalid.", "content": { "application/json": { "schema": { "type": "object", "properties": { "code": { "type": "integer", "enum": [ 400 ], "description": "HTTP status code." }, "timestamp": { "type": "integer", "format": "int64", "description": "Response timestamp in epoch milliseconds." }, "transaction_id": { "type": "string", "format": "uuid", "description": "Unique identifier for this API transaction." }, "message": { "type": "string", "description": "Reason the request could not be completed." } }, "required": [ "code", "timestamp", "transaction_id", "message" ] }, "examples": { "Missing TAN": { "summary": "Missing TAN", "value": { "code": 400, "timestamp": 1792136874200, "message": "Invalid request body", "transaction_id": "6b31ee70-abdf-4428-8678-67c75d42712a" } }, "Invalid TAN format": { "summary": "Invalid TAN format", "value": { "code": 400, "timestamp": 1792136874678, "message": "Invalid request body", "transaction_id": "330b6df2-a419-4942-be5d-8ffd1073ada8" } } } } }, "headers": {} }, "401": { "description": "Sandbox authorization is missing, invalid, or expired.", "content": { "application/json": { "schema": { "type": "object", "properties": { "code": { "type": "integer", "enum": [ 401 ], "description": "HTTP status code." }, "timestamp": { "type": "integer", "format": "int64", "description": "Response timestamp in epoch milliseconds." }, "transaction_id": { "type": "string", "format": "uuid", "description": "Unique identifier for this API transaction." }, "message": { "type": "string", "description": "Reason the request could not be completed." } }, "required": [ "code", "timestamp", "transaction_id", "message" ] }, "examples": { "Missing authorization": { "summary": "Missing authorization", "value": { "code": 401, "message": "Unauthorized", "timestamp": 1792136874846, "transaction_id": "b0b82447-fe6a-4852-a320-405f6744ce08" } } } } }, "headers": {} }, "403": { "description": "Access to this API is denied.", "content": { "application/json": { "schema": { "type": "object", "properties": { "code": { "type": "integer", "enum": [ 403 ], "description": "HTTP status code." }, "timestamp": { "type": "integer", "format": "int64", "description": "Response timestamp in epoch milliseconds." }, "transaction_id": { "type": "string", "format": "uuid", "description": "Unique identifier for this API transaction." }, "message": { "type": "string", "description": "Reason the request could not be completed." } }, "required": [ "code", "timestamp", "transaction_id", "message" ] }, "examples": { "Missing API key": { "summary": "Missing API key", "value": { "code": 403, "message": "Forbidden", "timestamp": 1792136874924, "transaction_id": "90caaf62-2271-4172-b711-c5f5a5cc07d2" } } } } }, "headers": {} }, "500": { "description": "The API request could not be completed.", "content": { "application/json": { "schema": { "type": "object", "properties": { "code": { "type": "integer", "enum": [ 500 ], "description": "HTTP status code." }, "timestamp": { "type": "integer", "format": "int64", "description": "Response timestamp in epoch milliseconds." }, "transaction_id": { "type": "string", "format": "uuid", "description": "Unique identifier for this API transaction." }, "message": { "type": "string", "description": "Reason the request could not be completed." } }, "required": [ "code", "timestamp", "transaction_id", "message" ] } } }, "headers": {} } }, "security": [] } }, "/tds/compliance/enriched/traces/deductors/pan/verify/status": { "get": { "summary": "Get bulk PAN verification job status", "deprecated": false, "description": "Returns the current status of a bulk PAN verification job in your workspace. This GET request has no body.\n\nA created job waits for the workbook upload. queued waits to start processing. in_progress covers input-size checks, TRACES authentication and verification, and output workbook generation. A job succeeds after the output JSON workbook is saved and provides output_json_url for its download. A failed job provides message. Retrieving a failed job returns HTTP 200.\n\nTRACES report availability is polled for up to one day after successful submission. Authentication, processing, and report-availability failures appear on the job.\n\nThe output workbook contains payee_sheet and payee_table with the header [\"sr_no\", \"pan\", \"pan_status\"]. It includes only submitted PANs returned by TRACES. The first input sr_no is retained for each PAN. A missing PAN is omitted and does not fail the job.\n\nThe pan_status value is the exact text returned by TRACES. Known values include Valid and Operative, Valid and Inoperative, Valid, Inactive, and Invalid. Other source values are returned unchanged. An Invalid PAN result does not mean the job failed. The input file limit does not limit the output file.\n\nOutput workbook example:\n\n```json\n{\n \"@entity\": \"workbook\",\n \"name\": \"pan_verification_workbook\",\n \"sheets\": [\n {\n \"@entity\": \"sheet\",\n \"name\": \"payee_sheet\",\n \"blocks\": [\n {\n \"@entity\": \"table\",\n \"name\": \"payee_table\",\n \"header\": [\n \"sr_no\",\n \"pan\",\n \"pan_status\"\n ],\n \"rows\": [\n [\n 1,\n \"ABCPD1234E\",\n \"Valid and Operative\"\n ],\n [\n 2,\n \"XYZPK5678L\",\n \"Valid and Inoperative\"\n ]\n ]\n }\n ]\n }\n ]\n}\n```\n\nThis example omits the repeated input PAN and a PAN absent from the TRACES report.", "operationId": "GetPanVerificationJobStatus", "tags": [ "TDS", "TRACES", "PAN Verification" ], "parameters": [ { "name": "job_id", "in": "query", "description": "Job ID returned when the PAN verification job was created.", "required": true, "schema": { "type": "string", "format": "uuid" }, "examples": { "Status created": { "summary": "Status created", "value": "b5084575-7bdf-4a40-a8db-e19c93d34ec4" }, "Verification in progress": { "summary": "Verification in progress", "value": "b5084575-7bdf-4a40-a8db-e19c93d34ec4" }, "Verification completed": { "summary": "Verification completed", "value": "8941b6c4-8104-4a4b-b38c-14b0a1ed6837" }, "Verification failed": { "summary": "Verification failed", "value": "b5084575-7bdf-4a40-a8db-e19c93d34ec4" }, "Job not found": { "summary": "Job not found", "value": "00000000-0000-4000-8000-000000000000" } } }, { "name": "Authorization", "in": "header", "description": "Sandbox JWT access token. See 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": "Sandbox API key for the request.", "required": true, "example": "{{api_key}}", "schema": { "type": "string" } } ], "responses": { "200": { "description": "The current job status. Failed verification jobs are returned with HTTP 200 and status failed.", "content": { "application/json": { "schema": { "type": "object", "properties": { "code": { "type": "integer", "enum": [ 200 ], "description": "HTTP status code." }, "timestamp": { "type": "integer", "format": "int64", "description": "Response timestamp in epoch milliseconds." }, "transaction_id": { "type": "string", "format": "uuid", "description": "Unique identifier for this API transaction." }, "data": { "$ref": "#/components/schemas/PanVerificationJob" } }, "required": [ "code", "timestamp", "transaction_id", "data" ] }, "examples": { "Status created": { "summary": "Status created", "value": { "code": 200, "timestamp": 1792136875077, "data": { "created_at": 1792136873733, "updated_at": 1792136873769, "@entity": "in.co.sandbox.tds.compliance.pan.verification.job", "job_id": "b5084575-7bdf-4a40-a8db-e19c93d34ec4", "tan": "AHMA12345A", "status": "created" }, "transaction_id": "41586383-1df1-4c50-8c46-b1e810d6a70d" } }, "Verification in progress": { "summary": "Verification in progress", "value": { "code": 200, "timestamp": 1792136921704, "data": { "created_at": 1792136873733, "updated_at": 1792136921653, "@entity": "in.co.sandbox.tds.compliance.pan.verification.job", "job_id": "b5084575-7bdf-4a40-a8db-e19c93d34ec4", "tan": "AHMA12345A", "status": "in_progress" }, "transaction_id": "825ecaf8-df37-4ca7-9dcf-3f134d9747a6" } }, "Verification completed": { "summary": "Verification completed", "value": { "code": 200, "timestamp": 1792136917339, "data": { "created_at": 1792054456408, "updated_at": 1792054527258, "@entity": "in.co.sandbox.tds.compliance.pan.verification.job", "job_id": "8941b6c4-8104-4a4b-b38c-14b0a1ed6837", "tan": "AHMA12345A", "status": "succeeded", "output_json_url": "https://sandbox-example.s3.ap-south-1.amazonaws.com/example-workspace/8941b6c4-8104-4a4b-b38c-14b0a1ed6837/pan-verification.json?X-Amz-Signature=example" }, "transaction_id": "3663d8df-d06f-4d88-a250-a74d99e5750e" } }, "Verification failed": { "summary": "Verification failed", "value": { "code": 200, "timestamp": 1792136925346, "data": { "created_at": 1792136873733, "updated_at": 1792136925094, "@entity": "in.co.sandbox.tds.compliance.pan.verification.job", "job_id": "b5084575-7bdf-4a40-a8db-e19c93d34ec4", "tan": "AHMA12345A", "message": "Credentials not found", "status": "failed" }, "transaction_id": "f77d73e8-5f0f-4e96-a16f-045fdd41618a" } } } } }, "headers": {} }, "401": { "description": "Sandbox authorization is missing, invalid, or expired.", "content": { "application/json": { "schema": { "type": "object", "properties": { "code": { "type": "integer", "enum": [ 401 ], "description": "HTTP status code." }, "timestamp": { "type": "integer", "format": "int64", "description": "Response timestamp in epoch milliseconds." }, "transaction_id": { "type": "string", "format": "uuid", "description": "Unique identifier for this API transaction." }, "message": { "type": "string", "description": "Reason the request could not be completed." } }, "required": [ "code", "timestamp", "transaction_id", "message" ] } } }, "headers": {} }, "403": { "description": "Access to this API is denied.", "content": { "application/json": { "schema": { "type": "object", "properties": { "code": { "type": "integer", "enum": [ 403 ], "description": "HTTP status code." }, "timestamp": { "type": "integer", "format": "int64", "description": "Response timestamp in epoch milliseconds." }, "transaction_id": { "type": "string", "format": "uuid", "description": "Unique identifier for this API transaction." }, "message": { "type": "string", "description": "Reason the request could not be completed." } }, "required": [ "code", "timestamp", "transaction_id", "message" ] } } }, "headers": {} }, "500": { "description": "The API request could not be completed.", "content": { "application/json": { "schema": { "type": "object", "properties": { "code": { "type": "integer", "enum": [ 500 ], "description": "HTTP status code." }, "timestamp": { "type": "integer", "format": "int64", "description": "Response timestamp in epoch milliseconds." }, "transaction_id": { "type": "string", "format": "uuid", "description": "Unique identifier for this API transaction." }, "message": { "type": "string", "description": "Reason the request could not be completed." } }, "required": [ "code", "timestamp", "transaction_id", "message" ] } } }, "headers": {} }, "521": { "description": "No PAN verification job matches the supplied job ID in your workspace.", "content": { "application/json": { "schema": { "type": "object", "properties": { "code": { "type": "integer", "enum": [ 521 ], "description": "HTTP status code." }, "timestamp": { "type": "integer", "format": "int64", "description": "Response timestamp in epoch milliseconds." }, "transaction_id": { "type": "string", "format": "uuid", "description": "Unique identifier for this API transaction." }, "message": { "type": "string", "description": "Reason the request could not be completed." } }, "required": [ "code", "timestamp", "transaction_id", "message" ] }, "examples": { "Job not found": { "summary": "Job not found", "value": { "code": 521, "timestamp": 1792136877482, "message": "Data not found", "transaction_id": "8eb6e7a7-518b-4471-a6bc-a3bd30b71106" } } } } }, "headers": {} } }, "security": [] } } }, "components": { "schemas": { "CertificateJob": { "type": "object", "additionalProperties": false, "description": "Certificate download job.", "required": [ "@entity", "job_id", "tan", "tax_year", "quarter", "form", "status", "created_at" ], "properties": { "@entity": { "type": "string", "enum": [ "in.co.sandbox.tds.compliance.certificate.job" ], "description": "Identifies the object as a certificate job." }, "job_id": { "type": "string", "format": "uuid", "description": "Unique identifier for the certificate job." }, "tan": { "type": "string", "pattern": "^[A-Z]{4}[0-9]{5}[A-Z]$", "description": "TAN used to request the certificate.", "example": "AHMS12345C" }, "tax_year": { "type": "string", "pattern": "^TY [0-9]{4}-[0-9]{2}$", "description": "Tax year of the requested certificate.", "example": "TY 2025-26" }, "quarter": { "type": "string", "enum": [ "Q1", "Q2", "Q3", "Q4" ], "description": "Quarter of the requested certificate." }, "form": { "type": "string", "description": "TDS return form of the requested certificate.", "example": "24Q" }, "status": { "type": "string", "enum": [ "created", "queued", "in_progress", "succeeded", "failed" ], "description": "Current status of the certificate job." }, "created_at": { "type": "integer", "format": "int64", "description": "Time the job was created, in epoch milliseconds." }, "updated_at": { "type": "integer", "format": "int64", "description": "Time the job was last updated, in epoch milliseconds. Omitted while the job is queued." }, "certificate_pdf_zip_urls": { "type": "array", "minItems": 1, "description": "Presigned URLs for the certificate PDF ZIP files. Returned only for a succeeded job.", "items": { "type": "string", "format": "uri" } }, "message": { "type": "string", "description": "Reason the job failed. Returned only for a failed job." } }, "x-apidog-orders": [ "@entity", "job_id", "tan", "tax_year", "quarter", "form", "status", "created_at", "updated_at", "certificate_pdf_zip_urls", "message" ], "x-apidog-ignore-properties": [], "x-apidog-folder": "" }, "CertificatePaginatedList": { "type": "object", "additionalProperties": false, "description": "Page of certificate jobs.", "required": [ "@entity", "items" ], "properties": { "@entity": { "type": "string", "enum": [ "in.co.sandbox.tds.compliance.certificate.paginated_list" ], "description": "Identifies the object as a page of certificate jobs." }, "items": { "type": "array", "description": "Certificate jobs in the current page.", "items": { "$ref": "#/components/schemas/CertificateJob" } }, "last_evaluated_key": { "type": "string", "description": "Opaque cursor for the next page. Omitted when no more results exist." } }, "x-apidog-orders": [ "@entity", "items", "last_evaluated_key" ], "x-apidog-ignore-properties": [], "x-apidog-folder": "" }, "CertificateJobRequest": { "type": "object", "additionalProperties": false, "required": [ "@entity", "tan", "quarter", "tax_year", "form" ], "properties": { "@entity": { "type": "string", "enum": [ "in.co.sandbox.tds.compliance.certificate.job.request" ], "description": "Identifies the object as a certificate job request." }, "tan": { "type": "string", "pattern": "^[A-Z]{4}[0-9]{5}[A-Z]$", "description": "TAN used to request the certificate.", "example": "AHMS45586C" }, "quarter": { "type": "string", "enum": [ "Q1", "Q2", "Q3", "Q4" ], "description": "Quarter of the requested certificate." }, "tax_year": { "type": "string", "pattern": "^TY [0-9]{4}-[0-9]{2}$", "description": "Tax year of the requested certificate.", "example": "TY 2025-26" }, "form": { "type": "string", "description": "TDS return form of the requested certificate.", "example": "24Q" } }, "x-apidog-orders": [ "@entity", "tan", "quarter", "tax_year", "form" ], "x-apidog-ignore-properties": [], "x-apidog-folder": "" }, "CertificateJobSearchRequest": { "type": "object", "description": "Filters used to search certificate generation jobs.", "properties": { "@entity": { "type": "string", "description": "Search request entity type.", "example": "in.co.sandbox.tds.compliance.certificate.job.search" }, "tan": { "type": "string", "description": "Tax Deduction and Collection Account Number (TAN).", "example": "AHMS45586C" }, "tax_year": { "type": "string", "description": "Tax year used to filter certificate jobs. Use the TY YYYY-YY format.", "example": "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" ], "x-apidog-orders": [ "@entity", "tan", "tax_year", "quarter", "form", "status", "page_size", "last_evaluated_key" ], "x-apidog-ignore-properties": [], "x-apidog-folder": "" }, "CertificateJobResponse": { "type": "object", "additionalProperties": false, "required": [ "code", "timestamp", "transaction_id", "data" ], "properties": { "code": { "type": "integer", "description": "HTTP status code.", "example": 200 }, "timestamp": { "type": "integer", "format": "int64", "description": "Response timestamp in epoch milliseconds.", "example": 1716870600000 }, "transaction_id": { "type": "string", "description": "Transaction identifier used to trace the API request.", "example": "f24cd229-42c8-43de-af79-8ce2d3c4c3db" }, "data": { "$ref": "#/components/schemas/CertificateJob" } }, "x-apidog-orders": [ "code", "timestamp", "transaction_id", "data" ], "x-apidog-ignore-properties": [], "x-apidog-folder": "" }, "CertificatePaginatedListResponse": { "type": "object", "additionalProperties": false, "required": [ "code", "timestamp", "transaction_id", "data" ], "properties": { "code": { "type": "integer", "description": "HTTP status code.", "example": 200 }, "timestamp": { "type": "integer", "format": "int64", "description": "Response timestamp in epoch milliseconds.", "example": 1716870600000 }, "transaction_id": { "type": "string", "description": "Transaction identifier used to trace the API request.", "example": "f24cd229-42c8-43de-af79-8ce2d3c4c3db" }, "data": { "$ref": "#/components/schemas/CertificatePaginatedList" } }, "x-apidog-orders": [ "code", "timestamp", "transaction_id", "data" ], "x-apidog-ignore-properties": [], "x-apidog-folder": "" }, "ErrorResponse": { "type": "object", "additionalProperties": false, "required": [ "code", "timestamp", "transaction_id", "message" ], "properties": { "code": { "type": "integer", "description": "HTTP status code." }, "timestamp": { "type": "integer", "format": "int64", "description": "Response timestamp in epoch milliseconds." }, "transaction_id": { "type": "string", "description": "Transaction identifier used to trace the API request." }, "message": { "type": "string", "description": "Error message." } }, "x-apidog-orders": [ "code", "timestamp", "transaction_id", "message" ], "x-apidog-ignore-properties": [], "x-apidog-folder": "" }, "ChallanTaxBreakdown": { "title": "ChallanTaxBreakdown", "type": "object", "additionalProperties": false, "properties": { "@entity": { "type": "string", "default": "in.co.sandbox.tds.compliance.challan.tax_breakdown", "enum": [ "in.co.sandbox.tds.compliance.challan.tax_breakdown" ], "description": "Identifies the type of this object." }, "id": { "type": "string", "description": "Object identifier, when available." }, "description": { "type": "string", "description": "Additional information about the object, when available." }, "created_at": { "type": "string", "description": "Creation timestamp, when available." }, "updated_at": { "type": "string", "description": "Last update timestamp, when available." }, "section": { "type": "string", "description": "TDS section reported by TRACES for this tax breakdown." }, "tax_amount": { "type": "number", "description": "Base tax amount in INR, excluding surcharge and cess." }, "surcharge": { "type": "number", "description": "Surcharge amount in INR." }, "cess": { "type": "number", "description": "Cess amount in INR." }, "total_amount": { "type": "number", "description": "Total amount in INR." } }, "required": [ "@entity", "section", "tax_amount", "surcharge", "cess", "total_amount" ], "description": "Tax, surcharge, and cess for a section reported against the challan. All amounts are in INR.", "x-apidog-ignore-properties": [], "x-apidog-orders": [ "@entity", "id", "description", "created_at", "updated_at", "section", "tax_amount", "surcharge", "cess", "total_amount" ], "x-apidog-folder": "" }, "ChallanConsumptionDetails": { "title": "ChallanConsumptionDetails", "description": "Challan utilization for the statement reported by TRACES. This record is not a complete history of utilization across statements.", "type": "object", "additionalProperties": false, "properties": { "@entity": { "type": "string", "default": "in.co.sandbox.tds.compliance.challan.consumption_details", "enum": [ "in.co.sandbox.tds.compliance.challan.consumption_details" ], "description": "Identifies the type of this object." }, "id": { "type": "string", "description": "Object identifier, when available." }, "description": { "type": "string", "description": "Additional information about the object, when available." }, "created_at": { "type": "string", "description": "Creation timestamp, when available." }, "updated_at": { "type": "string", "description": "Last update timestamp, when available." }, "statement_token_number": { "type": "string", "description": "Token number of the statement against which the challan was claimed." }, "financial_year": { "type": "string", "pattern": "^FY [0-9]{4}-[0-9]{2}$", "description": "Financial year of the reported TDS statement in FY YYYY-YY format." }, "quarter": { "type": "string", "description": "Quarter of the TDS statement, from Q1 to Q4." }, "form": { "type": "string", "description": "TDS statement form code reported by TRACES." }, "status": { "type": "string", "description": "Consumption status of the challan in the reported statement." }, "claimed_amount": { "type": "number", "description": "Amount claimed against the challan in the reported statement, in INR." }, "excess_claimed_amount": { "type": "number", "description": "Excess claimed amount reported by TRACES, in INR." }, "available_amount": { "type": "number", "description": "Available challan amount reported by TRACES, in INR." } }, "required": [ "@entity", "statement_token_number", "financial_year", "quarter", "form", "status", "claimed_amount", "excess_claimed_amount", "available_amount" ], "x-apidog-ignore-properties": [], "x-apidog-orders": [ "@entity", "id", "description", "created_at", "updated_at", "statement_token_number", "financial_year", "quarter", "form", "status", "claimed_amount", "excess_claimed_amount", "available_amount" ], "x-apidog-folder": "" }, "Challan": { "title": "Challan", "type": "object", "additionalProperties": false, "properties": { "@entity": { "type": "string", "default": "in.co.sandbox.tds.compliance.challan.response", "enum": [ "in.co.sandbox.tds.compliance.challan.response" ], "description": "Identifies the type of this object." }, "id": { "type": "string", "description": "Object identifier, when available." }, "description": { "type": "string", "description": "Additional information about the object, when available." }, "created_at": { "type": "string", "description": "Creation timestamp, when available." }, "updated_at": { "type": "string", "description": "Last update timestamp, when available." }, "tan": { "type": "string", "description": "Tax Deduction and Collection Account Number (TAN) of the deductor." }, "bsr_code": { "type": "string", "description": "Basic Statistical Return (BSR) code of the bank branch where the challan was deposited." }, "challan_serial": { "type": "string", "description": "Five-digit challan serial number, including leading zeroes." }, "paid_date_epoch": { "type": "integer", "description": "Deposit date in epoch milliseconds. The calendar date is interpreted in Asia/Kolkata." }, "challan_identification_number": { "type": "string", "description": "Challan Identification Number (CIN) reported by TRACES." }, "receipt_number": { "type": "string", "description": "Receipt number reported by TRACES." }, "financial_year": { "type": "string", "description": "Financial year reported by TRACES in FY YYYY-YY format. This year can differ from the financial year of the deposit date." }, "major_head": { "type": "string", "description": "Major head of tax, including leading zeroes, such as 0021." }, "minor_head": { "type": "string", "description": "Minor head of payment, such as 200." }, "total_amount": { "type": "number", "description": "Total amount in INR." }, "status": { "type": "string", "description": "Challan matching status reported by TRACES." }, "section_code": { "type": [ "string", "null" ], "description": "Legacy section code reported by TRACES, or null if unavailable. This code can be present even when tax_breakdown is empty." }, "residency_status": { "type": [ "string", "null" ], "description": "Residency status code reported by TRACES, or null if unavailable." }, "tax_breakdown": { "type": "array", "items": { "title": "ChallanTaxBreakdown", "type": "object", "additionalProperties": false, "properties": { "@entity": { "type": "string", "default": "in.co.sandbox.tds.compliance.challan.tax_breakdown", "enum": [ "in.co.sandbox.tds.compliance.challan.tax_breakdown" ], "description": "Identifies the type of this object." }, "id": { "type": "string", "description": "Object identifier, when available." }, "description": { "type": "string", "description": "Additional information about the object, when available." }, "created_at": { "type": "string", "description": "Creation timestamp, when available." }, "updated_at": { "type": "string", "description": "Last update timestamp, when available." }, "section": { "type": "string", "description": "TDS section reported by TRACES for this tax breakdown." }, "tax_amount": { "type": "number", "description": "Base tax amount in INR, excluding surcharge and cess." }, "surcharge": { "type": "number", "description": "Surcharge amount in INR." }, "cess": { "type": "number", "description": "Cess amount in INR." }, "total_amount": { "type": "number", "description": "Total amount in INR." } }, "required": [ "@entity", "section", "tax_amount", "surcharge", "cess", "total_amount" ], "description": "Tax, surcharge, and cess for a section reported against the challan. All amounts are in INR.", "x-apidog-ignore-properties": [], "x-apidog-orders": [ "@entity", "id", "description", "created_at", "updated_at", "section", "tax_amount", "surcharge", "cess", "total_amount" ] }, "description": "Section-wise tax breakdown in INR. An empty list means no breakdown is available." }, "consumption_details": { "title": "ChallanConsumptionDetails", "description": "Statement utilization reported by TRACES. null means utilization details are unavailable and does not indicate an unused challan.", "type": [ "object", "null" ], "additionalProperties": false, "properties": { "@entity": { "type": "string", "default": "in.co.sandbox.tds.compliance.challan.consumption_details", "enum": [ "in.co.sandbox.tds.compliance.challan.consumption_details" ], "description": "Identifies the type of this object." }, "id": { "type": "string", "description": "Object identifier, when available." }, "description": { "type": "string", "description": "Additional information about the object, when available." }, "created_at": { "type": "string", "description": "Creation timestamp, when available." }, "updated_at": { "type": "string", "description": "Last update timestamp, when available." }, "statement_token_number": { "type": "string", "description": "Token number of the statement against which the challan was claimed." }, "financial_year": { "type": "string", "pattern": "^FY [0-9]{4}-[0-9]{2}$", "description": "Financial year of the reported TDS statement in FY YYYY-YY format." }, "quarter": { "type": "string", "description": "Quarter of the TDS statement, from Q1 to Q4." }, "form": { "type": "string", "description": "TDS statement form code reported by TRACES." }, "status": { "type": "string", "description": "Consumption status of the challan in the reported statement." }, "claimed_amount": { "type": "number", "description": "Amount claimed against the challan in the reported statement, in INR." }, "excess_claimed_amount": { "type": "number", "description": "Excess claimed amount reported by TRACES, in INR." }, "available_amount": { "type": "number", "description": "Available challan amount reported by TRACES, in INR." } }, "required": [ "@entity", "statement_token_number", "financial_year", "quarter", "form", "status", "claimed_amount", "excess_claimed_amount", "available_amount" ], "x-apidog-ignore-properties": [], "x-apidog-orders": [ "@entity", "id", "description", "created_at", "updated_at", "statement_token_number", "financial_year", "quarter", "form", "status", "claimed_amount", "excess_claimed_amount", "available_amount" ] } }, "required": [ "@entity", "tan", "bsr_code", "challan_serial", "paid_date_epoch", "challan_identification_number", "receipt_number", "financial_year", "major_head", "minor_head", "total_amount", "status", "section_code", "residency_status", "tax_breakdown", "consumption_details" ], "description": "A TDS challan with its tax breakdown and available utilization details from TRACES. All amounts are in INR.", "x-apidog-ignore-properties": [], "x-apidog-orders": [ "@entity", "id", "description", "created_at", "updated_at", "tan", "bsr_code", "challan_serial", "paid_date_epoch", "challan_identification_number", "receipt_number", "financial_year", "major_head", "minor_head", "total_amount", "status", "section_code", "residency_status", "tax_breakdown", "consumption_details" ], "x-apidog-folder": "" }, "ChallanLookupRequest": { "title": "ChallanLookupRequest", "type": "object", "additionalProperties": false, "properties": { "@entity": { "type": "string", "default": "in.co.sandbox.tds.compliance.challan.request", "enum": [ "in.co.sandbox.tds.compliance.challan.request" ], "description": "Identifies the type of this object." }, "id": { "type": "string", "description": "Object identifier, when available." }, "description": { "type": "string", "description": "Additional information about the object, when available." }, "created_at": { "type": "string", "description": "Creation timestamp, when available." }, "updated_at": { "type": "string", "description": "Last update timestamp, when available." }, "tan": { "type": "string", "pattern": "^[A-Z]{4}[0-9]{5}[A-Z]$", "description": "Tax Deduction and Collection Account Number (TAN) of the deductor." }, "bsr_code": { "type": "string", "pattern": "^[0-9]{7}$", "description": "Basic Statistical Return (BSR) code of the bank branch where the challan was deposited." }, "challan_serial": { "type": "string", "pattern": "^[0-9]{5}$", "description": "Five-digit challan serial number, including leading zeroes." }, "paid_date_epoch": { "type": "integer", "minimum": 0, "description": "Deposit date in epoch milliseconds. The calendar date is interpreted in Asia/Kolkata." } }, "required": [ "@entity", "tan", "bsr_code", "challan_serial", "paid_date_epoch" ], "description": "Particulars that identify a TDS challan for a deductor.", "x-apidog-ignore-properties": [], "x-apidog-orders": [ "@entity", "id", "description", "created_at", "updated_at", "tan", "bsr_code", "challan_serial", "paid_date_epoch" ], "x-apidog-folder": "" }, "ChallanSearchRequest": { "title": "ChallanSearchRequest", "description": "Deposit-date filters for a deductor's challan search. Both dates are required. Pagination is optional.", "type": "object", "additionalProperties": false, "properties": { "@entity": { "type": "string", "default": "in.co.sandbox.tds.compliance.challan.search", "enum": [ "in.co.sandbox.tds.compliance.challan.search" ], "description": "Identifies the type of this object." }, "id": { "type": "string", "description": "Object identifier, when available." }, "description": { "type": "string", "description": "Additional information about the object, when available." }, "created_at": { "type": "string", "description": "Creation timestamp, when available." }, "updated_at": { "type": "string", "description": "Last update timestamp, when available." }, "tan": { "type": "string", "pattern": "^[A-Z]{4}[0-9]{5}[A-Z]$", "description": "Tax Deduction and Collection Account Number (TAN) of the deductor." }, "from_date_epoch": { "type": "integer", "minimum": 0, "description": "Start of the deposit-date range in epoch milliseconds, interpreted in Asia/Kolkata." }, "to_date_epoch": { "type": "integer", "minimum": 0, "description": "End of the deposit-date range in epoch milliseconds, interpreted in Asia/Kolkata." }, "page_number": { "type": "integer", "minimum": 0, "description": "Zero-based page number. 0 requests the first page. Omit to use the default page." }, "page_size": { "type": "integer", "minimum": 1, "description": "Number of challans requested per page. Omit to use the default page size." } }, "required": [ "@entity", "tan", "from_date_epoch", "to_date_epoch" ], "x-apidog-ignore-properties": [], "x-apidog-orders": [ "@entity", "id", "description", "created_at", "updated_at", "tan", "from_date_epoch", "to_date_epoch", "page_number", "page_size" ], "x-apidog-folder": "" }, "ChallanSearchResponse": { "title": "ChallanSearchResponse", "type": "object", "additionalProperties": false, "properties": { "@entity": { "type": "string", "default": "in.co.sandbox.tds.compliance.challan.search.response", "enum": [ "in.co.sandbox.tds.compliance.challan.search.response" ], "description": "Identifies the type of this object." }, "id": { "type": "string", "description": "Object identifier, when available." }, "description": { "type": "string", "description": "Additional information about the object, when available." }, "created_at": { "type": "string", "description": "Creation timestamp, when available." }, "updated_at": { "type": "string", "description": "Last update timestamp, when available." }, "data": { "type": "array", "items": { "title": "Challan", "type": "object", "additionalProperties": false, "properties": { "@entity": { "type": "string", "default": "in.co.sandbox.tds.compliance.challan.response", "enum": [ "in.co.sandbox.tds.compliance.challan.response" ], "description": "Identifies the type of this object." }, "id": { "type": "string", "description": "Object identifier, when available." }, "description": { "type": "string", "description": "Additional information about the object, when available." }, "created_at": { "type": "string", "description": "Creation timestamp, when available." }, "updated_at": { "type": "string", "description": "Last update timestamp, when available." }, "tan": { "type": "string", "description": "Tax Deduction and Collection Account Number (TAN) of the deductor." }, "bsr_code": { "type": "string", "description": "Basic Statistical Return (BSR) code of the bank branch where the challan was deposited." }, "challan_serial": { "type": "string", "description": "Five-digit challan serial number, including leading zeroes." }, "paid_date_epoch": { "type": "integer", "description": "Deposit date in epoch milliseconds. The calendar date is interpreted in Asia/Kolkata." }, "challan_identification_number": { "type": "string", "description": "Challan Identification Number (CIN) reported by TRACES." }, "receipt_number": { "type": "string", "description": "Receipt number reported by TRACES." }, "financial_year": { "type": "string", "description": "Financial year reported by TRACES in FY YYYY-YY format. This year can differ from the financial year of the deposit date." }, "major_head": { "type": "string", "description": "Major head of tax, including leading zeroes, such as 0021." }, "minor_head": { "type": "string", "description": "Minor head of payment, such as 200." }, "total_amount": { "type": "number", "description": "Total amount in INR." }, "status": { "type": "string", "description": "Challan matching status reported by TRACES." }, "section_code": { "type": [ "string", "null" ], "description": "Legacy section code reported by TRACES, or null if unavailable. This code can be present even when tax_breakdown is empty." }, "residency_status": { "type": [ "string", "null" ], "description": "Residency status code reported by TRACES, or null if unavailable." }, "tax_breakdown": { "type": "array", "items": { "title": "ChallanTaxBreakdown", "type": "object", "additionalProperties": false, "properties": { "@entity": { "type": "string", "default": "in.co.sandbox.tds.compliance.challan.tax_breakdown", "enum": [ "in.co.sandbox.tds.compliance.challan.tax_breakdown" ], "description": "Identifies the type of this object." }, "id": { "type": "string", "description": "Object identifier, when available." }, "description": { "type": "string", "description": "Additional information about the object, when available." }, "created_at": { "type": "string", "description": "Creation timestamp, when available." }, "updated_at": { "type": "string", "description": "Last update timestamp, when available." }, "section": { "type": "string", "description": "TDS section reported by TRACES for this tax breakdown." }, "tax_amount": { "type": "number", "description": "Base tax amount in INR, excluding surcharge and cess." }, "surcharge": { "type": "number", "description": "Surcharge amount in INR." }, "cess": { "type": "number", "description": "Cess amount in INR." }, "total_amount": { "type": "number", "description": "Total amount in INR." } }, "required": [ "@entity", "section", "tax_amount", "surcharge", "cess", "total_amount" ], "description": "Tax, surcharge, and cess for a section reported against the challan. All amounts are in INR.", "x-apidog-ignore-properties": [], "x-apidog-orders": [ "@entity", "id", "description", "created_at", "updated_at", "section", "tax_amount", "surcharge", "cess", "total_amount" ] }, "description": "Section-wise tax breakdown in INR. An empty list means no breakdown is available." }, "consumption_details": { "title": "ChallanConsumptionDetails", "description": "Statement utilization reported by TRACES. null means utilization details are unavailable and does not indicate an unused challan.", "type": [ "object", "null" ], "additionalProperties": false, "properties": { "@entity": { "type": "string", "default": "in.co.sandbox.tds.compliance.challan.consumption_details", "enum": [ "in.co.sandbox.tds.compliance.challan.consumption_details" ], "description": "Identifies the type of this object." }, "id": { "type": "string", "description": "Object identifier, when available." }, "description": { "type": "string", "description": "Additional information about the object, when available." }, "created_at": { "type": "string", "description": "Creation timestamp, when available." }, "updated_at": { "type": "string", "description": "Last update timestamp, when available." }, "statement_token_number": { "type": "string", "description": "Token number of the statement against which the challan was claimed." }, "financial_year": { "type": "string", "pattern": "^FY [0-9]{4}-[0-9]{2}$", "description": "Financial year of the reported TDS statement in FY YYYY-YY format." }, "quarter": { "type": "string", "description": "Quarter of the TDS statement, from Q1 to Q4." }, "form": { "type": "string", "description": "TDS statement form code reported by TRACES." }, "status": { "type": "string", "description": "Consumption status of the challan in the reported statement." }, "claimed_amount": { "type": "number", "description": "Amount claimed against the challan in the reported statement, in INR." }, "excess_claimed_amount": { "type": "number", "description": "Excess claimed amount reported by TRACES, in INR." }, "available_amount": { "type": "number", "description": "Available challan amount reported by TRACES, in INR." } }, "required": [ "@entity", "statement_token_number", "financial_year", "quarter", "form", "status", "claimed_amount", "excess_claimed_amount", "available_amount" ], "x-apidog-ignore-properties": [], "x-apidog-orders": [ "@entity", "id", "description", "created_at", "updated_at", "statement_token_number", "financial_year", "quarter", "form", "status", "claimed_amount", "excess_claimed_amount", "available_amount" ] } }, "required": [ "@entity", "tan", "bsr_code", "challan_serial", "paid_date_epoch", "challan_identification_number", "receipt_number", "financial_year", "major_head", "minor_head", "total_amount", "status", "section_code", "residency_status", "tax_breakdown", "consumption_details" ], "description": "A TDS challan with its tax breakdown and available utilization details from TRACES. All amounts are in INR.", "x-apidog-ignore-properties": [], "x-apidog-orders": [ "@entity", "id", "description", "created_at", "updated_at", "tan", "bsr_code", "challan_serial", "paid_date_epoch", "challan_identification_number", "receipt_number", "financial_year", "major_head", "minor_head", "total_amount", "status", "section_code", "residency_status", "tax_breakdown", "consumption_details" ] }, "description": "Challans in the requested page. An empty list means no challans were returned for that page." }, "totalPages": { "type": "integer", "minimum": 0, "description": "Total number of result pages reported by TRACES." }, "totalElements": { "type": "integer", "minimum": 0, "description": "Total number of matching challans reported by TRACES." } }, "required": [ "@entity", "data", "totalPages", "totalElements" ], "description": "One page of challans with pagination totals reported by TRACES.", "x-apidog-ignore-properties": [], "x-apidog-orders": [ "@entity", "id", "description", "created_at", "updated_at", "data", "totalPages", "totalElements" ], "x-apidog-folder": "" }, "PanVerificationJob": { "type": "object", "description": "A bulk PAN verification job. Upload the input through json_url. A succeeded job provides output_json_url. A failed job provides message.", "properties": { "@entity": { "type": "string", "enum": [ "in.co.sandbox.tds.compliance.pan.verification.job" ], "description": "Job entity type." }, "job_id": { "type": "string", "format": "uuid", "description": "Unique identifier returned when the job is created." }, "tan": { "type": "string", "pattern": "^[A-Z]{4}[0-9]{5}[A-Z]$", "description": "TAN associated with the verification job." }, "status": { "type": "string", "enum": [ "created", "queued", "in_progress", "succeeded", "failed" ], "description": "Current job status. created waits for the workbook upload. queued waits to start processing. in_progress covers workbook validation, TRACES authentication and verification, and output workbook generation. succeeded means the output JSON workbook is saved. failed means processing did not complete." }, "created_at": { "type": "integer", "format": "int64", "description": "Job creation timestamp in epoch milliseconds." }, "updated_at": { "type": "integer", "format": "int64", "description": "Last job update timestamp in epoch milliseconds. Omitted from the job creation response." }, "json_url": { "type": "string", "format": "uri", "description": "Signed URL for uploading the input JSON workbook with HTTP PUT. The input limit is 5,000,000 bytes." }, "output_json_url": { "type": "string", "format": "uri", "description": "Signed URL for downloading the completed output JSON workbook with HTTP GET. Available when status is succeeded." }, "message": { "type": "string", "description": "Reason the job failed. Present when status is failed." } }, "required": [ "@entity", "job_id", "tan", "status", "created_at" ], "additionalProperties": false, "oneOf": [ { "properties": { "status": { "enum": [ "created", "queued", "in_progress" ] } }, "type": "object" }, { "properties": { "status": { "enum": [ "succeeded" ] } }, "type": "object" }, { "properties": { "status": { "enum": [ "failed" ] } }, "type": "object" } ] }, "PanVerificationRequest": { "type": "object", "description": "Creates a bulk PAN verification job for a TAN. The payee workbook is uploaded separately to the returned signed URL.", "properties": { "@entity": { "type": "string", "enum": [ "in.co.sandbox.tds.compliance.pan.verification.request" ], "description": "Request entity type." }, "tan": { "type": "string", "pattern": "^[A-Z]{4}[0-9]{5}[A-Z]$", "description": "Tax Deduction and Collection Account Number associated with the saved TRACES credentials.", "examples": [ "AHMA12345A" ] } }, "required": [ "@entity", "tan" ], "additionalProperties": false } }, "responses": {}, "securitySchemes": {} }, "servers": [ { "url": "https://test-api.sandbox.co.in", "description": "test" }, { "url": "https://api.sandbox.co.in", "description": "prod" } ], "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": [] } }, "PanVerificationJobStatus": { "post": { "summary": "Bulk PAN verification webhook", "deprecated": false, "description": "Sandbox sends this webhook when a bulk PAN verification job changes to `succeeded` or `failed`. The `data` object contains the same job fields as the [PAN verification status response](https://developer.sandbox.co.in/api-reference/tds/compliance/pan-verification/endpoints/poll_job). A successful job includes `output_json_url`. A failed job includes `message`.\n\nSubscribe to these events in the Sandbox Console:\n\n- `in.co.sandbox.tds.compliance.pan.verification.job.succeeded`\n- `in.co.sandbox.tds.compliance.pan.verification.job.failed`\n\nSee the [webhooks guide](https://developer.sandbox.co.in/guides/developer-resources/webhooks) to configure your webhook URL and validate the `x-sandbox-signature` header.", "operationId": "PanVerificationJobStatus", "tags": [ "PAN Verification" ], "parameters": [], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "description": "PAN verification job status notification.", "properties": { "data": { "$ref": "#/components/schemas/PanVerificationJob", "description": "Job details use the same schema as data in the PAN verification status response." } }, "required": [ "data" ] }, "examples": { "Verification completed": { "value": { "data": { "created_at": 1792054456408, "updated_at": 1792054527258, "@entity": "in.co.sandbox.tds.compliance.pan.verification.job", "job_id": "8941b6c4-8104-4a4b-b38c-14b0a1ed6837", "tan": "AHMA12345A", "status": "succeeded", "output_json_url": "https://sandbox-example.s3.ap-south-1.amazonaws.com/example-workspace/8941b6c4-8104-4a4b-b38c-14b0a1ed6837/pan-verification.json?X-Amz-Signature=example" } }, "summary": "Verification completed" }, "Verification failed": { "value": { "data": { "created_at": 1792136873733, "updated_at": 1792136925094, "@entity": "in.co.sandbox.tds.compliance.pan.verification.job", "job_id": "b5084575-7bdf-4a40-a8db-e19c93d34ec4", "tan": "AHMA12345A", "message": "Credentials not found", "status": "failed" } }, "summary": "Verification failed" } } } }, "required": true }, "responses": { "200": { "description": "Return a 2xx status to acknowledge receipt of the notification.", "headers": {} } }, "security": [] } } } }