{ "openapi": "3.0.1", "info": { "title": "in-co-sandbox-tds-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" }, "servers": [ { "url": "https://test-api.sandbox.co.in" }, { "url": "https://api.sandbox.co.in" } ], "paths": { "/tds/compliance/206ab/check": { "post": { "summary": "Section 206AB & 206CCA Compliance Check", "deprecated": false, "description": "", "tags": [ "TDS Compliance Check" ], "parameters": [ { "name": "authorization", "in": "header", "description": "JWT access token", "required": true, "example": "", "schema": { "type": "string" } }, { "name": "x-api-key", "in": "header", "description": "API key for identification", "required": true, "example": "", "schema": { "type": "string" } }, { "name": "x-api-version", "in": "header", "description": "API version", "required": false, "example": "", "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "@entity": { "type": "string", "enum": [ "in.co.sandbox.tds.compliance.206ab_check.request" ] }, "pan": { "description": "10-character alphanumeric unique identifier for an income tax-payer.", "pattern": "[A-Z]{3}[PCFTGHLABJ]{1}[A-Z]{1}[0-9]{4}[A-Z]{1}", "type": "string" }, "consent": { "type": "string" }, "reason": { "type": "string" } }, "required": [ "@entity", "pan", "consent", "reason" ] }, "examples": { "200 Specified person": { "value": { "@entity": "in.co.sandbox.tds.compliance.206ab_check.request", "pan": "XXXPX1234A", "consent": "y", "reason": "TDS compliance" }, "summary": "200 Specified person" }, "200 Specified person (2)": { "value": { "@entity": "in.co.sandbox.tds.compliance.206ab_check.request", "pan": "XXXPX1234L", "consent": "y", "reason": "TDS compliance" }, "summary": "200 Specified person (2)" }, "200 Specified person (3)": { "value": { "@entity": "in.co.sandbox.tds.compliance.206ab_check.request", "pan": "XXXPX1234L", "consent": "y", "reason": "TDS compliance" }, "summary": "200 Specified person (3)" }, "200 Specified person with inoperative pan": { "value": { "@entity": "in.co.sandbox.tds.compliance.206ab_check.request", "pan": "XXXPX1234H", "consent": "y", "reason": "TDS compliance" }, "summary": "200 Specified person with inoperative pan" }, "200 Specified person with inoperative pan (2)": { "value": { "@entity": "in.co.sandbox.tds.compliance.206ab_check.request", "pan": "XXXAX2345A", "consent": "y", "reason": "TDS compliance" }, "summary": "200 Specified person with inoperative pan (2)" }, "200 Not a specified person": { "value": { "@entity": "in.co.sandbox.tds.compliance.206ab_check.request", "pan": "XXXPX2345A", "consent": "y", "reason": "TDS complaince" }, "summary": "200 Not a specified person" }, "200 Not a specified person (2)": { "value": { "@entity": "in.co.sandbox.tds.compliance.206ab_check.request", "pan": "XXXBX3456B", "consent": "y", "reason": "TDS complaince" }, "summary": "200 Not a specified person (2)" }, "200 Not a specified person with inoperative pan": { "value": { "@entity": "in.co.sandbox.tds.compliance.206ab_check.request", "pan": "XXXPX1234O", "consent": "y", "reason": "TDS complaince" }, "summary": "200 Not a specified person with inoperative pan" }, "200 Not a specified person with inoperative pan (2)": { "value": { "@entity": "in.co.sandbox.tds.compliance.206ab_check.request", "pan": "XXXTX1234P", "consent": "y", "reason": "TDS complaince" }, "summary": "200 Not a specified person with inoperative pan (2)" }, "200 Invalid PAN": { "value": { "@entity": "in.co.sandbox.tds.compliance.206ab_check.request", "pan": "XXXPX1234C", "consent": "y", "reason": "TDS compliance" }, "summary": "200 Invalid PAN" }, "422 Invalid PAN pattern": { "value": { "@entity": "in.co.sandbox.tds.compliance.206ab_check.request", "pan": "XXXQX1234A", "consent": "y", "reason": "TDS compliance" }, "summary": "422 Invalid PAN pattern" } } } } }, "responses": { "200": { "description": "200 - OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "code": { "type": "integer" }, "timestamp": { "type": "integer" }, "transaction_id": { "type": "string" }, "data": { "type": "object", "properties": { "@entity": { "type": "string", "enum": [ "in.co.sandbox.tds.compliance.206ab_check.response" ] }, "pan": { "type": "string" }, "name": { "type": "string" }, "pan_allotment_date": { "type": "integer" }, "financial_year": { "type": "string" }, "specified_person_us_206ab_&_206cca": { "type": "string" }, "pan_status": { "type": "string" } } } } }, "examples": { "200 Specified person": { "summary": "200 Specified person", "value": { "code": 200, "timestamp": 1763362637000, "transaction_id": "e2b9145f-69d5-4bbe-a6de-be6fc08b426f", "data": { "@entity": "in.co.sandbox.tds.compliance.206ab_check.response", "pan": "XXXPX1234A", "name": "SXXXXJ MXXXXXXXXR", "pan_allotment_date": 1527100200000, "financial_year": "FY 2024-25", "specified_person_us_206ab_&_206cca": "y", "pan_status": "operative" } } }, "200 Specified person (2)": { "summary": "200 Specified person (2)", "value": { "code": 200, "timestamp": 1763362637000, "transaction_id": "e2b9145f-69d5-4bbe-a6de-be6fc08b426f", "data": { "@entity": "in.co.sandbox.tds.compliance.206ab_check.response", "pan": "XXXPX1234L", "name": "MXXXA PXXXL", "pan_allotment_date": 1527100200000, "financial_year": "FY 2024-25", "specified_person_us_206ab_&_206cca": "y", "pan_status": "operative" } } }, "200 Specified person (3)": { "summary": "200 Specified person (3)", "value": { "code": 200, "timestamp": 1763362637000, "transaction_id": "e2b9145f-69d5-4bbe-a6de-be6fc08b426f", "data": { "@entity": "in.co.sandbox.tds.compliance.206ab_check.response", "pan": "XXXCX1234B", "name": "IXXL CXXP", "pan_allotment_date": 1527100200000, "financial_year": "FY 2024-25", "specified_person_us_206ab_&_206cca": "y", "pan_status": "operative" } } }, "200 Specified person with inoperative pan": { "summary": "200 Specified person with inoperative pan", "value": { "code": 200, "timestamp": 1763362637000, "transaction_id": "e2b9145f-69d5-4bbe-a6de-be6fc08b426f", "data": { "@entity": "in.co.sandbox.tds.compliance.206ab_check.response", "pan": "XXXPX1234H", "name": "AXXXV KXXXA", "pan_allotment_date": 1527100200000, "financial_year": "FY 2024-25", "specified_person_us_206ab_&_206cca": "y", "pan_status": "inoperative" } } }, "200 Specified person with inoperative pan (2)": { "summary": "200 Specified person with inoperative pan (2)", "value": { "code": 200, "timestamp": 1763362637000, "transaction_id": "e2b9145f-69d5-4bbe-a6de-be6fc08b426f", "data": { "@entity": "in.co.sandbox.tds.compliance.206ab_check.response", "pan": "XXXAX2345A", "name": "MXXR SXXR", "pan_allotment_date": 1527100200000, "financial_year": "FY 2024-25", "specified_person_us_206ab_&_206cca": "y", "pan_status": "inoperative" } } }, "200 Not a specified person": { "summary": "200 Not a specified person", "value": { "code": 200, "timestamp": 1763362637000, "transaction_id": "e2b9145f-69d5-4bbe-a6de-be6fc08b426f", "data": { "@entity": "in.co.sandbox.tds.compliance.206ab_check.response", "pan": "XXXPX1234B", "name": "JXXXR MXXXXXXA", "pan_allotment_date": 1527100200000, "financial_year": "FY 2024-25", "specified_person_us_206ab_&_206cca": "n", "pan_status": "operative" } } }, "200 Not a specified person (2)": { "summary": "200 Not a specified person (2)", "value": { "code": 200, "timestamp": 1763362637000, "transaction_id": "e2b9145f-69d5-4bbe-a6de-be6fc08b426f", "data": { "@entity": "in.co.sandbox.tds.compliance.206ab_check.response", "pan": "XXXBX3456B", "name": "FXXD TXXXG", "pan_allotment_date": 1527100200000, "financial_year": "FY 2024-25", "specified_person_us_206ab_&_206cca": "n", "pan_status": "operative" } } }, "200 Not a specified person with inoperative pan": { "summary": "200 Not a specified person with inoperative pan", "value": { "code": 200, "timestamp": 1763362637000, "transaction_id": "e2b9145f-69d5-4bbe-a6de-be6fc08b426f", "data": { "@entity": "in.co.sandbox.tds.compliance.206ab_check.response", "pan": "XXXPX1234B", "name": "RXXXL SXXXH", "pan_allotment_date": 1527100200000, "financial_year": "FY 2024-25", "specified_person_us_206ab_&_206cca": "n", "pan_status": "inoperative" } } }, "200 Not a specified person with inoperative pan (2)": { "summary": "200 Not a specified person with inoperative pan (2)", "value": { "code": 200, "timestamp": 1763362637000, "transaction_id": "e2b9145f-69d5-4bbe-a6de-be6fc08b426f", "data": { "@entity": "in.co.sandbox.tds.compliance.206ab_check.response", "pan": "XXXTX1234P", "name": "EXXXN MXXL", "pan_allotment_date": 1527100200000, "financial_year": "FY 2024-25", "specified_person_us_206ab_&_206cca": "n", "pan_status": "inoperative" } } }, "200 Invalid PAN": { "summary": "200 Invalid PAN", "value": { "code": 200, "timestamp": 1763362637000, "transaction_id": "e2b9145f-69d5-4bbe-a6de-be6fc08b426f", "data": { "@entity": "in.co.sandbox.tds.compliance.206ab_check.response", "message": "Invalid PAN" } } } } } }, "headers": {} }, "422": { "description": "422 - Unprocessable Entity", "content": { "application/json": { "schema": { "type": "object", "properties": { "code": { "type": "integer" }, "timestamp": { "type": "integer" }, "transaction_id": { "type": "string" }, "message": { "type": "string" } } }, "examples": { "422 Invalid PAN pattern": { "summary": "422 Invalid PAN pattern", "value": { "code": 422, "timestamp": 1687348772740, "transaction_id": "780b2332-d96e-4ef5-b7bc-d7b40e59fa9e", "message": "Invalid Pan pattern" } } } } }, "headers": {} } }, "security": [] } }, "/tds/compliance/csi/otp": { "post": { "summary": "Generate OTP", "deprecated": false, "description": "", "tags": [ "Download CSI" ], "parameters": [ { "name": "authorization", "in": "header", "description": "JWT access token", "required": true, "example": "{{access_token}}", "schema": { "type": "string" } }, { "name": "x-api-key", "in": "header", "description": "API key for identification", "required": true, "example": "{{api_key}}", "schema": { "type": "string" } }, { "name": "x-api-version", "in": "header", "description": "", "required": false, "example": "", "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "@entity": { "type": "string", "enum": [ "in.co.sandbox.tds.compliance.deductors.otp.request" ] }, "tan": { "description": "TAN of deductor/collector. Regular Expression: [A-Z]{4}[0-9]{5}[A-Z]{1}", "pattern": "[A-Z]{4}[0-9]{5}[A-Z]{1}", "type": "string" }, "mobile_number": { "description": "Mobile Number to send the OTP. Pattern: [1-9]{1}[0-9]{9}", "pattern": "[1-9]{1}[0-9]{9}", "type": "string" }, "from": { "description": "Date from which challan details are to be fetched. Value in EPOCH timestamp", "type": "integer" }, "to": { "description": "Date till which challan details are to be fetched. Value in EPOCH timestamp", "type": "integer" }, "consent": { "description": "Consent of the end-user to get their information. Possible values: Y or y", "type": "string" }, "reason": { "description": "Indicate the purpose. Min length: 20 characters", "type": "string" } }, "required": [ "@entity", "tan", "mobile_number", "from", "to", "consent", "reason" ] }, "examples": { "200 - Success": { "value": { "@entity": "in.co.sandbox.tds.compliance.deductors.otp.request", "tan": "AHMA09719B", "mobile_number": "1234567890", "from": 1722450600000, "to": 1730313000000, "consent": "Y", "reason": "TDS Return" }, "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": "TDS Return" }, "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": "TDS Return" }, "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": "TDS Return" }, "summary": "422 - Unprocessable Entity" } } } } }, "responses": { "200": { "description": "200 - OK", "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" }, "message": { "type": "string" } } }, "code": { "type": "integer" } } }, "examples": { "200 - Success": { "summary": "200 - Success", "value": { "timestamp": 1731669661517, "transaction_id": "166148b8-25e3-4ef2-b052-5a27098ebb0e", "data": { "@entity": "in.co.sandbox.tds.compliance.deductors.otp.response", "tan": "AHMA09719B", "mobile_number": "1234567890", "from": 1722450600000, "to": 1730313000000, "reference_id": "FOS005981930273", "message": "OTP sent successfully" }, "code": 200 } }, "200 Invalid TAN": { "summary": "200 Invalid TAN", "value": { "code": 200, "timestamp": 1763362637000, "transaction_id": "e2b9145f-69d5-4bbe-a6de-be6fc08b426f", "data": { "@entity": "in.co.sandbox.tds.compliance.deductors.csi.response", "message": "Invalid TAN" } } }, "200 OTP already generated": { "summary": "200 OTP already generated", "value": { "code": 200, "timestamp": 1763362637000, "transaction_id": "e2b9145f-69d5-4bbe-a6de-be6fc08b426f", "data": { "@entity": "in.co.sandbox.tds.compliance.deductors.csi.response", "message": "OTP generated for this TAN, please try after 30 seconds" } } } } } }, "headers": {} }, "422": { "description": "422 - Unprocessable Entity", "content": { "application/json": { "schema": { "type": "object", "properties": { "code": { "type": "integer" }, "timestamp": { "type": "integer" }, "transaction_id": { "type": "string" }, "message": { "type": "string" } } }, "examples": { "422 - Unprocessable Entity": { "summary": "422 - Unprocessable Entity", "value": { "code": 422, "timestamp": 1763362637000, "transaction_id": "e2b9145f-69d5-4bbe-a6de-be6fc08b426f", "message": "Invalid TAN pattern" } } } } }, "headers": {} } }, "security": [] } }, "/tds/compliance/csi/otp/verify": { "post": { "summary": "Verify OTP", "deprecated": false, "description": "", "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" }, "otp": { "type": "string" } }, "required": [ "@entity", "reference_id", "otp" ] }, "examples": { "200 - Success": { "value": { "@entity": "in.co.sandbox.tds.compliance.deductors.csi.request", "reference_id": "FOS005981930273", "otp": "834201" }, "summary": "200 - Success" }, "200 Invalid OTP": { "value": { "@entity": "in.co.sandbox.tds.compliance.deductors.csi.request", "reference_id": "FOS101212121212121", "otp": "121212" }, "summary": "200 Invalid OTP" }, "200 OTP Expired": { "value": { "@entity": "in.co.sandbox.tds.compliance.deductors.csi.request", "reference_id": "FOS101212121212121", "otp": "121212" }, "summary": "200 OTP Expired" } } } } }, "responses": { "200": { "description": "200 - OK", "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" }, "csi_url": { "type": "string" } } }, "code": { "type": "integer" } } }, "examples": { "200 - Success": { "summary": "200 - Success", "value": { "timestamp": 1731669721578, "transaction_id": "8a0c097f-8e6d-4c11-8228-87d3c8cc44ce", "data": { "@entity": "in.co.sandbox.tds.compliance.deductors.csi.response", "tan": "AHMA09719B", "from": 1722450600000, "to": 1730313000000, "reference_id": "FOS005981930273", "csi_url": ".." }, "code": 200 } }, "200 Invalid OTP": { "summary": "200 Invalid OTP", "value": { "code": 200, "timestamp": 1763362637000, "transaction_id": "e2b9145f-69d5-4bbe-a6de-be6fc08b426f", "data": { "@entity": "in.co.sandbox.tds.compliance.deductors.csi", "message": "The OTP you have entered is incorrect." } } }, "200 OTP Expired": { "summary": "200 OTP Expired", "value": { "code": 200, "timestamp": 1763362637000, "transaction_id": "e2b9145f-69d5-4bbe-a6de-be6fc08b426f", "data": { "@entity": "in.co.sandbox.tds.compliance.deductors.csi", "message": "OTP expired" } } } } } }, "headers": {} } }, "security": [] } }, "/tds/compliance/fvu/generate": { "post": { "summary": "Create FVU Generation Job", "deprecated": false, "description": "", "tags": [ "FVU Generation" ], "parameters": [ { "name": "authorization", "in": "header", "description": "JWT authorization token", "required": true, "example": "", "schema": { "type": "string" } }, { "name": "x-api-key", "in": "header", "description": "Public key required to authorize API access.", "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.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" ] }, "examples": { "200 - Success": { "value": { "@entity": "in.co.sandbox.tds.compliance.fvu.generate.request", "tax_year": "TY 2026-27", "form": "138", "quarter": "Q3", "tan": "AHMA09719B", "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" }, "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" }, "csi_file_upload_url": { "type": "string", "format": "uri" } } } } }, "examples": { "200 - Success": { "summary": "200 - Success", "value": { "code": 200, "timestamp": 1763362637000, "transaction_id": "e2b9145f-69d5-4bbe-a6de-be6fc08b426f", "data": { "@entity": "in.co.sandbox.tds.compliance.fvu.generate.job", "job_id": "4ef92975-aea8-4628-9eaa-18eb439c13d9", "tan": "AHMA09719B", "tax_year": "TY 2026-27", "quarter": "Q3", "form": "138", "filing_type": "regular", "status": "created", "created_at": 1763362637000, "txt_file_upload_url": "https://in-co-sandbox-tds-test-storage.s3.ap-south-1.amazonaws.com/upload/file", "csi_file_upload_url": "https://in-co-sandbox-tds-test-storage.s3.ap-south-1.amazonaws.com/upload/file" } } }, "200 Job created for Correction return": { "summary": "200 Job created for Correction return", "value": { "code": 200, "timestamp": 1763362637000, "transaction_id": "e2b9145f-69d5-4bbe-a6de-be6fc08b426f", "data": { "@entity": "in.co.sandbox.tds.compliance.fvu.generate.job", "job_id": "f845f37e-7f05-4de9-a282-a3b23b9d370a", "tan": "AHMA09719B", "tax_year": "TY 2026-27", "quarter": "Q4", "form": "138", "filing_type": "correction", "status": "created", "created_at": 1763362637000, "txt_file_upload_url": "https://in-co-sandbox-tds-test-storage.s3.ap-south-1.amazonaws.com/upload/file", "csi_file_upload_url": "https://in-co-sandbox-tds-test-storage.s3.ap-south-1.amazonaws.com/upload/file", "conso_file_upload_url": "https://in-co-sandbox-tds-test-storage.s3.ap-south-1.amazonaws.com/upload/file" } } } } } }, "headers": {} } }, "security": [] }, "get": { "summary": "Fetch FVU Generation Status", "deprecated": false, "description": "", "tags": [ "FVU Generation" ], "parameters": [ { "name": "job_id", "in": "query", "description": "Unique identifier of a job", "required": false, "example": "4ef92975-aea8-4628-9eaa-18eb439c13d9", "schema": {} }, { "name": "authorization", "in": "header", "description": "JWT authorization token", "required": true, "example": "", "schema": { "type": "string" } }, { "name": "x-api-key", "in": "header", "description": "Public key required to authorize API access.", "required": true, "example": "", "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" }, "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" } } } } }, { "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" }, "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" } } } } }, { "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" }, "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" } } } } } ] }, "examples": { "200 - Job Success": { "summary": "200 - Job Success", "value": { "code": 200, "timestamp": 1763362637000, "transaction_id": "e2b9145f-69d5-4bbe-a6de-be6fc08b426f", "data": { "@entity": "in.co.sandbox.tds.compliance.fvu.generate.job", "job_id": "4ef92975-aea8-4628-9eaa-18eb439c13d9", "tan": "AHMA09719B", "tax_year": "TY 2026-27", "quarter": "Q3", "form": "138", "filing_type": "regular", "status": "succeeded", "created_at": 1763362637000, "updated_at": 1763362637000, "fvu_zip_file_url": "https://in-co-sandbox-tds-test-storage.s3.ap-south-1.amazonaws.com/AHMS45586C/FY+2025-26/Q3/140/4049c226-4988-4978-b5ad-d25705453da8/140.zip" } } }, "200 Job succeeded for Correction return": { "summary": "200 Job succeeded for Correction return", "value": { "code": 200, "timestamp": 1763362637000, "transaction_id": "e2b9145f-69d5-4bbe-a6de-be6fc08b426f", "data": { "@entity": "in.co.sandbox.tds.compliance.fvu.generate.job", "job_id": "445731fc-f785-4672-989a-6d332149e06f", "tan": "AHMA09719B", "tax_year": "TY 2026-27", "quarter": "Q3", "form": "138", "filing_type": "correction", "status": "succeeded", "created_at": 1763362637000, "updated_at": 1763362637000, "fvu_zip_file_url": "https://in-co-sandbox-tds-compliance-fvu-test.s3.ap-south-1.amazonaws.com/tan/tax_year/quarter/form/f845f37e-7f05-4de9-a282-a3b23b9d370a.zip" } } }, "200 - Job Failed": { "summary": "200 - Job Failed", "value": { "code": 200, "timestamp": 1763362637000, "transaction_id": "e2b9145f-69d5-4bbe-a6de-be6fc08b426f", "data": { "@entity": "in.co.sandbox.tds.compliance.fvu.generate.job", "job_id": "7a9176ef-1e59-4b8e-a1de-ee15b09963f8", "tan": "AHMA09719B", "tax_year": "TY 2026-27", "quarter": "Q3", "form": "138", "filing_type": "regular", "status": "failed", "created_at": 1763362637000, "updated_at": 1763362637000, "validation_report_file_url": "https://in-co-sandbox-cms-prod1.s3.ap-south-1.amazonaws.com/test-api-mock/tds/json.json" } } }, "200 Job Queued": { "summary": "200 Job Queued", "value": { "code": 200, "timestamp": 1763362637000, "transaction_id": "e2b9145f-69d5-4bbe-a6de-be6fc08b426f", "data": { "@entity": "in.co.sandbox.tds.compliance.fvu.generate.job", "job_id": "db544879-a592-466f-a948-83b5a11cd52d", "tan": "AHMA09719B", "tax_year": "TY 2026-27", "quarter": "Q3", "form": "138", "filing_type": "regular", "status": "queued", "created_at": 1763362637000, "updated_at": 1763362637000 } } }, "200 Job created": { "summary": "200 Job created", "value": { "code": 200, "timestamp": 1763362637000, "transaction_id": "e2b9145f-69d5-4bbe-a6de-be6fc08b426f", "data": { "@entity": "in.co.sandbox.tds.compliance.fvu.generate.job", "job_id": "a88ce705-e16f-4a44-9b56-273bfbc039d5", "tan": "AHMA09719B", "tax_year": "TY 2026-27", "quarter": "Q3", "form": "138", "filing_type": "regular", "status": "created", "created_at": 1763362637000 } } } } } }, "headers": {} }, "521": { "description": "521 - Data Not Found", "content": { "application/json": { "schema": { "type": "object", "properties": { "code": { "type": "integer" }, "timestamp": { "type": "integer" }, "transaction_id": { "type": "string" }, "message": { "type": "string" } } }, "examples": { "521 Data not found": { "summary": "521 Data not found", "value": { "code": 521, "timestamp": 1763362637000, "transaction_id": "e2b9145f-69d5-4bbe-a6de-be6fc08b426f", "message": "Data not found" } } } } }, "headers": {} } }, "security": [] } }, "/tds/compliance/fvu/generate/search": { "post": { "summary": "Search FVU Generation Job", "deprecated": false, "description": "", "tags": [ "FVU Generation" ], "parameters": [ { "name": "authorization", "in": "header", "description": "JWT authorization token", "required": true, "example": "", "schema": { "type": "string" } }, { "name": "x-api-key", "in": "header", "description": "Public key required to authorize API access.", "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.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": "Date from which jobs are to be fetched. Value in EPOCH timestamp", "type": "integer" }, "to_date": { "description": "Date till which jobs are to be fetched. Value in EPOCH timestamp", "type": "integer" }, "page_size": { "description": "Number of records in the API response. Maximum allowed size is 50", "type": "integer" }, "last_evaluated_key": { "description": "Base64 encoding of the stringified JSON object, which includes x-api-key, created_at, and job_id", "type": "string" } }, "required": [ "@entity" ] }, "examples": { "200 job success": { "value": { "@entity": "in.co.sandbox.tds.compliance.fvu.generate.search" }, "summary": "200 job success" } } } } }, "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" }, "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" } } } } } }, "transaction_id": { "type": "string" } } }, "examples": { "200 job success": { "summary": "200 job success", "value": { "code": 200, "timestamp": 1763035746825, "data": { "@entity": "in.co.sandbox.tds.compliance.fvu.generate.paginated_list", "items": [ { "created_at": 1762511623903, "@entity": "in.co.sandbox.tds.compliance.fvu.generate.job", "job_id": "6622b26a-9601-4692-9c9c-a9b3a1ff8a6e", "tan": "AHMA44270C", "tax_year": "TY 2026-27", "quarter": "Q3", "form": "140", "filing_type": "regular", "status": "created" }, { "created_at": 1762238825579, "@entity": "in.co.sandbox.tds.compliance.fvu.generate.job", "job_id": "c4894d31-c59d-4955-b5a8-5c124e3e8072", "tan": "AHMA00000C", "tax_year": "TY 2026-27", "quarter": "Q2", "form": "140", "filing_type": "regular", "status": "created" }, { "created_at": 1762238798138, "@entity": "in.co.sandbox.tds.compliance.fvu.generate.job", "job_id": "83526ecf-9401-4472-9894-0dded05a5b2d", "tan": "AHMA00000C", "tax_year": "TY 2026-27", "quarter": "Q2", "form": "140", "filing_type": "regular", "status": "created" }, { "created_at": 1761819084423, "updated_at": 1761819130863, "@entity": "in.co.sandbox.tds.compliance.fvu.generate.job", "job_id": "6f006f8d-7680-47de-8982-950a6bba48c2", "tan": "AHMQ00112A", "tax_year": "TY 2026-27", "quarter": "Q2", "form": "140", "filing_type": "regular", "status": "succeeded" }, { "created_at": 1761818231823, "updated_at": 1761818280529, "@entity": "in.co.sandbox.tds.compliance.fvu.generate.job", "job_id": "98e92413-b1a1-4f15-9efc-84f0b617dd64", "tan": "AHMQ00112A", "tax_year": "TY 2026-27", "quarter": "Q2", "form": "140", "filing_type": "regular", "status": "failed" }, { "created_at": 1761738587585, "updated_at": 1761738622697, "@entity": "in.co.sandbox.tds.compliance.fvu.generate.job", "job_id": "183a31e4-fdc4-437b-8054-f87121af6dcc", "tan": "AHMQ00112A", "tax_year": "TY 2026-27", "quarter": "Q2", "form": "138", "filing_type": "regular", "status": "succeeded" }, { "created_at": 1761738584006, "@entity": "in.co.sandbox.tds.compliance.fvu.generate.job", "job_id": "e5142096-8182-46e7-8e19-b12159f8c965", "tan": "AHMQ00112A", "tax_year": "TY 2026-27", "quarter": "Q2", "form": "138", "filing_type": "regular", "status": "created" }, { "created_at": 1761737173402, "updated_at": 1761737219289, "@entity": "in.co.sandbox.tds.compliance.fvu.generate.job", "job_id": "1c8fce43-401e-4876-a78d-1043f81a7954", "tan": "AHMQ00112A", "tax_year": "TY 2026-27", "quarter": "Q2", "form": "138", "filing_type": "regular", "message": "Form mismatch", "status": "failed" }, { "created_at": 1761732724431, "updated_at": 1761732773453, "@entity": "in.co.sandbox.tds.compliance.fvu.generate.job", "job_id": "5c7dfb7d-7915-42e2-b0d5-7aa93449a648", "tan": "AHMS45586C", "tax_year": "TY 2026-27", "quarter": "Q2", "form": "140", "filing_type": "regular", "status": "succeeded" }, { "created_at": 1761659003619, "updated_at": 1761659086073, "@entity": "in.co.sandbox.tds.compliance.fvu.generate.job", "job_id": "2c35a44b-e61b-4a70-9a92-079354710133", "tan": "AHMS45586C", "tax_year": "TY 2026-27", "quarter": "Q2", "form": "138", "filing_type": "regular", "status": "succeeded" }, { "created_at": 1761634299914, "updated_at": 1761634345747, "@entity": "in.co.sandbox.tds.compliance.fvu.generate.job", "job_id": "56625794-b1a9-4d7d-a26d-7fcbd18632a7", "tan": "BLRR32170F", "tax_year": "TY 2026-27", "quarter": "Q2", "form": "144", "filing_type": "regular", "status": "succeeded" }, { "created_at": 1761571384235, "updated_at": 1761571434955, "@entity": "in.co.sandbox.tds.compliance.fvu.generate.job", "job_id": "e4f848a0-5bb6-448b-ba69-250a38455517", "tan": "DELG20840B", "tax_year": "TY 2026-27", "quarter": "Q2", "form": "144", "filing_type": "regular", "status": "succeeded" }, { "created_at": 1761570981608, "updated_at": 1761571018207, "@entity": "in.co.sandbox.tds.compliance.fvu.generate.job", "job_id": "6fe7be04-96db-4b18-90c3-0a8ea7692225", "tan": "DELG20840B", "tax_year": "TY 2026-27", "quarter": "Q2", "form": "144", "filing_type": "regular", "status": "failed" }, { "created_at": 1761557897110, "updated_at": 1761557936792, "@entity": "in.co.sandbox.tds.compliance.fvu.generate.job", "job_id": "d281be50-92c7-4b53-ac9f-1b4e61b20dbf", "tan": "BLRV26339F", "tax_year": "TY 2026-27", "quarter": "Q2", "form": "144", "filing_type": "regular", "status": "succeeded" }, { "created_at": 1761551312937, "updated_at": 1761551348037, "@entity": "in.co.sandbox.tds.compliance.fvu.generate.job", "job_id": "9b2349d4-a754-4fab-8e7f-320849436709", "tan": "MUMK37337G", "tax_year": "TY 2026-27", "quarter": "Q2", "form": "144", "filing_type": "regular", "status": "succeeded" }, { "created_at": 1760539426714, "updated_at": 1760539477220, "@entity": "in.co.sandbox.tds.compliance.fvu.generate.job", "job_id": "410c3dfb-86b1-4f17-bf5e-537485be3979", "tan": "MRTA26471E", "tax_year": "TY 2026-27", "quarter": "Q2", "form": "144", "filing_type": "regular", "status": "succeeded" }, { "created_at": 1760015060012, "updated_at": 1760015230331, "@entity": "in.co.sandbox.tds.compliance.fvu.generate.job", "job_id": "5264a512-fba0-408d-8c22-3b1e876248d3", "tan": "MUMP51255B", "tax_year": "TY 2026-27", "quarter": "Q2", "form": "144", "filing_type": "regular", "status": "succeeded" } ] }, "transaction_id": "c93b4b70-67e8-4853-9dd4-15d3ef50c5b2" } } } } }, "headers": {} } }, "security": [] } }, "/tds/compliance/e-file": { "post": { "summary": "Create TDS Return Filing Job", "deprecated": false, "description": "", "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": "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" ] }, "examples": { "200 Job created": { "value": { "@entity": "in.co.sandbox.tds.compliance.e-file.request", "tax_year": "TY 2026-27", "form": "138", "quarter": "Q2", "tan": "AHMA09719B" }, "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" }, "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" } } } } }, "examples": { "200 Job created": { "summary": "200 Job created", "value": { "code": 200, "timestamp": 1763362637000, "transaction_id": "e2b9145f-69d5-4bbe-a6de-be6fc08b426f", "data": { "@entity": "in.co.sandbox.tds.compliance.e-file.job", "job_id": "f845f37e-7f05-4de9-a282-a3b23b9d370a", "tan": "AHMA09719B", "tax_year": "TY 2026-27", "quarter": "Q2", "form": "138", "status": "created", "created_at": 1763362637000, "fvu_upload_file_url": "https://in-co-sandbox-tds-test-storage.s3.ap-south-1.amazonaws.com/upload/file" } } }, "200 Job created: Statement furnished": { "summary": "200 Job created: Statement furnished", "value": { "code": 200, "timestamp": 1763362637000, "transaction_id": "e2b9145f-69d5-4bbe-a6de-be6fc08b426f", "data": { "@entity": "in.co.sandbox.tds.compliance.e-file.job", "job_id": "6e8d1908-c062-4846-a811-8f73054acd65", "tan": "MUMR09719B", "tax_year": "TY 2026-27", "quarter": "Q2", "form": "140", "status": "created", "created_at": 1763362637000, "fvu_upload_file_url": "https://in-co-sandbox-tds-test-storage.s3.ap-south-1.amazonaws.com/upload/file" } } }, "200 Job created: Unacceptable fvu": { "summary": "200 Job created: Unacceptable fvu", "value": { "code": 200, "timestamp": 1763362637000, "transaction_id": "e2b9145f-69d5-4bbe-a6de-be6fc08b426f", "data": { "@entity": "in.co.sandbox.tds.compliance.e-file.job", "job_id": "d75c3d26-4f81-451f-ab38-e217ea801ea1", "tan": "AABC23456D", "tax_year": "TY 2026-27", "quarter": "Q2", "form": "144", "status": "created", "created_at": 1763362637000, "fvu_upload_file_url": "https://in-co-sandbox-tds-test-storage.s3.ap-south-1.amazonaws.com/upload/file" } } }, "200 Job created: invalid archive": { "summary": "200 Job created: invalid archive", "value": { "code": 200, "timestamp": 1763362637000, "transaction_id": "e2b9145f-69d5-4bbe-a6de-be6fc08b426f", "data": { "@entity": "in.co.sandbox.tds.compliance.e-file.job", "job_id": "d1213059-ec22-4e10-b0c1-a91814377001", "tan": "PDES03028E", "tax_year": "TY 2026-27", "quarter": "Q4", "form": "140", "status": "created", "created_at": 1763362637000, "fvu_upload_file_url": "https://in-co-sandbox-tds-test-storage.s3.ap-south-1.amazonaws.com/upload/file" } } }, "200 Job created: Form type mismatch": { "summary": "200 Job created: Form type mismatch", "value": { "code": 200, "timestamp": 1763362637000, "transaction_id": "e2b9145f-69d5-4bbe-a6de-be6fc08b426f", "data": { "@entity": "in.co.sandbox.tds.compliance.e-file.job", "job_id": "d6f5b340-440b-400c-9b86-16e691e768b0", "tan": "HYDC23456G", "tax_year": "TY 2026-27", "quarter": "Q4", "form": "138", "status": "created", "created_at": 1763362637000, "fvu_upload_file_url": "https://in-co-sandbox-tds-test-storage.s3.ap-south-1.amazonaws.com/upload/file" } } }, "200 Job created: Quarter mismatch": { "summary": "200 Job created: Quarter mismatch", "value": { "code": 200, "timestamp": 1763362637000, "transaction_id": "e2b9145f-69d5-4bbe-a6de-be6fc08b426f", "data": { "@entity": "in.co.sandbox.tds.compliance.e-file.job", "job_id": "7a62876a-d638-430c-ad77-8fe33d9e63d5", "tan": "MUMC23456H", "tax_year": "TY 2026-27", "quarter": "Q2", "form": "140", "status": "created", "created_at": 1763362637000, "fvu_upload_file_url": "https://in-co-sandbox-tds-test-storage.s3.ap-south-1.amazonaws.com/upload/file" } } }, "200 Job created: Barcode mismatch": { "summary": "200 Job created: Barcode mismatch", "value": { "code": 200, "timestamp": 1763362637000, "transaction_id": "e2b9145f-69d5-4bbe-a6de-be6fc08b426f", "data": { "@entity": "in.co.sandbox.tds.compliance.e-file.job", "job_id": "6b11d176-b3c5-483c-9052-b533a6e92377", "tan": "DELC23456I", "tax_year": "TY 2026-27", "quarter": "Q3", "form": "144", "status": "created", "created_at": 1763362637000, "fvu_upload_file_url": "https://in-co-sandbox-tds-test-storage.s3.ap-south-1.amazonaws.com/upload/file" } } }, "200 Job created: Invalid entries": { "summary": "200 Job created: Invalid entries", "value": { "code": 200, "timestamp": 1763362637000, "transaction_id": "e2b9145f-69d5-4bbe-a6de-be6fc08b426f", "data": { "@entity": "in.co.sandbox.tds.compliance.e-file.job", "job_id": "3b979ce9-ef4e-4157-a4a3-51e8747e76d7", "tan": "BLRC23456F", "tax_year": "TY 2026-27", "quarter": "Q2", "form": "140", "status": "created", "created_at": 1763362637000, "fvu_upload_file_url": "https://in-co-sandbox-tds-test-storage.s3.ap-south-1.amazonaws.com/upload/file" } } }, "200 Job created: Tax year mismatch": { "summary": "200 Job created: Tax year mismatch", "value": { "code": 200, "timestamp": 1763362637000, "transaction_id": "e2b9145f-69d5-4bbe-a6de-be6fc08b426f", "data": { "@entity": "in.co.sandbox.tds.compliance.e-file.job", "job_id": "7928082e-34ca-474c-ba05-4ede9598b9b5", "tan": "PUNC23456J", "tax_year": "TY 2026-27", "quarter": "Q4", "form": "140", "status": "created", "created_at": 1763362637000, "fvu_upload_file_url": "https://in-co-sandbox-tds-test-storage.s3.ap-south-1.amazonaws.com/upload/file" } } }, "200 Job created: TAN mismatch": { "summary": "200 Job created: TAN mismatch", "value": { "code": 200, "timestamp": 1763362637000, "transaction_id": "e2b9145f-69d5-4bbe-a6de-be6fc08b426f", "data": { "@entity": "in.co.sandbox.tds.compliance.e-file.job", "job_id": "5fd2679f-040f-435c-a285-df5817a150b5", "tan": "KOLT23456K", "tax_year": "TY 2026-27", "quarter": "Q2", "form": "140", "status": "created", "created_at": 1763362637000, "fvu_upload_file_url": "https://in-co-sandbox-tds-test-storage.s3.ap-south-1.amazonaws.com/upload/file" } } }, "200 Job created: Form27A missing": { "summary": "200 Job created: Form27A missing", "value": { "code": 200, "timestamp": 1763362637000, "transaction_id": "e2b9145f-69d5-4bbe-a6de-be6fc08b426f", "data": { "@entity": "in.co.sandbox.tds.compliance.e-file.job", "job_id": "b411fbee-68e4-4da3-9f62-8de8ca09a74c", "tan": "CABC23456M", "tax_year": "TY 2026-27", "quarter": "Q3", "form": "140", "status": "created", "created_at": 1763362637000, "fvu_upload_file_url": "https://in-co-sandbox-tds-test-storage.s3.ap-south-1.amazonaws.com/upload/file" } } }, "200 Job created: FVU missing": { "summary": "200 Job created: FVU missing", "value": { "code": 200, "timestamp": 1763362637000, "transaction_id": "e2b9145f-69d5-4bbe-a6de-be6fc08b426f", "data": { "@entity": "in.co.sandbox.tds.compliance.e-file.job", "job_id": "9bf0b6f8-5957-484f-9aea-0d235054974c", "tan": "BABC23456L", "tax_year": "TY 2026-27", "quarter": "Q1", "form": "140", "status": "created", "created_at": 1763362637000, "fvu_upload_file_url": "https://in-co-sandbox-tds-test-storage.s3.ap-south-1.amazonaws.com/upload/file" } } }, "test csi file": { "summary": "test csi file", "value": "csi mock data" } } } }, "headers": {} } }, "security": [] }, "get": { "summary": "Fetch TDS Return Job Status", "deprecated": false, "description": "", "tags": [ "E-File TDS Return" ], "parameters": [ { "name": "job_id", "in": "query", "description": "Unique identifier of the job", "required": true, "example": "f845f37e-7f05-4de9-a282-a3b23b9d370a", "schema": { "type": "string" } }, { "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" } } ], "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" }, "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" } } } } }, { "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" }, "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" }, "fvu_file_url": { "type": "string", "format": "uri" }, "form27a_file_url": { "type": "string", "format": "uri" } } } } }, { "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" }, "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" }, "created_at": { "type": "integer" }, "updated_at": { "type": "integer" } } } } } ] }, "examples": { "200 Job Succeeded": { "summary": "200 Job Succeeded", "value": { "code": 200, "timestamp": 1763362637000, "transaction_id": "e2b9145f-69d5-4bbe-a6de-be6fc08b426f", "data": { "@entity": "in.co.sandbox.tds.compliance.e-file.job", "job_id": "f845f37e-7f05-4de9-a282-a3b23b9d370a", "tan": "AHMA09719B", "tax_year": "TY 2026-27", "quarter": "Q2", "form": "140", "filing_type": "regular", "status": "succeeded", "receipt_number": 123456789012345, "created_at": 1763362637000, "updated_at": 1763362637000, "receipt_file_url": "https://in-co-sandbox-tds-test-storage.s3.ap-south-1.amazonaws.com/AHMS45586C/FY+2025-26/Q3/140/4049c226-4988-4978-b5ad-d25705453da8/receipt.pdf", "fvu_file_url": "https://in-co-sandbox-tds-test-storage.s3.ap-south-1.amazonaws.com/AHMS45586C/FY+2025-26/Q3/140/4049c226-4988-4978-b5ad-d25705453da8/140.fvu", "form27a_file_url": "https://in-co-sandbox-tds-test-storage.s3.ap-south-1.amazonaws.com/AHMS45586C/FY+2025-26/Q3/140/4049c226-4988-4978-b5ad-d25705453da8/form27A_140.pdf" } } }, "200 Job Queued": { "summary": "200 Job Queued", "value": { "code": 200, "timestamp": 1763362637000, "transaction_id": "e2b9145f-69d5-4bbe-a6de-be6fc08b426f", "data": { "@entity": "in.co.sandbox.tds.compliance.e-file.job", "job_id": "2aa54d2b-68f6-4871-866a-4eba957a8672", "tan": "AHMA09719B", "tax_year": "TY 2026-27", "quarter": "Q2", "form": "140", "filing_type": "original", "status": "queued", "created_at": 1763362637000, "updated_at": 1763362637000 } } }, "200 Job Failed: Statement furnished": { "summary": "200 Job Failed: Statement furnished", "value": { "code": 200, "timestamp": 1763362637000, "transaction_id": "e2b9145f-69d5-4bbe-a6de-be6fc08b426f", "data": { "@entity": "in.co.sandbox.tds.compliance.e-file.job", "job_id": "6e8d1908-c062-4846-a811-8f73054acd65", "tan": "MUMR09719B", "tax_year": "TY 2026-27", "quarter": "Q2", "form": "140", "filing_type": "original", "status": "failed", "message": "Regular Statement with the same TAN, Tax Year, FORM and Quarter is already furnished", "created_at": 1763362637000, "updated_at": 1763362637000 } } }, "200 Job Failed: Unacceptable fvu": { "summary": "200 Job Failed: Unacceptable fvu", "value": { "code": 200, "timestamp": 1763362637000, "transaction_id": "e2b9145f-69d5-4bbe-a6de-be6fc08b426f", "data": { "@entity": "in.co.sandbox.tds.compliance.e-file.job", "job_id": "d75c3d26-4f81-451f-ab38-e217ea801ea1", "tan": "AABC23456D", "tax_year": "TY 2026-27", "quarter": "Q2", "form": "144", "filing_type": "original", "status": "failed", "message": "Unacceptable FVU", "created_at": 1763362637000, "updated_at": 1763362637000 } } }, "200 Job Failed: Invalid archive": { "summary": "200 Job Failed: Invalid archive", "value": { "code": 200, "timestamp": 1763362637000, "transaction_id": "e2b9145f-69d5-4bbe-a6de-be6fc08b426f", "data": { "@entity": "in.co.sandbox.tds.compliance.e-file.job", "job_id": "d1213059-ec22-4e10-b0c1-a91814377001", "tan": "PDES03028E", "tax_year": "TY 2026-27", "quarter": "Q4", "form": "140", "filing_type": "original", "status": "failed", "message": "Invalid Archive", "created_at": 1763362637000, "updated_at": 1763362637000 } } }, "200 Job Failed: Form type mismatch": { "summary": "200 Job Failed: Form type mismatch", "value": { "code": 200, "timestamp": 1763362637000, "transaction_id": "e2b9145f-69d5-4bbe-a6de-be6fc08b426f", "data": { "@entity": "in.co.sandbox.tds.compliance.e-file.job", "job_id": "d6f5b340-440b-400c-9b86-16e691e768b0", "tan": "HYDC23456G", "tax_year": "TY 2026-27", "quarter": "Q4", "form": "138", "filing_type": "original", "status": "failed", "message": "Form Type Mismatch", "created_at": 1763362637000, "updated_at": 1763362637000 } } }, "200 Job Failed: Quarter mismatch": { "summary": "200 Job Failed: Quarter mismatch", "value": { "code": 200, "timestamp": 1763362637000, "transaction_id": "e2b9145f-69d5-4bbe-a6de-be6fc08b426f", "data": { "@entity": "in.co.sandbox.tds.compliance.e-file.job", "job_id": "7a62876a-d638-430c-ad77-8fe33d9e63d5", "tan": "MUMC23456H", "tax_year": "TY 2026-27", "quarter": "Q2", "form": "140", "filing_type": "original", "status": "failed", "message": "Quarter mismatch", "created_at": 1763362637000, "updated_at": 1763362637000 } } }, "200 Job Failed: Barcode mismatch": { "summary": "200 Job Failed: Barcode mismatch", "value": { "code": 200, "timestamp": 1763362637000, "transaction_id": "e2b9145f-69d5-4bbe-a6de-be6fc08b426f", "data": { "@entity": "in.co.sandbox.tds.compliance.e-file.job", "job_id": "6b11d176-b3c5-483c-9052-b533a6e92377", "tan": "DELC23456I", "tax_year": "TY 2026-27", "quarter": "Q3", "form": "144", "filing_type": "original", "status": "failed", "message": "Barcode mismatch", "created_at": 1763362637000, "updated_at": 1763362637000 } } }, "200 Job Failed: Invalid number of entries in archive": { "summary": "200 Job Failed: Invalid number of entries in archive", "value": { "code": 200, "timestamp": 1763362637000, "transaction_id": "e2b9145f-69d5-4bbe-a6de-be6fc08b426f", "data": { "@entity": "in.co.sandbox.tds.compliance.e-file.job", "job_id": "3b979ce9-ef4e-4157-a4a3-51e8747e76d7", "tan": "BLRC23456F", "tax_year": "TY 2026-27", "quarter": "Q2", "form": "140", "filing_type": "original", "status": "failed", "message": "Invalid Number of entries in Archive: 1", "created_at": 1763362637000, "updated_at": 1763362637000 } } }, "200 Job Failed: Tax year mismatch": { "summary": "200 Job Failed: Tax year mismatch", "value": { "code": 200, "timestamp": 1763362637000, "transaction_id": "e2b9145f-69d5-4bbe-a6de-be6fc08b426f", "data": { "@entity": "in.co.sandbox.tds.compliance.e-file.job", "job_id": "7928082e-34ca-474c-ba05-4ede9598b9b5", "tan": "PUNC23456J", "tax_year": "TY 2026-27", "form": "138", "quarter": "Q4", "filing_type": "original", "status": "failed", "message": "Tax year mismatch", "created_at": 1763362637000, "updated_at": 1763362637000 } } }, "200 Job Failed: TAN mismatch": { "summary": "200 Job Failed: TAN mismatch", "value": { "code": 200, "timestamp": 1763362637000, "transaction_id": "e2b9145f-69d5-4bbe-a6de-be6fc08b426f", "data": { "@entity": "in.co.sandbox.tds.compliance.e-file.job", "job_id": "5fd2679f-040f-435c-a285-df5817a150b5", "tan": "KOLT23456K", "tax_year": "TY 2026-27", "quarter": "Q2", "form": "140", "filing_type": "original", "status": "failed", "message": "TAN mismatch", "created_at": 1763362637000, "updated_at": 1763362637000 } } }, "200 Job Failed: Form27A missing": { "summary": "200 Job Failed: Form27A missing", "value": { "code": 200, "timestamp": 1763362637000, "transaction_id": "e2b9145f-69d5-4bbe-a6de-be6fc08b426f", "data": { "@entity": "in.co.sandbox.tds.compliance.e-file.job", "job_id": "b411fbee-68e4-4da3-9f62-8de8ca09a74c", "tan": "CABC23456M", "tax_year": "TY 2026-27", "quarter": "Q3", "form": "140", "filing_type": "original", "status": "failed", "message": "Form 27A missing", "created_at": 1763362637000, "updated_at": 1763362637000 } } }, "200 Job Failed: FVU missing": { "summary": "200 Job Failed: FVU missing", "value": { "code": 200, "timestamp": 1763362637000, "transaction_id": "e2b9145f-69d5-4bbe-a6de-be6fc08b426f", "data": { "@entity": "in.co.sandbox.tds.compliance.e-file.job", "job_id": "9bf0b6f8-5957-484f-9aea-0d235054974c", "tan": "BABC23456L", "tax_year": "TY 2026-27", "quarter": "Q1", "form": "140", "filing_type": "original", "status": "failed", "message": "FVU missing", "created_at": 1763362637000, "updated_at": 1763362637000 } } } } } }, "headers": {} }, "521": { "description": "521 - Data Not Found", "content": { "application/json": { "schema": { "type": "object", "properties": { "code": { "type": "integer" }, "timestamp": { "type": "integer" }, "transaction_id": { "type": "string" }, "message": { "type": "string" } } }, "examples": { "521 Data not found": { "summary": "521 Data not found", "value": { "code": 521, "timestamp": 1763362637000, "transaction_id": "e2b9145f-69d5-4bbe-a6de-be6fc08b426f", "message": "Data not found" } } } } }, "headers": {} } }, "security": [] } }, "/tds/compliance/e-file/search": { "post": { "summary": "Fetch Jobs", "deprecated": false, "description": "", "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": "Date from which jobs are to be fetched. Value in EPOCH timestamP", "type": "integer" }, "to_date": { "description": "Date till which jobs are to be fetched. Value in EPOCH timestamp", "type": "integer" }, "page_size": { "description": "Number of records in the API response. Maximum allowed size is 50", "type": "integer" }, "last_evaluated_key": { "description": "Base64 encoding of the stringified JSON object, which includes x-api-key, created_at, and job_id", "type": "string" } }, "required": [ "@entity" ] }, "examples": { "200 Job succeeded": { "value": { "@entity": "in.co.sandbox.tds.compliance.e-file.search" }, "summary": "200 Job succeeded" } } } } }, "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" }, "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" } } } } } }, "transaction_id": { "type": "string" } } }, "examples": { "200 Job succeeded": { "summary": "200 Job succeeded", "value": { "code": 200, "timestamp": 1763035357079, "data": { "@entity": "in.co.sandbox.tds.compliance.e-file.paginated_list", "items": [ { "created_at": 1763034775467, "@entity": "in.co.sandbox.tds.compliance.e-file.job", "job_id": "f139447f-07c0-4de1-9f35-0224e253aeec", "tan": "AHMA09719B", "tax_year": "TY 2026-27", "quarter": "Q2", "form": "138", "filing_type": "regular", "status": "created" }, { "created_at": 1763034374362, "@entity": "in.co.sandbox.tds.compliance.e-file.job", "job_id": "6cc8a10e-6c09-4c6f-9bfe-d10b6f6afbb0", "tan": "SRTH05889C", "tax_year": "TY 2026-27", "quarter": "Q2", "form": "140", "filing_type": "regular", "status": "created" }, { "created_at": 1745588854631, "updated_at": 1745588884436, "@entity": "in.co.sandbox.tds.compliance.e-file.job", "job_id": "8566e974-9f6f-49ca-96cb-c75680261405", "tan": "SRTH05889C", "tax_year": "TY 2026-27", "quarter": "Q2", "form": "140", "filing_type": "regular", "status": "succeeded" } ] }, "transaction_id": "a109f017-10ae-44aa-ade7-3902a8cddd6b" } } } } }, "headers": {} } }, "security": [] } }, "/tds/compliance/traces/deductors/forms/{certificate_type}": { "post": { "summary": "Submit TDS Certificate Download Job", "deprecated": false, "description": "", "tags": [ "TDS Certificate" ], "parameters": [ { "name": "certificate_type", "in": "path", "description": "", "required": true, "example": "form16", "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": "", "required": false, "example": "", "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "@entity": { "description": "Entity type identifier. Must be `in.co.sandbox.tds.compliance.traces.credentials`.", "type": "string", "enum": [ "in.co.sandbox.tds.compliance.traces.credentials" ] }, "username": { "description": "Username of the TRACES portal. Must be a non-empty string.", "type": "string" }, "password": { "description": "Password of the TRACES portal. Must be a non-empty string.", "type": "string" }, "tan": { "description": "Tax Deduction Account Number (TAN) of the deductor. Must match `[A-Z]{4}[0-9]{5}[A-Z]{1}` (e.g., `AHMA09719B`).", "type": "string" }, "security_captcha": { "description": "Challan and return details used to authenticate the TRACES session and identify the certificate to download.", "type": "object", "properties": { "@entity": { "description": "Entity type identifier. Must be `in.co.sandbox.tds.compliance.traces.credentials.security_captcha`.", "type": "string", "enum": [ "in.co.sandbox.tds.compliance.traces.credentials.security_captcha" ] }, "quarter": { "description": "Quarter for which the TDS certificate is to be generated.", "enum": [ "Q1", "Q2", "Q3", "Q4" ], "type": "string" }, "financial_year": { "description": "Financial year for which the TDS certificate is to be generated. Must match `FY YYYY-YY` (e.g., `FY 2023-24`).", "type": "string", "example": "FY 2024-25" }, "form": { "description": "TDS return form type. Form 16 can only be generated for 24Q returns; Form 16A can be generated for 26Q or 27Q returns.", "enum": [ "24Q", "26Q", "27Q" ], "type": "string" }, "bsr_code": { "description": "Bank-Branch Code or Form 24G Receipt Number. Must be exactly 7 characters.", "type": "string", "minLength": 7, "maxLength": 7 }, "challan_date": { "description": "Date on which the challan was paid, as an EPOCH timestamp in milliseconds. Must be a positive integer.", "type": "integer" }, "challan_serial_no": { "description": "Bank challan serial number. Must be exactly 5 characters.\n\nWhen multiple challans are available, choose based on the number of distinct PAN-amount combinations in the challan:\n\n**3 distinct PAN-amount combinations** (highest priority)\n\n**2 distinct PAN-amount combinations**\n\n**1 distinct PAN-amount combination** (lowest priority)", "type": "string", "minLength": 5, "maxLength": 5 }, "provisional_receipt_number": { "description": "Provisional regular return receipt number of the most recently filed return. Must be exactly 15 characters.", "type": "string", "minLength": 15, "maxLength": 15 }, "challan_amount": { "description": "Total amount of the challan. Must be a positive integer.", "type": "integer", "minimum": 1 }, "unique_pan_amount_combination_for_challan": { "description": "Array of PAN-amount pairs for the selected challan. Must contain between 2 and 4 elements (1 header row + 1 to 3 data rows).\n\n**First element (header row):** `[\"sr_no\", \"pan\", \"total_amount_deposited_against_pan\"]`\n\n**Subsequent elements (data rows):**\n\n`sr_no`: positive integer\n\n`pan`: string matching `[A-Z]{3}[PCFTGHLABJ]{1}[A-Z]{1}[0-9]{4}[A-Z]{1}` (e.g., `XXXPX1234A`)\n\n`total_amount_deposited_against_pan`: non-negative number", "type": "array", "minItems": 2, "maxItems": 4, "items": { "type": "array", "items": {} } } }, "required": [ "@entity", "quarter", "financial_year", "form", "bsr_code", "challan_date", "challan_serial_no", "provisional_receipt_number", "challan_amount", "unique_pan_amount_combination_for_challan" ] }, "remember_me": { "description": "Whether to save the TRACES credentials for future requests. When `true`, subsequent jobs can be submitted without re-entering credentials.", "type": "boolean" } }, "required": [ "@entity", "username", "password", "tan", "security_captcha", "remember_me" ] }, "examples": { "200 - Success": { "value": { "@entity": "in.co.sandbox.tds.compliance.traces.credentials", "username": "sandbox.co", "password": "Sandbox&2023", "tan": "AHMS45586C", "security_captcha": { "@entity": "in.co.sandbox.tds.compliance.traces.credentials.security_captcha", "quarter": "Q4", "financial_year": "FY 2025-26", "form": "24Q", "bsr_code": "6390009", "challan_date": 1771824540000, "challan_serial_no": "02556", "provisional_receipt_number": "780236600264811", "challan_amount": 100, "unique_pan_amount_combination_for_challan": [ [ "sr_no", "pan", "total_amount_deposited_against_pan" ], [ 1, "CGIPN6158E", 0 ], [ 2, "KIIPS5702K", 0 ], [ 3, "BASPT3106P", 0 ] ] }, "remember_me": false }, "summary": "200 - Success" }, "200 Job created: Form 16A": { "value": { "@entity": "in.co.sandbox.tds.compliance.traces.credentials", "username": "T.STARK", "password": "TEST1234", "tan": "AHMA09719B", "security_captcha": { "@entity": "in.co.sandbox.tds.compliance.traces.credentials.security_captcha", "quarter": "Q4", "financial_year": "FY 2023-24", "form": "26Q", "bsr_code": "0510002", "challan_date": 1701109800000, "challan_serial_no": "01905", "provisional_receipt_number": "770000211345676", "challan_amount": 21, "unique_pan_amount_combination_for_challan": [ [ "sr_no", "pan", "total_amount_deposited_against_pan" ], [ 1, "XXXPX1234A", 1 ] ] }, "remember_me": true }, "summary": "200 Job created: Form 16A" }, "200 Job created: Invalid Credentials": { "value": { "@entity": "in.co.sandbox.tds.compliance.traces.credentials", "username": "T.STARK", "password": "TEST1234", "tan": "AHMA09719B", "security_captcha": { "@entity": "in.co.sandbox.tds.compliance.traces.credentials.security_captcha", "quarter": "Q4", "financial_year": "FY 2023-24", "form": "26Q", "bsr_code": "0510002", "challan_date": 1701109800000, "challan_serial_no": "01906", "provisional_receipt_number": "770000211345676", "challan_amount": 50000, "unique_pan_amount_combination_for_challan": [ [ "sr_no", "pan", "total_amount_deposited_against_pan" ], [ 1, "XXXPX1234H", 100 ], [ 2, "XXXPX1234O", 50 ], [ 3, "XXXPX1234L", 2000 ] ] }, "remember_me": true }, "summary": "200 Job created: Invalid Credentials" }, "200 Job created: Invalid Security Captcha": { "value": { "@entity": "in.co.sandbox.tds.compliance.traces.credentials", "username": "T.STARK", "password": "TEST1234", "tan": "AHMA09719B", "security_captcha": { "@entity": "in.co.sandbox.tds.compliance.traces.credentials.security_captcha", "quarter": "Q4", "financial_year": "FY 2023-24", "form": "26Q", "bsr_code": "0510002", "challan_date": 1701109800000, "challan_serial_no": "01906", "provisional_receipt_number": "770000211345676", "challan_amount": 50000, "unique_pan_amount_combination_for_challan": [ [ "sr_no", "pan", "total_amount_deposited_against_pan" ], [ 1, "XXXCX1234B", 1000 ], [ 2, "XXXAX2345A ", 2222 ], [ 3, "XXXBX3456B", 7999 ] ] }, "remember_me": true }, "summary": "200 Job created: Invalid Security Captcha" }, "200 Job created: Invalid TAN": { "value": { "@entity": "in.co.sandbox.tds.compliance.traces.credentials", "username": "T.STARK", "password": "TEST1234", "tan": "AHMA09719B", "security_captcha": { "@entity": "in.co.sandbox.tds.compliance.traces.credentials.security_captcha", "quarter": "Q4", "financial_year": "FY 2023-24", "form": "27Q", "bsr_code": "0510002", "challan_date": 1701109800000, "challan_serial_no": "01907", "provisional_receipt_number": "770000211345676", "challan_amount": 12000, "unique_pan_amount_combination_for_challan": [ [ "sr_no", "pan", "total_amount_deposited_against_pan" ], [ 1, "XXXTX1234P", 10000 ] ] }, "remember_me": true }, "summary": "200 Job created: Invalid TAN" }, "200 Job created: Form not available": { "value": { "@entity": "in.co.sandbox.tds.compliance.traces.credentials", "username": "T.STARK", "password": "TEST1234", "tan": "AHMA09719B", "security_captcha": { "@entity": "in.co.sandbox.tds.compliance.traces.credentials.security_captcha", "quarter": "Q4", "financial_year": "FY 2023-24", "form": "26Q", "bsr_code": "0510002", "challan_date": 1701109800000, "challan_serial_no": "01905", "provisional_receipt_number": "770000211345676", "challan_amount": 21, "unique_pan_amount_combination_for_challan": [ [ "sr_no", "pan", "total_amount_deposited_against_pan" ], [ 1, "XXXPX1234B", 21 ] ] }, "remember_me": true }, "summary": "200 Job created: Form not available" }, "200 Job created: Job already submitted": { "value": { "@entity": "in.co.sandbox.tds.compliance.traces.credentials", "username": "T.STARK", "password": "TEST1234", "tan": "AHMA09719B", "security_captcha": { "@entity": "in.co.sandbox.tds.compliance.traces.credentials.security_captcha", "quarter": "Q4", "financial_year": "FY 2023-24", "form": "26Q", "bsr_code": "0910005", "challan_date": 1701109800000, "challan_serial_no": "03905", "provisional_receipt_number": "770000211345596", "challan_amount": 21, "unique_pan_amount_combination_for_challan": [ [ "sr_no", "pan", "total_amount_deposited_against_pan" ], [ 1, "XXXPX1234B", 21 ] ] }, "remember_me": true }, "summary": "200 Job created: Job already submitted" }, "422 Missing Credentials": { "value": { "@entity": "in.co.sandbox.tds.compliance.traces.credentials", "tan": "AHMA09719B", "security_captcha": { "@entity": "in.co.sandbox.tds.compliance.traces.credentials.security_captcha", "quarter": "Q4", "financial_year": "FY 2023-24", "form": "26Q", "bsr_code": "0510002", "challan_date": 1701109800000, "challan_serial_no": "01905", "provisional_receipt_number": "770000211345676", "challan_amount": 21, "unique_pan_amount_combination_for_challan": [ [ "sr_no", "pan", "total_amount_deposited_against_pan" ], [ 1, "XXXPX1234A", 1 ] ] }, "remember_me": true }, "summary": "422 Missing Credentials" }, "422 Security Captcha Missing": { "value": { "@entity": "in.co.sandbox.tds.compliance.traces.credentials", "username": "T.STARK", "password": "TEST1234", "tan": "AHMA09719B", "remember_me": true }, "summary": "422 Security Captcha Missing" }, "422 Invalid TAN pattern": { "value": { "@entity": "in.co.sandbox.tds.compliance.traces.credentials", "username": "T.STARK", "password": "TEST1234", "tan": "DABC2345DD", "security_captcha": { "@entity": "in.co.sandbox.tds.compliance.traces.credentials.security_captcha", "quarter": "Q4", "financial_year": "FY 2023-24", "form": "26Q", "bsr_code": "0510002", "challan_date": 1701109800000, "challan_serial_no": "01905", "provisional_receipt_number": "770000211345676", "challan_amount": 21, "unique_pan_amount_combination_for_challan": [ [ "sr_no", "pan", "total_amount_deposited_against_pan" ], [ 1, "XXXPX1234A", 1 ] ] }, "remember_me": true }, "summary": "422 Invalid TAN pattern" }, "422 Invalid Form Type": { "value": { "@entity": "in.co.sandbox.tds.compliance.traces.credentials", "username": "T.STARK", "password": "TEST1234", "tan": "AHMA09719B", "security_captcha": { "@entity": "in.co.sandbox.tds.compliance.traces.credentials.security_captcha", "quarter": "Q4", "financial_year": "FY 2023-24", "form": "27Q", "bsr_code": "0510002", "challan_date": 1701109800000, "challan_serial_no": "01905", "provisional_receipt_number": "770000211345676", "challan_amount": 21, "unique_pan_amount_combination_for_challan": [ [ "sr_no", "pan", "total_amount_deposited_against_pan" ], [ 1, "XXXPX1234A", 1 ] ] }, "remember_me": true }, "summary": "422 Invalid Form Type" }, "422 Invalid Quarter": { "value": { "@entity": "in.co.sandbox.tds.compliance.traces.credentials", "username": "T.STARK", "password": "TEST1234", "tan": "AHMA09719B", "security_captcha": { "@entity": "in.co.sandbox.tds.compliance.traces.credentials.security_captcha", "quarter": "Q9", "financial_year": "FY 2023-24", "form": "26Q", "bsr_code": "0510002", "challan_date": 1701109800000, "challan_serial_no": "01905", "provisional_receipt_number": "770000211345676", "challan_amount": 21, "unique_pan_amount_combination_for_challan": [ [ "sr_no", "pan", "total_amount_deposited_against_pan" ], [ 1, "XXXPX1234A", 1 ] ] }, "remember_me": true }, "summary": "422 Invalid Quarter" }, "422 Invalid Financial Year": { "value": { "@entity": "in.co.sandbox.tds.compliance.traces.credentials", "username": "T.STARK", "password": "TEST1234", "tan": "AHMA09719B", "security_captcha": { "@entity": "in.co.sandbox.tds.compliance.traces.credentials.security_captcha", "quarter": "Q4", "financial_year": "FY 2022-2", "form": "26Q", "bsr_code": "0510002", "challan_date": 1701109800000, "challan_serial_no": "01905", "provisional_receipt_number": "770000211345676", "challan_amount": 21, "unique_pan_amount_combination_for_challan": [ [ "sr_no", "pan", "total_amount_deposited_against_pan" ], [ 1, "XXXPX1234A", 1 ] ] }, "remember_me": true }, "summary": "422 Invalid Financial Year" }, "422 Form Mismatch: Form16A": { "value": { "@entity": "in.co.sandbox.tds.compliance.traces.credentials", "username": "T.STARK", "password": "TEST1234", "tan": "AHMA09719B", "security_captcha": { "@entity": "in.co.sandbox.tds.compliance.traces.credentials.security_captcha", "quarter": "Q4", "financial_year": "FY 2022-2", "form": "24Q", "bsr_code": "0510002", "challan_date": 1701109800000, "challan_serial_no": "01905", "provisional_receipt_number": "770000211345676", "challan_amount": 21, "unique_pan_amount_combination_for_challan": [ [ "sr_no", "pan", "total_amount_deposited_against_pan" ], [ 1, "XXXPX1234A", 1 ] ] }, "remember_me": true }, "summary": "422 Form Mismatch: Form16A" }, "422 Quarter Mismatch: Form 16": { "value": { "@entity": "in.co.sandbox.tds.compliance.traces.credentials", "username": "T.STARK", "password": "TEST1234", "tan": "AHMA09719B", "security_captcha": { "@entity": "in.co.sandbox.tds.compliance.traces.credentials.security_captcha", "quarter": "Q3", "financial_year": "FY 2022-2", "form": "24Q", "bsr_code": "0510002", "challan_date": 1701109800000, "challan_serial_no": "01905", "provisional_receipt_number": "770000211345676", "challan_amount": 21, "unique_pan_amount_combination_for_challan": [ [ "sr_no", "pan", "total_amount_deposited_against_pan" ], [ 1, "XXXPX1234A", 1 ] ] }, "remember_me": true }, "summary": "422 Quarter Mismatch: Form 16" }, "422 Form Mismatch: Form16": { "value": { "@entity": "in.co.sandbox.tds.compliance.traces.credentials", "username": "T.STARK", "password": "TEST1234", "tan": "AHMA09719B", "security_captcha": { "@entity": "in.co.sandbox.tds.compliance.traces.credentials.security_captcha", "quarter": "Q4", "financial_year": "FY 2022-2", "form": "27Q", "bsr_code": "0510002", "challan_date": 1701109800000, "challan_serial_no": "01905", "provisional_receipt_number": "770000211345676", "challan_amount": 21, "unique_pan_amount_combination_for_challan": [ [ "sr_no", "pan", "total_amount_deposited_against_pan" ], [ 1, "XXXPX1234A", 1 ] ] }, "remember_me": true }, "summary": "422 Form Mismatch: Form16" } } } } }, "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" }, "tan": { "type": "string" }, "quarter": { "type": "string" }, "financial_year": { "type": "string" }, "form": { "type": "string" }, "status": { "type": "string" }, "remember_me": { "type": "boolean" }, "created_at": { "type": "integer" } } } } }, "examples": { "200 - Success": { "summary": "200 - Success", "value": { "code": 200, "timestamp": 1716870600000, "transaction_id": "f24cd229-42c8-43de-af79-8ce2d3c4c3db", "data": { "@entity": "in.co.sandbox.tds.compliance.certificate.job", "job_id": "f24cd229-42c8-43de-af79-8ce2d3c4c3db", "tan": "AHMA09719B", "quarter": "Q4", "financial_year": "FY 2023-24", "form": "24Q", "status": "created", "remember_me": false, "created_at": 1716870600000 } } }, "200 Job created: Form 16A": { "summary": "200 Job created: Form 16A", "value": { "code": 200, "timestamp": 1716870600000, "transaction_id": "67addd14-df35-4e74-b27b-2333784f5f24", "data": { "@entity": "in.co.sandbox.tds.compliance.certificate.job", "job_id": "67addd14-df35-4e74-b27b-2333784f5f24", "tan": "AHMA09719B", "quarter": "Q4", "form": "26Q", "financial_year": "FY 2023-24", "status": "created", "remember_me": true, "created_at": 1716870600000 } } }, "200 Job created: Invalid Credentials": { "summary": "200 Job created: Invalid Credentials", "value": { "code": 200, "timestamp": 1716870600000, "transaction_id": "0b205f2c-d27d-4bf3-b128-c6b16ebc065d", "data": { "@entity": "in.co.sandbox.tds.compliance.certificate.job", "job_id": "0b205f2c-d27d-4bf3-b128-c6b16ebc065d", "tan": "AHMA09719B", "quarter": "Q4", "form": "26Q", "financial_year": "FY 2023-24", "status": "created", "remember_me": true, "created_at": 1716870600000 } } }, "200 Job created: Invalid Security Captcha": { "summary": "200 Job created: Invalid Security Captcha", "value": { "code": 200, "timestamp": 1716870600000, "transaction_id": "c6cb65db-51dd-4369-882c-b90faccaeb28", "data": { "@entity": "in.co.sandbox.tds.compliance.certificate.job", "job_id": "c6cb65db-51dd-4369-882c-b90faccaeb28", "tan": "AHMA09719B", "quarter": "Q4", "form": "26Q", "financial_year": "FY 2023-24", "status": "created", "remember_me": true, "created_at": 1716870600000 } } }, "200 Job created: Invalid TAN": { "summary": "200 Job created: Invalid TAN", "value": { "code": 200, "timestamp": 1716870600000, "transaction_id": "ff78e6e2-3ea9-402b-9a09-a88c2413165f", "data": { "@entity": "in.co.sandbox.tds.compliance.certificate.job", "job_id": "ff78e6e2-3ea9-402b-9a09-a88c2413165f", "tan": "AHMA09719B", "quarter": "Q4", "form": "26Q", "financial_year": "FY 2023-24", "status": "created", "remember_me": true, "created_at": 1716870600000 } } }, "200 Job created: Form not available": { "summary": "200 Job created: Form not available", "value": { "code": 200, "timestamp": 1716870600000, "transaction_id": "3e93481b-b9fb-41f7-9eeb-f76369b8291e", "data": { "@entity": "in.co.sandbox.tds.compliance.certificate.job", "job_id": "3e93481b-b9fb-41f7-9eeb-f76369b8291e", "tan": "AHMA09719B", "quarter": "Q4", "form": "26Q", "financial_year": "FY 2023-24", "status": "created", "remember_me": true, "created_at": 1716870600000 } } }, "200 Job created: Job already submitted": { "summary": "200 Job created: Job already submitted", "value": { "code": 200, "timestamp": 1716870600000, "transaction_id": "28cc5c28-db2d-4224-be5c-9842c213c100", "data": { "@entity": "in.co.sandbox.tds.compliance.certificate.job", "job_id": "28cc5c28-db2d-4224-be5c-9842c213c100", "tan": "AHMA09719B", "quarter": "Q4", "form": "26Q", "financial_year": "FY 2023-24", "status": "created", "remember_me": true, "created_at": 1716870600000 } } } } } }, "headers": {} }, "422": { "description": "422 - Unprocessable Entity", "content": { "application/json": { "schema": { "type": "object", "properties": { "code": { "type": "integer" }, "timestamp": { "type": "integer" }, "transaction_id": { "type": "string" }, "message": { "type": "string" } } }, "examples": { "422 Missing Credentials": { "summary": "422 Missing Credentials", "value": { "code": 422, "timestamp": 1716870600000, "transaction_id": "f24cd229-42c8-43de-af79-8ce2d3c4c3db", "message": "Missing credentials" } }, "422 Security Captcha Missing": { "summary": "422 Security Captcha Missing", "value": { "code": 422, "timestamp": 1716870600000, "transaction_id": "f24cd229-42c8-43de-af79-8ce2d3c4c3db", "message": "Security captcha is missing" } }, "422 Invalid TAN pattern": { "summary": "422 Invalid TAN pattern", "value": { "code": 422, "timestamp": 1716870600000, "transaction_id": "f24cd229-42c8-43de-af79-8ce2d3c4c3db", "message": "Invalid TAN: DABC2345DD" } }, "422 Invalid Form Type": { "summary": "422 Invalid Form Type", "value": { "code": 422, "timestamp": 1716870600000, "transaction_id": "f24cd229-42c8-43de-af79-8ce2d3c4c3db", "message": "Invalid form_type: part-a" } }, "422 Invalid Quarter": { "summary": "422 Invalid Quarter", "value": { "code": 422, "timestamp": 1716870600000, "transaction_id": "f24cd229-42c8-43de-af79-8ce2d3c4c3db", "message": "Invalid quarter: Q9" } }, "422 Invalid Financial Year": { "summary": "422 Invalid Financial Year", "value": { "code": 422, "timestamp": 1716870600000, "transaction_id": "f24cd229-42c8-43de-af79-8ce2d3c4c3db", "message": "Invalid financial year: FY 2022-2" } }, "422 Form Mismatch: Form16A": { "summary": "422 Form Mismatch: Form16A", "value": { "code": 422, "timestamp": 1716870600000, "transaction_id": "f24cd229-42c8-43de-af79-8ce2d3c4c3db", "message": "Form 16A certificate cannot be generated for 24Q returns" } }, "422 Quarter Mismatch: Form 16": { "summary": "422 Quarter Mismatch: Form 16", "value": { "code": 422, "timestamp": 1716870600000, "transaction_id": "f24cd229-42c8-43de-af79-8ce2d3c4c3db", "message": "Form 16 certificate can be generated only for Q4 returns" } }, "422 Form Mismatch: Form16": { "summary": "422 Form Mismatch: Form16", "value": { "code": 422, "timestamp": 1716870600000, "transaction_id": "f24cd229-42c8-43de-af79-8ce2d3c4c3db", "message": "Form 16 certificate can be generated only for 24Q returns" } }, "422 Invalid Username": { "summary": "422 Invalid Username", "value": { "code": 422, "timestamp": 1716870600000, "transaction_id": "f24cd229-42c8-43de-af79-8ce2d3c4c3db", "message": "Invalid username: " } }, "422 Invalid Password": { "summary": "422 Invalid Password", "value": { "code": 422, "timestamp": 1716870600000, "transaction_id": "f24cd229-42c8-43de-af79-8ce2d3c4c3db", "message": "Invalid password: " } }, "422 Invalid Challan Amount": { "summary": "422 Invalid Challan Amount", "value": { "code": 422, "timestamp": 1716870600000, "transaction_id": "f24cd229-42c8-43de-af79-8ce2d3c4c3db", "message": "Invalid challan_amount: 0" } }, "422 Invalid Provisional Receipt Number": { "summary": "422 Invalid Provisional Receipt Number", "value": { "code": 422, "timestamp": 1716870600000, "transaction_id": "f24cd229-42c8-43de-af79-8ce2d3c4c3db", "message": "Invalid provisional_receipt_number length" } }, "422 Invalid BSR Code": { "summary": "422 Invalid BSR Code", "value": { "code": 422, "timestamp": 1716870600000, "transaction_id": "f24cd229-42c8-43de-af79-8ce2d3c4c3db", "message": "invalid bsr_code length" } }, "422 Invalid Challan Serial Number": { "summary": "422 Invalid Challan Serial Number", "value": { "code": 422, "timestamp": 1716870600000, "transaction_id": "f24cd229-42c8-43de-af79-8ce2d3c4c3db", "message": "Invalid challan_serial_no length" } }, "422 Invalid Challan Date": { "summary": "422 Invalid Challan Date", "value": { "code": 422, "timestamp": 1716870600000, "transaction_id": "f24cd229-42c8-43de-af79-8ce2d3c4c3db", "message": "Invalid challan_date" } }, "422 Invalid Remember Me": { "summary": "422 Invalid Remember Me", "value": { "code": 422, "timestamp": 1716870600000, "transaction_id": "f24cd229-42c8-43de-af79-8ce2d3c4c3db", "message": "Invalid remember_me" } }, "422 Invalid PAN Amount Combination": { "summary": "422 Invalid PAN Amount Combination", "value": { "code": 422, "timestamp": 1716870600000, "transaction_id": "f24cd229-42c8-43de-af79-8ce2d3c4c3db", "message": "Invalid unique_pan_amount_combination_for_challan" } } } } }, "headers": {} } }, "security": [] } }, "/tds/compliance/traces/deductors/forms/{certificate_type}/status": { "post": { "summary": "Poll Certificate Job Status", "deprecated": false, "description": "", "tags": [ "TDS Certificate" ], "parameters": [ { "name": "certificate_type", "in": "path", "description": "", "required": true, "example": "form16a", "schema": { "type": "string" } }, { "name": "job_id", "in": "query", "description": "Check job status of Download Form16", "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": "", "required": false, "example": "", "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "@entity": { "type": "string" }, "username": { "type": "string" }, "password": { "type": "string" }, "tan": { "type": "string" } }, "required": [ "@entity" ] }, "examples": { "200 - Success": { "value": { "@entity": "in.co.sandbox.tds.compliance.traces.credentials", "username": "sandbox.co", "password": "Sandbox&2023", "tan": "AHMS45586C" }, "summary": "200 - Success" }, "200 Job Queued": { "value": { "@entity": "in.co.sandbox.tds.compliance.traces.credentials" }, "summary": "200 Job Queued" }, "200 Job In Progress": { "value": { "@entity": "in.co.sandbox.tds.compliance.traces.credentials" }, "summary": "200 Job In Progress" }, "200 Job Succeeded: Form 16": { "value": { "@entity": "in.co.sandbox.tds.compliance.traces.credentials", "username": "T.STARK", "password": "TEST1234", "tan": "AHMA09719B" }, "summary": "200 Job Succeeded: Form 16" }, "200 Job Succeeded: Form 16A": { "value": { "@entity": "in.co.sandbox.tds.compliance.traces.credentials" }, "summary": "200 Job Succeeded: Form 16A" }, "200 Job Failed: Invalid Credentials": { "value": { "@entity": "in.co.sandbox.tds.compliance.traces.credentials" }, "summary": "200 Job Failed: Invalid Credentials" }, "200 Job Failed: Invalid Security Captcha": { "value": { "@entity": "in.co.sandbox.tds.compliance.traces.credentials" }, "summary": "200 Job Failed: Invalid Security Captcha" }, "200 Job Failed: Invalid TAN": { "value": { "@entity": "in.co.sandbox.tds.compliance.traces.credentials" }, "summary": "200 Job Failed: Invalid TAN" }, "200 Job Failed: Form Not Available": { "value": { "@entity": "in.co.sandbox.tds.compliance.traces.credentials" }, "summary": "200 Job Failed: Form Not Available" }, "200 Job Failed: Job Already Submitted": { "value": { "@entity": "in.co.sandbox.tds.compliance.traces.credentials" }, "summary": "200 Job Failed: Job Already Submitted" }, "422 - Unprocessable Entity": { "value": { "@entity": "in.co.sandbox.tds.compliance.traces.credentials" }, "summary": "422 - Unprocessable Entity" }, "521 Data Not Found": { "value": { "@entity": "in.co.sandbox.tds.compliance.traces.credentials" }, "summary": "521 Data Not Found" } } } } }, "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" }, "tan": { "type": "string" }, "quarter": { "type": "string" }, "form": { "type": "string" }, "financial_year": { "type": "string" }, "status": { "type": "string" }, "remember_me": { "type": "boolean" }, "created_at": { "type": "integer" } } } } }, { "title": "Job Succeeded", "type": "object", "properties": { "code": { "type": "integer" }, "timestamp": { "type": "integer" }, "transaction_id": { "type": "string" }, "data": { "type": "object", "properties": { "@entity": { "type": "string" }, "job_id": { "type": "string" }, "tan": { "type": "string" }, "quarter": { "type": "string" }, "form": { "type": "string" }, "financial_year": { "type": "string" }, "status": { "type": "string" }, "remember_me": { "type": "boolean" }, "created_at": { "type": "integer" }, "updated_at": { "type": "integer" }, "certificate_zip_urls": { "type": "array", "items": { "type": "string", "format": "uri" } } } } } }, { "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" }, "tan": { "type": "string" }, "quarter": { "type": "string" }, "form": { "type": "string" }, "financial_year": { "type": "string" }, "status": { "type": "string" }, "remember_me": { "type": "boolean" }, "created_at": { "type": "integer" }, "updated_at": { "type": "integer" }, "message": { "type": "string" } } } } } ] }, "examples": { "200 - Success": { "summary": "200 - Success", "value": { "code": 200, "timestamp": 1716870600000, "transaction_id": "f24cd229-42c8-43de-af79-8ce2d3c4c3db", "data": { "@entity": "in.co.sandbox.tds.compliance.certificate.job", "job_id": "52a52404-0b10-4029-acda-967eebcd5bce", "tan": "AHMA09719B", "quarter": "Q4", "form": "26Q", "financial_year": "FY 2023-24", "status": "created", "remember_me": true, "created_at": 1716870600000 } } }, "200 Job Queued": { "summary": "200 Job Queued", "value": { "code": 200, "timestamp": 1716870600000, "transaction_id": "f24cd229-42c8-43de-af79-8ce2d3c4c3db", "data": { "@entity": "in.co.sandbox.tds.compliance.certificate.job", "job_id": "32a4c93f-cff5-4c78-b90f-590f82ebd169", "tan": "AHMA09719B", "quarter": "Q4", "form": "26Q", "financial_year": "FY 2023-24", "status": "queued", "remember_me": true, "created_at": 1716870600000, "updated_at": 1716871020000 } } }, "200 Job In Progress": { "summary": "200 Job In Progress", "value": { "code": 200, "timestamp": 1716870600000, "transaction_id": "f24cd229-42c8-43de-af79-8ce2d3c4c3db", "data": { "@entity": "in.co.sandbox.tds.compliance.certificate.job", "job_id": "474c9caf-e7e9-4ed7-ac28-9450a9218056", "tan": "AHMA09719B", "quarter": "Q4", "form": "26Q", "financial_year": "FY 2023-24", "status": "in_progress", "remember_me": true, "created_at": 1716870600000, "updated_at": 1716871020000 } } }, "200 Job Succeeded: Form 16": { "summary": "200 Job Succeeded: Form 16", "value": { "code": 200, "timestamp": 1716870600000, "transaction_id": "f24cd229-42c8-43de-af79-8ce2d3c4c3db", "data": { "@entity": "in.co.sandbox.tds.compliance.certificate.job", "job_id": "f24cd229-42c8-43de-af79-8ce2d3c4c3db", "tan": "AHMA09719B", "quarter": "Q4", "form": "24Q", "financial_year": "FY 2023-24", "status": "succeeded", "remember_me": false, "created_at": 1716870600000, "updated_at": 1716871500000, "certificate_zip_urls": [ "https://in-co-sandbox-tds-test-storage.s3.ap-south-1.amazonaws.com/AHMS45586C/FY+2025-26/Q3/26Q/4049c226-4988-4978-b5ad-d25705453da8/26Q.zip", "https://in-co-sandbox-tds-test-storage.s3.ap-south-1.amazonaws.com/AHMS45586C/FY+2025-26/Q3/26Q/4049c226-4988-4978-b5ad-d25705453da8/26Q.zip" ] } } }, "200 Job Succeeded: Form 16A": { "summary": "200 Job Succeeded: Form 16A", "value": { "code": 200, "timestamp": 1716870600000, "transaction_id": "f24cd229-42c8-43de-af79-8ce2d3c4c3db", "data": { "@entity": "in.co.sandbox.tds.compliance.certificate.job", "job_id": "67addd14-df35-4e74-b27b-2333784f5f24", "tan": "AHMA09719B", "quarter": "Q4", "form": "26Q", "financial_year": "FY 2023-24", "status": "succeeded", "remember_me": true, "created_at": 1716870600000, "updated_at": 1716871500000, "certificate_zip_urls": [ "https://in-co-sandbox-tds-compliance-certificate-test.s3.ap-south-1.amazonaws.com/tan/financial_year/quarter/form/e5c2f029-8ddf-48e4-bcf2-c40277f0da20/1_form16a_pdf.zip", "https://in-co-sandbox-tds-compliance-certificate-test.s3.ap-south-1.amazonaws.com/tan/financial_year/quarter/form/e5c2f029-8ddf-48e4-bcf2-c40277f0da20/2_form16a_pdf.zip" ] } } }, "200 Job Failed: Invalid Credentials": { "summary": "200 Job Failed: Invalid Credentials", "value": { "code": 200, "timestamp": 1716870600000, "transaction_id": "f24cd229-42c8-43de-af79-8ce2d3c4c3db", "data": { "@entity": "in.co.sandbox.tds.compliance.certificate.job", "job_id": "0b205f2c-d27d-4bf3-b128-c6b16ebc065d", "tan": "AHMA09719B", "quarter": "Q4", "form": "27Q", "financial_year": "FY 2023-24", "status": "failed", "remember_me": true, "created_at": 1716870600000, "updated_at": 1716870900000, "message": "Invalid credentials" } } }, "200 Job Failed: Invalid Security Captcha": { "summary": "200 Job Failed: Invalid Security Captcha", "value": { "code": 200, "timestamp": 1716870600000, "transaction_id": "f24cd229-42c8-43de-af79-8ce2d3c4c3db", "data": { "@entity": "in.co.sandbox.tds.compliance.certificate.job", "job_id": "c6cb65db-51dd-4369-882c-b90faccaeb28", "tan": "AHMA09719B", "quarter": "Q4", "form": "27Q", "financial_year": "FY 2023-24", "status": "failed", "remember_me": true, "created_at": 1716870600000, "updated_at": 1716870900000, "message": "Invalid security captcha" } } }, "200 Job Failed: Invalid TAN": { "summary": "200 Job Failed: Invalid TAN", "value": { "code": 200, "timestamp": 1716870600000, "transaction_id": "f24cd229-42c8-43de-af79-8ce2d3c4c3db", "data": { "@entity": "in.co.sandbox.tds.compliance.certificate.job", "job_id": "ff78e6e2-3ea9-402b-9a09-a88c2413165f", "tan": "AHMA09719B", "quarter": "Q4", "form": "26Q", "financial_year": "FY 2023-24", "status": "failed", "remember_me": true, "created_at": 1716870600000, "updated_at": 1716870900000, "message": "Invalid tan" } } }, "200 Job Failed: Form Not Available": { "summary": "200 Job Failed: Form Not Available", "value": { "code": 200, "timestamp": 1716870600000, "transaction_id": "f24cd229-42c8-43de-af79-8ce2d3c4c3db", "data": { "@entity": "in.co.sandbox.tds.compliance.certificate.job", "job_id": "3e93481b-b9fb-41f7-9eeb-f76369b8291e", "tan": "AHMA09719B", "quarter": "Q4", "form": "27Q", "financial_year": "FY 2023-24", "status": "failed", "remember_me": true, "created_at": 1716870600000, "updated_at": 1716871020000, "message": "Form not available for the given quarter and financial year" } } }, "200 Job Failed: Job Already Submitted": { "summary": "200 Job Failed: Job Already Submitted", "value": { "code": 200, "timestamp": 1716870600000, "transaction_id": "f24cd229-42c8-43de-af79-8ce2d3c4c3db", "data": { "@entity": "in.co.sandbox.tds.compliance.certificate.job", "job_id": "28cc5c28-db2d-4224-be5c-9842c213c100", "tan": "AHMA09719B", "quarter": "Q4", "form": "27Q", "financial_year": "FY 2023-24", "status": "failed", "remember_me": true, "created_at": 1716870600000, "updated_at": 1716871020000, "message": "Job already submitted for the given quarter and financial year" } } } } } }, "headers": {} }, "422": { "description": "422 - Unprocessable Entity", "content": { "application/json": { "schema": { "type": "object", "properties": { "code": { "type": "integer" }, "timestamp": { "type": "integer" }, "transaction_id": { "type": "string" }, "message": { "type": "string" } } }, "examples": { "422 - Unprocessable Entity": { "summary": "422 - Unprocessable Entity", "value": { "code": 422, "timestamp": 1716870600000, "transaction_id": "f24cd229-42c8-43de-af79-8ce2d3c4c3db", "message": "Invalid Job ID: 123313jojj" } } } } }, "headers": {} }, "521": { "description": "521 - Data Not Found", "content": { "application/json": { "schema": { "type": "object", "properties": { "code": { "type": "integer" }, "timestamp": { "type": "integer" }, "transaction_id": { "type": "string" }, "message": { "type": "string" } } }, "examples": { "521 Data Not Found": { "summary": "521 Data Not Found", "value": { "code": 521, "timestamp": 1716870600000, "transaction_id": "f24cd229-42c8-43de-af79-8ce2d3c4c3db", "message": "Data not found: 4d46a915-acf5-405d-b79c-e7672375304a" } } } } }, "headers": {} } }, "security": [] } }, "/tds/compliance/traces/deductors/forms/{certificate_type}/search": { "post": { "summary": "Fetch Jobs", "deprecated": false, "description": "", "tags": [ "TDS Certificate" ], "parameters": [ { "name": "certificate_type", "in": "path", "description": "", "required": true, "example": "", "schema": { "type": "string" } }, { "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.certificate.job.search" ] }, "tan": { "description": "Regular Expression: [A-Z]{4}[0-9]{5}[A-Z]{1}", "type": "string" }, "quarter": { "description": "Quarter (e.g. Q2)", "type": "string" }, "form": { "description": "TDS return form", "type": "string" }, "financial_year": { "description": "Financial Year (e.g. FY 2022-23)", "type": "string" }, "from_date": { "description": "Date from which jobs are to be fetched. Value in EPOCH timestamp", "type": "integer" }, "to_date": { "description": "Date till which jobs are to be fetched. Value in EPOCH timestamp", "type": "integer" }, "page_size": { "description": "Number of records in the API response. Maximum allowed size is 50", "type": "integer" }, "last_evaluated_key": { "description": "Base64 encoding of the stringified JSON object, which includes x-api-key, created_at, and job_id", "type": "string" } }, "required": [ "@entity" ] }, "examples": { "200 Jobs fetched": { "value": { "@entity": "in.co.sandbox.tds.compliance.certificate.job.search" }, "summary": "200 Jobs fetched" } } } } }, "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" }, "items": { "type": "array", "items": { "type": "object", "properties": { "@entity": { "type": "string" }, "job_id": { "type": "string" }, "tan": { "type": "string" }, "financial_year": { "type": "string" }, "quarter": { "type": "string" }, "form": { "type": "string" }, "created_at": { "type": "integer" }, "updated_at": { "type": "integer" }, "status": { "type": "string" }, "remember_me": { "type": "boolean" } } } }, "last_evaluated_key": { "type": "string" } } } } }, "examples": { "200 Jobs fetched": { "summary": "200 Jobs fetched", "value": { "code": 200, "timestamp": 1616223746147, "transaction_id": "f24cd229-42c8-43de-af79-8ce2d3c4c3db", "data": { "@entity": "in.co.sandbox.tds.compliance.certificate.paginated_list", "items": [ { "@entity": "in.co.sandbox.tds.compliance.certificate.job", "job_id": "096c4812-1829-4ee1-a3c6-3bd291654b72", "tan": "AHMS12345C", "financial_year": "FY 2023-24", "quarter": "Q2", "form": "26Q", "created_at": 1714529043000, "updated_at": 1714529044000, "status": "succeeded", "remember_me": true }, { "@entity": "in.co.sandbox.tds.compliance.certificate.job", "job_id": "096c4812-1829-4ee1-a3c6-3bd291654b72", "tan": "AHMS12345C", "financial_year": "FY 2023-24", "quarter": "Q2", "form": "26Q", "created_at": 1714527043000, "updated_at": 1714527044000, "status": "failed", "message": "Invalid credentials", "remember_me": false }, { "@entity": "in.co.sandbox.tds.compliance.certificate.job", "job_id": "096c4812-1829-4ee1-a3c6-3bd291654b72", "tan": "AHMS12345C", "financial_year": "FY 2023-24", "quarter": "Q2", "form": "26Q", "created_at": 1714530043000, "updated_at": 1714530044000, "status": "failed", "message": "Form not available for the given quarter and financial year", "remember_me": false } ], "last_evaluated_key": "eydadadadada...==" } } } } } }, "headers": {} } }, "security": [] } } }, "components": { "schemas": {}, "responses": {}, "securitySchemes": {} }, "security": [] }