---
title: Bulk VAT Rates by Country API Reference
version: 1.0.0
description: Get VAT rates for up to 100 countries or country/state combinations in a single API call. Returns a JSON array of VAT rate results, one entry per country that resolves successfully — entries with an invalid country/state are silently omitted rather than returned as per-item errors, so the array can be shorter than the requested list. Returns a 400 for a missing/malformed request body and a 413 if the payload exceeds the size limit.
openapi: 3.1.1
servers:
  - https://api.apifreaks.com/v1.0
paths: 1
operations: 1
schemas: 7
---

## Table of Contents

- [Bulk VAT Rates by Country API Reference v1.0.0](#bulk-vat-rates-by-country-api-reference-v100)
  - [Authentication](#authentication)
  - [Financial APIs](#financial-apis)
    - [bulkVatRatesByCountry](#bulkvatratesbycountry)
      - [Parameters](#parameters)
      - [Responses](#responses)
  - [Schemas](#schemas)
    - [VatCountryBulkResponse](#vatcountrybulkresponse)
    - [VatBulkResponseItem](#vatbulkresponseitem)
    - [VatRateDecimal](#vatratedecimal)
    - [VatCategories](#vatcategories)
    - [BulkVatRequest](#bulkvatrequest)
    - [BulkVatRequestItem](#bulkvatrequestitem)
    - [ErrorResponse](#errorresponse)



# Bulk VAT Rates by Country API Reference v1.0.0

Get VAT rates for up to 100 countries or country/state combinations in a single API call. Returns a JSON array of VAT rate results, one entry per country that resolves successfully — entries with an invalid country/state are silently omitted rather than returned as per-item errors, so the array can be shorter than the requested list. Returns a 400 for a missing/malformed request body and a 413 if the payload exceeds the size limit.

Base URLs:

* [https://api.apifreaks.com/v1.0](https://api.apifreaks.com/v1.0)

## Authentication

* API Key (ApiKeyAuthHeader)
    - Parameter Name: **X-apiKey**, in: header. Pass your API key via the X-apiKey request header.

* API Key (ApiKeyAuthQuery)
    - Parameter Name: **apiKey**, in: query. Pass your API key via the apiKey query parameter.

## Financial APIs

### bulkVatRatesByCountry

`POST /vat/rates/country`

*Bulk VAT lookup by country*

Retrieves VAT details for multiple countries or country-state combinations in a single request. Maximum of `100` entries per request are allowed.

> Body parameter

```json
{
  "countries": [
    {
      "country": "DE"
    },
    {
      "country": "United_States",
      "state": "New_York"
    }
  ]
}
```

#### Parameters

|Name|In|Type|Required|Description|
|---|---|---|---|---|
|format|query|string|false|Specify the desired response format. Options: 'json' (default) or 'xml'.|
|body|body|[BulkVatRequest](#bulkvatrequest)|true|none|

##### Enumerated Values

|Parameter|Value|
|---|---|
|format|json|
|format|xml|

> Example responses

> 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.

```json
[
  {
    "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
  }
]
```

```json
[
  {
    "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
    }
  }
]
```

> Bad Request — Missing or malformed request body

```json
{
  "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"
}
```

> Payload Too Large — Request body exceeds the size limit

```json
{
  "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"
}
```

#### Responses

|Status|Meaning|Description|Schema|
|---|---|---|---|
|200|[OK](https://tools.ietf.org/html/rfc7231#section-6.3.1)|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.|[VatCountryBulkResponse](#vatcountrybulkresponse)|
|400|[Bad Request](https://tools.ietf.org/html/rfc7231#section-6.5.1)|Bad Request — Missing or malformed request body|[ErrorResponse](#errorresponse)|
|413|[Payload Too Large](https://tools.ietf.org/html/rfc7231#section-6.5.11)|Payload Too Large — Request body exceeds the size limit|[ErrorResponse](#errorresponse)|

#### Response Headers

|Status|Header|Type|Format|Description|
|---|---|---|---|---|
|200|X-AF-Credits-Cost|integer||Specifies the number of credits consumed by the current request.|
|400|X-AF-Credits-Cost|integer||Specifies the number of credits consumed by the current request.|
|413|X-AF-Credits-Cost|integer||Specifies the number of credits consumed by the current request.|

To perform this operation, you must be authenticated by means of one of the following methods:
ApiKeyAuthHeader, ApiKeyAuthQuery

## Schemas

### VatCountryBulkResponse

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.

#### Properties

|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|*anonymous*|[[VatBulkResponseItem](#vatbulkresponseitem)]|false|none|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.|

### VatBulkResponseItem

A VAT rate result for a single country or state in a bulk response.

#### Properties

|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|country|string|true|none|Country identifier returned in the result item.|
|state|string|false|none|State or region returned for sub-national lookups. Only present when the request included a state.|
|type|string|true|none|Tax type applied for the country or state.|
|currency|string|true|none|ISO 4217 currency code for the returned location. Can be an empty string for some state-level entries.|
|standard_rate|number(float)|true|none|Standard VAT or sales tax rate for the returned location.|
|reduced_rate|[[VatRateDecimal](#vatratedecimal)]|false|none|Reduced VAT rates when defined for the location.|
|super_reduced_rate|[[VatRateDecimal](#vatratedecimal)]|false|none|Super-reduced VAT rates for specific categories, when defined.|
|parking_rate|number(float)|false|none|Parking rate, when applicable.|
|categories|[VatCategories](#vatcategories)|false|none|Category-specific VAT rates, where defined (EU/UK only).|

### VatRateDecimal

A VAT rate expressed as a decimal (e.g., 0.19 = 19%).

#### Properties

|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|*anonymous*|number(float)|false|none|A VAT rate expressed as a decimal (e.g., 0.19 = 19%).|

### VatCategories

Category-specific VAT rates, where defined (EU/UK only). Keys vary by country.

#### Properties

|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|books|number(float)|false|none|VAT rate for books, as a decimal (e.g., 0.07 = 7%).|
|newspapers|number(float)|false|none|VAT rate for newspapers, as a decimal (e.g., 0.07 = 7%).|
|periodicals|number(float)|false|none|VAT rate for periodicals, as a decimal (e.g., 0.07 = 7%).|
|broadcasting|number(float)|false|none|VAT rate for broadcasting services, as a decimal (e.g., 0.19 = 19%).|

### BulkVatRequest

Request body for bulk VAT rate lookup by country.

#### Properties

|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|countries|[[BulkVatRequestItem](#bulkvatrequestitem)]|true|none|Array of country entries to look up. Maximum 100 entries.|

### BulkVatRequestItem

A single country entry in a bulk VAT request.

#### Properties

|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|country|string|true|none|Country identifier in Alpha-2, Alpha-3, or full name.|
|state|string|false|none|Optional state or region for sub-national VAT.|

### ErrorResponse

Standard error envelope returned by the API on failed requests.

#### Properties

|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|error|string|false|none|Short error category or exception type.|
|message|string|true|none|Human-readable error message describing the failure.|
|path|string|false|none|API endpoint path that produced the error.|
|status|integer|false|none|HTTP status code returned with the error.|
|timestamp|string(date-time)|false|none|Timestamp when the error occurred (ISO 8601).|