{
  "openapi": "3.1.0",
  "info": {
    "title": "Checkfmt API",
    "version": "1.0.0",
    "description": "Validate IBANs, BIC/SWIFT codes, EU VAT numbers (via the official EU VIES service), and vehicle VINs (via the US NHTSA vPIC database) through one fast developer API. IBAN and BIC are pure compute (ISO 13616 mod-97 and ISO 9362); VAT and VIN relay official government sources. No submitted identifiers are stored.\n\nFree tier: 1,000 calls/month with no card. Get a key at https://www.checkfmt.com/#get-key.",
    "contact": { "name": "Checkfmt", "url": "https://www.checkfmt.com" }
  },
  "servers": [{ "url": "https://www.checkfmt.com", "description": "Production" }],
  "security": [{ "bearerAuth": [] }, { "apiKeyQuery": [] }],
  "tags": [
    { "name": "Bank identifiers", "description": "IBAN and BIC/SWIFT validation (pure compute)." },
    { "name": "Business & vehicle", "description": "EU VAT (VIES relay) and VIN (NHTSA relay) lookups." }
  ],
  "paths": {
    "/api/v1/iban": {
      "get": {
        "operationId": "validateIban",
        "summary": "Validate an IBAN",
        "description": "Validates an IBAN against the ISO 13616 mod-97 checksum and per-country length (40 countries). Pure compute, no external lookup.",
        "tags": ["Bank identifiers"],
        "parameters": [
          {
            "name": "iban",
            "in": "query",
            "required": true,
            "description": "IBAN to validate. Spaces are ignored and input is upper-cased.",
            "schema": { "type": "string", "example": "DE89370400440532013000" }
          },
          { "$ref": "#/components/parameters/KeyQuery" }
        ],
        "responses": {
          "200": {
            "description": "Validation result.",
            "content": {
              "application/json": {
                "schema": { "$ref": "#/components/schemas/IbanResult" },
                "example": {
                  "input": "DE89370400440532013000",
                  "normalized": "DE89370400440532013000",
                  "valid": true,
                  "countryCode": "DE",
                  "country": "Germany",
                  "expectedLength": 22,
                  "actualLength": 22,
                  "checksumValid": true,
                  "lengthValid": true
                }
              }
            }
          },
          "400": { "$ref": "#/components/responses/MissingParam" },
          "401": { "$ref": "#/components/responses/Unauthorized" },
          "429": { "$ref": "#/components/responses/RateLimited" }
        }
      }
    },
    "/api/v1/bic": {
      "get": {
        "operationId": "validateBic",
        "summary": "Validate a BIC / SWIFT code",
        "description": "Validates a BIC/SWIFT code against the ISO 9362 format and breaks out the bank, country, location, and branch codes. Pure compute, no external lookup.",
        "tags": ["Bank identifiers"],
        "parameters": [
          {
            "name": "bic",
            "in": "query",
            "required": true,
            "description": "BIC / SWIFT code (8 or 11 characters). Spaces are ignored and input is upper-cased.",
            "schema": { "type": "string", "example": "DEUTDEFF500" }
          },
          { "$ref": "#/components/parameters/KeyQuery" }
        ],
        "responses": {
          "200": {
            "description": "Validation result.",
            "content": {
              "application/json": {
                "schema": { "$ref": "#/components/schemas/BicResult" },
                "example": {
                  "input": "DEUTDEFF500",
                  "normalized": "DEUTDEFF500",
                  "valid": true,
                  "bankCode": "DEUT",
                  "countryCode": "DE",
                  "locationCode": "FF",
                  "branchCode": "500",
                  "type": "11-digit (branch)"
                }
              }
            }
          },
          "400": { "$ref": "#/components/responses/MissingParam" },
          "401": { "$ref": "#/components/responses/Unauthorized" },
          "429": { "$ref": "#/components/responses/RateLimited" }
        }
      }
    },
    "/api/v1/vat": {
      "get": {
        "operationId": "validateVat",
        "summary": "Validate an EU VAT number (VIES)",
        "description": "Relays a VAT lookup to the official EU VIES service. Returns validity and, when the member state exposes it, the registered company name and address.",
        "tags": ["Business & vehicle"],
        "parameters": [
          {
            "name": "vat",
            "in": "query",
            "required": true,
            "description": "Full VAT id including the two-letter EU country code.",
            "schema": { "type": "string", "example": "DE811569869" }
          },
          {
            "name": "number",
            "in": "query",
            "required": false,
            "description": "Alias for `vat`. Either parameter is accepted.",
            "schema": { "type": "string" }
          },
          { "$ref": "#/components/parameters/KeyQuery" }
        ],
        "responses": {
          "200": {
            "description": "VIES lookup result.",
            "content": {
              "application/json": {
                "schema": { "$ref": "#/components/schemas/VatResult" },
                "example": {
                  "vatNumber": "DE811569869",
                  "countryCode": "DE",
                  "valid": true,
                  "name": "—",
                  "address": null,
                  "source": "EU VIES"
                }
              }
            }
          },
          "400": { "$ref": "#/components/responses/MissingParam" },
          "401": { "$ref": "#/components/responses/Unauthorized" },
          "422": { "$ref": "#/components/responses/Unprocessable" },
          "429": { "$ref": "#/components/responses/RateLimited" },
          "502": { "$ref": "#/components/responses/UpstreamUnavailable" }
        }
      }
    },
    "/api/v1/vin": {
      "get": {
        "operationId": "decodeVin",
        "summary": "Decode & validate a VIN (NHTSA)",
        "description": "Validates a 17-character VIN format (no I/O/Q) and decodes it via the US NHTSA vPIC database. Returns make, model, year, manufacturer, body class, and plant country.",
        "tags": ["Business & vehicle"],
        "parameters": [
          {
            "name": "vin",
            "in": "query",
            "required": true,
            "description": "17-character Vehicle Identification Number.",
            "schema": { "type": "string", "example": "1HGCM82633A004352" }
          },
          { "$ref": "#/components/parameters/KeyQuery" }
        ],
        "responses": {
          "200": {
            "description": "Decoded VIN. Cached for 24 hours.",
            "content": {
              "application/json": {
                "schema": { "$ref": "#/components/schemas/VinResult" },
                "example": {
                  "vin": "1HGCM82633A004352",
                  "valid": true,
                  "make": "HONDA",
                  "model": "Accord",
                  "modelYear": "2003",
                  "manufacturer": "AMERICAN HONDA MOTOR CO., INC.",
                  "vehicleType": "PASSENGER CAR",
                  "bodyClass": "Coupe",
                  "plantCountry": "UNITED STATES (USA)",
                  "errorText": null,
                  "source": "US NHTSA vPIC"
                }
              }
            }
          },
          "400": { "$ref": "#/components/responses/MissingParam" },
          "401": { "$ref": "#/components/responses/Unauthorized" },
          "422": { "$ref": "#/components/responses/Unprocessable" },
          "429": { "$ref": "#/components/responses/RateLimited" },
          "502": { "$ref": "#/components/responses/UpstreamUnavailable" }
        }
      }
    }
  },
  "components": {
    "securitySchemes": {
      "bearerAuth": {
        "type": "http",
        "scheme": "bearer",
        "description": "Send your API key as `Authorization: Bearer YOUR_KEY`."
      },
      "apiKeyQuery": {
        "type": "apiKey",
        "in": "query",
        "name": "key",
        "description": "Send your API key as the `key` query parameter, e.g. `?key=YOUR_KEY`."
      }
    },
    "parameters": {
      "KeyQuery": {
        "name": "key",
        "in": "query",
        "required": false,
        "description": "API key. Provide here or via the `Authorization: Bearer` header. Free tier is 1,000 calls/month.",
        "schema": { "type": "string", "example": "YOUR_KEY" }
      }
    },
    "responses": {
      "MissingParam": {
        "description": "A required query parameter is missing.",
        "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }
      },
      "Unauthorized": {
        "description": "Missing or invalid API key.",
        "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }
      },
      "Unprocessable": {
        "description": "Input is malformed (e.g. VAT without a country code, or a VIN that is not 17 valid characters).",
        "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }
      },
      "RateLimited": {
        "description": "Monthly call limit reached for this key.",
        "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }
      },
      "UpstreamUnavailable": {
        "description": "The upstream government relay (EU VIES or US NHTSA) is temporarily unavailable. Safe to retry.",
        "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }
      }
    },
    "schemas": {
      "Error": {
        "type": "object",
        "required": ["error"],
        "properties": {
          "error": { "type": "string", "description": "Human-readable error message.", "example": "Missing API key" }
        }
      },
      "IbanResult": {
        "type": "object",
        "properties": {
          "input": { "type": "string" },
          "normalized": { "type": "string" },
          "valid": { "type": "boolean" },
          "countryCode": { "type": ["string", "null"] },
          "country": { "type": ["string", "null"] },
          "expectedLength": { "type": ["integer", "null"] },
          "actualLength": { "type": "integer" },
          "checksumValid": { "type": "boolean" },
          "lengthValid": { "type": "boolean" },
          "reason": { "type": "string", "description": "Present only when invalid." }
        }
      },
      "BicResult": {
        "type": "object",
        "properties": {
          "input": { "type": "string" },
          "normalized": { "type": "string" },
          "valid": { "type": "boolean" },
          "bankCode": { "type": ["string", "null"] },
          "countryCode": { "type": ["string", "null"] },
          "locationCode": { "type": ["string", "null"] },
          "branchCode": { "type": ["string", "null"] },
          "type": {
            "type": ["string", "null"],
            "enum": ["8-digit (primary office)", "11-digit (branch)", null]
          }
        }
      },
      "VatResult": {
        "type": "object",
        "properties": {
          "vatNumber": { "type": "string" },
          "countryCode": { "type": "string" },
          "valid": { "type": "boolean" },
          "name": { "type": ["string", "null"], "description": "Registered company name, when the member state exposes it." },
          "address": { "type": ["string", "null"] },
          "source": { "type": "string", "example": "EU VIES" }
        }
      },
      "VinResult": {
        "type": "object",
        "properties": {
          "vin": { "type": "string" },
          "valid": { "type": "boolean" },
          "make": { "type": ["string", "null"] },
          "model": { "type": ["string", "null"] },
          "modelYear": { "type": ["string", "null"] },
          "manufacturer": { "type": ["string", "null"] },
          "vehicleType": { "type": ["string", "null"] },
          "bodyClass": { "type": ["string", "null"] },
          "plantCountry": { "type": ["string", "null"] },
          "errorText": { "type": ["string", "null"], "description": "NHTSA error text when a VIN is partial or unrecognized." },
          "source": { "type": "string", "example": "US NHTSA vPIC" }
        }
      }
    }
  }
}