{
  "openapi": "3.1.0",
  "info": {
    "title": "compliance",
    "description": "Tax Deducted at Source (TDS) is an indirect method of collecting Income Tax. TDS is based on the principle of “Pay as you earn” which is beneficial for both the Government and the taxpayer. It is where a person making a payment of specified nature is liable to deduct tax at a prescribed rate. This ensures continuous revenue for the Government by way of Tax Deducted at the Source.\n\nThe Payer making a payment is also responsible to deposit TDS with the Income Tax Department within a specified date and file a TDS Return. Once filed, the deposited amount will be shown in the Payee's Form 26AS which they can then use to claim tax credits when filing ITR.\n\nHowever, staying TDS compliant can be a hassle for businesses, as they are required to :\n\n1. Deduct TDS from payments that are liable for TDS Deduction at an appropriate rate.\n    \n2. Deposit TDS to Government before the due date.\n    \n3. File TDS Returns on a Quarterly basis.\n    \n4. Issue a TDS Certificate by the deductor to the deductee.\n    \n\nOrganizations deducting TDS have to remain compliant with each of the steps. Failure to do so results in TDS Penalties by Authorities. Sandbox provides TDS Compliance APIs to help you automate end-to-end TDS compliance.",
    "version": "1.0.0"
  },
  "tags": [
    {
      "name": "TDS Compliance Check"
    },
    {
      "name": "Download CSI"
    },
    {
      "name": "FVU Generation"
    },
    {
      "name": "TDS"
    },
    {
      "name": "TDS Certificate"
    },
    {
      "name": "TRACES Credentials"
    },
    {
      "name": "E-File TDS Return"
    }
  ],
  "paths": {
    "/tds/compliance/206ab/check": {
      "post": {
        "summary": "Section 206AB & 206CCA Compliance Check",
        "deprecated": false,
        "description": "",
        "tags": [
          "TDS Compliance Check"
        ],
        "parameters": [
          {
            "name": "authorization",
            "in": "header",
            "description": "JWT access token",
            "required": true,
            "example": "",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "x-api-key",
            "in": "header",
            "description": "API key for identification",
            "required": true,
            "example": "",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "x-api-version",
            "in": "header",
            "description": "API version",
            "required": false,
            "example": "",
            "schema": {
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "@entity": {
                    "type": "string",
                    "enum": [
                      "in.co.sandbox.tds.compliance.206ab_check.request"
                    ]
                  },
                  "pan": {
                    "description": "10-character alphanumeric unique identifier for an income tax-payer.",
                    "pattern": "[A-Z]{3}[PCFTGHLABJ]{1}[A-Z]{1}[0-9]{4}[A-Z]{1}",
                    "type": "string"
                  },
                  "consent": {
                    "type": "string"
                  },
                  "reason": {
                    "type": "string"
                  }
                },
                "required": [
                  "@entity",
                  "pan",
                  "consent",
                  "reason"
                ]
              },
              "examples": {
                "200 Specified person": {
                  "value": {
                    "@entity": "in.co.sandbox.tds.compliance.206ab_check.request",
                    "pan": "XXXPX1234A",
                    "consent": "y",
                    "reason": "TDS compliance"
                  },
                  "summary": "200 Specified person"
                },
                "200 Specified person (2)": {
                  "value": {
                    "@entity": "in.co.sandbox.tds.compliance.206ab_check.request",
                    "pan": "XXXPX1234L",
                    "consent": "y",
                    "reason": "TDS compliance"
                  },
                  "summary": "200 Specified person (2)"
                },
                "200 Specified person (3)": {
                  "value": {
                    "@entity": "in.co.sandbox.tds.compliance.206ab_check.request",
                    "pan": "XXXPX1234L",
                    "consent": "y",
                    "reason": "TDS compliance"
                  },
                  "summary": "200 Specified person (3)"
                },
                "200 Specified person with inoperative pan": {
                  "value": {
                    "@entity": "in.co.sandbox.tds.compliance.206ab_check.request",
                    "pan": "XXXPX1234H",
                    "consent": "y",
                    "reason": "TDS compliance"
                  },
                  "summary": "200 Specified person with inoperative pan"
                },
                "200 Specified person with inoperative pan (2)": {
                  "value": {
                    "@entity": "in.co.sandbox.tds.compliance.206ab_check.request",
                    "pan": "XXXAX2345A",
                    "consent": "y",
                    "reason": "TDS compliance"
                  },
                  "summary": "200 Specified person with inoperative pan (2)"
                },
                "200 Not a specified person": {
                  "value": {
                    "@entity": "in.co.sandbox.tds.compliance.206ab_check.request",
                    "pan": "XXXPX2345A",
                    "consent": "y",
                    "reason": "TDS complaince"
                  },
                  "summary": "200 Not a specified person"
                },
                "200 Not a specified person (2)": {
                  "value": {
                    "@entity": "in.co.sandbox.tds.compliance.206ab_check.request",
                    "pan": "XXXBX3456B",
                    "consent": "y",
                    "reason": "TDS complaince"
                  },
                  "summary": "200 Not a specified person (2)"
                },
                "200 Not a specified person with inoperative pan": {
                  "value": {
                    "@entity": "in.co.sandbox.tds.compliance.206ab_check.request",
                    "pan": "XXXPX1234O",
                    "consent": "y",
                    "reason": "TDS complaince"
                  },
                  "summary": "200 Not a specified person with inoperative pan"
                },
                "200 Not a specified person with inoperative pan (2)": {
                  "value": {
                    "@entity": "in.co.sandbox.tds.compliance.206ab_check.request",
                    "pan": "XXXTX1234P",
                    "consent": "y",
                    "reason": "TDS complaince"
                  },
                  "summary": "200 Not a specified person with inoperative pan (2)"
                },
                "200 Invalid PAN": {
                  "value": {
                    "@entity": "in.co.sandbox.tds.compliance.206ab_check.request",
                    "pan": "XXXPX1234C",
                    "consent": "y",
                    "reason": "TDS compliance"
                  },
                  "summary": "200 Invalid PAN"
                },
                "422 Invalid PAN pattern": {
                  "value": {
                    "@entity": "in.co.sandbox.tds.compliance.206ab_check.request",
                    "pan": "XXXQX1234A",
                    "consent": "y",
                    "reason": "TDS compliance"
                  },
                  "summary": "422 Invalid PAN pattern"
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "200 - OK",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "code": {
                      "type": "integer"
                    },
                    "timestamp": {
                      "type": "integer"
                    },
                    "transaction_id": {
                      "type": "string"
                    },
                    "data": {
                      "type": "object",
                      "properties": {
                        "@entity": {
                          "type": "string",
                          "enum": [
                            "in.co.sandbox.tds.compliance.206ab_check.response"
                          ]
                        },
                        "pan": {
                          "type": "string"
                        },
                        "name": {
                          "type": "string"
                        },
                        "pan_allotment_date": {
                          "type": "integer"
                        },
                        "financial_year": {
                          "type": "string"
                        },
                        "specified_person_us_206ab_&_206cca": {
                          "type": "string"
                        },
                        "pan_status": {
                          "type": "string"
                        }
                      }
                    }
                  }
                },
                "examples": {
                  "200 Specified person": {
                    "summary": "200 Specified person",
                    "value": {
                      "code": 200,
                      "timestamp": 1763362637000,
                      "transaction_id": "e2b9145f-69d5-4bbe-a6de-be6fc08b426f",
                      "data": {
                        "@entity": "in.co.sandbox.tds.compliance.206ab_check.response",
                        "pan": "XXXPX1234A",
                        "name": "SXXXXJ MXXXXXXXXR",
                        "pan_allotment_date": 1527100200000,
                        "financial_year": "FY 2024-25",
                        "specified_person_us_206ab_&_206cca": "y",
                        "pan_status": "operative"
                      }
                    }
                  },
                  "200 Specified person (2)": {
                    "summary": "200 Specified person (2)",
                    "value": {
                      "code": 200,
                      "timestamp": 1763362637000,
                      "transaction_id": "e2b9145f-69d5-4bbe-a6de-be6fc08b426f",
                      "data": {
                        "@entity": "in.co.sandbox.tds.compliance.206ab_check.response",
                        "pan": "XXXPX1234L",
                        "name": "MXXXA PXXXL",
                        "pan_allotment_date": 1527100200000,
                        "financial_year": "FY 2024-25",
                        "specified_person_us_206ab_&_206cca": "y",
                        "pan_status": "operative"
                      }
                    }
                  },
                  "200 Specified person (3)": {
                    "summary": "200 Specified person (3)",
                    "value": {
                      "code": 200,
                      "timestamp": 1763362637000,
                      "transaction_id": "e2b9145f-69d5-4bbe-a6de-be6fc08b426f",
                      "data": {
                        "@entity": "in.co.sandbox.tds.compliance.206ab_check.response",
                        "pan": "XXXCX1234B",
                        "name": "IXXL CXXP",
                        "pan_allotment_date": 1527100200000,
                        "financial_year": "FY 2024-25",
                        "specified_person_us_206ab_&_206cca": "y",
                        "pan_status": "operative"
                      }
                    }
                  },
                  "200 Specified person with inoperative pan": {
                    "summary": "200 Specified person with inoperative pan",
                    "value": {
                      "code": 200,
                      "timestamp": 1763362637000,
                      "transaction_id": "e2b9145f-69d5-4bbe-a6de-be6fc08b426f",
                      "data": {
                        "@entity": "in.co.sandbox.tds.compliance.206ab_check.response",
                        "pan": "XXXPX1234H",
                        "name": "AXXXV KXXXA",
                        "pan_allotment_date": 1527100200000,
                        "financial_year": "FY 2024-25",
                        "specified_person_us_206ab_&_206cca": "y",
                        "pan_status": "inoperative"
                      }
                    }
                  },
                  "200 Specified person with inoperative pan (2)": {
                    "summary": "200 Specified person with inoperative pan (2)",
                    "value": {
                      "code": 200,
                      "timestamp": 1763362637000,
                      "transaction_id": "e2b9145f-69d5-4bbe-a6de-be6fc08b426f",
                      "data": {
                        "@entity": "in.co.sandbox.tds.compliance.206ab_check.response",
                        "pan": "XXXAX2345A",
                        "name": "MXXR SXXR",
                        "pan_allotment_date": 1527100200000,
                        "financial_year": "FY 2024-25",
                        "specified_person_us_206ab_&_206cca": "y",
                        "pan_status": "inoperative"
                      }
                    }
                  },
                  "200 Not a specified person": {
                    "summary": "200 Not a specified person",
                    "value": {
                      "code": 200,
                      "timestamp": 1763362637000,
                      "transaction_id": "e2b9145f-69d5-4bbe-a6de-be6fc08b426f",
                      "data": {
                        "@entity": "in.co.sandbox.tds.compliance.206ab_check.response",
                        "pan": "XXXPX1234B",
                        "name": "JXXXR MXXXXXXA",
                        "pan_allotment_date": 1527100200000,
                        "financial_year": "FY 2024-25",
                        "specified_person_us_206ab_&_206cca": "n",
                        "pan_status": "operative"
                      }
                    }
                  },
                  "200 Not a specified person (2)": {
                    "summary": "200 Not a specified person (2)",
                    "value": {
                      "code": 200,
                      "timestamp": 1763362637000,
                      "transaction_id": "e2b9145f-69d5-4bbe-a6de-be6fc08b426f",
                      "data": {
                        "@entity": "in.co.sandbox.tds.compliance.206ab_check.response",
                        "pan": "XXXBX3456B",
                        "name": "FXXD TXXXG",
                        "pan_allotment_date": 1527100200000,
                        "financial_year": "FY 2024-25",
                        "specified_person_us_206ab_&_206cca": "n",
                        "pan_status": "operative"
                      }
                    }
                  },
                  "200 Not a specified person with inoperative pan": {
                    "summary": "200 Not a specified person with inoperative pan",
                    "value": {
                      "code": 200,
                      "timestamp": 1763362637000,
                      "transaction_id": "e2b9145f-69d5-4bbe-a6de-be6fc08b426f",
                      "data": {
                        "@entity": "in.co.sandbox.tds.compliance.206ab_check.response",
                        "pan": "XXXPX1234B",
                        "name": "RXXXL SXXXH",
                        "pan_allotment_date": 1527100200000,
                        "financial_year": "FY 2024-25",
                        "specified_person_us_206ab_&_206cca": "n",
                        "pan_status": "inoperative"
                      }
                    }
                  },
                  "200 Not a specified person with inoperative pan (2)": {
                    "summary": "200 Not a specified person with inoperative pan (2)",
                    "value": {
                      "code": 200,
                      "timestamp": 1763362637000,
                      "transaction_id": "e2b9145f-69d5-4bbe-a6de-be6fc08b426f",
                      "data": {
                        "@entity": "in.co.sandbox.tds.compliance.206ab_check.response",
                        "pan": "XXXTX1234P",
                        "name": "EXXXN MXXL",
                        "pan_allotment_date": 1527100200000,
                        "financial_year": "FY 2024-25",
                        "specified_person_us_206ab_&_206cca": "n",
                        "pan_status": "inoperative"
                      }
                    }
                  },
                  "200 Invalid PAN": {
                    "summary": "200 Invalid PAN",
                    "value": {
                      "code": 200,
                      "timestamp": 1763362637000,
                      "transaction_id": "e2b9145f-69d5-4bbe-a6de-be6fc08b426f",
                      "data": {
                        "@entity": "in.co.sandbox.tds.compliance.206ab_check.response",
                        "message": "Invalid PAN"
                      }
                    }
                  }
                }
              }
            },
            "headers": {}
          },
          "422": {
            "description": "422 - Unprocessable Entity",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "code": {
                      "type": "integer"
                    },
                    "timestamp": {
                      "type": "integer"
                    },
                    "transaction_id": {
                      "type": "string"
                    },
                    "message": {
                      "type": "string"
                    }
                  }
                },
                "examples": {
                  "422 Invalid PAN pattern": {
                    "summary": "422 Invalid PAN pattern",
                    "value": {
                      "code": 422,
                      "timestamp": 1687348772740,
                      "transaction_id": "780b2332-d96e-4ef5-b7bc-d7b40e59fa9e",
                      "message": "Invalid Pan pattern"
                    }
                  }
                }
              }
            },
            "headers": {}
          }
        },
        "security": []
      }
    },
    "/tds/compliance/csi/otp": {
      "post": {
        "summary": "Generate OTP for CSI download",
        "deprecated": false,
        "description": "Send an OTP to the provided mobile number to request a CSI file.",
        "tags": [
          "Download CSI"
        ],
        "parameters": [
          {
            "name": "authorization",
            "in": "header",
            "description": "JWT access token",
            "required": true,
            "example": "{{access_token}}",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "x-api-key",
            "in": "header",
            "description": "API key for identification",
            "required": true,
            "example": "{{api_key}}",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "x-api-version",
            "in": "header",
            "description": "",
            "required": false,
            "example": "",
            "schema": {
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "@entity": {
                    "type": "string",
                    "enum": [
                      "in.co.sandbox.tds.compliance.deductors.otp.request"
                    ]
                  },
                  "tan": {
                    "description": "TAN of deductor/collector. Regular Expression: [A-Z]{4}[0-9]{5}[A-Z]{1}",
                    "pattern": "[A-Z]{4}[0-9]{5}[A-Z]{1}",
                    "type": "string"
                  },
                  "mobile_number": {
                    "description": "Mobile Number to send the OTP. Pattern: [1-9]{1}[0-9]{9}",
                    "pattern": "[1-9]{1}[0-9]{9}",
                    "type": "string"
                  },
                  "from": {
                    "description": "Date from which challan details are to be fetched. Value in EPOCH timestamp",
                    "type": "integer"
                  },
                  "to": {
                    "description": "Date till which challan details are to be fetched. Value in EPOCH timestamp",
                    "type": "integer"
                  },
                  "consent": {
                    "description": "Consent of the end-user to get their information. Possible values: Y or y",
                    "type": "string"
                  },
                  "reason": {
                    "description": "Indicate the purpose. Min length: 20 characters",
                    "type": "string"
                  }
                },
                "required": [
                  "@entity",
                  "tan",
                  "mobile_number",
                  "from",
                  "to",
                  "consent",
                  "reason"
                ]
              },
              "examples": {
                "200 - Success": {
                  "value": {
                    "@entity": "in.co.sandbox.tds.compliance.deductors.otp.request",
                    "tan": "AHMA09719B",
                    "mobile_number": "1234567890",
                    "from": 1722450600000,
                    "to": 1730313000000,
                    "consent": "Y",
                    "reason": "Download CSI for TDS return filing"
                  },
                  "summary": "200 - Success"
                },
                "200 Invalid TAN": {
                  "value": {
                    "@entity": "in.co.sandbox.tds.compliance.deductors.otp.request",
                    "tan": "AABC23456D",
                    "mobile_number": "1234567890",
                    "from": 1722450600000,
                    "to": 1730313000000,
                    "consent": "Y",
                    "reason": "Download CSI for TDS return filing"
                  },
                  "summary": "200 Invalid TAN"
                },
                "200 OTP already generated": {
                  "value": {
                    "@entity": "in.co.sandbox.tds.compliance.deductors.otp.request",
                    "tan": "PDES03028E",
                    "mobile_number": "1234567890",
                    "from": 1722450600000,
                    "to": 1730313000000,
                    "consent": "Y",
                    "reason": "Download CSI for TDS return filing"
                  },
                  "summary": "200 OTP already generated"
                },
                "422 - Unprocessable Entity": {
                  "value": {
                    "@entity": "in.co.sandbox.tds.compliance.deductors.otp.request",
                    "tan": "DABC2345DD",
                    "mobile_number": "1234567890",
                    "from": 1722450600000,
                    "to": 1730313000000,
                    "consent": "Y",
                    "reason": "Download CSI for TDS return filing"
                  },
                  "summary": "422 - Unprocessable Entity"
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Check the response body for the result. HTTP 200 can also contain an application error in data.message.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "timestamp": {
                      "type": "integer"
                    },
                    "transaction_id": {
                      "type": "string"
                    },
                    "data": {
                      "type": "object",
                      "properties": {
                        "@entity": {
                          "type": "string"
                        },
                        "tan": {
                          "type": "string"
                        },
                        "mobile_number": {
                          "type": "string"
                        },
                        "from": {
                          "type": "integer"
                        },
                        "to": {
                          "type": "integer"
                        },
                        "reference_id": {
                          "type": "string",
                          "description": "Reference ID for the OTP request. Pass this value with the received OTP to verify the request."
                        },
                        "message": {
                          "type": "string",
                          "description": "Result of the OTP request, including any application error."
                        }
                      }
                    },
                    "code": {
                      "type": "integer"
                    }
                  }
                },
                "examples": {
                  "200 - Success": {
                    "summary": "200 - Success",
                    "value": {
                      "timestamp": 1731669661517,
                      "transaction_id": "166148b8-25e3-4ef2-b052-5a27098ebb0e",
                      "data": {
                        "@entity": "in.co.sandbox.tds.compliance.deductors.otp.response",
                        "tan": "AHMA09719B",
                        "mobile_number": "1234567890",
                        "from": 1722450600000,
                        "to": 1730313000000,
                        "reference_id": "FOS005981930273",
                        "message": "OTP sent successfully"
                      },
                      "code": 200
                    }
                  },
                  "200 Invalid TAN": {
                    "summary": "200 Invalid TAN",
                    "value": {
                      "code": 200,
                      "timestamp": 1763362637000,
                      "transaction_id": "e2b9145f-69d5-4bbe-a6de-be6fc08b426f",
                      "data": {
                        "@entity": "in.co.sandbox.tds.compliance.deductors.csi.response",
                        "message": "Invalid TAN"
                      }
                    }
                  },
                  "200 OTP already generated": {
                    "summary": "200 OTP already generated",
                    "value": {
                      "code": 200,
                      "timestamp": 1763362637000,
                      "transaction_id": "e2b9145f-69d5-4bbe-a6de-be6fc08b426f",
                      "data": {
                        "@entity": "in.co.sandbox.tds.compliance.deductors.csi.response",
                        "message": "OTP generated for this TAN, please try after 30 seconds"
                      }
                    }
                  }
                }
              }
            },
            "headers": {}
          },
          "422": {
            "description": "422 - Unprocessable Entity",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "code": {
                      "type": "integer"
                    },
                    "timestamp": {
                      "type": "integer"
                    },
                    "transaction_id": {
                      "type": "string"
                    },
                    "message": {
                      "type": "string"
                    }
                  }
                },
                "examples": {
                  "422 - Unprocessable Entity": {
                    "summary": "422 - Unprocessable Entity",
                    "value": {
                      "code": 422,
                      "timestamp": 1763362637000,
                      "transaction_id": "e2b9145f-69d5-4bbe-a6de-be6fc08b426f",
                      "message": "Invalid TAN pattern"
                    }
                  }
                }
              }
            },
            "headers": {}
          }
        },
        "security": []
      }
    },
    "/tds/compliance/csi/otp/verify": {
      "post": {
        "summary": "Verify OTP for CSI download",
        "deprecated": false,
        "description": "Verify the OTP to download the CSI file.",
        "tags": [
          "Download CSI"
        ],
        "parameters": [
          {
            "name": "authorization",
            "in": "header",
            "description": "JWT access token",
            "required": true,
            "example": "",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "x-api-key",
            "in": "header",
            "description": "API key for identification",
            "required": true,
            "example": "",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "x-api-version",
            "in": "header",
            "description": "",
            "required": false,
            "example": "",
            "schema": {
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "@entity": {
                    "type": "string",
                    "enum": [
                      "in.co.sandbox.tds.compliance.deductors.csi.request"
                    ]
                  },
                  "reference_id": {
                    "type": "string",
                    "description": "The data.reference_id returned by Generate OTP for CSI download."
                  },
                  "otp": {
                    "type": "string",
                    "description": "OTP sent to the mobile number provided in the generation request."
                  }
                },
                "required": [
                  "@entity",
                  "reference_id",
                  "otp"
                ]
              },
              "examples": {
                "200 - Success": {
                  "value": {
                    "@entity": "in.co.sandbox.tds.compliance.deductors.csi.request",
                    "reference_id": "FOS005981930273",
                    "otp": "834201"
                  },
                  "summary": "200 - Success"
                },
                "200 Invalid OTP": {
                  "value": {
                    "@entity": "in.co.sandbox.tds.compliance.deductors.csi.request",
                    "reference_id": "FOS101212121212121",
                    "otp": "121212"
                  },
                  "summary": "200 Invalid OTP"
                },
                "200 OTP Expired": {
                  "value": {
                    "@entity": "in.co.sandbox.tds.compliance.deductors.csi.request",
                    "reference_id": "FOS101212121212121",
                    "otp": "121212"
                  },
                  "summary": "200 OTP Expired"
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Check the response body for the result. HTTP 200 can also contain an application error in data.message.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "timestamp": {
                      "type": "integer"
                    },
                    "transaction_id": {
                      "type": "string"
                    },
                    "data": {
                      "type": "object",
                      "properties": {
                        "@entity": {
                          "type": "string"
                        },
                        "tan": {
                          "type": "string"
                        },
                        "from": {
                          "type": "integer"
                        },
                        "to": {
                          "type": "integer"
                        },
                        "reference_id": {
                          "type": "string",
                          "description": "Reference ID associated with the verified OTP request."
                        },
                        "csi_url": {
                          "type": "string",
                          "description": "Download the CSI file from this URL after successful verification. The example URL is illustrative."
                        },
                        "message": {
                          "type": "string",
                          "description": "Application error message when verification fails, such as an incorrect or expired OTP."
                        }
                      }
                    },
                    "code": {
                      "type": "integer"
                    }
                  }
                },
                "examples": {
                  "200 - Success": {
                    "summary": "200 - Success",
                    "value": {
                      "timestamp": 1731669721578,
                      "transaction_id": "8a0c097f-8e6d-4c11-8228-87d3c8cc44ce",
                      "data": {
                        "@entity": "in.co.sandbox.tds.compliance.deductors.csi.response",
                        "tan": "AHMA09719B",
                        "from": 1722450600000,
                        "to": 1730313000000,
                        "reference_id": "FOS005981930273",
                        "csi_url": "https://example.com/challan.csi"
                      },
                      "code": 200
                    }
                  },
                  "200 Invalid OTP": {
                    "summary": "200 Invalid OTP",
                    "value": {
                      "code": 200,
                      "timestamp": 1763362637000,
                      "transaction_id": "e2b9145f-69d5-4bbe-a6de-be6fc08b426f",
                      "data": {
                        "@entity": "in.co.sandbox.tds.compliance.deductors.csi",
                        "message": "The OTP you have entered is incorrect."
                      }
                    }
                  },
                  "200 OTP Expired": {
                    "summary": "200 OTP Expired",
                    "value": {
                      "code": 200,
                      "timestamp": 1763362637000,
                      "transaction_id": "e2b9145f-69d5-4bbe-a6de-be6fc08b426f",
                      "data": {
                        "@entity": "in.co.sandbox.tds.compliance.deductors.csi",
                        "message": "OTP expired"
                      }
                    }
                  }
                }
              }
            },
            "headers": {}
          }
        },
        "security": []
      }
    },
    "/tds/compliance/fvu/generate": {
      "post": {
        "summary": "Create FVU generation job",
        "deprecated": false,
        "description": "Creates an FVU generation job for a TDS or TCS return. Upload the return text and CSI files to the returned URLs using HTTP PUT. For correction returns, the response also includes a consolidated file upload URL. Use `job_id` to check the validation result.",
        "tags": [
          "FVU Generation"
        ],
        "parameters": [
          {
            "name": "authorization",
            "in": "header",
            "description": "JWT authorization token",
            "required": true,
            "example": "{{access_token}}",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "x-api-key",
            "in": "header",
            "description": "Public key required to authorize API access.",
            "required": true,
            "example": "{{api_key}}",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "x-api-version",
            "in": "header",
            "description": "",
            "required": false,
            "example": "",
            "schema": {
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "@entity": {
                    "type": "string",
                    "enum": [
                      "in.co.sandbox.tds.compliance.fvu.generate.request"
                    ]
                  },
                  "tax_year": {
                    "description": "Tax Year (e.g. TY 2026-27)",
                    "type": "string",
                    "examples": [
                      "TY 2026-27"
                    ],
                    "pattern": "^TY [0-9]{4}-[0-9]{2}$"
                  },
                  "quarter": {
                    "enum": [
                      "Q1",
                      "Q2",
                      "Q3",
                      "Q4"
                    ],
                    "type": "string",
                    "examples": [
                      "Q1"
                    ]
                  },
                  "form": {
                    "enum": [
                      "138",
                      "140",
                      "144",
                      "143"
                    ],
                    "type": "string",
                    "examples": [
                      "140"
                    ],
                    "description": "TDS/TCS return form. Use 138 for erstwhile 24Q, 140 for erstwhile 26Q, 144 for erstwhile 27Q, and 143 for erstwhile 27EQ."
                  },
                  "tan": {
                    "description": "TAN of deductor/collector. Regular Expression: [A-Z]{4}[0-9]{5}[A-Z]{1}",
                    "pattern": "[A-Z]{4}[0-9]{5}[A-Z]{1}",
                    "type": "string"
                  },
                  "filing_type": {
                    "description": "Type of TDS/TCS Return",
                    "enum": [
                      "regular",
                      "correction"
                    ],
                    "type": "string",
                    "examples": [
                      "regular"
                    ]
                  }
                },
                "required": [
                  "@entity",
                  "tax_year",
                  "tan",
                  "form",
                  "quarter",
                  "filing_type"
                ]
              },
              "examples": {
                "200 - Success": {
                  "value": {
                    "@entity": "in.co.sandbox.tds.compliance.fvu.generate.request",
                    "tax_year": "TY 2026-27",
                    "form": "138",
                    "quarter": "Q1",
                    "tan": "AHMQ00112A",
                    "filing_type": "regular"
                  },
                  "summary": "200 - Success"
                },
                "200 Job created for Correction return": {
                  "value": {
                    "@entity": "in.co.sandbox.tds.compliance.fvu.generate.request",
                    "tax_year": "TY 2026-27",
                    "form": "138",
                    "quarter": "Q4",
                    "tan": "AHMA09719B",
                    "filing_type": "correction"
                  },
                  "summary": "200 Job created for Correction return"
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "200 - OK",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "code": {
                      "type": "integer"
                    },
                    "timestamp": {
                      "type": "integer"
                    },
                    "transaction_id": {
                      "type": "string"
                    },
                    "data": {
                      "type": "object",
                      "properties": {
                        "@entity": {
                          "type": "string"
                        },
                        "job_id": {
                          "type": "string",
                          "description": "Job ID used to check status."
                        },
                        "tan": {
                          "type": "string"
                        },
                        "tax_year": {
                          "type": "string",
                          "description": "Tax Year (e.g. TY 2026-27)",
                          "examples": [
                            "TY 2026-27"
                          ],
                          "pattern": "^TY [0-9]{4}-[0-9]{2}$"
                        },
                        "quarter": {
                          "type": "string"
                        },
                        "form": {
                          "type": "string"
                        },
                        "filing_type": {
                          "type": "string"
                        },
                        "status": {
                          "type": "string"
                        },
                        "created_at": {
                          "type": "integer"
                        },
                        "txt_file_upload_url": {
                          "type": "string",
                          "format": "uri",
                          "description": "Pre-signed URL for uploading the return text file with HTTP PUT."
                        },
                        "csi_file_upload_url": {
                          "type": "string",
                          "format": "uri",
                          "description": "Pre-signed URL for uploading the CSI file with HTTP PUT."
                        }
                      }
                    }
                  }
                },
                "examples": {
                  "200 - Success": {
                    "summary": "200 - Success",
                    "value": {
                      "code": 200,
                      "timestamp": 1763362637000,
                      "transaction_id": "e2b9145f-69d5-4bbe-a6de-be6fc08b426f",
                      "data": {
                        "@entity": "in.co.sandbox.tds.compliance.fvu.generate.job",
                        "job_id": "4ef92975-aea8-4628-9eaa-18eb439c13d9",
                        "tan": "AHMA09719B",
                        "tax_year": "TY 2026-27",
                        "quarter": "Q3",
                        "form": "138",
                        "filing_type": "regular",
                        "status": "created",
                        "created_at": 1763362637000,
                        "txt_file_upload_url": "https://in-co-sandbox-tds-test-storage.s3.ap-south-1.amazonaws.com/upload/file",
                        "csi_file_upload_url": "https://in-co-sandbox-tds-test-storage.s3.ap-south-1.amazonaws.com/upload/file"
                      }
                    }
                  },
                  "200 Job created for Correction return": {
                    "summary": "200 Job created for Correction return",
                    "value": {
                      "code": 200,
                      "timestamp": 1763362637000,
                      "transaction_id": "e2b9145f-69d5-4bbe-a6de-be6fc08b426f",
                      "data": {
                        "@entity": "in.co.sandbox.tds.compliance.fvu.generate.job",
                        "job_id": "f845f37e-7f05-4de9-a282-a3b23b9d370a",
                        "tan": "AHMA09719B",
                        "tax_year": "TY 2026-27",
                        "quarter": "Q4",
                        "form": "138",
                        "filing_type": "correction",
                        "status": "created",
                        "created_at": 1763362637000,
                        "txt_file_upload_url": "https://in-co-sandbox-tds-test-storage.s3.ap-south-1.amazonaws.com/upload/file",
                        "csi_file_upload_url": "https://in-co-sandbox-tds-test-storage.s3.ap-south-1.amazonaws.com/upload/file",
                        "conso_file_upload_url": "https://in-co-sandbox-tds-test-storage.s3.ap-south-1.amazonaws.com/upload/file"
                      }
                    }
                  }
                }
              }
            },
            "headers": {}
          }
        },
        "security": []
      },
      "get": {
        "summary": "Get FVU generation job status",
        "deprecated": false,
        "description": "Returns the FVU generation status for `job_id`. On success, download the ZIP from `data.fvu_zip_file_url`. On validation failure, check `data.validation_report_file_url`. HTTP 200 does not mean the job succeeded.",
        "tags": [
          "FVU Generation"
        ],
        "parameters": [
          {
            "name": "job_id",
            "in": "query",
            "description": "Job ID returned when the job was created.",
            "required": false,
            "example": "{{job_id}}",
            "schema": {}
          },
          {
            "name": "authorization",
            "in": "header",
            "description": "JWT authorization token",
            "required": true,
            "example": "{{access_token}}",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "x-api-key",
            "in": "header",
            "description": "Public key required to authorize API access.",
            "required": true,
            "example": "{{api_key}}",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "x-api-version",
            "in": "header",
            "description": "",
            "required": false,
            "example": "",
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "200 - OK",
            "content": {
              "application/json": {
                "schema": {
                  "oneOf": [
                    {
                      "title": "Job Queued",
                      "type": "object",
                      "properties": {
                        "code": {
                          "type": "integer"
                        },
                        "timestamp": {
                          "type": "integer"
                        },
                        "transaction_id": {
                          "type": "string"
                        },
                        "data": {
                          "type": "object",
                          "properties": {
                            "@entity": {
                              "type": "string"
                            },
                            "job_id": {
                              "type": "string",
                              "description": "Job ID used to check status."
                            },
                            "tan": {
                              "type": "string"
                            },
                            "tax_year": {
                              "type": "string",
                              "description": "Tax Year (e.g. TY 2026-27)",
                              "examples": [
                                "TY 2026-27"
                              ],
                              "pattern": "^TY [0-9]{4}-[0-9]{2}$"
                            },
                            "quarter": {
                              "type": "string"
                            },
                            "form": {
                              "type": "string"
                            },
                            "filing_type": {
                              "type": "string"
                            },
                            "status": {
                              "type": "string"
                            },
                            "created_at": {
                              "type": "integer"
                            },
                            "updated_at": {
                              "type": "integer"
                            }
                          }
                        }
                      }
                    },
                    {
                      "title": "Job Succeeded",
                      "type": "object",
                      "properties": {
                        "code": {
                          "type": "integer"
                        },
                        "timestamp": {
                          "type": "integer"
                        },
                        "transaction_id": {
                          "type": "string"
                        },
                        "data": {
                          "type": "object",
                          "properties": {
                            "@entity": {
                              "type": "string"
                            },
                            "job_id": {
                              "type": "string",
                              "description": "Job ID used to check status."
                            },
                            "tan": {
                              "type": "string"
                            },
                            "tax_year": {
                              "type": "string",
                              "description": "Tax Year (e.g. TY 2026-27)",
                              "examples": [
                                "TY 2026-27"
                              ],
                              "pattern": "^TY [0-9]{4}-[0-9]{2}$"
                            },
                            "quarter": {
                              "type": "string"
                            },
                            "form": {
                              "type": "string"
                            },
                            "filing_type": {
                              "type": "string"
                            },
                            "status": {
                              "type": "string"
                            },
                            "created_at": {
                              "type": "integer"
                            },
                            "updated_at": {
                              "type": "integer"
                            },
                            "fvu_zip_file_url": {
                              "type": "string",
                              "format": "uri",
                              "description": "Download URL for the FVU ZIP produced by a successful validation job."
                            }
                          }
                        }
                      }
                    },
                    {
                      "title": "Job Failed",
                      "type": "object",
                      "properties": {
                        "code": {
                          "type": "integer"
                        },
                        "timestamp": {
                          "type": "integer"
                        },
                        "transaction_id": {
                          "type": "string"
                        },
                        "data": {
                          "type": "object",
                          "properties": {
                            "@entity": {
                              "type": "string"
                            },
                            "job_id": {
                              "type": "string",
                              "description": "Job ID used to check status."
                            },
                            "tan": {
                              "type": "string"
                            },
                            "tax_year": {
                              "type": "string",
                              "description": "Tax Year (e.g. TY 2026-27)",
                              "examples": [
                                "TY 2026-27"
                              ],
                              "pattern": "^TY [0-9]{4}-[0-9]{2}$"
                            },
                            "quarter": {
                              "type": "string"
                            },
                            "form": {
                              "type": "string"
                            },
                            "filing_type": {
                              "type": "string"
                            },
                            "status": {
                              "type": "string"
                            },
                            "created_at": {
                              "type": "integer"
                            },
                            "updated_at": {
                              "type": "integer"
                            },
                            "validation_report_file_url": {
                              "type": "string",
                              "format": "uri",
                              "description": "Download URL for the report describing input validation failures."
                            }
                          }
                        }
                      }
                    }
                  ]
                },
                "examples": {
                  "200 - Job Success": {
                    "summary": "200 - Job Success",
                    "value": {
                      "code": 200,
                      "timestamp": 1763362637000,
                      "transaction_id": "e2b9145f-69d5-4bbe-a6de-be6fc08b426f",
                      "data": {
                        "@entity": "in.co.sandbox.tds.compliance.fvu.generate.job",
                        "job_id": "4ef92975-aea8-4628-9eaa-18eb439c13d9",
                        "tan": "AHMA09719B",
                        "tax_year": "TY 2026-27",
                        "quarter": "Q3",
                        "form": "138",
                        "filing_type": "regular",
                        "status": "succeeded",
                        "created_at": 1763362637000,
                        "updated_at": 1763362637000,
                        "fvu_zip_file_url": "https://in-co-sandbox-tds-test-storage.s3.ap-south-1.amazonaws.com/AHMS45586C/FY+2025-26/Q3/140/4049c226-4988-4978-b5ad-d25705453da8/140.zip"
                      }
                    }
                  },
                  "200 Job succeeded for Correction return": {
                    "summary": "200 Job succeeded for Correction return",
                    "value": {
                      "code": 200,
                      "timestamp": 1763362637000,
                      "transaction_id": "e2b9145f-69d5-4bbe-a6de-be6fc08b426f",
                      "data": {
                        "@entity": "in.co.sandbox.tds.compliance.fvu.generate.job",
                        "job_id": "445731fc-f785-4672-989a-6d332149e06f",
                        "tan": "AHMA09719B",
                        "tax_year": "TY 2026-27",
                        "quarter": "Q3",
                        "form": "138",
                        "filing_type": "correction",
                        "status": "succeeded",
                        "created_at": 1763362637000,
                        "updated_at": 1763362637000,
                        "fvu_zip_file_url": "https://in-co-sandbox-tds-compliance-fvu-test.s3.ap-south-1.amazonaws.com/tan/tax_year/quarter/form/f845f37e-7f05-4de9-a282-a3b23b9d370a.zip"
                      }
                    }
                  },
                  "200 - Job Failed": {
                    "summary": "200 - Job Failed",
                    "value": {
                      "code": 200,
                      "timestamp": 1763362637000,
                      "transaction_id": "e2b9145f-69d5-4bbe-a6de-be6fc08b426f",
                      "data": {
                        "@entity": "in.co.sandbox.tds.compliance.fvu.generate.job",
                        "job_id": "7a9176ef-1e59-4b8e-a1de-ee15b09963f8",
                        "tan": "AHMA09719B",
                        "tax_year": "TY 2026-27",
                        "quarter": "Q3",
                        "form": "138",
                        "filing_type": "regular",
                        "status": "failed",
                        "created_at": 1763362637000,
                        "updated_at": 1763362637000,
                        "validation_report_file_url": "https://in-co-sandbox-cms-prod1.s3.ap-south-1.amazonaws.com/test-api-mock/tds/json.json"
                      }
                    }
                  },
                  "200 Job Queued": {
                    "summary": "200 Job Queued",
                    "value": {
                      "code": 200,
                      "timestamp": 1763362637000,
                      "transaction_id": "e2b9145f-69d5-4bbe-a6de-be6fc08b426f",
                      "data": {
                        "@entity": "in.co.sandbox.tds.compliance.fvu.generate.job",
                        "job_id": "db544879-a592-466f-a948-83b5a11cd52d",
                        "tan": "AHMA09719B",
                        "tax_year": "TY 2026-27",
                        "quarter": "Q3",
                        "form": "138",
                        "filing_type": "regular",
                        "status": "queued",
                        "created_at": 1763362637000,
                        "updated_at": 1763362637000
                      }
                    }
                  },
                  "200 Job created": {
                    "summary": "200 Job created",
                    "value": {
                      "code": 200,
                      "timestamp": 1763362637000,
                      "transaction_id": "e2b9145f-69d5-4bbe-a6de-be6fc08b426f",
                      "data": {
                        "@entity": "in.co.sandbox.tds.compliance.fvu.generate.job",
                        "job_id": "a88ce705-e16f-4a44-9b56-273bfbc039d5",
                        "tan": "AHMA09719B",
                        "tax_year": "TY 2026-27",
                        "quarter": "Q3",
                        "form": "138",
                        "filing_type": "regular",
                        "status": "created",
                        "created_at": 1763362637000
                      }
                    }
                  }
                }
              }
            },
            "headers": {}
          },
          "521": {
            "description": "521 - Data Not Found",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "code": {
                      "type": "integer"
                    },
                    "timestamp": {
                      "type": "integer"
                    },
                    "transaction_id": {
                      "type": "string"
                    },
                    "message": {
                      "type": "string",
                      "description": "Reason for the job failure."
                    }
                  }
                },
                "examples": {
                  "521 Data not found": {
                    "summary": "521 Data not found",
                    "value": {
                      "code": 521,
                      "timestamp": 1763362637000,
                      "transaction_id": "e2b9145f-69d5-4bbe-a6de-be6fc08b426f",
                      "message": "Data not found"
                    }
                  }
                }
              }
            },
            "headers": {}
          }
        },
        "security": []
      }
    },
    "/tds/compliance/fvu/generate/search": {
      "post": {
        "summary": "Search FVU generation jobs",
        "deprecated": false,
        "description": "Finds FVU generation jobs by TAN, form, tax year, quarter, filing type, or creation date. Results appear in `data.items`. Set `page_size` to request up to 50 records. Use `last_evaluated_key` for pagination.",
        "tags": [
          "FVU Generation"
        ],
        "parameters": [
          {
            "name": "authorization",
            "in": "header",
            "description": "JWT authorization token",
            "required": true,
            "example": "{{access_token}}",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "x-api-key",
            "in": "header",
            "description": "Public key required to authorize API access.",
            "required": true,
            "example": "{{api_key}}",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "x-api-version",
            "in": "header",
            "description": "",
            "required": false,
            "example": "",
            "schema": {
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "@entity": {
                    "type": "string",
                    "enum": [
                      "in.co.sandbox.tds.compliance.fvu.generate.search"
                    ]
                  },
                  "tax_year": {
                    "description": "Tax Year (e.g. TY 2026-27)",
                    "type": "string",
                    "pattern": "^TY [0-9]{4}-[0-9]{2}$",
                    "examples": [
                      "TY 2026-27"
                    ]
                  },
                  "form": {
                    "description": "TDS return form",
                    "type": "string"
                  },
                  "quarter": {
                    "description": "Quarter (e.g. Q2)",
                    "type": "string"
                  },
                  "tan": {
                    "description": "TAN of deductor/collector. Regular Expression: [A-Z]{4}[0-9]{5}[A-Z]{1}",
                    "type": "string"
                  },
                  "filing_type": {
                    "description": "Type of TDS/TCS Return",
                    "type": "string"
                  },
                  "from_date": {
                    "description": "Start of the job creation-date range, expressed as an epoch timestamp.",
                    "type": "integer"
                  },
                  "to_date": {
                    "description": "End of the job creation-date range, expressed as an epoch timestamp.",
                    "type": "integer"
                  },
                  "page_size": {
                    "description": "Number of records in the API response. Maximum allowed size is 50",
                    "type": "integer"
                  },
                  "last_evaluated_key": {
                    "description": "Base64 encoding of the stringified JSON object, which includes x-api-key, created_at, and job_id",
                    "type": "string"
                  }
                },
                "required": [
                  "@entity"
                ]
              },
              "examples": {
                "Search by TAN and tax period": {
                  "value": {
                    "@entity": "in.co.sandbox.tds.compliance.fvu.generate.search",
                    "tan": "AHMA09719B",
                    "tax_year": "TY 2026-27",
                    "quarter": "Q1",
                    "form": "140",
                    "page_size": 10
                  },
                  "summary": "Search by TAN and tax period"
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "200 - OK",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "code": {
                      "type": "integer"
                    },
                    "timestamp": {
                      "type": "integer"
                    },
                    "data": {
                      "type": "object",
                      "properties": {
                        "@entity": {
                          "type": "string",
                          "enum": [
                            "in.co.sandbox.tds.compliance.fvu.generate.paginated_list"
                          ]
                        },
                        "items": {
                          "type": "array",
                          "items": {
                            "type": "object",
                            "properties": {
                              "created_at": {
                                "type": "integer"
                              },
                              "@entity": {
                                "type": "string"
                              },
                              "job_id": {
                                "type": "string",
                                "description": "Job ID used to check status."
                              },
                              "tan": {
                                "type": "string"
                              },
                              "tax_year": {
                                "type": "string",
                                "description": "Tax Year (e.g. TY 2026-27)",
                                "examples": [
                                  "TY 2026-27"
                                ],
                                "pattern": "^TY [0-9]{4}-[0-9]{2}$"
                              },
                              "quarter": {
                                "type": "string"
                              },
                              "form": {
                                "type": "string"
                              },
                              "filing_type": {
                                "type": "string"
                              },
                              "status": {
                                "type": "string"
                              }
                            }
                          }
                        }
                      }
                    },
                    "transaction_id": {
                      "type": "string"
                    }
                  }
                },
                "examples": {
                  "200 job success": {
                    "summary": "200 job success",
                    "value": {
                      "code": 200,
                      "timestamp": 1763035746825,
                      "data": {
                        "@entity": "in.co.sandbox.tds.compliance.fvu.generate.paginated_list",
                        "items": [
                          {
                            "created_at": 1762511623903,
                            "@entity": "in.co.sandbox.tds.compliance.fvu.generate.job",
                            "job_id": "6622b26a-9601-4692-9c9c-a9b3a1ff8a6e",
                            "tan": "AHMA44270C",
                            "tax_year": "TY 2026-27",
                            "quarter": "Q3",
                            "form": "140",
                            "filing_type": "regular",
                            "status": "created"
                          },
                          {
                            "created_at": 1762238825579,
                            "@entity": "in.co.sandbox.tds.compliance.fvu.generate.job",
                            "job_id": "c4894d31-c59d-4955-b5a8-5c124e3e8072",
                            "tan": "AHMA00000C",
                            "tax_year": "TY 2026-27",
                            "quarter": "Q2",
                            "form": "140",
                            "filing_type": "regular",
                            "status": "created"
                          },
                          {
                            "created_at": 1762238798138,
                            "@entity": "in.co.sandbox.tds.compliance.fvu.generate.job",
                            "job_id": "83526ecf-9401-4472-9894-0dded05a5b2d",
                            "tan": "AHMA00000C",
                            "tax_year": "TY 2026-27",
                            "quarter": "Q2",
                            "form": "140",
                            "filing_type": "regular",
                            "status": "created"
                          },
                          {
                            "created_at": 1761819084423,
                            "updated_at": 1761819130863,
                            "@entity": "in.co.sandbox.tds.compliance.fvu.generate.job",
                            "job_id": "6f006f8d-7680-47de-8982-950a6bba48c2",
                            "tan": "AHMQ00112A",
                            "tax_year": "TY 2026-27",
                            "quarter": "Q2",
                            "form": "140",
                            "filing_type": "regular",
                            "status": "succeeded"
                          },
                          {
                            "created_at": 1761818231823,
                            "updated_at": 1761818280529,
                            "@entity": "in.co.sandbox.tds.compliance.fvu.generate.job",
                            "job_id": "98e92413-b1a1-4f15-9efc-84f0b617dd64",
                            "tan": "AHMQ00112A",
                            "tax_year": "TY 2026-27",
                            "quarter": "Q2",
                            "form": "140",
                            "filing_type": "regular",
                            "status": "failed"
                          },
                          {
                            "created_at": 1761738587585,
                            "updated_at": 1761738622697,
                            "@entity": "in.co.sandbox.tds.compliance.fvu.generate.job",
                            "job_id": "183a31e4-fdc4-437b-8054-f87121af6dcc",
                            "tan": "AHMQ00112A",
                            "tax_year": "TY 2026-27",
                            "quarter": "Q2",
                            "form": "138",
                            "filing_type": "regular",
                            "status": "succeeded"
                          },
                          {
                            "created_at": 1761738584006,
                            "@entity": "in.co.sandbox.tds.compliance.fvu.generate.job",
                            "job_id": "e5142096-8182-46e7-8e19-b12159f8c965",
                            "tan": "AHMQ00112A",
                            "tax_year": "TY 2026-27",
                            "quarter": "Q2",
                            "form": "138",
                            "filing_type": "regular",
                            "status": "created"
                          },
                          {
                            "created_at": 1761737173402,
                            "updated_at": 1761737219289,
                            "@entity": "in.co.sandbox.tds.compliance.fvu.generate.job",
                            "job_id": "1c8fce43-401e-4876-a78d-1043f81a7954",
                            "tan": "AHMQ00112A",
                            "tax_year": "TY 2026-27",
                            "quarter": "Q2",
                            "form": "138",
                            "filing_type": "regular",
                            "message": "Form mismatch",
                            "status": "failed"
                          },
                          {
                            "created_at": 1761732724431,
                            "updated_at": 1761732773453,
                            "@entity": "in.co.sandbox.tds.compliance.fvu.generate.job",
                            "job_id": "5c7dfb7d-7915-42e2-b0d5-7aa93449a648",
                            "tan": "AHMS45586C",
                            "tax_year": "TY 2026-27",
                            "quarter": "Q2",
                            "form": "140",
                            "filing_type": "regular",
                            "status": "succeeded"
                          },
                          {
                            "created_at": 1761659003619,
                            "updated_at": 1761659086073,
                            "@entity": "in.co.sandbox.tds.compliance.fvu.generate.job",
                            "job_id": "2c35a44b-e61b-4a70-9a92-079354710133",
                            "tan": "AHMS45586C",
                            "tax_year": "TY 2026-27",
                            "quarter": "Q2",
                            "form": "138",
                            "filing_type": "regular",
                            "status": "succeeded"
                          },
                          {
                            "created_at": 1761634299914,
                            "updated_at": 1761634345747,
                            "@entity": "in.co.sandbox.tds.compliance.fvu.generate.job",
                            "job_id": "56625794-b1a9-4d7d-a26d-7fcbd18632a7",
                            "tan": "BLRR32170F",
                            "tax_year": "TY 2026-27",
                            "quarter": "Q2",
                            "form": "144",
                            "filing_type": "regular",
                            "status": "succeeded"
                          },
                          {
                            "created_at": 1761571384235,
                            "updated_at": 1761571434955,
                            "@entity": "in.co.sandbox.tds.compliance.fvu.generate.job",
                            "job_id": "e4f848a0-5bb6-448b-ba69-250a38455517",
                            "tan": "DELG20840B",
                            "tax_year": "TY 2026-27",
                            "quarter": "Q2",
                            "form": "144",
                            "filing_type": "regular",
                            "status": "succeeded"
                          },
                          {
                            "created_at": 1761570981608,
                            "updated_at": 1761571018207,
                            "@entity": "in.co.sandbox.tds.compliance.fvu.generate.job",
                            "job_id": "6fe7be04-96db-4b18-90c3-0a8ea7692225",
                            "tan": "DELG20840B",
                            "tax_year": "TY 2026-27",
                            "quarter": "Q2",
                            "form": "144",
                            "filing_type": "regular",
                            "status": "failed"
                          },
                          {
                            "created_at": 1761557897110,
                            "updated_at": 1761557936792,
                            "@entity": "in.co.sandbox.tds.compliance.fvu.generate.job",
                            "job_id": "d281be50-92c7-4b53-ac9f-1b4e61b20dbf",
                            "tan": "BLRV26339F",
                            "tax_year": "TY 2026-27",
                            "quarter": "Q2",
                            "form": "144",
                            "filing_type": "regular",
                            "status": "succeeded"
                          },
                          {
                            "created_at": 1761551312937,
                            "updated_at": 1761551348037,
                            "@entity": "in.co.sandbox.tds.compliance.fvu.generate.job",
                            "job_id": "9b2349d4-a754-4fab-8e7f-320849436709",
                            "tan": "MUMK37337G",
                            "tax_year": "TY 2026-27",
                            "quarter": "Q2",
                            "form": "144",
                            "filing_type": "regular",
                            "status": "succeeded"
                          },
                          {
                            "created_at": 1760539426714,
                            "updated_at": 1760539477220,
                            "@entity": "in.co.sandbox.tds.compliance.fvu.generate.job",
                            "job_id": "410c3dfb-86b1-4f17-bf5e-537485be3979",
                            "tan": "MRTA26471E",
                            "tax_year": "TY 2026-27",
                            "quarter": "Q2",
                            "form": "144",
                            "filing_type": "regular",
                            "status": "succeeded"
                          },
                          {
                            "created_at": 1760015060012,
                            "updated_at": 1760015230331,
                            "@entity": "in.co.sandbox.tds.compliance.fvu.generate.job",
                            "job_id": "5264a512-fba0-408d-8c22-3b1e876248d3",
                            "tan": "MUMP51255B",
                            "tax_year": "TY 2026-27",
                            "quarter": "Q2",
                            "form": "144",
                            "filing_type": "regular",
                            "status": "succeeded"
                          }
                        ]
                      },
                      "transaction_id": "c93b4b70-67e8-4853-9dd4-15d3ef50c5b2"
                    }
                  }
                }
              }
            },
            "headers": {}
          }
        },
        "security": []
      }
    },
    "/tds/traces/deductors/authenticate": {
      "post": {
        "summary": "Authenticate with TRACES",
        "deprecated": false,
        "description": "Authenticate with a deductor TAN and TRACES password to receive access and refresh tokens. Omit pan to use the administrator account. To use a sub-user account, include the sub-user PAN and password. Sub-user access follows the permissions assigned in TRACES. Send your Sandbox API access token in the Authorization header. Example credentials and tokens are illustrative.",
        "operationId": "authenticateTraces",
        "tags": [],
        "parameters": [
          {
            "name": "Authorization",
            "in": "header",
            "description": "Sandbox access token. For token-generation steps, see the [Quickstart guide](https://developer.sandbox.co.in/guides/get-started/quickstart).",
            "required": true,
            "example": "{{access_token}}",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "x-api-key",
            "in": "header",
            "description": "Sandbox API key.",
            "required": true,
            "example": "{{api_key}}",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "Content-Type",
            "in": "header",
            "description": "Request body format.",
            "required": true,
            "example": "application/json",
            "schema": {
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "@entity": {
                    "type": "string",
                    "enum": [
                      "in.co.sandbox.tds.compliance.traces.authentication.request"
                    ]
                  },
                  "tan": {
                    "type": "string",
                    "pattern": "^[A-Z]{4}[0-9]{5}[A-Z]$",
                    "description": "Deductor TAN registered with TRACES."
                  },
                  "password": {
                    "type": "string",
                    "minLength": 1,
                    "writeOnly": true,
                    "description": "TRACES password for the sub-user when pan is provided, or for the administrator when pan is omitted."
                  },
                  "pan": {
                    "type": "string",
                    "pattern": "^[A-Z]{5}[0-9]{4}[A-Z]$",
                    "description": "PAN of the TRACES sub-user. Omit to use the administrator account."
                  }
                },
                "required": [
                  "@entity",
                  "tan",
                  "password"
                ]
              },
              "examples": {
                "Session created": {
                  "summary": "Session created",
                  "description": "A valid TAN and TRACES password return access and refresh tokens. Example credentials and tokens are illustrative.",
                  "value": {
                    "@entity": "in.co.sandbox.tds.compliance.traces.authentication.request",
                    "tan": "AHMA12345A",
                    "password": "your-traces-password"
                  }
                },
                "Missing password": {
                  "summary": "Missing password",
                  "description": "The password field is missing. Include the password for the deductor TAN.",
                  "value": {
                    "@entity": "in.co.sandbox.tds.compliance.traces.authentication.request",
                    "tan": "AHMA12345A"
                  }
                },
                "Incorrect TRACES credentials": {
                  "summary": "Incorrect TRACES credentials",
                  "description": "TRACES rejects the supplied credentials. Check the TAN and password before authenticating again.",
                  "value": {
                    "@entity": "in.co.sandbox.tds.compliance.traces.authentication.request",
                    "tan": "AHMA12345A",
                    "password": "incorrect-example-password"
                  }
                },
                "Missing Sandbox authorization": {
                  "summary": "Missing Sandbox authorization",
                  "description": "The Authorization header is missing. Send the Sandbox access token in this header.",
                  "value": {
                    "@entity": "in.co.sandbox.tds.compliance.traces.authentication.request",
                    "tan": "AHMA12345A",
                    "password": "your-traces-password"
                  }
                },
                "Sub-user session created": {
                  "summary": "Sub-user session created",
                  "description": "An active TRACES sub-user account returns access and refresh tokens. Credentials and tokens in the example are illustrative.",
                  "value": {
                    "@entity": "in.co.sandbox.tds.compliance.traces.authentication.request",
                    "tan": "AHMQ00112A",
                    "pan": "{{traces_sub_user_pan}}",
                    "password": "{{traces_sub_user_password}}"
                  }
                },
                "No active sub-user": {
                  "summary": "No active sub-user",
                  "description": "The TAN has no active sub-user registered with TRACES.",
                  "value": {
                    "@entity": "in.co.sandbox.tds.compliance.traces.authentication.request",
                    "tan": "AHMS45586C",
                    "pan": "{{traces_sub_user_pan}}",
                    "password": "{{traces_sub_user_password}}"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Returns access and refresh tokens for the TRACES session.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "code": {
                      "type": "integer",
                      "enum": [
                        200
                      ]
                    },
                    "timestamp": {
                      "type": "integer",
                      "format": "int64",
                      "description": "Unix timestamp in milliseconds."
                    },
                    "transaction_id": {
                      "type": "string"
                    },
                    "data": {
                      "type": "object",
                      "properties": {
                        "@entity": {
                          "type": "string",
                          "enum": [
                            "in.co.sandbox.tds.compliance.traces.authentication.response"
                          ]
                        },
                        "access_token": {
                          "type": "string",
                          "description": "Deductor access token for TRACES requests. Obtain a token with [Authenticate a TRACES deductor](https://developer.sandbox.co.in/api-reference/tds/compliance/traces/endpoints/authenticate)."
                        },
                        "refresh_token": {
                          "type": "string",
                          "description": "Deductor refresh token used by [Refresh a TRACES deductor session](https://developer.sandbox.co.in/api-reference/tds/compliance/traces/endpoints/refresh) to renew the TRACES session."
                        },
                        "access_token_expiry": {
                          "type": "integer",
                          "format": "int64",
                          "description": "Access token expiry as Unix time in milliseconds."
                        },
                        "refresh_token_expiry": {
                          "type": "integer",
                          "format": "int64",
                          "description": "Refresh token expiry as Unix time in milliseconds."
                        }
                      },
                      "required": [
                        "@entity",
                        "access_token",
                        "refresh_token",
                        "access_token_expiry",
                        "refresh_token_expiry"
                      ]
                    }
                  },
                  "required": [
                    "code",
                    "timestamp",
                    "transaction_id",
                    "data"
                  ]
                },
                "examples": {
                  "Session created": {
                    "summary": "Session created",
                    "description": "A valid TAN and TRACES password return access and refresh tokens. Example credentials and tokens are illustrative.",
                    "value": {
                      "code": 200,
                      "timestamp": 1792176139900,
                      "transaction_id": "198e8f90-691e-4c04-afaf-377611afa55f",
                      "data": {
                        "@entity": "in.co.sandbox.tds.compliance.traces.authentication.response",
                        "access_token": "eyJhbGciOiJSU0FTU0FfUFNTX1NIQV81MTIiLCJ0eXAiOiJKV1QiLCJraWQiOiJleGFtcGxlLXNpZ25pbmcta2V5In0.eyJpc3MiOiJhcGkuc2FuZGJveC5jby5pbiIsImF1ZCI6IkFQSSIsImludGVudCI6IkFDQ0VTU19UT0tFTiIsImlhdCI6MTc5MjE3NjEzOSwiZXhwIjoxNzkyMTc3MDQ3fQ.invalid-example-signature",
                        "refresh_token": "eyJhbGciOiJSU0FTU0FfUFNTX1NIQV81MTIiLCJ0eXAiOiJKV1QiLCJraWQiOiJleGFtcGxlLXNpZ25pbmcta2V5In0.eyJpc3MiOiJhcGkuc2FuZGJveC5jby5pbiIsImF1ZCI6IkFQSSIsImludGVudCI6IlJFRlJFU0hfVE9LRU4iLCJpYXQiOjE3OTIxNzYxMzksImV4cCI6MTc5MjE4MzM0N30.invalid-example-signature",
                        "access_token_expiry": 1792177047000,
                        "refresh_token_expiry": 1792183347000
                      }
                    }
                  },
                  "Sub-user session created": {
                    "summary": "Sub-user session created",
                    "description": "An active TRACES sub-user account returns access and refresh tokens. Credentials and tokens in the example are illustrative.",
                    "value": {
                      "code": 200,
                      "timestamp": 1793006107551,
                      "data": {
                        "@entity": "in.co.sandbox.tds.compliance.traces.authentication.response",
                        "access_token": "your-deductor-access-token",
                        "refresh_token": "your-deductor-refresh-token",
                        "access_token_expiry": 1793007014000,
                        "refresh_token_expiry": 1793013314000
                      },
                      "transaction_id": "902189fe-20da-4a5a-8ea0-5ecc0189c9b5"
                    }
                  }
                }
              }
            }
          },
          "400": {
            "description": "The request body is invalid, the TAN is not registered with TRACES, or the TAN has no active sub-user.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "code": {
                      "type": "integer"
                    },
                    "timestamp": {
                      "type": "integer",
                      "format": "int64",
                      "description": "Unix timestamp in milliseconds."
                    },
                    "transaction_id": {
                      "type": "string"
                    },
                    "message": {
                      "type": "string"
                    }
                  },
                  "required": [
                    "code",
                    "timestamp",
                    "transaction_id",
                    "message"
                  ]
                },
                "examples": {
                  "Missing password": {
                    "summary": "Missing password",
                    "description": "The password field is missing. Include the password for the deductor TAN.",
                    "value": {
                      "code": 400,
                      "timestamp": 1792176147907,
                      "transaction_id": "807b7940-d53e-4a19-8ead-718fcaa5868d",
                      "message": "Invalid request body"
                    }
                  },
                  "No active sub-user": {
                    "summary": "No active sub-user",
                    "description": "The TAN has no active sub-user registered with TRACES.",
                    "value": {
                      "code": 400,
                      "timestamp": 1793006237476,
                      "message": "There is no active Sub-user for the entered TAN, please retry.",
                      "transaction_id": "8a33c4f9-0bc3-46cd-99c0-67b80e91f9f7"
                    }
                  }
                }
              }
            }
          },
          "401": {
            "description": "TRACES rejected the credentials, or the Sandbox Authorization header is missing.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "code": {
                      "type": "integer"
                    },
                    "timestamp": {
                      "type": "integer",
                      "format": "int64",
                      "description": "Unix timestamp in milliseconds."
                    },
                    "transaction_id": {
                      "type": "string"
                    },
                    "message": {
                      "type": "string"
                    }
                  },
                  "required": [
                    "code",
                    "timestamp",
                    "transaction_id",
                    "message"
                  ]
                },
                "examples": {
                  "Incorrect TRACES credentials": {
                    "summary": "Incorrect TRACES credentials",
                    "description": "TRACES rejects the supplied credentials. Check the TAN and password before authenticating again.",
                    "value": {
                      "code": 401,
                      "timestamp": 1792176148207,
                      "transaction_id": "b7000183-316b-46b3-a7b9-494f9d16a995",
                      "message": "Invalid credentials"
                    }
                  },
                  "Missing Sandbox authorization": {
                    "summary": "Missing Sandbox authorization",
                    "description": "The Authorization header is missing. Send the Sandbox access token in this header.",
                    "value": {
                      "code": 401,
                      "timestamp": 1792176151923,
                      "transaction_id": "e1dab6c2-d333-41a3-815b-932f869708e4",
                      "message": "Unauthorized"
                    }
                  }
                }
              }
            }
          },
          "403": {
            "description": "The Sandbox API key or access token is invalid.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "code": {
                      "type": "integer"
                    },
                    "timestamp": {
                      "type": "integer",
                      "format": "int64",
                      "description": "Unix timestamp in milliseconds."
                    },
                    "transaction_id": {
                      "type": "string"
                    },
                    "message": {
                      "type": "string"
                    }
                  },
                  "required": [
                    "code",
                    "timestamp",
                    "transaction_id",
                    "message"
                  ]
                }
              }
            }
          },
          "500": {
            "description": "TRACES authentication could not be completed. Retry the request.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "code": {
                      "type": "integer"
                    },
                    "timestamp": {
                      "type": "integer",
                      "format": "int64",
                      "description": "Unix timestamp in milliseconds."
                    },
                    "transaction_id": {
                      "type": "string"
                    },
                    "message": {
                      "type": "string"
                    }
                  },
                  "required": [
                    "code",
                    "timestamp",
                    "transaction_id",
                    "message"
                  ]
                }
              }
            }
          }
        },
        "security": []
      }
    },
    "/tds/traces/deductors/refresh": {
      "post": {
        "summary": "Refresh TRACES session",
        "deprecated": false,
        "description": "Refresh a TRACES deductor session using the deductor refresh token returned by [Authenticate a TRACES deductor](https://developer.sandbox.co.in/api-reference/tds/compliance/traces/endpoints/authenticate). Send the token in the Authorization header with your Sandbox API key. This request has no body. Replace both saved deductor tokens with the returned values. If the refresh token has expired or is rejected, authenticate again.",
        "operationId": "refreshTracesSession",
        "tags": [],
        "parameters": [
          {
            "name": "Authorization",
            "in": "header",
            "description": "Deductor refresh token returned by [Authenticate a TRACES deductor](https://developer.sandbox.co.in/api-reference/tds/compliance/traces/endpoints/authenticate) or this endpoint. Send the token without a Bearer prefix.",
            "required": true,
            "schema": {
              "type": "string"
            },
            "examples": {
              "Session refreshed": {
                "summary": "Session refreshed",
                "value": "{{deductor_refresh_token}}"
              },
              "Missing refresh token": {
                "summary": "Missing refresh token",
                "description": "Omit the Authorization header.",
                "value": ""
              },
              "Invalid refresh token": {
                "summary": "Invalid refresh token",
                "value": "invalid-deductor-refresh-token"
              },
              "Access token used for refresh": {
                "summary": "Access token used for refresh",
                "description": "An access token cannot refresh a session.",
                "value": "{{deductor_access_token}}"
              }
            }
          },
          {
            "name": "x-api-key",
            "in": "header",
            "description": "Sandbox API key.",
            "required": true,
            "schema": {
              "type": "string"
            },
            "examples": {
              "Session refreshed": {
                "summary": "Session refreshed",
                "value": "{{api_key}}"
              },
              "Missing refresh token": {
                "summary": "Missing refresh token",
                "value": "{{api_key}}"
              },
              "Invalid refresh token": {
                "summary": "Invalid refresh token",
                "value": "{{api_key}}"
              },
              "Access token used for refresh": {
                "summary": "Access token used for refresh",
                "value": "{{api_key}}"
              }
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Returns replacement access and refresh tokens for the TRACES session.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "code": {
                      "type": "integer",
                      "enum": [
                        200
                      ]
                    },
                    "timestamp": {
                      "type": "integer",
                      "format": "int64",
                      "description": "Unix timestamp in milliseconds."
                    },
                    "transaction_id": {
                      "type": "string"
                    },
                    "data": {
                      "type": "object",
                      "properties": {
                        "@entity": {
                          "type": "string",
                          "enum": [
                            "in.co.sandbox.tds.compliance.traces.authentication.response"
                          ]
                        },
                        "access_token": {
                          "type": "string",
                          "description": "Deductor access token for TRACES requests. Obtain a token with [Authenticate a TRACES deductor](https://developer.sandbox.co.in/api-reference/tds/compliance/traces/endpoints/authenticate)."
                        },
                        "refresh_token": {
                          "type": "string",
                          "description": "Deductor refresh token used by [Refresh a TRACES deductor session](https://developer.sandbox.co.in/api-reference/tds/compliance/traces/endpoints/refresh) to renew the TRACES session."
                        },
                        "access_token_expiry": {
                          "type": "integer",
                          "format": "int64",
                          "description": "Access token expiry as Unix time in milliseconds."
                        },
                        "refresh_token_expiry": {
                          "type": "integer",
                          "format": "int64",
                          "description": "Refresh token expiry as Unix time in milliseconds."
                        }
                      },
                      "required": [
                        "@entity",
                        "access_token",
                        "refresh_token",
                        "access_token_expiry",
                        "refresh_token_expiry"
                      ]
                    }
                  },
                  "required": [
                    "code",
                    "timestamp",
                    "transaction_id",
                    "data"
                  ]
                },
                "examples": {
                  "Session refreshed": {
                    "summary": "Session refreshed",
                    "description": "Returns replacement deductor tokens.",
                    "value": {
                      "code": 200,
                      "timestamp": 1792176147631,
                      "transaction_id": "068a8718-9122-47b4-8e2f-56635d6299ed",
                      "data": {
                        "@entity": "in.co.sandbox.tds.compliance.traces.authentication.response",
                        "access_token": "eyJhbGciOiJSU0FTU0FfUFNTX1NIQV81MTIiLCJ0eXAiOiJKV1QiLCJraWQiOiJleGFtcGxlLXNpZ25pbmcta2V5In0.eyJpc3MiOiJhcGkuc2FuZGJveC5jby5pbiIsImF1ZCI6IkFQSSIsImludGVudCI6IkFDQ0VTU19UT0tFTiIsImlhdCI6MTc5MjE3NjE0NywiZXhwIjoxNzkyMTc3MDQ3fQ.invalid-example-signature",
                        "refresh_token": "eyJhbGciOiJSU0FTU0FfUFNTX1NIQV81MTIiLCJ0eXAiOiJKV1QiLCJraWQiOiJleGFtcGxlLXNpZ25pbmcta2V5In0.eyJpc3MiOiJhcGkuc2FuZGJveC5jby5pbiIsImF1ZCI6IkFQSSIsImludGVudCI6IlJFRlJFU0hfVE9LRU4iLCJpYXQiOjE3OTIxNzYxNDcsImV4cCI6MTc5MjE4MzM0N30.invalid-example-signature",
                        "access_token_expiry": 1792177047000,
                        "refresh_token_expiry": 1792183347000
                      }
                    }
                  }
                }
              }
            }
          },
          "401": {
            "description": "The Authorization header is missing, or TRACES rejected the session refresh token. Authenticate again if the refresh token is rejected.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "code": {
                      "type": "integer"
                    },
                    "timestamp": {
                      "type": "integer",
                      "format": "int64",
                      "description": "Unix timestamp in milliseconds."
                    },
                    "transaction_id": {
                      "type": "string"
                    },
                    "message": {
                      "type": "string"
                    }
                  },
                  "required": [
                    "code",
                    "timestamp",
                    "transaction_id",
                    "message"
                  ]
                },
                "examples": {
                  "Missing refresh token": {
                    "summary": "Missing refresh token",
                    "description": "The Authorization header is missing.",
                    "value": {
                      "code": 401,
                      "timestamp": 1792176148027,
                      "transaction_id": "8a0adb97-61cb-4004-99ac-069d98c91ecf",
                      "message": "Unauthorized"
                    }
                  }
                }
              }
            }
          },
          "403": {
            "description": "The deductor token or API key is not authorized for this request.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "code": {
                      "type": "integer"
                    },
                    "timestamp": {
                      "type": "integer",
                      "format": "int64",
                      "description": "Unix timestamp in milliseconds."
                    },
                    "transaction_id": {
                      "type": "string"
                    },
                    "message": {
                      "type": "string"
                    }
                  },
                  "required": [
                    "code",
                    "timestamp",
                    "transaction_id",
                    "message"
                  ]
                },
                "examples": {
                  "Invalid refresh token": {
                    "summary": "Invalid refresh token",
                    "description": "The Authorization header contains an invalid token.",
                    "value": {
                      "code": 403,
                      "timestamp": 1792176151795,
                      "transaction_id": "557c2e5a-357c-4fe3-ad65-139206bfef85",
                      "message": "Insufficient privilege"
                    }
                  },
                  "Access token used for refresh": {
                    "summary": "Access token used for refresh",
                    "description": "An access token cannot refresh a session.",
                    "value": {
                      "code": 403,
                      "timestamp": 1792176151991,
                      "transaction_id": "1cfa715f-1a5a-452e-8843-b8e860e17fc1",
                      "message": "Insufficient privilege"
                    }
                  }
                }
              }
            }
          },
          "500": {
            "description": "The TRACES session could not be refreshed. Retry the request.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "code": {
                      "type": "integer"
                    },
                    "timestamp": {
                      "type": "integer",
                      "format": "int64",
                      "description": "Unix timestamp in milliseconds."
                    },
                    "transaction_id": {
                      "type": "string"
                    },
                    "message": {
                      "type": "string"
                    }
                  },
                  "required": [
                    "code",
                    "timestamp",
                    "transaction_id",
                    "message"
                  ]
                },
                "examples": {}
              }
            }
          }
        },
        "security": []
      }
    },
    "/tds/compliance/enriched/traces/deductor/certificates/{certificate_type}/status": {
      "get": {
        "summary": "Get certificate job status",
        "deprecated": false,
        "description": "Get the current status of a certificate generation job using its job_id and certificate type. A succeeded job includes signed URLs for the certificate ZIP files. A failed job includes a message describing the failure.",
        "operationId": "GetCertificateJobStatus",
        "tags": [],
        "parameters": [
          {
            "name": "certificate_type",
            "in": "path",
            "description": "Certificate type. Use 130 for salary TDS, 131 for other TDS, or 133 for TCS.",
            "required": true,
            "example": "131",
            "schema": {
              "type": "string",
              "enum": [
                "130",
                "131",
                "133"
              ]
            }
          },
          {
            "name": "job_id",
            "in": "query",
            "description": "Unique identifier returned when the certificate job was created.",
            "required": true,
            "example": "{{job_id}}",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "x-api-version",
            "in": "header",
            "description": "API version for the request.",
            "required": true,
            "example": "{{api_version}}",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "Authorization",
            "in": "header",
            "description": "JWT access token. For token-generation steps, refer to the [Quickstart Guide](https://developer.sandbox.co.in/guides/get-started/quickstart).",
            "required": true,
            "example": "{{access_token}}",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "x-api-key",
            "in": "header",
            "description": "API key used to identify and authenticate the client.",
            "required": true,
            "example": "{{api_key}}",
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "code": {
                      "type": "integer"
                    },
                    "timestamp": {
                      "type": "integer"
                    },
                    "data": {
                      "type": "object",
                      "properties": {
                        "@entity": {
                          "type": "string",
                          "description": "Certificate job entity type."
                        },
                        "job_id": {
                          "type": "string",
                          "description": "Unique identifier for the certificate job."
                        },
                        "tan": {
                          "type": "string",
                          "description": "Tax Deduction and Collection Account Number (TAN)."
                        },
                        "tax_year": {
                          "type": "string",
                          "description": "Tax year for the certificate job, in TY YYYY-YY format."
                        },
                        "quarter": {
                          "type": "string",
                          "enum": [
                            "Q1",
                            "Q2",
                            "Q3",
                            "Q4"
                          ],
                          "description": "Quarter of the tax year."
                        },
                        "created_at": {
                          "type": "integer",
                          "description": "Job creation time as a Unix timestamp in milliseconds."
                        },
                        "updated_at": {
                          "type": "integer",
                          "description": "Last job update time as a Unix timestamp in milliseconds, when available."
                        },
                        "status": {
                          "type": "string",
                          "enum": [
                            "created",
                            "queued",
                            "in_progress",
                            "succeeded",
                            "failed"
                          ],
                          "description": "Current status of the certificate job."
                        },
                        "message": {
                          "type": "string",
                          "description": "Reason the job failed, when available."
                        },
                        "certificate_pdf_zip_urls": {
                          "type": "array",
                          "description": "Signed URLs for the certificate ZIP files, available after the job succeeds.",
                          "items": {
                            "type": "string",
                            "format": "uri"
                          }
                        }
                      },
                      "required": [
                        "@entity",
                        "job_id",
                        "tan",
                        "tax_year",
                        "quarter",
                        "status"
                      ]
                    },
                    "transaction_id": {
                      "type": "string"
                    }
                  },
                  "required": [
                    "code",
                    "timestamp",
                    "data",
                    "transaction_id"
                  ]
                },
                "examples": {
                  "Failed to submit certificate job": {
                    "summary": "Failed to submit certificate job",
                    "value": {
                      "code": 200,
                      "timestamp": 1788762887353,
                      "data": {
                        "created_at": 1788762771957,
                        "updated_at": 1788762775867,
                        "@entity": "in.co.sandbox.tds.compliance.certificate.job",
                        "job_id": "b88f494e-e60c-407c-aca4-09676d1c1f9b",
                        "tan": "AHMS45586C",
                        "tax_year": "TY 2026-27",
                        "quarter": "Q1",
                        "message": "Failed to submit the certificate job",
                        "status": "failed"
                      },
                      "transaction_id": "a0a12a28-82bb-4fab-bdb2-2b314c97deba"
                    }
                  },
                  "Certificate generated": {
                    "summary": "Certificate generated",
                    "value": {
                      "code": 200,
                      "timestamp": 1788764430169,
                      "data": {
                        "created_at": 1788763729910,
                        "updated_at": 1788763734899,
                        "@entity": "in.co.sandbox.tds.compliance.certificate.job",
                        "job_id": "745cde57-7a6a-42db-b940-e83eea6b817b",
                        "tan": "AHMS45586C",
                        "tax_year": "TY 2026-27",
                        "quarter": "Q1",
                        "certificate_pdf_zip_urls": [
                          "https://in-co-sandbox-tds-test-storage.s3.ap-south-1.amazonaws.com/AHMS45586C/TY+2026-27/1_AHMxxxxx6C_FORM131_2026_Q1_certificate.zip"
                        ],
                        "status": "succeeded"
                      },
                      "transaction_id": "cdb8d7a8-95d3-44c9-a28d-a69c5dd74588"
                    }
                  },
                  "Status Queued": {
                    "summary": "Status Queued",
                    "value": {
                      "code": 200,
                      "timestamp": 1788764483668,
                      "data": {
                        "created_at": 1788764478529,
                        "updated_at": 1788764480520,
                        "@entity": "in.co.sandbox.tds.compliance.certificate.job",
                        "job_id": "26a67dd9-70a8-4ec6-be9a-869191cbd9bf",
                        "tan": "AHMS45586C",
                        "tax_year": "TY 2026-27",
                        "quarter": "Q1",
                        "status": "queued"
                      },
                      "transaction_id": "4dd921f2-aa17-4f8e-9365-15fb1397f2bc"
                    }
                  },
                  "Status In progress": {
                    "summary": "Status In progress",
                    "value": {
                      "code": 200,
                      "timestamp": 1788764514931,
                      "data": {
                        "created_at": 1788764478529,
                        "updated_at": 1788764480520,
                        "@entity": "in.co.sandbox.tds.compliance.certificate.job",
                        "job_id": "26a67dd9-70a8-4ec6-be9a-869191cbd9bf",
                        "tan": "AHMS45586C",
                        "tax_year": "TY 2026-27",
                        "quarter": "Q1",
                        "status": "in_progress"
                      },
                      "transaction_id": "fb474b02-bc0e-419e-a506-57de18ee554e"
                    }
                  },
                  "Credentials not found": {
                    "summary": "Credentials not found",
                    "value": {
                      "code": 200,
                      "timestamp": 1788765768854,
                      "data": {
                        "created_at": 1788765755936,
                        "updated_at": 1788765759820,
                        "@entity": "in.co.sandbox.tds.compliance.certificate.job",
                        "job_id": "70c7df85-8860-4d61-b168-4881cb48792f",
                        "tan": "AHMS45586C",
                        "tax_year": "TY 2026-27",
                        "quarter": "Q1",
                        "message": "Credentials not found",
                        "status": "failed"
                      },
                      "transaction_id": "a970bc6d-42b6-4f31-b1d8-257a574c7168"
                    }
                  },
                  "Certificate not available": {
                    "summary": "Certificate not available",
                    "value": {
                      "code": 200,
                      "timestamp": 1788770774783,
                      "data": {
                        "created_at": 1788770757399,
                        "updated_at": 1788770762605,
                        "@entity": "in.co.sandbox.tds.compliance.certificate.job",
                        "job_id": "d09bba2a-3302-4469-a784-b72924e6bce2",
                        "tan": "AHMS45586C",
                        "tax_year": "TY 2026-27",
                        "quarter": "Q1",
                        "message": "No statement is available for the selected period. Please choose a valid period to generate the certificate.",
                        "status": "failed"
                      },
                      "transaction_id": "b6109848-9f6d-47d3-b47c-82b039935a86"
                    }
                  },
                  "Invalid Credentials": {
                    "summary": "Invalid Credentials",
                    "value": {
                      "code": 200,
                      "timestamp": 1788770965182,
                      "data": {
                        "created_at": 1788770941288,
                        "updated_at": 1788770941436,
                        "@entity": "in.co.sandbox.tds.compliance.certificate.job",
                        "job_id": "e75e7d3d-0a44-4454-bfa5-3a2ce3caa2a0",
                        "tan": "AHMS45586C",
                        "tax_year": "TY 2026-27",
                        "quarter": "Q1",
                        "message": "Invalid credentials",
                        "status": "failed"
                      },
                      "transaction_id": "607e51d9-803e-4422-802d-9933c1388007"
                    }
                  }
                }
              }
            },
            "headers": {}
          },
          "521": {
            "description": "",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "code": {
                      "type": "integer"
                    },
                    "timestamp": {
                      "type": "integer"
                    },
                    "message": {
                      "type": "string"
                    },
                    "transaction_id": {
                      "type": "string"
                    }
                  },
                  "required": [
                    "code",
                    "timestamp",
                    "message",
                    "transaction_id"
                  ]
                },
                "examples": {
                  "Data Not Found": {
                    "summary": "Data Not Found",
                    "value": {
                      "code": 521,
                      "timestamp": 1788765830963,
                      "message": "Data not found",
                      "transaction_id": "6bc012e4-e16f-4814-a809-710479da3334"
                    }
                  }
                }
              }
            },
            "headers": {}
          }
        },
        "security": []
      }
    },
    "/tds/compliance/enriched/traces/deductor/certificates/{certificate_type}": {
      "post": {
        "summary": "Create TDS or TCS certificate job",
        "deprecated": false,
        "description": "Create a certificate generation job for a TAN, tax year, and quarter. Select the certificate type in the path: 130 for salary TDS, 131 for other TDS, or 133 for TCS. Save TRACES credentials for the TAN before creating the job. Use the returned job_id to check its status.",
        "operationId": "SubmitCertificateJob",
        "tags": [
          "TDS",
          "TDS Certificate"
        ],
        "parameters": [
          {
            "name": "certificate_type",
            "in": "path",
            "description": "Certificate type. Use 130 for salary TDS, 131 for other TDS, or 133 for TCS.",
            "required": true,
            "example": "131",
            "schema": {
              "type": "string",
              "enum": [
                "130",
                "131",
                "133"
              ]
            }
          },
          {
            "name": "Authorization",
            "in": "header",
            "description": "JWT access token. For token-generation steps, refer to the [Quickstart Guide](https://developer.sandbox.co.in/guides/get-started/quickstart).",
            "required": true,
            "example": "{{access_token}}",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "x-api-key",
            "in": "header",
            "description": "API key used to identify and authenticate the client.",
            "required": true,
            "example": "{{api_key}}",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "Content-Type",
            "in": "header",
            "description": "Request body format.",
            "required": true,
            "example": "application/json",
            "schema": {
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "@entity": {
                    "type": "string",
                    "description": "Request entity type.",
                    "examples": [
                      "in.co.sandbox.tds.compliance.certificate.job.request"
                    ],
                    "const": "in.co.sandbox.tds.compliance.certificate.job.request"
                  },
                  "quarter": {
                    "type": "string",
                    "description": "Quarter of the tax year.",
                    "enum": [
                      "Q1",
                      "Q2",
                      "Q3",
                      "Q4"
                    ]
                  },
                  "tax_year": {
                    "type": "string",
                    "description": "Tax year for the certificate request. Use the TY YYYY-YY format.",
                    "examples": [
                      "TY 2026-27"
                    ],
                    "pattern": "^TY [0-9]{4}-[0-9]{2}$"
                  },
                  "tan": {
                    "type": "string",
                    "description": "Tax Deduction and Collection Account Number (TAN).",
                    "examples": [
                      "AHMS45586C"
                    ],
                    "pattern": "^[A-Z]{4}[0-9]{5}[A-Z]$"
                  }
                },
                "required": [
                  "@entity",
                  "quarter",
                  "tax_year",
                  "tan"
                ],
                "additionalProperties": false
              },
              "examples": {
                "Submit form 133 job": {
                  "value": {
                    "@entity": "in.co.sandbox.tds.compliance.certificate.job.request",
                    "quarter": "Q1",
                    "tax_year": "TY 2026-27",
                    "tan": "AHMS45586C"
                  },
                  "summary": "Submit form 133 job"
                },
                "Submit form 131 job": {
                  "value": {
                    "@entity": "in.co.sandbox.tds.compliance.certificate.job.request",
                    "quarter": "Q1",
                    "tax_year": "TY 2026-27",
                    "tan": "AHMS45586C"
                  },
                  "summary": "Submit form 131 job"
                },
                "Invalid Request Body": {
                  "value": {
                    "@entity": "in.co.sandbox.tds.compliance.certificate.job.request",
                    "quarter": "Q1",
                    "tax_year": "FY 2026-27",
                    "tan": "AHMS45586C"
                  },
                  "summary": "Invalid Request Body"
                }
              }
            }
          },
          "required": true
        },
        "responses": {
          "200": {
            "description": "Certificate generation job created.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "code": {
                      "type": "integer"
                    },
                    "timestamp": {
                      "type": "integer"
                    },
                    "data": {
                      "type": "object",
                      "properties": {
                        "@entity": {
                          "type": "string",
                          "description": "Certificate job entity type."
                        },
                        "job_id": {
                          "type": "string",
                          "description": "Unique identifier for the certificate job."
                        },
                        "tan": {
                          "type": "string",
                          "description": "Tax Deduction and Collection Account Number (TAN)."
                        },
                        "tax_year": {
                          "type": "string",
                          "description": "Tax year for the certificate job, in TY YYYY-YY format."
                        },
                        "quarter": {
                          "type": "string",
                          "enum": [
                            "Q1",
                            "Q2",
                            "Q3",
                            "Q4"
                          ],
                          "description": "Quarter of the tax year."
                        },
                        "created_at": {
                          "type": "integer",
                          "description": "Job creation time as a Unix timestamp in milliseconds."
                        },
                        "updated_at": {
                          "type": "integer",
                          "description": "Last job update time as a Unix timestamp in milliseconds, when available."
                        },
                        "status": {
                          "type": "string",
                          "enum": [
                            "created",
                            "queued",
                            "in_progress",
                            "succeeded",
                            "failed"
                          ],
                          "description": "Current status of the certificate job."
                        },
                        "message": {
                          "type": "string",
                          "description": "Reason the job failed, when available."
                        },
                        "certificate_pdf_zip_urls": {
                          "type": "array",
                          "description": "Signed URLs for the certificate ZIP files, available after the job succeeds.",
                          "items": {
                            "type": "string",
                            "format": "uri"
                          }
                        }
                      },
                      "required": [
                        "@entity",
                        "job_id",
                        "tan",
                        "tax_year",
                        "quarter",
                        "status"
                      ]
                    },
                    "transaction_id": {
                      "type": "string",
                      "description": "Unique identifier for the API transaction."
                    }
                  },
                  "required": [
                    "code",
                    "timestamp",
                    "data",
                    "transaction_id"
                  ]
                },
                "examples": {
                  "Submit form 133 job": {
                    "summary": "Submit form 133 job",
                    "value": {
                      "code": 200,
                      "timestamp": 1788770941235,
                      "data": {
                        "created_at": 1788770941288,
                        "@entity": "in.co.sandbox.tds.compliance.certificate.job",
                        "job_id": "e75e7d3d-0a44-4454-bfa5-3a2ce3caa2a0",
                        "tan": "AHMS45586C",
                        "tax_year": "TY 2026-27",
                        "quarter": "Q1",
                        "status": "created"
                      },
                      "transaction_id": "e75e7d3d-0a44-4454-bfa5-3a2ce3caa2a0"
                    }
                  },
                  "Submit form 131 job": {
                    "summary": "Submit form 131 job",
                    "value": {
                      "code": 200,
                      "timestamp": 1788771381210,
                      "data": {
                        "created_at": 1788771384109,
                        "@entity": "in.co.sandbox.tds.compliance.certificate.job",
                        "job_id": "518bf6d5-be9d-4723-8fee-2382919fb605",
                        "tan": "AHMS45586C",
                        "tax_year": "TY 2026-27",
                        "quarter": "Q1",
                        "status": "created"
                      },
                      "transaction_id": "518bf6d5-be9d-4723-8fee-2382919fb605"
                    }
                  }
                }
              }
            },
            "headers": {}
          },
          "400": {
            "description": "The request body or certificate parameters are invalid.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "code": {
                      "type": "integer"
                    },
                    "timestamp": {
                      "type": "integer"
                    },
                    "message": {
                      "type": "string"
                    },
                    "transaction_id": {
                      "type": "string"
                    }
                  },
                  "required": [
                    "code",
                    "timestamp",
                    "message",
                    "transaction_id"
                  ]
                },
                "examples": {
                  "Invalid Request Body": {
                    "summary": "Invalid Request Body",
                    "value": {
                      "code": 400,
                      "timestamp": 1788771428630,
                      "message": "Invalid request body",
                      "transaction_id": "934e030b-e094-4533-84ad-8e68d234a6db"
                    }
                  }
                }
              }
            },
            "headers": {}
          }
        },
        "security": []
      }
    },
    "/tds/compliance/enriched/traces/deductor/certificates/{certificate_type}/search": {
      "post": {
        "summary": "Search certificate jobs",
        "deprecated": false,
        "description": "Search certificate jobs for the selected certificate type. Filter by TAN, tax year, quarter, status, and creation dates. Send last_evaluated_key from a response to retrieve the next page.",
        "operationId": "SearchCertificateJobs",
        "tags": [
          "TDS",
          "TDS Certificate"
        ],
        "parameters": [
          {
            "name": "certificate_type",
            "in": "path",
            "description": "Certificate type. Use 130 for salary TDS, 131 for other TDS, or 133 for TCS.",
            "required": true,
            "example": "131",
            "schema": {
              "type": "string",
              "enum": [
                "130",
                "131",
                "133"
              ]
            }
          },
          {
            "name": "x-api-version",
            "in": "header",
            "description": "API version for the request.",
            "required": false,
            "example": "{{api_version}}",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "x-api-key",
            "in": "header",
            "description": "API key used to identify and authenticate the client.",
            "required": true,
            "example": "{{api_key}}",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "Authorization",
            "in": "header",
            "description": "JWT access token. For token-generation steps, refer to the [Quickstart Guide](https://developer.sandbox.co.in/guides/get-started/quickstart).",
            "required": true,
            "example": "{{access_token}}",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "Content-Type",
            "in": "header",
            "description": "Request body format.",
            "required": true,
            "example": "application/json",
            "schema": {
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/CertificateJobSearchRequest"
              },
              "examples": {
                "Success with Last evaluated key": {
                  "value": {
                    "@entity": "in.co.sandbox.tds.compliance.certificate.job.search",
                    "tan": "AHMS45586C",
                    "tax_year": "TY 2026-27",
                    "quarter": "Q1",
                    "page_size": 5,
                    "last_evaluated_key": "eyJqb2JfaWQiOiI3NDVjZGU1Ny03YTZhLTQyZGItYjk0MC1lODNlZWE2YjgxN2IiLCJ3b3Jrc3BhY2VfaWQiOiJkYzQ5NTdlZC1kZTBlLTQyYzctODBkZC04MjIxY2VlOGNkYTAiLCJjcmVhdGVkX2F0IjoxNzg4NzYzNzI5OTEwfQ=="
                  },
                  "summary": "Success with Last evaluated key"
                },
                "Success without jobs": {
                  "value": {
                    "@entity": "in.co.sandbox.tds.compliance.certificate.job.search",
                    "tan": "AHMS45586C",
                    "tax_year": "TY 2026-27",
                    "quarter": "Q1",
                    "page_size": 5
                  },
                  "summary": "Success without jobs"
                },
                "Failure Invalid Request Body": {
                  "value": {
                    "@entity": "in.co.sandbox.tds.compliance.certificate.job.search",
                    "tan": "AHMS45586C",
                    "tax_year": "FY 2026-27",
                    "quarter": "Q1",
                    "page_size": 5
                  },
                  "summary": "Failure Invalid Request Body"
                }
              }
            }
          },
          "required": true
        },
        "responses": {
          "200": {
            "description": "Certificate generation jobs returned.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "code": {
                      "type": "integer"
                    },
                    "timestamp": {
                      "type": "integer"
                    },
                    "transaction_id": {
                      "type": "string"
                    },
                    "data": {
                      "type": "object",
                      "properties": {
                        "@entity": {
                          "type": "string",
                          "description": "Response entity type."
                        },
                        "items": {
                          "type": "array",
                          "description": "Certificate jobs that match the search criteria.",
                          "items": {
                            "type": "object",
                            "properties": {
                              "@entity": {
                                "type": "string",
                                "description": "Certificate job entity type."
                              },
                              "job_id": {
                                "type": "string",
                                "description": "Unique identifier for the certificate job."
                              },
                              "tan": {
                                "type": "string",
                                "description": "Tax Deduction and Collection Account Number (TAN)."
                              },
                              "tax_year": {
                                "type": "string",
                                "description": "Tax year for the certificate job, in TY YYYY-YY format."
                              },
                              "quarter": {
                                "type": "string",
                                "enum": [
                                  "Q1",
                                  "Q2",
                                  "Q3",
                                  "Q4"
                                ],
                                "description": "Quarter of the tax year."
                              },
                              "created_at": {
                                "type": "integer",
                                "description": "Job creation time as a Unix timestamp in milliseconds."
                              },
                              "updated_at": {
                                "type": "integer",
                                "description": "Last job update time as a Unix timestamp in milliseconds, when available."
                              },
                              "status": {
                                "type": "string",
                                "enum": [
                                  "created",
                                  "queued",
                                  "in_progress",
                                  "succeeded",
                                  "failed"
                                ],
                                "description": "Current status of the certificate job."
                              },
                              "message": {
                                "type": "string",
                                "description": "Reason the job failed, when available."
                              },
                              "certificate_pdf_zip_urls": {
                                "type": "array",
                                "description": "Signed URLs for the certificate ZIP files, available after the job succeeds.",
                                "items": {
                                  "type": "string",
                                  "format": "uri"
                                }
                              }
                            },
                            "required": [
                              "@entity",
                              "job_id",
                              "tan",
                              "tax_year",
                              "quarter",
                              "status"
                            ]
                          }
                        },
                        "last_evaluated_key": {
                          "type": "string",
                          "description": "Opaque pagination cursor. Send this value in the next search request to retrieve the next page."
                        }
                      },
                      "required": [
                        "@entity",
                        "items"
                      ]
                    }
                  },
                  "required": [
                    "code",
                    "timestamp",
                    "transaction_id",
                    "data"
                  ]
                },
                "examples": {
                  "Success with Last evaluated key": {
                    "summary": "Success with Last evaluated key",
                    "value": {
                      "code": 200,
                      "timestamp": 1788772789304,
                      "data": {
                        "@entity": "in.co.sandbox.tds.compliance.certificate.paginated_list",
                        "last_evaluated_key": "eyJ3b3Jrc3BhY2VfaWQiOiJkYzQ5NTdlZC1kZTBlLTQyYzctODBkZC04MjIxY2VlOGNkYTAiLCJjcmVhdGVkX2F0IjoxNzg4NzA0OTg0MjM0LCJqb2JfaWQiOiJhZDcxNGFkMy03Y2QyLTQ2YWEtYTNiMy1jZTY2Njg2MDMxN2YifQ==",
                        "items": [
                          {
                            "created_at": 1788762771957,
                            "updated_at": 1788762775867,
                            "@entity": "in.co.sandbox.tds.compliance.certificate.job",
                            "job_id": "b88f494e-e60c-407c-aca4-09676d1c1f9b",
                            "tan": "AHMS45586C",
                            "tax_year": "TY 2026-27",
                            "quarter": "Q1",
                            "message": "Failed to submit the certificate job",
                            "status": "failed"
                          },
                          {
                            "created_at": 1788761715040,
                            "updated_at": 1788761718733,
                            "@entity": "in.co.sandbox.tds.compliance.certificate.job",
                            "job_id": "b2050206-7c13-4669-a82a-ce58b5622585",
                            "tan": "AHMS45586C",
                            "tax_year": "TY 2026-27",
                            "quarter": "Q1",
                            "status": "succeeded"
                          },
                          {
                            "created_at": 1788713969000,
                            "updated_at": 1788713973336,
                            "@entity": "in.co.sandbox.tds.compliance.certificate.job",
                            "job_id": "94f0447c-62d4-4521-8af7-390de5c837d1",
                            "tan": "AHMS45586C",
                            "tax_year": "TY 2026-27",
                            "quarter": "Q1",
                            "status": "succeeded"
                          },
                          {
                            "created_at": 1788713289073,
                            "updated_at": 1788713294413,
                            "@entity": "in.co.sandbox.tds.compliance.certificate.job",
                            "job_id": "5d3a9031-46c7-4fa9-b2f5-cac1fccf4d95",
                            "tan": "AHMS45586C",
                            "tax_year": "TY 2026-27",
                            "quarter": "Q1",
                            "message": "Failed to submit the certificate job",
                            "status": "failed"
                          },
                          {
                            "created_at": 1788704984234,
                            "updated_at": 1788704988663,
                            "@entity": "in.co.sandbox.tds.compliance.certificate.job",
                            "job_id": "ad714ad3-7cd2-46aa-a3b3-ce666860317f",
                            "tan": "AHMS45586C",
                            "tax_year": "TY 2026-27",
                            "quarter": "Q1",
                            "message": "Failed to submit the certificate job",
                            "status": "failed"
                          }
                        ]
                      },
                      "transaction_id": "d1ff4c62-8aa7-4ae6-8b4d-1c46727e58e2"
                    }
                  },
                  "Success without jobs": {
                    "summary": "Success without jobs",
                    "value": {
                      "code": 200,
                      "timestamp": 1788773983947,
                      "data": {
                        "@entity": "in.co.sandbox.tds.compliance.certificate.paginated_list",
                        "items": []
                      },
                      "transaction_id": "04c20a08-c90c-495c-8404-4eeb827c766b"
                    }
                  }
                }
              }
            },
            "headers": {}
          },
          "400": {
            "description": "Invalid request body.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "code": {
                      "type": "integer"
                    },
                    "timestamp": {
                      "type": "integer"
                    },
                    "message": {
                      "type": "string"
                    },
                    "transaction_id": {
                      "type": "string"
                    }
                  },
                  "required": [
                    "code",
                    "timestamp",
                    "message",
                    "transaction_id"
                  ]
                },
                "examples": {
                  "Failure Invalid Request Body": {
                    "summary": "Failure Invalid Request Body",
                    "value": {
                      "code": 400,
                      "timestamp": 1788774038411,
                      "message": "Invalid request body",
                      "transaction_id": "3d6295b8-901e-404c-950b-da09692f46e9"
                    }
                  }
                }
              }
            },
            "headers": {}
          }
        },
        "security": []
      }
    },
    "/tds/traces/deductors/credential": {
      "post": {
        "summary": "Add TRACES credentials",
        "deprecated": false,
        "description": "Store one TRACES credential for a deductor TAN in your workspace. Omit pan to use the administrator account. To use a sub-user account, include the sub-user PAN and password. Enriched TRACES APIs use the stored account and its assigned permissions. To replace the stored account, delete the existing credential before you add another.",
        "operationId": "AddTracesCredentials",
        "tags": [
          "TRACES Credentials"
        ],
        "parameters": [
          {
            "name": "Authorization",
            "in": "header",
            "description": "JWT access token. For token-generation steps, refer to the [Quickstart Guide](https://developer.sandbox.co.in/guides/get-started/quickstart).",
            "required": true,
            "example": "{{access_token}}",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "x-api-key",
            "in": "header",
            "description": "API key used to identify and authenticate the client.",
            "required": true,
            "example": "{{api_key}}",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "Content-Type",
            "in": "header",
            "description": "Request body format.",
            "required": true,
            "example": "application/json",
            "schema": {
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "@entity": {
                    "type": "string",
                    "description": "Entity identifier for the request."
                  },
                  "tan": {
                    "type": "string",
                    "description": "TAN for the TRACES account."
                  },
                  "pan": {
                    "type": "string",
                    "pattern": "^[A-Z]{5}[0-9]{4}[A-Z]$",
                    "description": "PAN of the TRACES sub-user. Omit to use the administrator account."
                  },
                  "password": {
                    "type": "string",
                    "format": "password",
                    "writeOnly": true,
                    "description": "TRACES password for the sub-user when pan is provided, or for the administrator when pan is omitted."
                  }
                },
                "required": [
                  "@entity",
                  "tan",
                  "password"
                ]
              },
              "examples": {
                "Success": {
                  "value": {
                    "@entity": "in.co.sandbox.tds.traces.deductor.credential.request",
                    "tan": "AHMS45586C",
                    "password": "{{password}}"
                  },
                  "summary": "Success"
                },
                "Failure: Invalid Request Body": {
                  "value": {
                    "@entity": "in.co.sandbox.tds.traces.deductor.credential.request",
                    "tan": "AHMS45586C"
                  },
                  "summary": "Failure: Invalid Request Body"
                },
                "Failure: Credential already exists": {
                  "value": {
                    "@entity": "in.co.sandbox.tds.traces.deductor.credential.request",
                    "tan": "AHMS45586C",
                    "password": "{{password}}"
                  },
                  "summary": "Failure: Credential already exists"
                },
                "Sub-user credentials added": {
                  "value": {
                    "@entity": "in.co.sandbox.tds.traces.deductor.credential.request",
                    "tan": "AHMQ00112A",
                    "pan": "{{traces_sub_user_pan}}",
                    "password": "{{traces_sub_user_password}}"
                  },
                  "summary": "Sub-user credentials added",
                  "description": "The sub-user credential is stored for the deductor TAN. Delete an existing credential before you add another."
                }
              }
            }
          },
          "required": true
        },
        "responses": {
          "200": {
            "description": "The TRACES credentials were added.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "code": {
                      "type": "integer"
                    },
                    "timestamp": {
                      "type": "integer"
                    },
                    "transaction_id": {
                      "type": "string"
                    }
                  },
                  "required": [
                    "code",
                    "timestamp",
                    "transaction_id"
                  ]
                },
                "examples": {
                  "Success": {
                    "summary": "Success",
                    "value": {
                      "code": 200,
                      "timestamp": 1788414642383,
                      "transaction_id": "45a5d0e7-d428-47c3-906e-b039d0e4e157"
                    }
                  },
                  "Sub-user credentials added": {
                    "summary": "Sub-user credentials added",
                    "value": {
                      "code": 200,
                      "timestamp": 1793006237023,
                      "transaction_id": "612d5613-e113-4943-a239-cceb2e4e21f8"
                    }
                  }
                }
              }
            },
            "headers": {}
          },
          "400": {
            "description": "The request body is invalid.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "code": {
                      "type": "integer"
                    },
                    "timestamp": {
                      "type": "integer"
                    },
                    "message": {
                      "type": "string"
                    },
                    "transaction_id": {
                      "type": "string"
                    }
                  },
                  "required": [
                    "code",
                    "timestamp",
                    "message",
                    "transaction_id"
                  ]
                },
                "examples": {
                  "Failure: Invalid Request Body": {
                    "summary": "Failure: Invalid Request Body",
                    "value": {
                      "code": 400,
                      "timestamp": 1788414799493,
                      "message": "Invalid request body",
                      "transaction_id": "1113442c-0914-42d5-91e8-c372f67f902f"
                    }
                  }
                }
              }
            },
            "headers": {}
          },
          "409": {
            "description": "Credentials already exist for the TAN. Delete the existing credentials before you add new credentials.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "code": {
                      "type": "integer"
                    },
                    "timestamp": {
                      "type": "integer"
                    },
                    "message": {
                      "type": "string"
                    },
                    "transaction_id": {
                      "type": "string"
                    }
                  },
                  "required": [
                    "code",
                    "timestamp",
                    "message",
                    "transaction_id"
                  ]
                },
                "examples": {
                  "Failure: Credential already exists": {
                    "summary": "Failure: Credential already exists",
                    "value": {
                      "code": 409,
                      "timestamp": 1788415156044,
                      "message": "TRACES credential already exists",
                      "transaction_id": "57e1ee72-71ae-4c5d-bc6b-eab44cccab3c"
                    }
                  }
                }
              }
            },
            "headers": {}
          }
        },
        "security": []
      },
      "delete": {
        "summary": "Delete TRACES credentials",
        "deprecated": false,
        "description": "Delete the TRACES login credentials for a TAN. Add the credentials again before you use an API that requires TRACES access for the TAN.",
        "operationId": "DeleteTracesCredentials",
        "tags": [
          "TRACES Credentials"
        ],
        "parameters": [
          {
            "name": "x-api-key",
            "in": "header",
            "description": "API key used to identify and authenticate the client.",
            "required": true,
            "example": "{{api_key}}",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "Authorization",
            "in": "header",
            "description": "JWT access token. For token-generation steps, refer to the [Quickstart Guide](https://developer.sandbox.co.in/guides/get-started/quickstart).",
            "required": true,
            "example": "{{access_token}}",
            "schema": {
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "@entity": {
                    "type": "string",
                    "description": "Entity identifier for the request."
                  },
                  "tan": {
                    "type": "string",
                    "description": "TAN for the TRACES account."
                  }
                },
                "required": [
                  "@entity",
                  "tan"
                ]
              },
              "examples": {
                "Success": {
                  "value": {
                    "@entity": "in.co.sandbox.tds.traces.deductor.credential.delete.request",
                    "tan": "AHMS45586C"
                  },
                  "summary": "Success"
                }
              }
            }
          },
          "required": true
        },
        "responses": {
          "200": {
            "description": "The credentials were deleted or did not exist.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "code": {
                      "type": "integer"
                    },
                    "timestamp": {
                      "type": "integer"
                    },
                    "transaction_id": {
                      "type": "string"
                    }
                  },
                  "required": [
                    "code",
                    "timestamp",
                    "transaction_id"
                  ]
                },
                "examples": {
                  "Success": {
                    "summary": "Success",
                    "value": {
                      "code": 200,
                      "timestamp": 1788414871321,
                      "transaction_id": "cc440798-8d60-4346-9622-527861e626ea"
                    }
                  }
                }
              }
            },
            "headers": {}
          }
        },
        "security": []
      }
    },
    "/tds/compliance/traces/deductor/certificates/{certificate_type}": {
      "post": {
        "summary": "Create TDS or TCS certificate job",
        "deprecated": false,
        "description": "Create a certificate job for the deductor identified by your access token. Use certificate type 131 for TDS on non-salary payments or 133 for TCS. The response includes a job_id and the current job status. Use the status endpoint to check progress and retrieve signed download URLs when the certificate ZIP files are ready.",
        "operationId": "SubmitVanillaCertificateJob",
        "tags": [
          "TDS Certificate"
        ],
        "parameters": [
          {
            "name": "certificate_type",
            "in": "path",
            "description": "Certificate type. Use 131 for TDS on non-salary payments or 133 for TCS.",
            "required": true,
            "example": "131",
            "schema": {
              "type": "string",
              "enum": [
                "131",
                "133"
              ]
            }
          },
          {
            "name": "Authorization",
            "in": "header",
            "description": "Deductor access token returned by [Authenticate a TRACES deductor](https://developer.sandbox.co.in/api-reference/tds/compliance/traces/endpoints/authenticate). The token identifies the deductor TAN.",
            "required": true,
            "example": "{{deductor_access_token}}",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "x-api-key",
            "in": "header",
            "description": "Sandbox API key.",
            "required": true,
            "example": "{{api_key}}",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "Content-Type",
            "in": "header",
            "description": "Request body format.",
            "required": true,
            "example": "application/json",
            "schema": {
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "@entity": {
                    "type": "string",
                    "description": "Request entity type.",
                    "examples": [
                      "in.co.sandbox.tds.compliance.certificate.job.request"
                    ],
                    "const": "in.co.sandbox.tds.compliance.certificate.job.request"
                  },
                  "tax_year": {
                    "type": "string",
                    "description": "Tax year for the certificate request. Use the TY YYYY-YY format.",
                    "examples": [
                      "TY 2026-27"
                    ],
                    "pattern": "^TY [0-9]{4}-[0-9]{2}$"
                  },
                  "quarter": {
                    "type": "string",
                    "description": "Quarter of the tax year.",
                    "enum": [
                      "Q1",
                      "Q2",
                      "Q3",
                      "Q4"
                    ]
                  }
                },
                "required": [
                  "@entity",
                  "quarter",
                  "tax_year"
                ],
                "additionalProperties": false
              },
              "examples": {
                "Non-salary TDS certificates requested": {
                  "value": {
                    "@entity": "in.co.sandbox.tds.compliance.certificate.job.request",
                    "tax_year": "TY 2026-27",
                    "quarter": "Q1"
                  },
                  "summary": "Non-salary TDS certificates requested"
                },
                "TCS certificates requested": {
                  "value": {
                    "@entity": "in.co.sandbox.tds.compliance.certificate.job.request",
                    "tax_year": "TY 2026-27",
                    "quarter": "Q1"
                  },
                  "summary": "TCS certificates requested"
                },
                "Quarter is missing": {
                  "value": {
                    "@entity": "in.co.sandbox.tds.compliance.certificate.job.request",
                    "tax_year": "TY 2026-27"
                  },
                  "summary": "Quarter is missing"
                },
                "Deductor access token is missing": {
                  "value": {
                    "@entity": "in.co.sandbox.tds.compliance.certificate.job.request",
                    "tax_year": "TY 2026-27",
                    "quarter": "Q1"
                  },
                  "summary": "Deductor access token is missing"
                },
                "Deductor access token has expired": {
                  "value": {
                    "@entity": "in.co.sandbox.tds.compliance.certificate.job.request",
                    "tax_year": "TY 2026-27",
                    "quarter": "Q1"
                  },
                  "summary": "Deductor access token has expired"
                }
              }
            }
          },
          "required": true
        },
        "responses": {
          "200": {
            "description": "Certificate generation job created.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "code": {
                      "type": "integer"
                    },
                    "timestamp": {
                      "type": "integer"
                    },
                    "data": {
                      "type": "object",
                      "properties": {
                        "@entity": {
                          "type": "string",
                          "description": "Certificate job entity type."
                        },
                        "job_id": {
                          "type": "string",
                          "description": "Unique identifier for the certificate job."
                        },
                        "tan": {
                          "type": "string",
                          "description": "Tax Deduction and Collection Account Number (TAN)."
                        },
                        "tax_year": {
                          "type": "string",
                          "description": "Tax year for the certificate job, in TY YYYY-YY format."
                        },
                        "quarter": {
                          "type": "string",
                          "enum": [
                            "Q1",
                            "Q2",
                            "Q3",
                            "Q4"
                          ],
                          "description": "Quarter of the tax year."
                        },
                        "created_at": {
                          "type": "integer",
                          "description": "Job creation time as a Unix timestamp in milliseconds."
                        },
                        "updated_at": {
                          "type": "integer",
                          "description": "Last job update time as a Unix timestamp in milliseconds, when available."
                        },
                        "status": {
                          "type": "string",
                          "enum": [
                            "created",
                            "queued",
                            "in_progress",
                            "succeeded",
                            "failed"
                          ],
                          "description": "Current status of the certificate job."
                        },
                        "message": {
                          "type": "string",
                          "description": "Reason the job failed, when available."
                        },
                        "certificate_pdf_zip_urls": {
                          "type": "array",
                          "description": "Signed URLs for the certificate ZIP files, available after the job succeeds.",
                          "items": {
                            "type": "string",
                            "format": "uri"
                          }
                        }
                      },
                      "required": [
                        "@entity",
                        "job_id",
                        "tan",
                        "tax_year",
                        "quarter",
                        "status"
                      ]
                    },
                    "transaction_id": {
                      "type": "string",
                      "description": "Unique identifier for the API transaction."
                    }
                  },
                  "required": [
                    "code",
                    "timestamp",
                    "data",
                    "transaction_id"
                  ]
                },
                "examples": {
                  "Non-salary TDS certificates requested": {
                    "summary": "Non-salary TDS certificates requested",
                    "value": {
                      "code": 200,
                      "timestamp": 1792479600000,
                      "data": {
                        "@entity": "in.co.sandbox.tds.compliance.certificate.job",
                        "job_id": "4d882797-f968-474e-b05b-85cb5eba3d9a",
                        "tan": "AHMA12345A",
                        "tax_year": "TY 2026-27",
                        "quarter": "Q1",
                        "created_at": 1792479600000,
                        "updated_at": 1792479600000,
                        "status": "in_progress"
                      },
                      "transaction_id": "171f4869-bcd6-4f7d-905a-b1186b907857"
                    }
                  },
                  "TCS certificates requested": {
                    "summary": "TCS certificates requested",
                    "value": {
                      "code": 200,
                      "timestamp": 1792479600000,
                      "data": {
                        "@entity": "in.co.sandbox.tds.compliance.certificate.job",
                        "job_id": "4d882797-f968-474e-b05b-85cb5eba3d9a",
                        "tan": "AHMA12345A",
                        "tax_year": "TY 2026-27",
                        "quarter": "Q1",
                        "created_at": 1792479600000,
                        "updated_at": 1792479600000,
                        "status": "in_progress"
                      },
                      "transaction_id": "171f4869-bcd6-4f7d-905a-b1186b907857"
                    }
                  }
                }
              }
            },
            "headers": {}
          },
          "400": {
            "description": "The request body or certificate type is invalid.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "code": {
                      "type": "integer"
                    },
                    "timestamp": {
                      "type": "integer"
                    },
                    "message": {
                      "type": "string"
                    },
                    "transaction_id": {
                      "type": "string"
                    }
                  },
                  "required": [
                    "code",
                    "timestamp",
                    "message",
                    "transaction_id"
                  ]
                },
                "examples": {
                  "Quarter is missing": {
                    "summary": "Quarter is missing",
                    "value": {
                      "code": 400,
                      "timestamp": 1792479600000,
                      "message": "Invalid request body",
                      "transaction_id": "171f4869-bcd6-4f7d-905a-b1186b907857"
                    }
                  }
                }
              }
            },
            "headers": {}
          },
          "401": {
            "description": "The deductor access token is missing.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "code": {
                      "type": "integer"
                    },
                    "timestamp": {
                      "type": "integer"
                    },
                    "message": {
                      "type": "string"
                    },
                    "transaction_id": {
                      "type": "string"
                    }
                  },
                  "required": [
                    "code",
                    "timestamp",
                    "message",
                    "transaction_id"
                  ]
                },
                "examples": {
                  "Deductor access token is missing": {
                    "summary": "Deductor access token is missing",
                    "value": {
                      "code": 401,
                      "timestamp": 1792479600000,
                      "message": "Unauthorized",
                      "transaction_id": "171f4869-bcd6-4f7d-905a-b1186b907857"
                    }
                  }
                }
              }
            },
            "headers": {}
          },
          "403": {
            "description": "The deductor access token has expired, or the API key or deductor token does not permit this request.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "code": {
                      "type": "integer"
                    },
                    "timestamp": {
                      "type": "integer"
                    },
                    "message": {
                      "type": "string"
                    },
                    "transaction_id": {
                      "type": "string"
                    }
                  },
                  "required": [
                    "code",
                    "timestamp",
                    "message",
                    "transaction_id"
                  ]
                },
                "examples": {
                  "Deductor access token has expired": {
                    "summary": "Deductor access token has expired",
                    "value": {
                      "code": 403,
                      "timestamp": 1792479600000,
                      "message": "Insufficient privilege",
                      "transaction_id": "171f4869-bcd6-4f7d-905a-b1186b907857"
                    }
                  }
                }
              }
            },
            "headers": {}
          },
          "500": {
            "description": "The request could not be completed.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "code": {
                      "type": "integer"
                    },
                    "timestamp": {
                      "type": "integer"
                    },
                    "message": {
                      "type": "string"
                    },
                    "transaction_id": {
                      "type": "string"
                    }
                  },
                  "required": [
                    "code",
                    "timestamp",
                    "message",
                    "transaction_id"
                  ]
                }
              }
            },
            "headers": {}
          },
          "503": {
            "description": "TRACES is temporarily unavailable.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "code": {
                      "type": "integer"
                    },
                    "timestamp": {
                      "type": "integer"
                    },
                    "message": {
                      "type": "string"
                    },
                    "transaction_id": {
                      "type": "string"
                    }
                  },
                  "required": [
                    "code",
                    "timestamp",
                    "message",
                    "transaction_id"
                  ]
                }
              }
            },
            "headers": {}
          }
        },
        "security": []
      }
    },
    "/tds/compliance/traces/deductor/certificates/{certificate_type}/status": {
      "get": {
        "summary": "Get certificate job status",
        "deprecated": false,
        "description": "Get the current status of a certificate job using its job_id and certificate type. The response has status in_progress while the certificates are being prepared. A succeeded job includes signed URLs for the PDF ZIP files. A failed job includes a message describing the failure. Refresh your deductor access token if it expires, then repeat the request with the same job_id.",
        "operationId": "GetVanillaCertificateJobStatus",
        "tags": [
          "TDS Certificate"
        ],
        "parameters": [
          {
            "name": "certificate_type",
            "in": "path",
            "description": "Certificate type. Use 131 for TDS on non-salary payments or 133 for TCS.",
            "required": true,
            "example": "131",
            "schema": {
              "type": "string",
              "enum": [
                "131",
                "133"
              ]
            }
          },
          {
            "name": "job_id",
            "in": "query",
            "description": "Unique identifier returned when the certificate job was created.",
            "required": true,
            "schema": {
              "type": "string"
            },
            "examples": {
              "Certificates are being prepared": {
                "summary": "Certificates are being prepared",
                "value": "4d882797-f968-474e-b05b-85cb5eba3d9a"
              },
              "Certificates are ready": {
                "summary": "Certificates are ready",
                "value": "4d882797-f968-474e-b05b-85cb5eba3d9a"
              },
              "Certificate generation failed": {
                "summary": "Certificate generation failed",
                "value": "4d882797-f968-474e-b05b-85cb5eba3d9a"
              },
              "Job was not found": {
                "summary": "Job was not found",
                "value": "00000000-0000-4000-8000-000000000000"
              },
              "Deductor access token is missing": {
                "summary": "Deductor access token is missing",
                "value": "4d882797-f968-474e-b05b-85cb5eba3d9a"
              }
            }
          },
          {
            "name": "Authorization",
            "in": "header",
            "description": "Deductor access token returned by [Authenticate a TRACES deductor](https://developer.sandbox.co.in/api-reference/tds/compliance/traces/endpoints/authenticate). The token identifies the deductor TAN.",
            "required": true,
            "example": "{{deductor_access_token}}",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "x-api-key",
            "in": "header",
            "description": "Sandbox API key.",
            "required": true,
            "example": "{{api_key}}",
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Certificate job status and available download URLs.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "code": {
                      "type": "integer"
                    },
                    "timestamp": {
                      "type": "integer"
                    },
                    "data": {
                      "type": "object",
                      "properties": {
                        "@entity": {
                          "type": "string",
                          "description": "Certificate job entity type."
                        },
                        "job_id": {
                          "type": "string",
                          "description": "Unique identifier for the certificate job."
                        },
                        "tan": {
                          "type": "string",
                          "description": "Tax Deduction and Collection Account Number (TAN)."
                        },
                        "tax_year": {
                          "type": "string",
                          "description": "Tax year for the certificate job, in TY YYYY-YY format."
                        },
                        "quarter": {
                          "type": "string",
                          "enum": [
                            "Q1",
                            "Q2",
                            "Q3",
                            "Q4"
                          ],
                          "description": "Quarter of the tax year."
                        },
                        "created_at": {
                          "type": "integer",
                          "description": "Job creation time as a Unix timestamp in milliseconds."
                        },
                        "updated_at": {
                          "type": "integer",
                          "description": "Last job update time as a Unix timestamp in milliseconds, when available."
                        },
                        "status": {
                          "type": "string",
                          "enum": [
                            "created",
                            "queued",
                            "in_progress",
                            "succeeded",
                            "failed"
                          ],
                          "description": "Current status of the certificate job."
                        },
                        "message": {
                          "type": "string",
                          "description": "Reason the job failed, when available."
                        },
                        "certificate_pdf_zip_urls": {
                          "type": "array",
                          "description": "Signed URLs for the certificate ZIP files, available after the job succeeds.",
                          "items": {
                            "type": "string",
                            "format": "uri"
                          }
                        }
                      },
                      "required": [
                        "@entity",
                        "job_id",
                        "tan",
                        "tax_year",
                        "quarter",
                        "status"
                      ]
                    },
                    "transaction_id": {
                      "type": "string"
                    }
                  },
                  "required": [
                    "code",
                    "timestamp",
                    "data",
                    "transaction_id"
                  ]
                },
                "examples": {
                  "Certificates are being prepared": {
                    "summary": "Certificates are being prepared",
                    "value": {
                      "code": 200,
                      "timestamp": 1792479600000,
                      "data": {
                        "@entity": "in.co.sandbox.tds.compliance.certificate.job",
                        "job_id": "4d882797-f968-474e-b05b-85cb5eba3d9a",
                        "tan": "AHMA12345A",
                        "tax_year": "TY 2026-27",
                        "quarter": "Q1",
                        "created_at": 1792479600000,
                        "updated_at": 1792479600000,
                        "status": "in_progress"
                      },
                      "transaction_id": "171f4869-bcd6-4f7d-905a-b1186b907857"
                    }
                  },
                  "Certificates are ready": {
                    "summary": "Certificates are ready",
                    "value": {
                      "code": 200,
                      "timestamp": 1792479600000,
                      "data": {
                        "@entity": "in.co.sandbox.tds.compliance.certificate.job",
                        "job_id": "4d882797-f968-474e-b05b-85cb5eba3d9a",
                        "tan": "AHMA12345A",
                        "tax_year": "TY 2026-27",
                        "quarter": "Q1",
                        "created_at": 1792479600000,
                        "updated_at": 1792479600000,
                        "status": "succeeded",
                        "certificate_pdf_zip_urls": [
                          "https://example-bucket.s3.ap-south-1.amazonaws.com/workspace-id/job-id/certificates.zip?X-Amz-Expires=86400&X-Amz-Signature=example"
                        ]
                      },
                      "transaction_id": "171f4869-bcd6-4f7d-905a-b1186b907857"
                    }
                  },
                  "Certificate generation failed": {
                    "summary": "Certificate generation failed",
                    "value": {
                      "code": 200,
                      "timestamp": 1792479600000,
                      "data": {
                        "@entity": "in.co.sandbox.tds.compliance.certificate.job",
                        "job_id": "4d882797-f968-474e-b05b-85cb5eba3d9a",
                        "tan": "AHMA12345A",
                        "tax_year": "TY 2026-27",
                        "quarter": "Q1",
                        "created_at": 1792479600000,
                        "updated_at": 1792479600000,
                        "status": "failed",
                        "message": "Failed to generate certificate PDFs"
                      },
                      "transaction_id": "171f4869-bcd6-4f7d-905a-b1186b907857"
                    }
                  }
                }
              }
            },
            "headers": {}
          },
          "400": {
            "description": "Required request parameters are missing, or the certificate type is not supported.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "code": {
                      "type": "integer"
                    },
                    "timestamp": {
                      "type": "integer"
                    },
                    "message": {
                      "type": "string"
                    },
                    "transaction_id": {
                      "type": "string"
                    }
                  },
                  "required": [
                    "code",
                    "timestamp",
                    "message",
                    "transaction_id"
                  ]
                }
              }
            },
            "headers": {}
          },
          "401": {
            "description": "The deductor access token is missing.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "code": {
                      "type": "integer"
                    },
                    "timestamp": {
                      "type": "integer"
                    },
                    "message": {
                      "type": "string"
                    },
                    "transaction_id": {
                      "type": "string"
                    }
                  },
                  "required": [
                    "code",
                    "timestamp",
                    "message",
                    "transaction_id"
                  ]
                },
                "examples": {
                  "Deductor access token is missing": {
                    "summary": "Deductor access token is missing",
                    "value": {
                      "code": 401,
                      "timestamp": 1792479600000,
                      "message": "Unauthorized",
                      "transaction_id": "171f4869-bcd6-4f7d-905a-b1186b907857"
                    }
                  }
                }
              }
            },
            "headers": {}
          },
          "403": {
            "description": "The deductor access token has expired, or the API key or deductor token does not permit this request.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "code": {
                      "type": "integer"
                    },
                    "timestamp": {
                      "type": "integer"
                    },
                    "message": {
                      "type": "string"
                    },
                    "transaction_id": {
                      "type": "string"
                    }
                  },
                  "required": [
                    "code",
                    "timestamp",
                    "message",
                    "transaction_id"
                  ]
                }
              }
            },
            "headers": {}
          },
          "500": {
            "description": "The request could not be completed.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "code": {
                      "type": "integer"
                    },
                    "timestamp": {
                      "type": "integer"
                    },
                    "message": {
                      "type": "string"
                    },
                    "transaction_id": {
                      "type": "string"
                    }
                  },
                  "required": [
                    "code",
                    "timestamp",
                    "message",
                    "transaction_id"
                  ]
                }
              }
            },
            "headers": {}
          },
          "503": {
            "description": "TRACES is temporarily unavailable.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "code": {
                      "type": "integer"
                    },
                    "timestamp": {
                      "type": "integer"
                    },
                    "message": {
                      "type": "string"
                    },
                    "transaction_id": {
                      "type": "string"
                    }
                  },
                  "required": [
                    "code",
                    "timestamp",
                    "message",
                    "transaction_id"
                  ]
                }
              }
            },
            "headers": {}
          },
          "521": {
            "description": "No certificate job matches the supplied job_id and certificate type for this deductor.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "code": {
                      "type": "integer"
                    },
                    "timestamp": {
                      "type": "integer"
                    },
                    "message": {
                      "type": "string"
                    },
                    "transaction_id": {
                      "type": "string"
                    }
                  },
                  "required": [
                    "code",
                    "timestamp",
                    "message",
                    "transaction_id"
                  ]
                },
                "examples": {
                  "Job was not found": {
                    "summary": "Job was not found",
                    "value": {
                      "code": 521,
                      "timestamp": 1792479600000,
                      "message": "Data not found",
                      "transaction_id": "171f4869-bcd6-4f7d-905a-b1186b907857"
                    }
                  }
                }
              }
            },
            "headers": {}
          }
        },
        "security": []
      }
    },
    "/tds/compliance/e-file": {
      "post": {
        "summary": "Create TDS return e-filing job",
        "deprecated": false,
        "description": "Creates a TDS or TCS e-filing job. Upload a ZIP containing the FVU file and Form 27A to `data.fvu_upload_file_url` using HTTP PUT. Use `data.job_id` to check the filing result. Creating the job does not file the return.",
        "tags": [
          "E-File TDS Return"
        ],
        "parameters": [
          {
            "name": "authorization",
            "in": "header",
            "description": "JWT access token",
            "required": true,
            "example": "{{access_token}}",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "x-api-key",
            "in": "header",
            "description": "API key for identification",
            "required": true,
            "example": "{{api_key}}",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "x-api-version",
            "in": "header",
            "description": "API version",
            "required": false,
            "example": "",
            "schema": {
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "@entity": {
                    "type": "string",
                    "enum": [
                      "in.co.sandbox.tds.compliance.e-file.request"
                    ]
                  },
                  "tax_year": {
                    "description": "Tax Year (e.g. TY 2026-27)",
                    "type": "string",
                    "examples": [
                      "TY 2026-27"
                    ],
                    "pattern": "^TY [0-9]{4}-[0-9]{2}$"
                  },
                  "form": {
                    "description": "TDS/TCS return form. Use 138 for erstwhile 24Q, 140 for erstwhile 26Q, 144 for erstwhile 27Q, and 143 for erstwhile 27EQ.",
                    "enum": [
                      "138",
                      "140",
                      "144",
                      "143"
                    ],
                    "type": "string"
                  },
                  "quarter": {
                    "enum": [
                      "Q1",
                      "Q2",
                      "Q3",
                      "Q4"
                    ],
                    "type": "string"
                  },
                  "tan": {
                    "description": "TAN of deductor/collector. Regular Expression: [A-Z]{4}[0-9]{5}[A-Z]{1}",
                    "type": "string",
                    "examples": [
                      "AHMA09719B"
                    ]
                  }
                },
                "required": [
                  "@entity",
                  "tax_year",
                  "quarter",
                  "tan",
                  "form"
                ]
              },
              "examples": {
                "200 Job created": {
                  "value": {
                    "@entity": "in.co.sandbox.tds.compliance.e-file.request",
                    "tax_year": "TY 2026-27",
                    "form": "140",
                    "quarter": "Q1",
                    "tan": "AHMS45586C"
                  },
                  "summary": "200 Job created"
                },
                "200 Job created: Statement furnished": {
                  "value": {
                    "@entity": "in.co.sandbox.tds.compliance.e-file.request",
                    "tax_year": "TY 2026-27",
                    "form": "140",
                    "quarter": "Q2",
                    "tan": "MUMR09719B"
                  },
                  "summary": "200 Job created: Statement furnished"
                },
                "200 Job created: Unacceptable fvu": {
                  "value": {
                    "@entity": "in.co.sandbox.tds.compliance.e-file.request",
                    "tax_year": "TY 2026-27",
                    "form": "144",
                    "quarter": "Q2",
                    "tan": "AABC23456D"
                  },
                  "summary": "200 Job created: Unacceptable fvu"
                },
                "200 Job created: invalid archive": {
                  "value": {
                    "@entity": "in.co.sandbox.tds.compliance.e-file.request",
                    "tax_year": "TY 2026-27",
                    "form": "140",
                    "quarter": "Q4",
                    "tan": "PDES03028E"
                  },
                  "summary": "200 Job created: invalid archive"
                },
                "200 Job created: Form type mismatch": {
                  "value": {
                    "@entity": "in.co.sandbox.tds.compliance.e-file.request",
                    "tax_year": "TY 2026-27",
                    "form": "138",
                    "quarter": "Q4",
                    "tan": "HYDC23456G"
                  },
                  "summary": "200 Job created: Form type mismatch"
                },
                "200 Job created: Quarter mismatch": {
                  "value": {
                    "@entity": "in.co.sandbox.tds.compliance.e-file.request",
                    "tax_year": "TY 2026-27",
                    "form": "140",
                    "quarter": "Q2",
                    "tan": "MUMC23456H"
                  },
                  "summary": "200 Job created: Quarter mismatch"
                },
                "200 Job created: Barcode mismatch": {
                  "value": {
                    "@entity": "in.co.sandbox.tds.compliance.e-file.request",
                    "tax_year": "TY 2026-27",
                    "form": "144",
                    "quarter": "Q3",
                    "tan": "DELC23456I"
                  },
                  "summary": "200 Job created: Barcode mismatch"
                },
                "200 Job created: Invalid entries": {
                  "value": {
                    "@entity": "in.co.sandbox.tds.compliance.e-file.request",
                    "tax_year": "TY 2026-27",
                    "form": "140",
                    "quarter": "Q2",
                    "tan": "BLRC23456F"
                  },
                  "summary": "200 Job created: Invalid entries"
                },
                "200 Job created: Tax year mismatch": {
                  "value": {
                    "@entity": "in.co.sandbox.tds.compliance.e-file.request",
                    "tax_year": "TY 2026-27",
                    "form": "138",
                    "quarter": "Q4",
                    "tan": "PUNC23456J"
                  },
                  "summary": "200 Job created: Tax year mismatch"
                },
                "200 Job created: TAN mismatch": {
                  "value": {
                    "@entity": "in.co.sandbox.tds.compliance.e-file.request",
                    "tax_year": "TY 2026-27",
                    "form": "138",
                    "quarter": "Q2",
                    "tan": "KOLT23456K"
                  },
                  "summary": "200 Job created: TAN mismatch"
                },
                "200 Job created: Form27A missing": {
                  "value": {
                    "@entity": "in.co.sandbox.tds.compliance.e-file.request",
                    "tax_year": "TY 2026-27",
                    "form": "144",
                    "quarter": "Q3",
                    "tan": "CABC23456M"
                  },
                  "summary": "200 Job created: Form27A missing"
                },
                "200 Job created: FVU missing": {
                  "value": {
                    "@entity": "in.co.sandbox.tds.compliance.e-file.request",
                    "tax_year": "TY 2026-27",
                    "form": "140",
                    "quarter": "Q1",
                    "tan": "BABC23456L"
                  },
                  "summary": "200 Job created: FVU missing"
                },
                "test csi file": {
                  "value": {
                    "@entity": "in.co.sandbox.tds.compliance.e-file.request",
                    "tax_year": "TY 2026-27",
                    "form": "140",
                    "quarter": "Q2",
                    "tan": "SRTH05889C"
                  },
                  "summary": "test csi file"
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "200 - OK",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "code": {
                      "type": "integer"
                    },
                    "timestamp": {
                      "type": "integer"
                    },
                    "transaction_id": {
                      "type": "string"
                    },
                    "data": {
                      "type": "object",
                      "properties": {
                        "@entity": {
                          "type": "string"
                        },
                        "job_id": {
                          "type": "string",
                          "description": "Job ID used to check status."
                        },
                        "tan": {
                          "type": "string"
                        },
                        "tax_year": {
                          "type": "string",
                          "description": "Tax Year (e.g. TY 2026-27)",
                          "examples": [
                            "TY 2026-27"
                          ],
                          "pattern": "^TY [0-9]{4}-[0-9]{2}$"
                        },
                        "quarter": {
                          "type": "string"
                        },
                        "form": {
                          "type": "string"
                        },
                        "status": {
                          "type": "string"
                        },
                        "created_at": {
                          "type": "integer"
                        },
                        "fvu_upload_file_url": {
                          "type": "string",
                          "format": "uri",
                          "description": "Pre-signed URL for uploading a ZIP containing the FVU file and Form 27A with HTTP PUT."
                        }
                      }
                    }
                  }
                },
                "examples": {
                  "200 Job created": {
                    "summary": "200 Job created",
                    "value": {
                      "code": 200,
                      "timestamp": 1763362637000,
                      "transaction_id": "e2b9145f-69d5-4bbe-a6de-be6fc08b426f",
                      "data": {
                        "@entity": "in.co.sandbox.tds.compliance.e-file.job",
                        "job_id": "f845f37e-7f05-4de9-a282-a3b23b9d370a",
                        "tan": "AHMA09719B",
                        "tax_year": "TY 2026-27",
                        "quarter": "Q2",
                        "form": "138",
                        "status": "created",
                        "created_at": 1763362637000,
                        "fvu_upload_file_url": "https://in-co-sandbox-tds-test-storage.s3.ap-south-1.amazonaws.com/upload/file"
                      }
                    }
                  },
                  "200 Job created: Statement furnished": {
                    "summary": "200 Job created: Statement furnished",
                    "value": {
                      "code": 200,
                      "timestamp": 1763362637000,
                      "transaction_id": "e2b9145f-69d5-4bbe-a6de-be6fc08b426f",
                      "data": {
                        "@entity": "in.co.sandbox.tds.compliance.e-file.job",
                        "job_id": "6e8d1908-c062-4846-a811-8f73054acd65",
                        "tan": "MUMR09719B",
                        "tax_year": "TY 2026-27",
                        "quarter": "Q2",
                        "form": "140",
                        "status": "created",
                        "created_at": 1763362637000,
                        "fvu_upload_file_url": "https://in-co-sandbox-tds-test-storage.s3.ap-south-1.amazonaws.com/upload/file"
                      }
                    }
                  },
                  "200 Job created: Unacceptable fvu": {
                    "summary": "200 Job created: Unacceptable fvu",
                    "value": {
                      "code": 200,
                      "timestamp": 1763362637000,
                      "transaction_id": "e2b9145f-69d5-4bbe-a6de-be6fc08b426f",
                      "data": {
                        "@entity": "in.co.sandbox.tds.compliance.e-file.job",
                        "job_id": "d75c3d26-4f81-451f-ab38-e217ea801ea1",
                        "tan": "AABC23456D",
                        "tax_year": "TY 2026-27",
                        "quarter": "Q2",
                        "form": "144",
                        "status": "created",
                        "created_at": 1763362637000,
                        "fvu_upload_file_url": "https://in-co-sandbox-tds-test-storage.s3.ap-south-1.amazonaws.com/upload/file"
                      }
                    }
                  },
                  "200 Job created: invalid archive": {
                    "summary": "200 Job created: invalid archive",
                    "value": {
                      "code": 200,
                      "timestamp": 1763362637000,
                      "transaction_id": "e2b9145f-69d5-4bbe-a6de-be6fc08b426f",
                      "data": {
                        "@entity": "in.co.sandbox.tds.compliance.e-file.job",
                        "job_id": "d1213059-ec22-4e10-b0c1-a91814377001",
                        "tan": "PDES03028E",
                        "tax_year": "TY 2026-27",
                        "quarter": "Q4",
                        "form": "140",
                        "status": "created",
                        "created_at": 1763362637000,
                        "fvu_upload_file_url": "https://in-co-sandbox-tds-test-storage.s3.ap-south-1.amazonaws.com/upload/file"
                      }
                    }
                  },
                  "200 Job created: Form type mismatch": {
                    "summary": "200 Job created: Form type mismatch",
                    "value": {
                      "code": 200,
                      "timestamp": 1763362637000,
                      "transaction_id": "e2b9145f-69d5-4bbe-a6de-be6fc08b426f",
                      "data": {
                        "@entity": "in.co.sandbox.tds.compliance.e-file.job",
                        "job_id": "d6f5b340-440b-400c-9b86-16e691e768b0",
                        "tan": "HYDC23456G",
                        "tax_year": "TY 2026-27",
                        "quarter": "Q4",
                        "form": "138",
                        "status": "created",
                        "created_at": 1763362637000,
                        "fvu_upload_file_url": "https://in-co-sandbox-tds-test-storage.s3.ap-south-1.amazonaws.com/upload/file"
                      }
                    }
                  },
                  "200 Job created: Quarter mismatch": {
                    "summary": "200 Job created: Quarter mismatch",
                    "value": {
                      "code": 200,
                      "timestamp": 1763362637000,
                      "transaction_id": "e2b9145f-69d5-4bbe-a6de-be6fc08b426f",
                      "data": {
                        "@entity": "in.co.sandbox.tds.compliance.e-file.job",
                        "job_id": "7a62876a-d638-430c-ad77-8fe33d9e63d5",
                        "tan": "MUMC23456H",
                        "tax_year": "TY 2026-27",
                        "quarter": "Q2",
                        "form": "140",
                        "status": "created",
                        "created_at": 1763362637000,
                        "fvu_upload_file_url": "https://in-co-sandbox-tds-test-storage.s3.ap-south-1.amazonaws.com/upload/file"
                      }
                    }
                  },
                  "200 Job created: Barcode mismatch": {
                    "summary": "200 Job created: Barcode mismatch",
                    "value": {
                      "code": 200,
                      "timestamp": 1763362637000,
                      "transaction_id": "e2b9145f-69d5-4bbe-a6de-be6fc08b426f",
                      "data": {
                        "@entity": "in.co.sandbox.tds.compliance.e-file.job",
                        "job_id": "6b11d176-b3c5-483c-9052-b533a6e92377",
                        "tan": "DELC23456I",
                        "tax_year": "TY 2026-27",
                        "quarter": "Q3",
                        "form": "144",
                        "status": "created",
                        "created_at": 1763362637000,
                        "fvu_upload_file_url": "https://in-co-sandbox-tds-test-storage.s3.ap-south-1.amazonaws.com/upload/file"
                      }
                    }
                  },
                  "200 Job created: Invalid entries": {
                    "summary": "200 Job created: Invalid entries",
                    "value": {
                      "code": 200,
                      "timestamp": 1763362637000,
                      "transaction_id": "e2b9145f-69d5-4bbe-a6de-be6fc08b426f",
                      "data": {
                        "@entity": "in.co.sandbox.tds.compliance.e-file.job",
                        "job_id": "3b979ce9-ef4e-4157-a4a3-51e8747e76d7",
                        "tan": "BLRC23456F",
                        "tax_year": "TY 2026-27",
                        "quarter": "Q2",
                        "form": "140",
                        "status": "created",
                        "created_at": 1763362637000,
                        "fvu_upload_file_url": "https://in-co-sandbox-tds-test-storage.s3.ap-south-1.amazonaws.com/upload/file"
                      }
                    }
                  },
                  "200 Job created: Tax year mismatch": {
                    "summary": "200 Job created: Tax year mismatch",
                    "value": {
                      "code": 200,
                      "timestamp": 1763362637000,
                      "transaction_id": "e2b9145f-69d5-4bbe-a6de-be6fc08b426f",
                      "data": {
                        "@entity": "in.co.sandbox.tds.compliance.e-file.job",
                        "job_id": "7928082e-34ca-474c-ba05-4ede9598b9b5",
                        "tan": "PUNC23456J",
                        "tax_year": "TY 2026-27",
                        "quarter": "Q4",
                        "form": "140",
                        "status": "created",
                        "created_at": 1763362637000,
                        "fvu_upload_file_url": "https://in-co-sandbox-tds-test-storage.s3.ap-south-1.amazonaws.com/upload/file"
                      }
                    }
                  },
                  "200 Job created: TAN mismatch": {
                    "summary": "200 Job created: TAN mismatch",
                    "value": {
                      "code": 200,
                      "timestamp": 1763362637000,
                      "transaction_id": "e2b9145f-69d5-4bbe-a6de-be6fc08b426f",
                      "data": {
                        "@entity": "in.co.sandbox.tds.compliance.e-file.job",
                        "job_id": "5fd2679f-040f-435c-a285-df5817a150b5",
                        "tan": "KOLT23456K",
                        "tax_year": "TY 2026-27",
                        "quarter": "Q2",
                        "form": "140",
                        "status": "created",
                        "created_at": 1763362637000,
                        "fvu_upload_file_url": "https://in-co-sandbox-tds-test-storage.s3.ap-south-1.amazonaws.com/upload/file"
                      }
                    }
                  },
                  "200 Job created: Form27A missing": {
                    "summary": "200 Job created: Form27A missing",
                    "value": {
                      "code": 200,
                      "timestamp": 1763362637000,
                      "transaction_id": "e2b9145f-69d5-4bbe-a6de-be6fc08b426f",
                      "data": {
                        "@entity": "in.co.sandbox.tds.compliance.e-file.job",
                        "job_id": "b411fbee-68e4-4da3-9f62-8de8ca09a74c",
                        "tan": "CABC23456M",
                        "tax_year": "TY 2026-27",
                        "quarter": "Q3",
                        "form": "140",
                        "status": "created",
                        "created_at": 1763362637000,
                        "fvu_upload_file_url": "https://in-co-sandbox-tds-test-storage.s3.ap-south-1.amazonaws.com/upload/file"
                      }
                    }
                  },
                  "200 Job created: FVU missing": {
                    "summary": "200 Job created: FVU missing",
                    "value": {
                      "code": 200,
                      "timestamp": 1763362637000,
                      "transaction_id": "e2b9145f-69d5-4bbe-a6de-be6fc08b426f",
                      "data": {
                        "@entity": "in.co.sandbox.tds.compliance.e-file.job",
                        "job_id": "9bf0b6f8-5957-484f-9aea-0d235054974c",
                        "tan": "BABC23456L",
                        "tax_year": "TY 2026-27",
                        "quarter": "Q1",
                        "form": "140",
                        "status": "created",
                        "created_at": 1763362637000,
                        "fvu_upload_file_url": "https://in-co-sandbox-tds-test-storage.s3.ap-south-1.amazonaws.com/upload/file"
                      }
                    }
                  },
                  "test csi file": {
                    "summary": "test csi file",
                    "value": "csi mock data"
                  }
                }
              }
            },
            "headers": {}
          }
        },
        "security": []
      },
      "get": {
        "summary": "Get TDS return e-filing status",
        "deprecated": false,
        "description": "Returns the e-filing status for `job_id`. On success, `data` contains the receipt, FVU, and Form 27A download URLs. On failure, read `data.message`. HTTP 200 does not mean the job succeeded.",
        "tags": [
          "E-File TDS Return"
        ],
        "parameters": [
          {
            "name": "job_id",
            "in": "query",
            "description": "Job ID returned when the job was created.",
            "required": true,
            "example": "{{job_id}}",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "authorization",
            "in": "header",
            "description": "JWT access token",
            "required": true,
            "example": "{{access_token}}",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "x-api-key",
            "in": "header",
            "description": "API key for identification",
            "required": true,
            "example": "{{api_key}}",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "x-api-version",
            "in": "header",
            "description": "API version",
            "required": false,
            "example": "",
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "200 - OK",
            "content": {
              "application/json": {
                "schema": {
                  "oneOf": [
                    {
                      "title": "Job Queued",
                      "type": "object",
                      "properties": {
                        "code": {
                          "type": "integer"
                        },
                        "timestamp": {
                          "type": "integer"
                        },
                        "transaction_id": {
                          "type": "string"
                        },
                        "data": {
                          "type": "object",
                          "properties": {
                            "@entity": {
                              "type": "string"
                            },
                            "job_id": {
                              "type": "string",
                              "description": "Job ID used to check status."
                            },
                            "tan": {
                              "type": "string"
                            },
                            "tax_year": {
                              "type": "string",
                              "description": "Tax Year (e.g. TY 2026-27)",
                              "examples": [
                                "TY 2026-27"
                              ],
                              "pattern": "^TY [0-9]{4}-[0-9]{2}$"
                            },
                            "quarter": {
                              "type": "string"
                            },
                            "form": {
                              "type": "string"
                            },
                            "filing_type": {
                              "type": "string"
                            },
                            "status": {
                              "type": "string"
                            },
                            "created_at": {
                              "type": "integer"
                            },
                            "updated_at": {
                              "type": "integer"
                            }
                          }
                        }
                      }
                    },
                    {
                      "title": "Job Succeeded",
                      "type": "object",
                      "properties": {
                        "code": {
                          "type": "integer"
                        },
                        "timestamp": {
                          "type": "integer"
                        },
                        "transaction_id": {
                          "type": "string"
                        },
                        "data": {
                          "type": "object",
                          "properties": {
                            "@entity": {
                              "type": "string"
                            },
                            "job_id": {
                              "type": "string",
                              "description": "Job ID used to check status."
                            },
                            "tan": {
                              "type": "string"
                            },
                            "tax_year": {
                              "type": "string",
                              "description": "Tax Year (e.g. TY 2026-27)",
                              "examples": [
                                "TY 2026-27"
                              ],
                              "pattern": "^TY [0-9]{4}-[0-9]{2}$"
                            },
                            "quarter": {
                              "type": "string"
                            },
                            "form": {
                              "type": "string"
                            },
                            "filing_type": {
                              "type": "string"
                            },
                            "status": {
                              "type": "string"
                            },
                            "receipt_number": {
                              "type": "integer"
                            },
                            "created_at": {
                              "type": "integer"
                            },
                            "updated_at": {
                              "type": "integer"
                            },
                            "receipt_file_url": {
                              "type": "string",
                              "format": "uri",
                              "description": "Download URL for the filing receipt after the e-filing job succeeds."
                            },
                            "fvu_file_url": {
                              "type": "string",
                              "format": "uri",
                              "description": "Download URL for the FVU file associated with the filing."
                            },
                            "form27a_file_url": {
                              "type": "string",
                              "format": "uri",
                              "description": "Download URL for Form 27A associated with the filing."
                            }
                          }
                        }
                      }
                    },
                    {
                      "title": "Job Failed",
                      "type": "object",
                      "properties": {
                        "code": {
                          "type": "integer"
                        },
                        "timestamp": {
                          "type": "integer"
                        },
                        "transaction_id": {
                          "type": "string"
                        },
                        "data": {
                          "type": "object",
                          "properties": {
                            "@entity": {
                              "type": "string"
                            },
                            "job_id": {
                              "type": "string",
                              "description": "Job ID used to check status."
                            },
                            "tan": {
                              "type": "string"
                            },
                            "tax_year": {
                              "type": "string",
                              "description": "Tax Year (e.g. TY 2026-27)",
                              "examples": [
                                "TY 2026-27"
                              ],
                              "pattern": "^TY [0-9]{4}-[0-9]{2}$"
                            },
                            "quarter": {
                              "type": "string"
                            },
                            "form": {
                              "type": "string"
                            },
                            "filing_type": {
                              "type": "string"
                            },
                            "status": {
                              "type": "string"
                            },
                            "message": {
                              "type": "string",
                              "description": "Reason for the job failure."
                            },
                            "created_at": {
                              "type": "integer"
                            },
                            "updated_at": {
                              "type": "integer"
                            }
                          }
                        }
                      }
                    }
                  ]
                },
                "examples": {
                  "200 Job Succeeded": {
                    "summary": "200 Job Succeeded",
                    "value": {
                      "code": 200,
                      "timestamp": 1763362637000,
                      "transaction_id": "e2b9145f-69d5-4bbe-a6de-be6fc08b426f",
                      "data": {
                        "@entity": "in.co.sandbox.tds.compliance.e-file.job",
                        "job_id": "f845f37e-7f05-4de9-a282-a3b23b9d370a",
                        "tan": "AHMA09719B",
                        "tax_year": "TY 2026-27",
                        "quarter": "Q2",
                        "form": "140",
                        "filing_type": "regular",
                        "status": "succeeded",
                        "receipt_number": 123456789012345,
                        "created_at": 1763362637000,
                        "updated_at": 1763362637000,
                        "receipt_file_url": "https://in-co-sandbox-tds-test-storage.s3.ap-south-1.amazonaws.com/AHMS45586C/FY+2025-26/Q3/140/4049c226-4988-4978-b5ad-d25705453da8/receipt.pdf",
                        "fvu_file_url": "https://in-co-sandbox-tds-test-storage.s3.ap-south-1.amazonaws.com/AHMS45586C/FY+2025-26/Q3/140/4049c226-4988-4978-b5ad-d25705453da8/140.fvu",
                        "form27a_file_url": "https://in-co-sandbox-tds-test-storage.s3.ap-south-1.amazonaws.com/AHMS45586C/FY+2025-26/Q3/140/4049c226-4988-4978-b5ad-d25705453da8/form27A_140.pdf"
                      }
                    }
                  },
                  "200 Job Queued": {
                    "summary": "200 Job Queued",
                    "value": {
                      "code": 200,
                      "timestamp": 1763362637000,
                      "transaction_id": "e2b9145f-69d5-4bbe-a6de-be6fc08b426f",
                      "data": {
                        "@entity": "in.co.sandbox.tds.compliance.e-file.job",
                        "job_id": "2aa54d2b-68f6-4871-866a-4eba957a8672",
                        "tan": "AHMA09719B",
                        "tax_year": "TY 2026-27",
                        "quarter": "Q2",
                        "form": "140",
                        "filing_type": "original",
                        "status": "queued",
                        "created_at": 1763362637000,
                        "updated_at": 1763362637000
                      }
                    }
                  },
                  "200 Job Failed: Statement furnished": {
                    "summary": "200 Job Failed: Statement furnished",
                    "value": {
                      "code": 200,
                      "timestamp": 1763362637000,
                      "transaction_id": "e2b9145f-69d5-4bbe-a6de-be6fc08b426f",
                      "data": {
                        "@entity": "in.co.sandbox.tds.compliance.e-file.job",
                        "job_id": "6e8d1908-c062-4846-a811-8f73054acd65",
                        "tan": "MUMR09719B",
                        "tax_year": "TY 2026-27",
                        "quarter": "Q2",
                        "form": "140",
                        "filing_type": "original",
                        "status": "failed",
                        "message": "Regular Statement with the same TAN, Tax Year, FORM and Quarter is already furnished",
                        "created_at": 1763362637000,
                        "updated_at": 1763362637000
                      }
                    }
                  },
                  "200 Job Failed: Unacceptable fvu": {
                    "summary": "200 Job Failed: Unacceptable fvu",
                    "value": {
                      "code": 200,
                      "timestamp": 1763362637000,
                      "transaction_id": "e2b9145f-69d5-4bbe-a6de-be6fc08b426f",
                      "data": {
                        "@entity": "in.co.sandbox.tds.compliance.e-file.job",
                        "job_id": "d75c3d26-4f81-451f-ab38-e217ea801ea1",
                        "tan": "AABC23456D",
                        "tax_year": "TY 2026-27",
                        "quarter": "Q2",
                        "form": "144",
                        "filing_type": "original",
                        "status": "failed",
                        "message": "Unacceptable FVU",
                        "created_at": 1763362637000,
                        "updated_at": 1763362637000
                      }
                    }
                  },
                  "200 Job Failed: Invalid archive": {
                    "summary": "200 Job Failed: Invalid archive",
                    "value": {
                      "code": 200,
                      "timestamp": 1763362637000,
                      "transaction_id": "e2b9145f-69d5-4bbe-a6de-be6fc08b426f",
                      "data": {
                        "@entity": "in.co.sandbox.tds.compliance.e-file.job",
                        "job_id": "d1213059-ec22-4e10-b0c1-a91814377001",
                        "tan": "PDES03028E",
                        "tax_year": "TY 2026-27",
                        "quarter": "Q4",
                        "form": "140",
                        "filing_type": "original",
                        "status": "failed",
                        "message": "Invalid Archive",
                        "created_at": 1763362637000,
                        "updated_at": 1763362637000
                      }
                    }
                  },
                  "200 Job Failed: Form type mismatch": {
                    "summary": "200 Job Failed: Form type mismatch",
                    "value": {
                      "code": 200,
                      "timestamp": 1763362637000,
                      "transaction_id": "e2b9145f-69d5-4bbe-a6de-be6fc08b426f",
                      "data": {
                        "@entity": "in.co.sandbox.tds.compliance.e-file.job",
                        "job_id": "d6f5b340-440b-400c-9b86-16e691e768b0",
                        "tan": "HYDC23456G",
                        "tax_year": "TY 2026-27",
                        "quarter": "Q4",
                        "form": "138",
                        "filing_type": "original",
                        "status": "failed",
                        "message": "Form Type Mismatch",
                        "created_at": 1763362637000,
                        "updated_at": 1763362637000
                      }
                    }
                  },
                  "200 Job Failed: Quarter mismatch": {
                    "summary": "200 Job Failed: Quarter mismatch",
                    "value": {
                      "code": 200,
                      "timestamp": 1763362637000,
                      "transaction_id": "e2b9145f-69d5-4bbe-a6de-be6fc08b426f",
                      "data": {
                        "@entity": "in.co.sandbox.tds.compliance.e-file.job",
                        "job_id": "7a62876a-d638-430c-ad77-8fe33d9e63d5",
                        "tan": "MUMC23456H",
                        "tax_year": "TY 2026-27",
                        "quarter": "Q2",
                        "form": "140",
                        "filing_type": "original",
                        "status": "failed",
                        "message": "Quarter mismatch",
                        "created_at": 1763362637000,
                        "updated_at": 1763362637000
                      }
                    }
                  },
                  "200 Job Failed: Barcode mismatch": {
                    "summary": "200 Job Failed: Barcode mismatch",
                    "value": {
                      "code": 200,
                      "timestamp": 1763362637000,
                      "transaction_id": "e2b9145f-69d5-4bbe-a6de-be6fc08b426f",
                      "data": {
                        "@entity": "in.co.sandbox.tds.compliance.e-file.job",
                        "job_id": "6b11d176-b3c5-483c-9052-b533a6e92377",
                        "tan": "DELC23456I",
                        "tax_year": "TY 2026-27",
                        "quarter": "Q3",
                        "form": "144",
                        "filing_type": "original",
                        "status": "failed",
                        "message": "Barcode mismatch",
                        "created_at": 1763362637000,
                        "updated_at": 1763362637000
                      }
                    }
                  },
                  "200 Job Failed: Invalid number of entries in archive": {
                    "summary": "200 Job Failed: Invalid number of entries in archive",
                    "value": {
                      "code": 200,
                      "timestamp": 1763362637000,
                      "transaction_id": "e2b9145f-69d5-4bbe-a6de-be6fc08b426f",
                      "data": {
                        "@entity": "in.co.sandbox.tds.compliance.e-file.job",
                        "job_id": "3b979ce9-ef4e-4157-a4a3-51e8747e76d7",
                        "tan": "BLRC23456F",
                        "tax_year": "TY 2026-27",
                        "quarter": "Q2",
                        "form": "140",
                        "filing_type": "original",
                        "status": "failed",
                        "message": "Invalid Number of entries in Archive: 1",
                        "created_at": 1763362637000,
                        "updated_at": 1763362637000
                      }
                    }
                  },
                  "200 Job Failed: Tax year mismatch": {
                    "summary": "200 Job Failed: Tax year mismatch",
                    "value": {
                      "code": 200,
                      "timestamp": 1763362637000,
                      "transaction_id": "e2b9145f-69d5-4bbe-a6de-be6fc08b426f",
                      "data": {
                        "@entity": "in.co.sandbox.tds.compliance.e-file.job",
                        "job_id": "7928082e-34ca-474c-ba05-4ede9598b9b5",
                        "tan": "PUNC23456J",
                        "tax_year": "TY 2026-27",
                        "form": "138",
                        "quarter": "Q4",
                        "filing_type": "original",
                        "status": "failed",
                        "message": "Tax year mismatch",
                        "created_at": 1763362637000,
                        "updated_at": 1763362637000
                      }
                    }
                  },
                  "200 Job Failed: TAN mismatch": {
                    "summary": "200 Job Failed: TAN mismatch",
                    "value": {
                      "code": 200,
                      "timestamp": 1763362637000,
                      "transaction_id": "e2b9145f-69d5-4bbe-a6de-be6fc08b426f",
                      "data": {
                        "@entity": "in.co.sandbox.tds.compliance.e-file.job",
                        "job_id": "5fd2679f-040f-435c-a285-df5817a150b5",
                        "tan": "KOLT23456K",
                        "tax_year": "TY 2026-27",
                        "quarter": "Q2",
                        "form": "140",
                        "filing_type": "original",
                        "status": "failed",
                        "message": "TAN mismatch",
                        "created_at": 1763362637000,
                        "updated_at": 1763362637000
                      }
                    }
                  },
                  "200 Job Failed: Form27A missing": {
                    "summary": "200 Job Failed: Form27A missing",
                    "value": {
                      "code": 200,
                      "timestamp": 1763362637000,
                      "transaction_id": "e2b9145f-69d5-4bbe-a6de-be6fc08b426f",
                      "data": {
                        "@entity": "in.co.sandbox.tds.compliance.e-file.job",
                        "job_id": "b411fbee-68e4-4da3-9f62-8de8ca09a74c",
                        "tan": "CABC23456M",
                        "tax_year": "TY 2026-27",
                        "quarter": "Q3",
                        "form": "140",
                        "filing_type": "original",
                        "status": "failed",
                        "message": "Form 27A missing",
                        "created_at": 1763362637000,
                        "updated_at": 1763362637000
                      }
                    }
                  },
                  "200 Job Failed: FVU missing": {
                    "summary": "200 Job Failed: FVU missing",
                    "value": {
                      "code": 200,
                      "timestamp": 1763362637000,
                      "transaction_id": "e2b9145f-69d5-4bbe-a6de-be6fc08b426f",
                      "data": {
                        "@entity": "in.co.sandbox.tds.compliance.e-file.job",
                        "job_id": "9bf0b6f8-5957-484f-9aea-0d235054974c",
                        "tan": "BABC23456L",
                        "tax_year": "TY 2026-27",
                        "quarter": "Q1",
                        "form": "140",
                        "filing_type": "original",
                        "status": "failed",
                        "message": "FVU missing",
                        "created_at": 1763362637000,
                        "updated_at": 1763362637000
                      }
                    }
                  }
                }
              }
            },
            "headers": {}
          },
          "521": {
            "description": "521 - Data Not Found",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "code": {
                      "type": "integer"
                    },
                    "timestamp": {
                      "type": "integer"
                    },
                    "transaction_id": {
                      "type": "string"
                    },
                    "message": {
                      "type": "string",
                      "description": "Reason for the job failure."
                    }
                  }
                },
                "examples": {
                  "521 Data not found": {
                    "summary": "521 Data not found",
                    "value": {
                      "code": 521,
                      "timestamp": 1763362637000,
                      "transaction_id": "e2b9145f-69d5-4bbe-a6de-be6fc08b426f",
                      "message": "Data not found"
                    }
                  }
                }
              }
            },
            "headers": {}
          }
        },
        "security": []
      }
    },
    "/tds/compliance/e-file/search": {
      "post": {
        "summary": "Search TDS return e-filing jobs",
        "deprecated": false,
        "description": "Finds TDS and TCS e-filing jobs by TAN, form, tax year, quarter, or creation date. Results appear in `data.items`. Set `page_size` to request up to 50 records. Use `last_evaluated_key` for pagination.",
        "tags": [
          "E-File TDS Return"
        ],
        "parameters": [
          {
            "name": "authorization",
            "in": "header",
            "description": "JWT access token",
            "required": true,
            "example": "",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "x-api-key",
            "in": "header",
            "description": "API key for identification",
            "required": true,
            "example": "",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "x-api-version",
            "in": "header",
            "description": "",
            "required": false,
            "example": "",
            "schema": {
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "@entity": {
                    "enum": [
                      "in.co.sandbox.tds.compliance.e-file.search"
                    ],
                    "type": "string"
                  },
                  "tan": {
                    "description": "TAN of deductor/collector. Regular Expression: [A-Z]{4}[0-9]{5}[A-Z]{1}",
                    "type": "string"
                  },
                  "quarter": {
                    "description": "Quarter (e.g. Q2)",
                    "enum": [
                      "Q1",
                      "Q2",
                      "Q3",
                      "Q4"
                    ],
                    "type": "string"
                  },
                  "form": {
                    "description": "TDS/TCS return form. Use 138 for erstwhile 24Q, 140 for erstwhile 26Q, 144 for erstwhile 27Q, and 143 for erstwhile 27EQ.",
                    "enum": [
                      "138",
                      "140",
                      "144",
                      "143"
                    ],
                    "type": "string"
                  },
                  "tax_year": {
                    "description": "Tax Year (e.g. TY 2026-27)",
                    "type": "string",
                    "pattern": "^TY [0-9]{4}-[0-9]{2}$",
                    "examples": [
                      "TY 2026-27"
                    ]
                  },
                  "from_date": {
                    "description": "Start of the job creation-date range, expressed as an epoch timestamp.",
                    "type": "integer"
                  },
                  "to_date": {
                    "description": "End of the job creation-date range, expressed as an epoch timestamp.",
                    "type": "integer"
                  },
                  "page_size": {
                    "description": "Number of records in the API response. Maximum allowed size is 50",
                    "type": "integer"
                  },
                  "last_evaluated_key": {
                    "description": "Base64 encoding of the stringified JSON object, which includes x-api-key, created_at, and job_id",
                    "type": "string"
                  }
                },
                "required": [
                  "@entity"
                ]
              },
              "examples": {
                "Search by TAN and tax period": {
                  "value": {
                    "@entity": "in.co.sandbox.tds.compliance.e-file.search",
                    "tan": "AHMA09719B",
                    "tax_year": "TY 2026-27",
                    "quarter": "Q1",
                    "form": "140",
                    "page_size": 10
                  },
                  "summary": "Search by TAN and tax period"
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "200 - OK",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "code": {
                      "type": "integer"
                    },
                    "timestamp": {
                      "type": "integer"
                    },
                    "data": {
                      "type": "object",
                      "properties": {
                        "@entity": {
                          "type": "string"
                        },
                        "items": {
                          "type": "array",
                          "items": {
                            "type": "object",
                            "properties": {
                              "created_at": {
                                "type": "integer"
                              },
                              "@entity": {
                                "type": "string"
                              },
                              "job_id": {
                                "type": "string",
                                "description": "Job ID used to check status."
                              },
                              "tan": {
                                "type": "string"
                              },
                              "tax_year": {
                                "type": "string",
                                "description": "Tax Year (e.g. TY 2026-27)",
                                "examples": [
                                  "TY 2026-27"
                                ],
                                "pattern": "^TY [0-9]{4}-[0-9]{2}$"
                              },
                              "quarter": {
                                "type": "string"
                              },
                              "form": {
                                "type": "string"
                              },
                              "filing_type": {
                                "type": "string"
                              },
                              "status": {
                                "type": "string"
                              }
                            }
                          }
                        }
                      }
                    },
                    "transaction_id": {
                      "type": "string"
                    }
                  }
                },
                "examples": {
                  "200 Job succeeded": {
                    "summary": "200 Job succeeded",
                    "value": {
                      "code": 200,
                      "timestamp": 1763035357079,
                      "data": {
                        "@entity": "in.co.sandbox.tds.compliance.e-file.paginated_list",
                        "items": [
                          {
                            "created_at": 1763034775467,
                            "@entity": "in.co.sandbox.tds.compliance.e-file.job",
                            "job_id": "f139447f-07c0-4de1-9f35-0224e253aeec",
                            "tan": "AHMA09719B",
                            "tax_year": "TY 2026-27",
                            "quarter": "Q2",
                            "form": "138",
                            "filing_type": "regular",
                            "status": "created"
                          },
                          {
                            "created_at": 1763034374362,
                            "@entity": "in.co.sandbox.tds.compliance.e-file.job",
                            "job_id": "6cc8a10e-6c09-4c6f-9bfe-d10b6f6afbb0",
                            "tan": "SRTH05889C",
                            "tax_year": "TY 2026-27",
                            "quarter": "Q2",
                            "form": "140",
                            "filing_type": "regular",
                            "status": "created"
                          },
                          {
                            "created_at": 1745588854631,
                            "updated_at": 1745588884436,
                            "@entity": "in.co.sandbox.tds.compliance.e-file.job",
                            "job_id": "8566e974-9f6f-49ca-96cb-c75680261405",
                            "tan": "SRTH05889C",
                            "tax_year": "TY 2026-27",
                            "quarter": "Q2",
                            "form": "140",
                            "filing_type": "regular",
                            "status": "succeeded"
                          }
                        ]
                      },
                      "transaction_id": "a109f017-10ae-44aa-ade7-3902a8cddd6b"
                    }
                  }
                }
              }
            },
            "headers": {}
          }
        },
        "security": []
      }
    }
  },
  "webhooks": {
    "FVUGenerateJobStatus": {
      "post": {
        "summary": "FVU generation status webhook",
        "deprecated": false,
        "description": "Sandbox sends this webhook when an FVU generation job transitions to `succeeded` or `failed`, not for `created` or `queued` states. Configure your webhook URL in the Sandbox Console. See the [webhooks guide](https://developer.sandbox.co.in/guides/developer-resources/webhooks) for signature validation.",
        "operationId": "FVUGenerateJobStatus",
        "tags": [
          "FVU Generation"
        ],
        "parameters": [],
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "data": {
                    "description": "Job details at the time of the status change.",
                    "oneOf": [
                      {
                        "title": "Job Succeeded",
                        "type": "object",
                        "required": [
                          "@entity",
                          "job_id",
                          "tan",
                          "tax_year",
                          "quarter",
                          "form",
                          "status",
                          "created_at",
                          "updated_at",
                          "fvu_zip_file_url"
                        ],
                        "properties": {
                          "@entity": {
                            "type": "string",
                            "description": "Entity type identifier"
                          },
                          "job_id": {
                            "type": "string",
                            "description": "Unique identifier of the job"
                          },
                          "tan": {
                            "type": "string",
                            "description": "Tax Deduction Account Number"
                          },
                          "tax_year": {
                            "type": "string",
                            "description": "Tax year of the return (e.g. TY 2026-27)",
                            "examples": [
                              "TY 2026-27"
                            ],
                            "pattern": "^TY [0-9]{4}-[0-9]{2}$"
                          },
                          "quarter": {
                            "type": "string",
                            "description": "Quarter for which the return is filed (Q1–Q4)"
                          },
                          "form": {
                            "type": "string",
                            "description": "TDS form type (138, 140, or 144)"
                          },
                          "filing_type": {
                            "type": "string",
                            "description": "Filing type (regular or correction)"
                          },
                          "status": {
                            "type": "string",
                            "description": "Job status",
                            "enum": [
                              "succeeded"
                            ]
                          },
                          "created_at": {
                            "type": "integer",
                            "description": "Job creation time as a Unix timestamp in milliseconds"
                          },
                          "updated_at": {
                            "type": "integer",
                            "description": "Last status update time as a Unix timestamp in milliseconds"
                          },
                          "fvu_zip_file_url": {
                            "type": "string",
                            "format": "uri",
                            "description": "Pre-signed URL to download the generated FVU ZIP file"
                          }
                        }
                      },
                      {
                        "title": "Job Failed",
                        "type": "object",
                        "required": [
                          "@entity",
                          "job_id",
                          "tan",
                          "tax_year",
                          "quarter",
                          "form",
                          "status",
                          "created_at",
                          "updated_at",
                          "validation_report_file_url"
                        ],
                        "properties": {
                          "@entity": {
                            "type": "string",
                            "description": "Entity type identifier"
                          },
                          "job_id": {
                            "type": "string",
                            "description": "Unique identifier of the job"
                          },
                          "tan": {
                            "type": "string",
                            "description": "Tax Deduction Account Number"
                          },
                          "tax_year": {
                            "type": "string",
                            "description": "Tax year of the return (e.g. TY 2026-27)",
                            "examples": [
                              "TY 2026-27"
                            ],
                            "pattern": "^TY [0-9]{4}-[0-9]{2}$"
                          },
                          "quarter": {
                            "type": "string",
                            "description": "Quarter for which the return is filed (Q1–Q4)"
                          },
                          "form": {
                            "type": "string",
                            "description": "TDS form type (138, 140, or 144)"
                          },
                          "filing_type": {
                            "type": "string",
                            "description": "Filing type (regular or correction)"
                          },
                          "status": {
                            "type": "string",
                            "description": "Job status",
                            "enum": [
                              "failed"
                            ]
                          },
                          "created_at": {
                            "type": "integer",
                            "description": "Job creation time as a Unix timestamp in milliseconds"
                          },
                          "updated_at": {
                            "type": "integer",
                            "description": "Last status update time as a Unix timestamp in milliseconds"
                          },
                          "validation_report_file_url": {
                            "type": "string",
                            "format": "uri",
                            "description": "Pre-signed URL to download the validation error report (JSON)"
                          }
                        }
                      }
                    ]
                  }
                }
              },
              "examples": {
                "Job Succeeded": {
                  "value": {
                    "data": {
                      "@entity": "in.co.sandbox.tds.compliance.fvu.generate.job",
                      "job_id": "4ef92975-aea8-4628-9eaa-18eb439c13d9",
                      "tan": "AHMA09719B",
                      "tax_year": "TY 2026-27",
                      "quarter": "Q3",
                      "form": "138",
                      "filing_type": "regular",
                      "status": "succeeded",
                      "created_at": 1763362637000,
                      "updated_at": 1763362650000,
                      "fvu_zip_file_url": "https://in-co-sandbox-tds-compliance-fvu-test.s3.ap-south-1.amazonaws.com/tan/tax_year/quarter/form/4ef92975-aea8-4628-9eaa-18eb439c13d9.zip"
                    }
                  },
                  "summary": "Job Succeeded"
                },
                "Job Failed": {
                  "value": {
                    "data": {
                      "@entity": "in.co.sandbox.tds.compliance.fvu.generate.job",
                      "job_id": "7a9176ef-1e59-4b8e-a1de-ee15b09963f8",
                      "tan": "AHMA09719B",
                      "tax_year": "TY 2026-27",
                      "quarter": "Q3",
                      "form": "138",
                      "filing_type": "regular",
                      "status": "failed",
                      "created_at": 1763362637000,
                      "updated_at": 1763362650000,
                      "validation_report_file_url": "https://in-co-sandbox-tds-compliance-fvu-test.s3.ap-south-1.amazonaws.com/tan/tax_year/quarter/form/9693f3f9-e7dd-4a70-9390-0501ab7f4d27_error.json"
                    }
                  },
                  "summary": "Job Failed"
                }
              }
            }
          },
          "required": true
        },
        "responses": {
          "200": {
            "description": "Return any 2xx status to acknowledge receipt. Sandbox retries delivery on non-2xx responses.",
            "headers": {}
          }
        },
        "security": []
      }
    },
    "CertificateJobStatus": {
      "post": {
        "summary": "Certificate job status",
        "deprecated": false,
        "description": "Receive a notification when a certificate generation job succeeds or fails. The data object contains the certificate job, including signed download URLs after success or a failure message.",
        "operationId": "CertificateJobStatus",
        "tags": [
          "TDS Certificate"
        ],
        "parameters": [],
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "data": {
                    "type": "object",
                    "properties": {
                      "@entity": {
                        "type": "string",
                        "description": "Certificate job entity type."
                      },
                      "job_id": {
                        "type": "string",
                        "description": "Unique identifier for the certificate job."
                      },
                      "tan": {
                        "type": "string",
                        "description": "Tax Deduction and Collection Account Number (TAN)."
                      },
                      "tax_year": {
                        "type": "string",
                        "description": "Tax year for the certificate job, in TY YYYY-YY format."
                      },
                      "quarter": {
                        "type": "string",
                        "enum": [
                          "Q1",
                          "Q2",
                          "Q3",
                          "Q4"
                        ],
                        "description": "Quarter of the tax year."
                      },
                      "created_at": {
                        "type": "integer",
                        "description": "Job creation time as a Unix timestamp in milliseconds."
                      },
                      "updated_at": {
                        "type": "integer",
                        "description": "Last job update time as a Unix timestamp in milliseconds, when available."
                      },
                      "status": {
                        "type": "string",
                        "enum": [
                          "created",
                          "queued",
                          "in_progress",
                          "succeeded",
                          "failed"
                        ],
                        "description": "Current status of the certificate job."
                      },
                      "message": {
                        "type": "string",
                        "description": "Reason the job failed, when available."
                      },
                      "certificate_pdf_zip_urls": {
                        "type": "array",
                        "description": "Signed URLs for the certificate ZIP files, available after the job succeeds.",
                        "items": {
                          "type": "string",
                          "format": "uri"
                        }
                      }
                    },
                    "required": [
                      "@entity",
                      "job_id",
                      "tan",
                      "tax_year",
                      "quarter",
                      "status"
                    ]
                  }
                },
                "required": [
                  "data"
                ]
              },
              "examples": {
                "Form 131 Job Succeeded": {
                  "value": {
                    "data": {
                      "created_at": 1788782460848,
                      "updated_at": 1788782462209,
                      "@entity": "in.co.sandbox.tds.compliance.certificate.job",
                      "job_id": "2b61a200-d225-48b5-a6a8-d29d9351c014",
                      "tan": "AHMS45586C",
                      "tax_year": "TY 2026-27",
                      "quarter": "Q1",
                      "certificate_pdf_zip_urls": [
                        "https://in-co-sandbox-tds-test-storage.s3.ap-south-1.amazonaws.com/AHMS45586C/TY+2026-27/1_AHMxxxxx6C_FORM131_2026_Q1_certificate.zip"
                      ],
                      "status": "succeeded"
                    }
                  },
                  "summary": "Form 131 Job Succeeded"
                },
                "Job Failed": {
                  "value": {
                    "data": {
                      "created_at": 1788782950446,
                      "updated_at": 1788782951671,
                      "@entity": "in.co.sandbox.tds.compliance.certificate.job",
                      "job_id": "a31097a4-6697-44ee-bbba-75d392f123db",
                      "tan": "AHMS45586C",
                      "tax_year": "TY 2026-27",
                      "quarter": "Q1",
                      "message": "Credentials not found",
                      "status": "failed"
                    }
                  },
                  "summary": "Job Failed"
                }
              }
            }
          },
          "required": true
        },
        "responses": {
          "200": {
            "description": "Return any 2xx status to acknowledge receipt. Sandbox retries delivery on non-2xx responses.",
            "headers": {}
          }
        },
        "security": []
      }
    },
    "EFileJobStatus": {
      "post": {
        "summary": "TDS return e-filing status webhook",
        "deprecated": false,
        "description": "Sandbox sends this webhook when an e-file job transitions to `succeeded` or `failed`, not for `created` or `queued` states. Configure your webhook URL in the Sandbox Console. See the [webhooks guide](https://developer.sandbox.co.in/guides/developer-resources/webhooks) for signature validation.",
        "operationId": "EFileJobStatus",
        "tags": [
          "E-File TDS Return"
        ],
        "parameters": [],
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "data": {
                    "description": "Job details at the time of the status change.",
                    "oneOf": [
                      {
                        "title": "Job Succeeded",
                        "type": "object",
                        "required": [
                          "@entity",
                          "job_id",
                          "tan",
                          "tax_year",
                          "quarter",
                          "form",
                          "filing_type",
                          "status",
                          "receipt_number",
                          "created_at",
                          "updated_at",
                          "receipt_file_url",
                          "fvu_file_url",
                          "form27a_file_url"
                        ],
                        "properties": {
                          "@entity": {
                            "type": "string",
                            "description": "Entity type identifier"
                          },
                          "job_id": {
                            "type": "string",
                            "description": "Unique identifier of the job"
                          },
                          "tan": {
                            "type": "string",
                            "description": "Tax Deduction Account Number"
                          },
                          "tax_year": {
                            "type": "string",
                            "description": "Tax year of the return (e.g. TY 2026-27)",
                            "examples": [
                              "TY 2026-27"
                            ],
                            "pattern": "^TY [0-9]{4}-[0-9]{2}$"
                          },
                          "quarter": {
                            "type": "string",
                            "description": "Quarter for which the return is filed (Q1–Q4)"
                          },
                          "form": {
                            "type": "string",
                            "description": "TDS form type (138, 140, 144, or 143)"
                          },
                          "filing_type": {
                            "type": "string",
                            "description": "Filing type (regular, original, or correction)"
                          },
                          "status": {
                            "type": "string",
                            "description": "Job status",
                            "enum": [
                              "succeeded"
                            ]
                          },
                          "receipt_number": {
                            "type": "integer",
                            "description": "Receipt number from the Income Tax Department confirming successful e-filing"
                          },
                          "created_at": {
                            "type": "integer",
                            "description": "Job creation time as a Unix timestamp in milliseconds"
                          },
                          "updated_at": {
                            "type": "integer",
                            "description": "Last status update time as a Unix timestamp in milliseconds"
                          },
                          "receipt_file_url": {
                            "type": "string",
                            "format": "uri",
                            "description": "Pre-signed URL to download the acknowledgement receipt PDF"
                          },
                          "fvu_file_url": {
                            "type": "string",
                            "format": "uri",
                            "description": "Pre-signed URL to download the FVU file"
                          },
                          "form27a_file_url": {
                            "type": "string",
                            "format": "uri",
                            "description": "Pre-signed URL to download the Form 27A PDF"
                          }
                        }
                      },
                      {
                        "title": "Job Failed",
                        "type": "object",
                        "required": [
                          "@entity",
                          "job_id",
                          "tan",
                          "tax_year",
                          "quarter",
                          "form",
                          "filing_type",
                          "status",
                          "message",
                          "created_at",
                          "updated_at"
                        ],
                        "properties": {
                          "@entity": {
                            "type": "string",
                            "description": "Entity type identifier"
                          },
                          "job_id": {
                            "type": "string",
                            "description": "Unique identifier of the job"
                          },
                          "tan": {
                            "type": "string",
                            "description": "Tax Deduction Account Number"
                          },
                          "tax_year": {
                            "type": "string",
                            "description": "Tax year of the return (e.g. TY 2026-27)",
                            "examples": [
                              "TY 2026-27"
                            ],
                            "pattern": "^TY [0-9]{4}-[0-9]{2}$"
                          },
                          "quarter": {
                            "type": "string",
                            "description": "Quarter for which the return is filed (Q1–Q4)"
                          },
                          "form": {
                            "type": "string",
                            "description": "TDS form type (138, 140, 144, or 143)"
                          },
                          "filing_type": {
                            "type": "string",
                            "description": "Filing type (regular, original, or correction)"
                          },
                          "status": {
                            "type": "string",
                            "description": "Job status",
                            "enum": [
                              "failed"
                            ]
                          },
                          "message": {
                            "type": "string",
                            "description": "Error message describing why the e-filing failed"
                          },
                          "created_at": {
                            "type": "integer",
                            "description": "Job creation time as a Unix timestamp in milliseconds"
                          },
                          "updated_at": {
                            "type": "integer",
                            "description": "Last status update time as a Unix timestamp in milliseconds"
                          }
                        }
                      }
                    ]
                  }
                }
              },
              "examples": {
                "Job Succeeded": {
                  "value": {
                    "data": {
                      "@entity": "in.co.sandbox.tds.compliance.e-file.job",
                      "job_id": "f845f37e-7f05-4de9-a282-a3b23b9d370a",
                      "tan": "AHMA09719B",
                      "tax_year": "TY 2026-27",
                      "quarter": "Q2",
                      "form": "140",
                      "filing_type": "regular",
                      "status": "succeeded",
                      "receipt_number": 123456789012345,
                      "created_at": 1763362637000,
                      "updated_at": 1763362650000,
                      "receipt_file_url": "https://in-co-sandbox-tds-test-storage.s3.ap-south-1.amazonaws.com/AHMS45586C/FY+2025-26/Q3/140/4049c226-4988-4978-b5ad-d25705453da8/receipt.pdf",
                      "fvu_file_url": "https://in-co-sandbox-tds-test-storage.s3.ap-south-1.amazonaws.com/AHMS45586C/FY+2025-26/Q3/140/4049c226-4988-4978-b5ad-d25705453da8/140.fvu",
                      "form27a_file_url": "https://in-co-sandbox-tds-test-storage.s3.ap-south-1.amazonaws.com/AHMS45586C/FY+2025-26/Q3/140/4049c226-4988-4978-b5ad-d25705453da8/form27A_140.pdf"
                    }
                  },
                  "summary": "Job Succeeded"
                },
                "Job Failed": {
                  "value": {
                    "data": {
                      "@entity": "in.co.sandbox.tds.compliance.e-file.job",
                      "job_id": "6e8d1908-c062-4846-a811-8f73054acd65",
                      "tan": "MUMR09719B",
                      "tax_year": "TY 2026-27",
                      "quarter": "Q2",
                      "form": "140",
                      "filing_type": "original",
                      "status": "failed",
                      "message": "Regular Statement with the same TAN, Tax Year, FORM and Quarter is already furnished",
                      "created_at": 1763362637000,
                      "updated_at": 1763362650000
                    }
                  },
                  "summary": "Job Failed"
                }
              }
            }
          },
          "required": true
        },
        "responses": {
          "200": {
            "description": "Return any 2xx status to acknowledge receipt. Sandbox retries delivery on non-2xx responses.",
            "headers": {}
          }
        },
        "security": []
      }
    }
  },
  "components": {
    "schemas": {
      "CertificateJob": {
        "type": "object",
        "additionalProperties": false,
        "description": "Certificate download job.",
        "required": [
          "@entity",
          "job_id",
          "tan",
          "tax_year",
          "quarter",
          "form",
          "status",
          "created_at"
        ],
        "properties": {
          "@entity": {
            "type": "string",
            "enum": [
              "in.co.sandbox.tds.compliance.certificate.job"
            ],
            "description": "Identifies the object as a certificate job."
          },
          "job_id": {
            "type": "string",
            "format": "uuid",
            "description": "Unique identifier for the certificate job."
          },
          "tan": {
            "type": "string",
            "pattern": "^[A-Z]{4}[0-9]{5}[A-Z]$",
            "description": "TAN used to request the certificate.",
            "examples": [
              "AHMS12345C"
            ]
          },
          "tax_year": {
            "type": "string",
            "pattern": "^TY [0-9]{4}-[0-9]{2}$",
            "description": "Tax year of the requested certificate.",
            "examples": [
              "TY 2025-26"
            ]
          },
          "quarter": {
            "type": "string",
            "enum": [
              "Q1",
              "Q2",
              "Q3",
              "Q4"
            ],
            "description": "Quarter of the requested certificate."
          },
          "form": {
            "type": "string",
            "description": "TDS return form of the requested certificate.",
            "examples": [
              "24Q"
            ]
          },
          "status": {
            "type": "string",
            "enum": [
              "created",
              "queued",
              "in_progress",
              "succeeded",
              "failed"
            ],
            "description": "Current status of the certificate job."
          },
          "created_at": {
            "type": "integer",
            "format": "int64",
            "description": "Time the job was created, in epoch milliseconds."
          },
          "updated_at": {
            "type": "integer",
            "format": "int64",
            "description": "Time the job was last updated, in epoch milliseconds. Omitted while the job is queued."
          },
          "certificate_pdf_zip_urls": {
            "type": "array",
            "minItems": 1,
            "description": "Presigned URLs for the certificate PDF ZIP files. Returned only for a succeeded job.",
            "items": {
              "type": "string",
              "format": "uri"
            }
          },
          "message": {
            "type": "string",
            "description": "Reason the job failed. Returned only for a failed job."
          }
        }
      },
      "CertificatePaginatedList": {
        "type": "object",
        "additionalProperties": false,
        "description": "Page of certificate jobs.",
        "required": [
          "@entity",
          "items"
        ],
        "properties": {
          "@entity": {
            "type": "string",
            "enum": [
              "in.co.sandbox.tds.compliance.certificate.paginated_list"
            ],
            "description": "Identifies the object as a page of certificate jobs."
          },
          "items": {
            "type": "array",
            "description": "Certificate jobs in the current page.",
            "items": {
              "$ref": "#/components/schemas/CertificateJob"
            }
          },
          "last_evaluated_key": {
            "type": "string",
            "description": "Opaque cursor for the next page. Omitted when no more results exist."
          }
        }
      },
      "CertificateJobRequest": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "@entity",
          "tan",
          "quarter",
          "tax_year",
          "form"
        ],
        "properties": {
          "@entity": {
            "type": "string",
            "enum": [
              "in.co.sandbox.tds.compliance.certificate.job.request"
            ],
            "description": "Identifies the object as a certificate job request."
          },
          "tan": {
            "type": "string",
            "pattern": "^[A-Z]{4}[0-9]{5}[A-Z]$",
            "description": "TAN used to request the certificate.",
            "examples": [
              "AHMS45586C"
            ]
          },
          "quarter": {
            "type": "string",
            "enum": [
              "Q1",
              "Q2",
              "Q3",
              "Q4"
            ],
            "description": "Quarter of the requested certificate."
          },
          "tax_year": {
            "type": "string",
            "pattern": "^TY [0-9]{4}-[0-9]{2}$",
            "description": "Tax year of the requested certificate.",
            "examples": [
              "TY 2025-26"
            ]
          },
          "form": {
            "type": "string",
            "description": "TDS return form of the requested certificate.",
            "examples": [
              "24Q"
            ]
          }
        }
      },
      "CertificateJobSearchRequest": {
        "type": "object",
        "description": "Filters used to search certificate generation jobs.",
        "properties": {
          "@entity": {
            "type": "string",
            "description": "Search request entity type.",
            "examples": [
              "in.co.sandbox.tds.compliance.certificate.job.search"
            ],
            "const": "in.co.sandbox.tds.compliance.certificate.job.search"
          },
          "tan": {
            "type": "string",
            "description": "Tax Deduction and Collection Account Number (TAN).",
            "examples": [
              "AHMS45586C"
            ]
          },
          "tax_year": {
            "type": "string",
            "description": "Tax year used to filter certificate jobs. Use the TY YYYY-YY format.",
            "examples": [
              "TY 2026-27"
            ],
            "pattern": "^TY [0-9]{4}-[0-9]{2}$"
          },
          "quarter": {
            "type": "string",
            "description": "Quarter used to filter certificate jobs.",
            "enum": [
              "Q1",
              "Q2",
              "Q3",
              "Q4"
            ]
          },
          "status": {
            "type": "string",
            "description": "Job status used to filter results.",
            "enum": [
              "created",
              "queued",
              "in_progress",
              "succeeded",
              "failed"
            ]
          },
          "page_size": {
            "type": "integer",
            "description": "Maximum number of jobs to return.",
            "minimum": 1,
            "maximum": 50,
            "default": 20
          },
          "last_evaluated_key": {
            "type": "string",
            "description": "Pagination key returned by the previous search response."
          },
          "from_date": {
            "type": "integer",
            "description": "Earliest job creation time, as a Unix timestamp in milliseconds."
          },
          "to_date": {
            "type": "integer",
            "description": "Latest job creation time, as a Unix timestamp in milliseconds."
          }
        },
        "required": [
          "@entity"
        ],
        "additionalProperties": false
      },
      "CertificateJobResponse": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "code",
          "timestamp",
          "transaction_id",
          "data"
        ],
        "properties": {
          "code": {
            "type": "integer",
            "description": "HTTP status code.",
            "examples": [
              200
            ]
          },
          "timestamp": {
            "type": "integer",
            "format": "int64",
            "description": "Response timestamp in epoch milliseconds.",
            "examples": [
              1716870600000
            ]
          },
          "transaction_id": {
            "type": "string",
            "description": "Transaction identifier used to trace the API request.",
            "examples": [
              "f24cd229-42c8-43de-af79-8ce2d3c4c3db"
            ]
          },
          "data": {
            "$ref": "#/components/schemas/CertificateJob"
          }
        }
      },
      "CertificatePaginatedListResponse": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "code",
          "timestamp",
          "transaction_id",
          "data"
        ],
        "properties": {
          "code": {
            "type": "integer",
            "description": "HTTP status code.",
            "examples": [
              200
            ]
          },
          "timestamp": {
            "type": "integer",
            "format": "int64",
            "description": "Response timestamp in epoch milliseconds.",
            "examples": [
              1716870600000
            ]
          },
          "transaction_id": {
            "type": "string",
            "description": "Transaction identifier used to trace the API request.",
            "examples": [
              "f24cd229-42c8-43de-af79-8ce2d3c4c3db"
            ]
          },
          "data": {
            "$ref": "#/components/schemas/CertificatePaginatedList"
          }
        }
      },
      "ErrorResponse": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "code",
          "timestamp",
          "transaction_id",
          "message"
        ],
        "properties": {
          "code": {
            "type": "integer",
            "description": "HTTP status code."
          },
          "timestamp": {
            "type": "integer",
            "format": "int64",
            "description": "Response timestamp in epoch milliseconds."
          },
          "transaction_id": {
            "type": "string",
            "description": "Transaction identifier used to trace the API request."
          },
          "message": {
            "type": "string",
            "description": "Error message."
          }
        }
      }
    },
    "responses": {
      "BadRequest": {
        "description": "Bad request",
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/ErrorResponse"
            }
          }
        }
      },
      "Forbidden": {
        "description": "TRACES access token is missing or expired",
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/ErrorResponse"
            }
          }
        }
      },
      "UnprocessableEntity": {
        "description": "Request validation failed",
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/ErrorResponse"
            },
            "examples": {
              "invalidRequest": {
                "summary": "invalidRequest",
                "value": {
                  "code": 422,
                  "timestamp": 1716870600000,
                  "transaction_id": "f24cd229-42c8-43de-af79-8ce2d3c4c3db",
                  "message": "Invalid certificate request"
                }
              }
            }
          }
        }
      },
      "DataNotFound": {
        "description": "Certificate job was not found",
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/ErrorResponse"
            },
            "examples": {
              "notFound": {
                "summary": "notFound",
                "value": {
                  "code": 521,
                  "timestamp": 1716870600000,
                  "transaction_id": "f24cd229-42c8-43de-af79-8ce2d3c4c3db",
                  "message": "Data not found for the supplied job_id"
                }
              }
            }
          }
        }
      },
      "InternalServerError": {
        "description": "Internal server error",
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/ErrorResponse"
            }
          }
        }
      },
      "Unauthorized": {
        "description": "The access token is missing or invalid.",
        "content": {
          "application/json": {
            "schema": {
              "type": "object",
              "properties": {}
            }
          }
        }
      },
      "CredentialAlreadyExists": {
        "description": "A credential already exists for the authenticated workspace and TAN.",
        "content": {
          "application/json": {
            "schema": {
              "type": "object",
              "properties": {}
            }
          }
        }
      },
      "CredentialNotFound": {
        "description": "No credential exists for the authenticated workspace and TAN.",
        "content": {
          "application/json": {
            "schema": {
              "type": "object",
              "properties": {}
            }
          }
        }
      }
    },
    "securitySchemes": {
      "TracesAccessToken": {
        "type": "apiKey",
        "in": "header",
        "name": "Authorization",
        "description": "Raw TRACES access token returned by login. Do not prefix the token with Bearer."
      },
      "ApiKeyAuth": {
        "type": "apiKey",
        "in": "header",
        "name": "x-api-key",
        "description": "API key used to identify and authenticate the client."
      },
      "SandboxAccessToken": {
        "type": "apiKey",
        "in": "header",
        "name": "Authorization",
        "description": "JWT access token. For token-generation steps, refer to the [Quickstart Guide](https://developer.sandbox.co.in/guides/get-started/quickstart)."
      },
      "accessTokenAuth": {
        "type": "apiKey",
        "in": "header",
        "name": "Authorization",
        "description": "JWT access token. For token-generation steps, refer to the [Quickstart Guide](https://developer.sandbox.co.in/guides/get-started/quickstart)."
      },
      "apiKeyAuth": {
        "type": "apiKey",
        "in": "header",
        "name": "x-api-key",
        "description": "API key used to identify and authenticate the client."
      }
    }
  },
  "servers": [
    {
      "url": "https://test-api.sandbox.co.in",
      "description": "test"
    },
    {
      "url": "https://api.sandbox.co.in",
      "description": "prod"
    }
  ],
  "security": []
}
