APIFreaks - API Hub for Developers Financial APIs API

openapi: 3.2.0
info:
  title: Apifreaks Api Hub For Developers Financial APIs API
  version: 1.0.0
  contact:
    name: APIFreaks Support
    url: https://apifreaks.com/contact
    email: support@apifreaks.com
  description: 'Operations tagged Financial APIs across 8 of this provider''s published API definitions: apifreaks-api-hub-for-developers-bulk-vat-rates-country-openapi.json, apifreaks-api-hub-for-developers-financial-apis-supported-countries-openapi.json, apifreaks-api-hub-for-developers-iban-validation-openapi.json, apifreaks-api-hub-for-developers-swift-code-finder-openapi.json, apifreaks-api-hub-for-developers-swift-code-lookup-openapi.json, apifreaks-api-hub-for-developers-vat-number-validation-openapi.json, apifreaks-api-hub-for-developers-vat-rates-by-ip-openapi.json, apifreaks-api-hub-for-developers-vat-rates-country-openapi.json. Each path carries the servers of the definition it was published in.'
servers:
- url: https://api.apifreaks.com/v1.0
  description: Bulk VAT Rates by Country API Server
security:
- ApiKeyAuthHeader: []
- ApiKeyAuthQuery: []
tags:
- name: Financial APIs
paths:
  /vat/rates/country:
    servers:
    - url: https://api.apifreaks.com/v1.0
      description: Bulk VAT Rates by Country API Server
    post:
      tags:
      - Financial APIs
      summary: Bulk VAT lookup by country
      description: Retrieves VAT details for multiple countries or country-state combinations in a single request. Maximum of `100` entries per request are allowed.
      operationId: bulkVatRatesByCountry
      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''.'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/BulkVatRequest'
            examples:
              typicalRequest:
                summary: Typical bulk VAT lookup request
                value:
                  countries:
                  - country: DE
                  - country: United_States
                    state: New_York
      responses:
        '200':
          description: Successful response — a JSON array of VAT results, one entry per country that resolved successfully, in request order. Countries that fail to resolve are omitted rather than represented as error entries.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/VatCountryBulkResponse'
              examples:
                typicalSuccess:
                  summary: All requested countries resolved
                  value:
                  - country: DE
                    type: vat
                    currency: EUR
                    standard_rate: 0.19
                    reduced_rate:
                    - 0.07
                    - 0
                    categories:
                      books: 0.07
                      newspapers: 0.07
                      periodicals: 0.07
                      broadcasting: 0
                  - country: United_States
                    state: New_York
                    type: vat
                    currency: ''
                    standard_rate: 0.04
                partialMatch:
                  summary: One of two requested countries resolved — the unresolved one is simply absent
                  value:
                  - country: DE
                    type: vat
                    currency: EUR
                    standard_rate: 0.19
                    reduced_rate:
                    - 0.07
                    - 0
                    categories:
                      books: 0.07
                      newspapers: 0.07
                      periodicals: 0.07
                      broadcasting: 0
        '400':
          description: Bad Request — Missing or malformed request body
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                InvalidBody:
                  summary: countries field missing or malformed
                  value:
                    error: Invalid request body Exception
                    message: Please provide data in required format in request body
                    path: /v1.0/vat/rates/country
                    status: 400
                    timestamp: '2026-07-27T11:46:29.315Z'
        '413':
          description: Payload Too Large — Request body exceeds the size limit
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                PayloadTooLarge:
                  summary: Too many entries / body too large
                  value:
                    error: Payload too large Exception
                    message: Maximum request body size limit exceeded
                    path: /v1.0/vat/rates/country
                    status: 413
                    timestamp: '2026-07-27T11:46:29.925Z'
    get:
      tags:
      - Financial APIs
      summary: Get VAT rate by country code
      description: Fetches VAT rates for a single country or state provided via query parameters.
      operationId: getVatRatesByCountry
      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: country
        in: query
        required: true
        schema:
          type: string
        description: Country identifier in Alpha-2 (PK), Alpha-3 (PAK), or full name (Pakistan). Combine with the optional "state" query for sub-national VAT; values are case-insensitive and may use underscores instead of spaces.
      - name: state
        in: query
        required: false
        schema:
          type: string
        description: Optional state or region in Alpha-2 (NY) or full name (New_York). Use with "country" for state-level VAT; values are case-insensitive and may use underscores.
      responses:
        '200':
          description: Successful response with a JSON array containing VAT rate objects for the requested country or state.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/VatCountryResponse'
              examples:
                typicalSuccess:
                  summary: Country-level VAT rate
                  value:
                  - country: DE
                    type: vat
                    currency: EUR
                    standard_rate: 0.19
                    reduced_rate:
                    - 0.07
                    - 0
                    categories:
                      books: 0.07
                      newspapers: 0.07
                      periodicals: 0.07
                      broadcasting: 0
                stateLevel:
                  summary: State/region-level sales tax rate
                  value:
                  - country: US
                    state: NY
                    type: vat
                    currency: ''
                    standard_rate: 0.04
        '400':
          description: Bad Request — Missing required country parameter
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                MissingCountry:
                  summary: Missing required country parameter
                  value:
                    error: Invalid Param Exception
                    message: please pass correct parameters
                    path: /v1.0/vat/rates/country
                    status: 400
                    timestamp: '2026-07-27T11:45:34.183Z'
        '404':
          description: Not Found — No VAT data for the given country/state
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                NotFound:
                  summary: No VAT data for the given country
                  value:
                    message: No VAT data found.
  /vat/supported-countries:
    servers:
    - url: https://api.apifreaks.com/v1.0
      description: Financial APIs Supported Countries API Server
    get:
      tags:
      - Financial APIs
      summary: Get supported countries
      description: Returns the countries and states supported by the VAT, IBAN, and SWIFT APIs.
      operationId: getSupportedCountries
      parameters:
      - name: format
        in: query
        required: false
        schema:
          type: string
          enum:
          - json
          - xml
          default: json
        description: Format of the response. Default is JSON.
      - name: type
        in: query
        required: false
        schema:
          type: string
        description: Accepted by the endpoint but currently has no effect — all three categories (VAT, IBAN, SWIFT) are always returned regardless of this value.
      responses:
        '200':
          description: Successful response — always returns all three categories
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SupportedCountriesResponse'
              examples:
                typicalSuccess:
                  summary: Typical successful response (truncated)
                  value:
                    VAT_Supported_Countries_And_States:
                    - germany:
                        code: de
                    - united_states:
                        code: us
                        states:
                          california: us:ca
                          new_york: us:ny
                          texas: us:tx
                    IBAN_Supported_Countries:
                    - countryCode: DE
                      name: Germany
                    - countryCode: GB
                      name: United Kingdom
                    SWIFT_Supported_Countries:
                    - name: Germany
                      countryCode: DE
                    - name: United States
                      countryCode: US
  /iban/validation:
    servers:
    - url: https://api.apifreaks.com/v1.0
      description: IBAN Validation API Server
    get:
      tags:
      - Financial APIs
      summary: Validate IBAN
      description: Checks an IBAN for structural validity, checksum accuracy, and bank metadata.
      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: iban
        in: query
        required: true
        schema:
          type: string
        description: IBAN to validate.
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/IbanValidationResponse'
              examples:
                validIban:
                  summary: Valid IBAN with full bank data
                  value:
                    valid: true
                    iban: GB29NWBK60161331926819
                    validation:
                      is_alpha_numeric: true
                      is_iban_supported_country: true
                      is_valid_length: true
                      is_valid_structure: true
                      is_iban_check_digit_valid: true
                      bban: valid
                    bank_data:
                      bic: NWBKGB2LBHM
                      bank: NATIONAL WESTMINSTER BANK PLC
                      bank_code: NWBK
                      branch_code: '601613'
                      country: United Kingdom
                      country_iso2: GB
                      city: BIRMINGHAM
                      address: 6 BRINDLEY PLACE - BIRMINGHAM, B1
                      account: '31926819'
                      sepa: true
                invalidIban:
                  summary: Structurally invalid IBAN — still a 200, not an error, with the failing checks flagged
                  value:
                    valid: false
                    iban: NOTANIBAN123
                    validation:
                      is_alpha_numeric: true
                      is_iban_supported_country: true
                      is_valid_length: false
                      is_valid_structure: false
                      is_iban_check_digit_valid: false
                      bban: unknown
                    bank_data:
                      bic: null
                      bank: null
                      bank_code: null
                      branch_code: ''
                      country: Norway
                      country_iso2: 'NO'
                      city: null
                      address: null
                      account: N123
                      sepa: true
                unsupportedCountry:
                  summary: Country prefix not covered by IBAN — bank_data fields are null
                  value:
                    valid: false
                    iban: US29NWBK60161331926819
                    validation:
                      is_alpha_numeric: true
                      is_iban_supported_country: false
                      is_valid_length: false
                      is_valid_structure: false
                      is_iban_check_digit_valid: false
                      bban: unknown
                    bank_data:
                      bic: null
                      bank: null
                      bank_code: null
                      branch_code: ''
                      country: null
                      country_iso2: US
                      city: null
                      address: null
                      account: null
                      sepa: null
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                MissingIban:
                  summary: Missing required iban parameter
                  value:
                    error: Invalid Param Exception
                    message: please pass correct parameters
                    path: /v1.0/iban/validation
                    status: 400
                    timestamp: '2026-07-27T11:49:29.286Z'
      operationId: validateIban
  /swift-code/finder:
    servers:
    - url: https://api.apifreaks.com/v1.0
      description: SWIFT/BIC Code Finder API Server
    get:
      tags:
      - Financial APIs
      summary: Find SWIFT codes
      description: Drills down from countries to banks to cities to SWIFT/BIC codes, one parameter level at a time.
      operationId: findSwiftCode
      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: country
        in: query
        required: false
        schema:
          type: string
        description: Country name (accepts full name, e.g., Pakistan, United States). If supplied alone, returns the list of bank names in that country. If omitted entirely, returns the list of all supported countries.
      - name: bank
        in: query
        required: false
        schema:
          type: string
        description: Bank name (upper case) to drill into. Requires country to also be set. If supplied without city, returns the list of cities that bank operates in.
      - name: city
        in: query
        required: false
        schema:
          type: string
        description: City (upper case) to narrow results to. Requires country and bank to also be set. Returns the matching SWIFT/BIC codes for that bank in that city.
      responses:
        '200':
          description: Successful response. The array's contents depend on which parameters were supplied — see the examples for each drill-down level.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SwiftCodeFinderResponse'
              examples:
                allCountries:
                  summary: No parameters — all supported countries
                  value:
                  - Albania
                  - Algeria
                  - Andorra
                  - Germany
                  - United States
                banksInCountry:
                  summary: country only — bank names in that country
                  value:
                  - 1NCE GMBH
                  - AAREAL BANK AG
                  - DEUTSCHE BANK AG
                citiesForBank:
                  summary: country + bank — cities that bank operates in
                  value:
                  - AACHEN
                  - BERLIN
                  - FRANKFURT AM MAIN
                  - MUENCHEN
                swiftCodes:
                  summary: country + bank + city — matching SWIFT/BIC codes
                  value:
                  - DEUTDEBB101
                  - DEUTDEBB162
                  - DEUTDEBB165
                  - DEUTDEBBXXX
                  - DEUTDEDB101
                noMatch:
                  summary: Unmatched country/bank/city — empty array, not an error
                  value: []
        '400':
          description: Bad Request — Parameters supplied out of order
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                OutOfOrder:
                  summary: bank supplied without country
                  value:
                    message: 'Invalid query parameters. Provide parameters in sequence: country → bank → city'
  /swift-code/lookup:
    servers:
    - url: https://api.apifreaks.com/v1.0
      description: SWIFT/BIC Code Lookup API Server
    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
  /vat/validation:
    servers:
    - url: https://api.apifreaks.com/v1.0
      description: VAT Number Validation API Server
    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
  /vat/rates/ip-address:
    servers:
    - url: https://api.apifreaks.com/v1.0
      description: VAT Rates by IP API Server
    get:
      tags:
      - Financial APIs
      summary: Get VAT rate by IP address
      description: Fetches VAT rate based on the specified or originating IP address.
      operationId: getVatRatesByIp
      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: ipAddress
        in: query
        required: false
        schema:
          type: string
        description: IPv4 or IPv6 address to look up VAT rate for. If omitted, the originating IP address will be used.
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/VatIpItemArray'
              examples:
                typicalSuccess:
                  summary: Country-level VAT rate
                  value:
                  - country: GB
                    type: vat
                    currency: GBP
                    standard_rate: 0.2
                    reduced_rate:
                    - 0
                    - 0.05
                    categories:
                      books: 0.2
                      newspapers: 0.2
                      periodicals: 0.2
                      broadcasting: 0.2
                stateLevel:
                  summary: IP resolved to a US state with sub-national sales tax
                  value:
                  - country: US
                    state: CA
                    type: vat
                    currency: ''
                    standard_rate: 0.0825
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                InvalidIp:
                  summary: Invalid IP address format
                  value:
                    message: Invalid IP address format. Please provide a valid IPv4 or IPv6 address.
        '404':
          description: Not Found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                NotFound:
                  summary: VAT data not found for IP
                  value:
                    message: No VAT data found. Please provide a valid ipAddress.
components:
  schemas:
    VatCountryBulkResponse:
      type: array
      description: Array of VAT rate results, one entry per country that resolved successfully, in request order. Countries that fail to resolve are omitted, so this array can be shorter than the requested countries list.
      items:
        $ref: '#/components/schemas/VatBulkResponseItem'
    VatCountryResponse:
      type: array
      description: Array of VAT rate objects for the requested country or state.
      items:
        $ref: '#/components/schemas/VatRateItem'
    IbanValidationResult:
      type: object
      description: Object contains IBAN validation details.
      required:
      - is_alpha_numeric
      - is_iban_supported_country
      - is_valid_length
      - is_valid_structure
      - is_iban_check_digit_valid
      properties:
        is_alpha_numeric:
          type: boolean
          description: Whether the IBAN contains only alphanumeric characters.
        is_iban_supported_country:
          type: boolean
          description: Whether the country extracted from the IBAN supports IBAN standards.
        is_valid_length:
          type: boolean
          description: Whether the IBAN length matches the expected length for its country.
        is_valid_structure:
          type: boolean
          description: Whether the IBAN structure matches the pattern for its country.
        is_iban_check_digit_valid:
          type: boolean
          description: Whether the IBAN check digit is valid.
        bban:
          type: string
          enum:
          - valid
          - invalid
          - unknown
          description: BBAN checksum status. "unknown" means BBAN checksum validation isn't supported for this country.
    SwiftCountryEntry:
      type: object
      description: A single country supported by the SWIFT/BIC Code Lookup and Finder APIs.
      required:
      - name
      - countryCode
      properties:
        name:
          type: string
          description: Full country name.
        countryCode:
          type: string
          description: ISO 3166-1 alpha-2 country code.
    BulkVatRequest:
      type: object
      description: Request body for bulk VAT rate lookup by country.
      required:
      - countries
      properties:
        countries:
          type: array
          description: Array of country entries to look up. Maximum 100 entries.
          items:
            $ref: '#/components/schemas/BulkVatRequestItem'
    VatCategories_2:
      type: object
      description: Category-specific VAT rates, where defined (EU/UK only). Keys vary by country.
      properties:
        books:
          type: number
          format: float
          description: VAT rate for books, as a decimal (e.g., 0.07 = 7%).
        newspapers:
          type: number
          format: float
          description: VAT rate for newspapers, as a decimal (e.g., 0.07 = 7%).
        periodicals:
          type: number
          format: float
          description: VAT rate for periodicals, as a decimal (e.g., 0.07 = 7%).
        broadcasting:
          type: number
          format: float
          description: VAT rate for broadcasting services, as a decimal (e.g., 0.19 = 19%).
      required: []
    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.
    IbanBankData:
      type: object
      description: Object contains Bank and BIC details. Most fields are null when the IBAN is structurally invalid or the country's bank data isn't resolvable.
      required:
      - country_iso2
      properties:
        bic:
          type:
          - string
          - 'null'
          description: SWIFT/BIC code extracted from the IBAN. Null when not available for this country or IBAN.
        bank:
          type:
          - string
          - 'null'
          description: Bank name extracted from the IBAN. Null when not resolvable.
        bank_code:
          type:
          - string
          - 'null'
          description: Bank code extracted from the IBAN. Null when not resolvable.
        branch_code:
          type: string
          description: Branch code extracted from the IBAN. Can be an empty string when not available.
        country:
          type:
  

# --- truncated at 32 KB (46 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/apifreaks-api-hub-for-developers/refs/heads/main/openapi/apifreaks-api-hub-for-developers-financial-apis-api-openapi.yml