{
  "openapi": "3.1.0",
  "info": {
    "title": "Verified Hotel Codes — public lookup",
    "version": "1.0.0",
    "description": "Read-only lookup of published hotel corporate codes. Returns the code, how many independent listings confirmed it, and the month it was last checked. No authentication is required or offered.",
    "contact": { "url": "https://verifiedhotelcodes.com/contact" },
    "license": { "name": "See site terms", "url": "https://verifiedhotelcodes.com/privacy" }
  },
  "servers": [ { "url": "https://verifiedhotelcodes.com" } ],
  "security": [],
  "tags": [
    { "name": "lookup", "description": "Published corporate code table" }
  ],
  "paths": {
    "/api/agent": {
      "get": {
        "operationId": "lookupCorporateCode",
        "tags": ["lookup"],
        "summary": "Look up a published hotel corporate code by company name",
        "description": "Case-insensitive substring match against the company column of the published table. Read-only. Returns found:false when nothing matches; this means not listed, not that no rate exists.",
        "security": [],
        "parameters": [
          {
            "name": "company",
            "in": "query",
            "required": false,
            "schema": { "type": "string", "minLength": 1, "maxLength": 80 },
            "description": "Company name or fragment, e.g. Microsoft",
            "example": "Microsoft"
          },
          {
            "name": "limit",
            "in": "query",
            "required": false,
            "schema": { "type": "integer", "minimum": 1, "maximum": 50, "default": 20 },
            "description": "Maximum number of results"
          }
        ],
        "responses": {
          "200": {
            "description": "Lookup completed. found may be true or false.",
            "content": {
              "application/json": {
                "schema": { "$ref": "#/components/schemas/LookupResponse" },
                "example": {
                  "found": true,
                  "query": "Microsoft",
                  "count": 1,
                  "results": [
                    { "company": "Microsoft", "code": "43773", "tier": "single-source", "sources": 1, "last_checked": "Sep 2026", "source_url": "https://verifiedhotelcodes.com/" }
                  ],
                  "source_url": "https://verifiedhotelcodes.com/"
                }
              }
            }
          }
        }
      }
    },
    "/data/codes.json": {
      "get": {
        "operationId": "getWholeTable",
        "tags": ["lookup"],
        "summary": "The whole published table",
        "security": [],
        "responses": {
          "200": {
            "description": "Full published table",
            "content": { "application/json": { "schema": { "type": "object" } } }
          }
        }
      }
    },
    "/api/health": {
      "get": {
        "operationId": "health",
        "tags": ["lookup"],
        "summary": "Service status",
        "security": [],
        "responses": {
          "200": {
            "description": "Service is up",
            "content": {
              "application/json": {
                "schema": { "type": "object" },
                "example": { "status": "ok", "service": "verifiedhotelcodes-lookup", "auth_required": false }
              }
            }
          }
        }
      }
    }
  },
  "components": {
    "schemas": {
      "CodeResult": {
        "type": "object",
        "required": ["company", "code", "tier", "last_checked"],
        "properties": {
          "company": { "type": "string" },
          "code": { "type": "string" },
          "tier": { "type": "string", "enum": ["multi-source", "single-source", "unverified-or-expired"] },
          "sources": { "type": "integer", "minimum": 0 },
          "last_checked": { "type": "string", "description": "Month the code was last confirmed as listed" },
          "note": { "type": "string" },
          "source_url": { "type": "string", "format": "uri" }
        }
      },
      "LookupResponse": {
        "type": "object",
        "required": ["found", "query", "count", "results"],
        "properties": {
          "found": { "type": "boolean" },
          "query": { "type": "string" },
          "count": { "type": "integer" },
          "results": { "type": "array", "items": { "$ref": "#/components/schemas/CodeResult" } },
          "message": { "type": "string" },
          "source_url": { "type": "string", "format": "uri" }
        }
      }
    }
  }
}