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:
VatCountryEntry:
type: object
description: 'VAT country metadata: an ISO 3166-1 alpha-2 code, plus an optional map of sub-national states/regions for countries with state-level VAT (US, Canada, Spain).'
required:
- code
properties:
code:
type: string
description: ISO 3166-1 alpha-2 country code, lowercase.
states:
type: object
description: Map of state/region name to its combined country:state code. Only present for countries with sub-national VAT rates.
additionalProperties:
title: StateCode
type: string
description: Combined country:state identifier (e.g. us:ca).
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.
VatIpItem:
type: object
required:
- country
- type
- currency
- standard_rate
description: Each item in the array represents a VAT rate object for the country resolved from the IP.
properties:
country:
type: string
description: Country resolved from the IP address.
state:
type: string
description: State or region resolved from the IP address, for countries with sub-national tax rates (e.g. US). Only present when applicable.
type:
type: string
description: Tax type for the resolved country (e.g., vat).
currency:
type: string
description: ISO 4217 currency code for the resolved country.
standard_rate:
type: number
format: float
description: Standard VAT rate as a decimal.
reduced_rate:
type: array
items:
$ref: '#/components/schemas/VatRateDecimal'
description: Reduced VAT rates (EU/UK only).
super_reduced_rate:
type: array
items:
$ref: '#/components/schemas/VatRateDecimal'
description: Super-reduced VAT rates (EU/UK only).
parking_rate:
type: number
format: float
description: Parking rate (EU/UK only).
categories:
description: Category-specific VAT rates, where defined (EU/UK only). Keys vary by country.
$ref: '#/components/schemas/VatCategories_2'
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.
VatCountryResponse:
type: array
description: Array of VAT rate objects for the requested country or state.
items:
$ref: '#/components/schemas/VatRateItem'
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'
SupportedCountriesResponse:
type: object
description: Countries and states supported by the VAT, IBAN, and SWIFT APIs.
required:
- VAT_Supported_Countries_And_States
- IBAN_Supported_Countries
- SWIFT_Supported_Countries
properties:
VAT_Supported_Countries_And_States:
type: array
description: Array of single-key objects, one per supported VAT country. Each key is the lowercase, underscore-separated country name.
items:
type: object
description: A single VAT-supported country, keyed by its lowercase name.
additionalProperties:
title: VatCountryEntry
$ref: '#/components/schemas/VatCountryEntry'
IBAN_Supported_Countries:
type: array
description: Array of countries supported by the IBAN Validation API.
items:
$ref: '#/components/schemas/IbanCountryEntry'
SWIFT_Su
# --- 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