@apifreaks/openapi-specs 0.1.0

package/specs/financial/swift-code-lookup.json

@@ -0,0 +1,220 @@
+{
+  "openapi": "3.1.1",
+  "info": {
+    "title": "SWIFT/BIC Code API - Look Up Bank Details or Find Codes by Country, Bank & City",
+    "version": "1.0.0",
+    "description": "Look up a SWIFT/BIC code to retrieve bank details. Returns the bank name, address, city, country, country code, and bank code for any valid 8 or 11 character SWIFT/BIC code. Supports both headquarters and branch-level SWIFT codes.",
+    "contact": {
+      "name": "APIFreaks Support",
+      "url": "https://apifreaks.com/contact",
+      "email": "support@apifreaks.com"
+    }
+  },
+  "servers": [
+    {
+      "url": "https://api.apifreaks.com/v1.0",
+      "description": "SWIFT/BIC Code Lookup API Server"
+    }
+  ],
+  "paths": {
+    "/swift-code/lookup": {
+      "get": {
+        "tags": ["Financial APIs"],
+        "summary": "Lookup SWIFT code details",
+        "description": "Fetches detailed information about a SWIFT code.",
+        "parameters": [
+          {
+            "name": "format",
+            "in": "query",
+            "required": false,
+            "schema": {
+              "type": "string",
+              "enum": ["json", "xml"],
+              "default": "json"
+            },
+            "description": "Specify the desired response format. Options: 'json' (default) or 'xml'."
+          },
+          {
+            "name": "swiftCode",
+            "in": "query",
+            "required": true,
+            "schema": {
+              "type": "string"
+            },
+            "description": "SWIFT/BIC code to lookup (must be 8 or 11 characters)."
+          }
+        ],
+        "responses": {
+          "200": {
+            "description": "Successful response",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/SwiftCodeLookup"
+                },
+                "examples": {
+                  "typicalSuccess": {
+                    "summary": "Typical successful response — normalized to 11-character form",
+                    "value": {
+                      "swiftCode": "NWBKGB2LXXX",
+                      "countryCode": "GB",
+                      "bankAddress": "250 BISHOPSGATE",
+                      "bankCode": "NWBK",
+                      "bankName": "NATIONAL WESTMINSTER BANK PLC",
+                      "city": "LONDON",
+                      "country": "United Kingdom"
+                    }
+                  }
+                }
+              }
+            }
+          },
+          "400": {
+            "description": "Bad Request",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/ErrorResponse"
+                },
+                "examples": {
+                  "MissingSwiftCode": {
+                    "summary": "Missing required swiftCode parameter",
+                    "value": {
+                      "error": "Invalid Param Exception",
+                      "message": "please pass correct parameters",
+                      "path": "/v1.0/swift-code/lookup",
+                      "status": 400,
+                      "timestamp": "2026-07-27T11:50:49.650Z"
+                    }
+                  },
+                  "BadLength": {
+                    "summary": "swiftCode is not 8 or 11 characters",
+                    "value": {
+                      "message": "Bad request: SWIFT code input must be either 8 characters or 11 characters"
+                    }
+                  }
+                }
+              }
+            }
+          },
+          "404": {
+            "description": "Not Found",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/ErrorResponse"
+                },
+                "examples": {
+                  "NotFound": {
+                    "summary": "SWIFT code not found",
+                    "value": {
+                      "message": "No bank found with the provided SWIFT code"
+                    }
+                  }
+                }
+              }
+            }
+          }
+        },
+        "operationId": "lookupSwiftCode"
+      }
+    }
+  },
+  "components": {
+    "securitySchemes": {
+      "ApiKeyAuthHeader": {
+        "type": "apiKey",
+        "in": "header",
+        "name": "X-apiKey",
+        "description": "Pass your API key via the X-apiKey request header."
+      },
+      "ApiKeyAuthQuery": {
+        "type": "apiKey",
+        "in": "query",
+        "name": "apiKey",
+        "description": "Pass your API key via the apiKey query parameter."
+      }
+    },
+    "schemas": {
+      "SwiftCodeLookup": {
+        "type": "object",
+        "properties": {
+          "swiftCode": {
+            "type": "string",
+            "description": "SWIFT/BIC code, normalized to its 11-character form (an 8-character input is returned padded with XXX)."
+          },
+          "countryCode": {
+            "type": "string",
+            "description": "ISO 3166-1 alpha-2 country code where the bank is registered."
+          },
+          "bankAddress": {
+            "type": "string",
+            "description": "Physical address of the bank branch."
+          },
+          "bankCode": {
+            "type": "string",
+            "description": "Bank code portion of the SWIFT code (first 4 characters)."
+          },
+          "bankName": {
+            "type": "string",
+            "description": "Full name of the bank or financial institution."
+          },
+          "city": {
+            "type": "string",
+            "description": "City where the bank branch is located."
+          },
+          "country": {
+            "type": "string",
+            "description": "Full country name where the bank is registered."
+          }
+        },
+        "required": [
+          "swiftCode",
+          "countryCode",
+          "bankAddress",
+          "bankCode",
+          "bankName",
+          "city",
+          "country"
+        ],
+        "description": "Bank details returned for a SWIFT/BIC code lookup."
+      },
+      "ErrorResponse": {
+        "type": "object",
+        "required": ["message"],
+        "properties": {
+          "error": {
+            "type": "string",
+            "description": "Short error category or exception type."
+          },
+          "message": {
+            "type": "string",
+            "description": "Human-readable error message describing the failure."
+          },
+          "path": {
+            "type": "string",
+            "description": "API endpoint path that produced the error."
+          },
+          "status": {
+            "type": "integer",
+            "description": "HTTP status code returned with the error."
+          },
+          "timestamp": {
+            "type": "string",
+            "format": "date-time",
+            "description": "Timestamp when the error occurred (ISO 8601)."
+          }
+        },
+        "description": "Standard error envelope returned by the API on failed requests."
+      }
+    }
+  },
+  "security": [
+    {
+      "ApiKeyAuthHeader": []
+    },
+    {
+      "ApiKeyAuthQuery": []
+    }
+  ]
+}

package/specs/financial/vat-number-validation.json

@@ -0,0 +1,283 @@
+{
+  "openapi": "3.1.1",
+  "info": {
+    "title": "VAT Number Validation API - Real-time VAT Validations across EU & UK",
+    "version": "1.0.0",
+    "description": "Validate a VAT number against the VIES or HMRC databases. Supports all EU VAT numbers (validated against VIES) and UK VAT numbers (validated against HMRC). Returns validation status, consultation number, authority used, and company registration details. Optionally accepts a requester VAT number for match-based validation.",
+    "contact": {
+      "name": "APIFreaks Support",
+      "url": "https://apifreaks.com/contact",
+      "email": "support@apifreaks.com"
+    }
+  },
+  "servers": [
+    {
+      "url": "https://api.apifreaks.com/v1.0",
+      "description": "VAT Number Validation API Server"
+    }
+  ],
+  "paths": {
+    "/vat/validation": {
+      "get": {
+        "tags": ["Financial APIs"],
+        "summary": "Validate EU and UK VAT number",
+        "description": "Validates an EU or UK VAT number and returns registration status details.",
+        "parameters": [
+          {
+            "name": "format",
+            "in": "query",
+            "required": false,
+            "schema": {
+              "type": "string",
+              "enum": ["json", "xml"],
+              "default": "json"
+            },
+            "description": "Specify the desired response format. Options: 'json' (default) or 'xml'."
+          },
+          {
+            "name": "vatNumber",
+            "in": "query",
+            "required": true,
+            "schema": {
+              "type": "string"
+            },
+            "description": "EU or UK VAT number to validate."
+          },
+          {
+            "name": "requesterVatNumber",
+            "in": "query",
+            "required": false,
+            "schema": {
+              "type": "string"
+            },
+            "description": "Requester EU or UK VAT number."
+          }
+        ],
+        "responses": {
+          "200": {
+            "description": "Successful response",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/VatValidationResponse"
+                },
+                "examples": {
+                  "typicalSuccess": {
+                    "summary": "Validation without a requester VAT number",
+                    "value": {
+                      "country_code": "GB",
+                      "vat_number": "289111588",
+                      "requested_at": "2026-07-27T11:48:43.000Z",
+                      "validation": {
+                        "is_valid": true,
+                        "consultation_authority": "HMRC"
+                      },
+                      "company": {
+                        "company_name": "EVENTURED LTD",
+                        "company_address": "SUITE 10, BEAUFORT COURT, ADMIRALS WAY, LONDON, E14 9XL, GB"
+                      }
+                    }
+                  },
+                  "withRequesterVatNumber": {
+                    "summary": "Validation with a requester VAT number (returns a consultation_number)",
+                    "value": {
+                      "country_code": "GB",
+                      "vat_number": "289111588",
+                      "requester_country_code": "GB",
+                      "requester_vat_number": "288305674",
+                      "requested_at": "2026-07-27T11:48:44.000Z",
+                      "validation": {
+                        "is_valid": true,
+                        "consultation_number": "YCM-VHX-WXF",
+                        "consultation_authority": "HMRC"
+                      },
+                      "company": {
+                        "company_name": "EVENTURED LTD",
+                        "company_address": "SUITE 10, BEAUFORT COURT, ADMIRALS WAY, LONDON, E14 9XL, GB"
+                      }
+                    }
+                  }
+                }
+              }
+            }
+          },
+          "400": {
+            "description": "Bad Request",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/ErrorResponse"
+                },
+                "examples": {
+                  "MissingVatNumber": {
+                    "summary": "Missing required vatNumber parameter",
+                    "value": {
+                      "error": "Invalid Param Exception",
+                      "message": "please pass correct parameters",
+                      "path": "/v1.0/vat/validation",
+                      "status": 400,
+                      "timestamp": "2026-07-27T11:48:44.845Z"
+                    }
+                  },
+                  "UnsupportedCountry": {
+                    "summary": "Unsupported VAT country code",
+                    "value": {
+                      "message": "Unsupported VAT country code. Supported prefixes are UK/GB and EU VAT country codes."
+                    }
+                  }
+                }
+              }
+            }
+          },
+          "404": {
+            "description": "Not Found",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/ErrorResponse"
+                },
+                "examples": {
+                  "NotFound": {
+                    "summary": "VAT number not found",
+                    "value": {
+                      "message": "targetVrn does not match a registered company"
+                    }
+                  }
+                }
+              }
+            }
+          }
+        },
+        "operationId": "validateVatNumber"
+      }
+    }
+  },
+  "components": {
+    "securitySchemes": {
+      "ApiKeyAuthHeader": {
+        "type": "apiKey",
+        "in": "header",
+        "name": "X-apiKey",
+        "description": "Pass your API key via the X-apiKey request header."
+      },
+      "ApiKeyAuthQuery": {
+        "type": "apiKey",
+        "in": "query",
+        "name": "apiKey",
+        "description": "Pass your API key via the apiKey query parameter."
+      }
+    },
+    "schemas": {
+      "VatValidationResponse": {
+        "type": "object",
+        "properties": {
+          "country_code": {
+            "type": "string",
+            "description": "VAT country prefix extracted from the validated VAT number (e.g., DE, GB)."
+          },
+          "vat_number": {
+            "type": "string",
+            "description": "VAT number without country prefix."
+          },
+          "requester_country_code": {
+            "type": "string",
+            "description": "Requester VAT country prefix (present only when requesterVatNumber was provided)."
+          },
+          "requester_vat_number": {
+            "type": "string",
+            "description": "Requester VAT number without country prefix."
+          },
+          "requested_at": {
+            "type": "string",
+            "format": "date-time",
+            "description": "ISO 8601 timestamp of the validation request."
+          },
+          "validation": {
+            "$ref": "#/components/schemas/VatValidationResult"
+          },
+          "company": {
+            "$ref": "#/components/schemas/VatValidationCompany"
+          }
+        },
+        "required": [
+          "country_code",
+          "vat_number",
+          "requested_at",
+          "validation",
+          "company"
+        ],
+        "description": "VAT number validation response containing registration status and company details."
+      },
+      "VatValidationResult": {
+        "type": "object",
+        "description": "Validation result block.",
+        "required": ["is_valid", "consultation_authority"],
+        "properties": {
+          "is_valid": {
+            "type": "boolean",
+            "description": "Whether the VAT number is active and registered."
+          },
+          "consultation_number": {
+            "type": "string",
+            "description": "VIES/HMRC consultation number. Only present when requesterVatNumber is provided."
+          },
+          "consultation_authority": {
+            "type": "string",
+            "description": "Upstream authority used for validation (VIES for EU, HMRC for UK)."
+          }
+        }
+      },
+      "VatValidationCompany": {
+        "type": "object",
+        "description": "Company details block.",
+        "required": ["company_name", "company_address"],
+        "properties": {
+          "company_name": {
+            "type": "string",
+            "description": "Company or trader name (may be empty string when unavailable)."
+          },
+          "company_address": {
+            "type": "string",
+            "description": "Formatted company address (may be empty string when unavailable)."
+          }
+        }
+      },
+      "ErrorResponse": {
+        "type": "object",
+        "required": ["message"],
+        "properties": {
+          "error": {
+            "type": "string",
+            "description": "Short error category or exception type."
+          },
+          "message": {
+            "type": "string",
+            "description": "Human-readable error message describing the failure."
+          },
+          "path": {
+            "type": "string",
+            "description": "API endpoint path that produced the error."
+          },
+          "status": {
+            "type": "integer",
+            "description": "HTTP status code returned with the error."
+          },
+          "timestamp": {
+            "type": "string",
+            "format": "date-time",
+            "description": "Timestamp when the error occurred (ISO 8601)."
+          }
+        },
+        "description": "Standard error envelope returned by the API on failed requests."
+      }
+    }
+  },
+  "security": [
+    {
+      "ApiKeyAuthHeader": []
+    },
+    {
+      "ApiKeyAuthQuery": []
+    }
+  ]
+}