{
  "openapi": "3.0.3",
  "info": {
    "title": "Tax Rates By Address",
    "description": "Provides tax rate data as applicable for a given address, reflecting actual processing logic in the application. Accepts address input and returns location-specific tax rate information, including status and fallback logic.",
    "termsOfService": "https://thefinder.tax.ohio.gov/webservice",
    "contact": {
      "name": "Ohio Department of Taxation Finder Team",
      "url": "https://thefinder.tax.ohio.gov/contactus",
      "email": "TheFinderHelp@tax.ohio.gov"
    },
    "version": "1.0.0"
  },
  "servers": [
    {
      "url": "https://api.finder.tax.ohio.gov",
      "description": "Production"
    }
  ],
  "tags": [
    {
      "name": "Address",
      "description": "Search Address"
    }
  ],
  "paths": {
    "/finder/api/v1/tax-rates/address": {
      "post": {
        "tags": [
          "Address"
        ],
        "summary": "Search Tax Rates by address",
        "description": "Returns tax rate data for a given address. If address is found, returns full data. If not found, returns zip code-based rates and status.",
        "operationId": "GetTaxRatesByAddress",
        "parameters": [
          {
            "name": "x-globalTransaction-id",
            "in": "header",
            "description": "Unique identifier of a transaction",
            "required": false,
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "x-source",
            "in": "header",
            "description": "Source system identifier for request tracking",
            "required": false,
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "x-api-key",
            "in": "header",
            "description": "User's API Key for access",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/AddressRequest"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Successful response with tax rates and address status if found or error response when no tax rates returned.",
            "content": {
              "application/json": {
                "schema": {
                  "oneOf": [
                    {
                      "$ref": "#/components/schemas/AddressResponse"
                    },
                    {
                      "$ref": "#/components/schemas/ErrorResponse"
                    }
                  ]
                }
              }
            }
          },
          "400": {
            "description": "Bad Request (Validation Error)",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          },
          "500": {
            "description": "Internal Server Error",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          }
        }
      }
    }
  },
  "components": {
    "schemas": {
      "Address": {
        "type": "object",
        "required": [
          "streetAddress",
          "state",
          "zipCode"
        ],
        "properties": {
          "streetAddress": {
            "type": "string",
            "nullable": true
          },
          "addressLine2": {
            "type": "string",
            "nullable": true
          },
          "city": {
            "type": "string",
            "nullable": true
          },
          "state": {
            "type": "string",
            "nullable": true
          },
          "zipCode": {
            "type": "string"
          },
          "zipPlus4": {
            "type": "string"
          }
        }
      },
      "AddressRequest": {
        "type": "object",
        "required": [
          "inputAddress",
          "date"
        ],
        "properties": {
          "inputAddress": {
            "$ref": "#/components/schemas/Address"
          },
          "date": {
            "type": "string",
            "description": "MM/DD/YYYY"
          },
          "taxableAmount": {
            "type": "number",
            "default": 0,
            "description": "Optional. Defaults to 0 when omitted."
          },
          "taxTypes": {
            "type": "array",
            "description": "Optional. When omitted or empty, all tax types are returned.",
            "items": {
              "type": "string",
              "enum": [
                "salesAndUse",
                "schoolDistrict",
                "municipal"
              ]
            }
          }
        }
      },
      "FoundAddress": {
        "type": "object",
        "properties": {
          "address": {
            "$ref": "#/components/schemas/Address"
          },
          "physicalCity": {
            "type": "string",
            "nullable": true
          },
          "townshipName": {
            "type": "string",
            "nullable": true
          },
          "townshipFips": {
            "type": "string",
            "nullable": true
          }
        }
      },
      "TaxRates": {
        "type": "object",
        "properties": {
          "date": {
            "type": "string",
            "description": "Returns in YYYY-MM-DD format."
          },
          "salesTaxRateData": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/SalesTRData"
            }
          },
          "schoolTaxRateData": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/SchoolDistrictTRData"
            }
          },
          "municipalTaxRateData": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/MunicipalTRData"
            }
          },
          "jedTaxRateData": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/JedTRData"
            }
          }
        }
      },
      "SalesTRData": {
        "type": "object",
        "properties": {
          "stateName": {
            "type": "string"
          },
          "stateFips": {
            "type": "string"
          },
          "stateSalesTaxRate": {
            "type": "number"
          },
          "countyName": {
            "type": "string"
          },
          "countyFips": {
            "type": "string"
          },
          "countyCode": {
            "type": "string"
          },
          "countySalesTaxRate": {
            "type": "number"
          },
          "transitName": {
            "type": "string"
          },
          "transitFipsPlace": {
            "type": "string"
          },
          "transitSalesTaxRate": {
            "type": "number",
            "nullable": true
          },
          "totalTaxRate": {
            "type": "number"
          },
          "totalTaxableAmount": {
            "type": "number"
          }
        }
      },
      "SchoolDistrictTRData": {
        "type": "object",
        "properties": {
          "name": {
            "type": "string"
          },
          "sd_Number": {
            "type": "string"
          },
          "doe_Number": {
            "type": "string"
          },
          "taxRate": {
            "type": "number",
            "nullable": true
          }
        }
      },
      "MunicipalTRData": {
        "type": "object",
        "properties": {
          "name": {
            "type": "string"
          },
          "fipsCode": {
            "type": "string"
          },
          "taxRate": {
            "type": "number",
            "nullable": true
          }
        }
      },
      "JedTRData": {
        "type": "object",
        "properties": {
          "name": {
            "type": "string"
          },
          "id": {
            "type": "string"
          },
          "taxRate": {
            "type": "number",
            "nullable": true
          }
        }
      },
      "AddressResponse": {
        "type": "object",
        "properties": {
          "inputAddress": {
            "$ref": "#/components/schemas/Address"
          },
          "foundAddress": {
            "$ref": "#/components/schemas/FoundAddress"
          },
          "taxRates": {
            "$ref": "#/components/schemas/TaxRates"
          },
          "referenceID": {
            "type": "string",
            "description": "Reference ID in the format of MMYY-#######, where M and Y are the month and year of the query."
          },
          "addressStatus": {
            "type": "string",
	    "description": "Confidence value of the address result.",
            "enum": [
              "Found",
              "FoundLowConfidence",
              "NotFound",
              "PoBox",
              "None"
            ]
          },
          "message": {
            "type": "string",
            "description": "Associated message and disclaimers with found address.",
            "nullable": true
          }
        }
      },
      "ErrorResponse": {
        "type": "object",
        "properties": {
          "errorCode": {
            "type": "string"
          },
          "errorMessage": {
            "type": "string"
          },
          "errorDescription": {
            "type": "string"
          }
        }
      }
    }
  }
}