# Belastingdienst — Wrapped API

> **You are on:** `https://api.paywithlocus.com/api` | [llms.txt](https://paywithlocus.com/llms.txt) | [docs](https://docs.paywithlocus.com)
>
> Locus runs on multiple environments -- make sure every URL you call matches your expected environment.
> | Environment | Landing | API | Docs |
> |---|---|---|---|
> | Production | paywithlocus.com | api.paywithlocus.com | docs.paywithlocus.com |
> | Beta | beta.paywithlocus.com | api.beta.paywithlocus.com | docs.paywithlocus.com |
> | Stage | stage.paywithlocus.com | api.stage.paywithlocus.com | docs.paywithlocus.com |
>
> If the API URL above doesn't match your expected environment, re-fetch this file from the correct domain.

> Search and retrieve official Dutch tax information, forms, and guidance directly from the Netherlands Tax Authority to find answers about tax obligations, deductions, and compliance requirements. Access specific pages and documents from the Belastingdienst database to get accurate, up-to-date tax details relevant to your situation.

**Category:** Government & Public Data | **Website:** [www.belastingdienst.nl/wps/wcm/connect/nl/home/home](https://www.belastingdienst.nl/wps/wcm/connect/nl/home/home) | **Docs:** [parse.bot/marketplace/5a2cd83e-3c5b-4091-84e5-c96b54d70b3d/belastingdienst-nl-api](https://parse.bot/marketplace/5a2cd83e-3c5b-4091-84e5-c96b54d70b3d/belastingdienst-nl-api)

Pay-per-use API proxy. Each call is automatically billed to your wallet in USDC.

## Access

**Base URL:** `https://api.paywithlocus.com/api/wrapped/parse-belastingdienst-nl-api-5a2cd83e/`
**Auth:** `Authorization: Bearer <LOCUS_API_KEY>`

## Endpoints

### get_aow_pension_info

Retrieve Dutch AOW (state pension) tax information including eligibility age, premium rates, premium-free tax brackets for retirees, and monthly pro-rated rates for the transition year. Data is sourced from the Box 1 rates page and the AOW info page on belastingdienst.nl.

**Estimated cost:** Metered

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `year` | string | No | Tax year to filter results (e.g. '2025', '2026'). Omitting returns all available years (currently 2024-2026). |

```bash
curl -X POST https://api.paywithlocus.com/api/wrapped/parse-belastingdienst-nl-api-5a2cd83e/get_aow_pension_info \
  -H "Authorization: Bearer YOUR_LOCUS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"year":"<string>"}'
```

### get_box2_box3_rates

Retrieve Box 2 (substantial interest income) and Box 3 (savings/investments) tax rates. Box 2 includes bracket thresholds and rates; Box 3 includes the flat tax rate. Returns data for multiple years.

**Estimated cost:** Metered

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `year` | string | No | Tax year to filter results (e.g. '2025'). Omitting returns all available years. |

```bash
curl -X POST https://api.paywithlocus.com/api/wrapped/parse-belastingdienst-nl-api-5a2cd83e/get_box2_box3_rates \
  -H "Authorization: Bearer YOUR_LOCUS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"year":"<string>"}'
```

### get_corporate_tax_rates

Retrieve Dutch corporate tax (vennootschapsbelasting) rate tiers. Returns profit threshold, low rate, and high rate as currently published on belastingdienst.nl.

**Estimated cost:** Metered

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `year` | string | No | Tax year (e.g. '2025'). Currently returns the latest published rates. |

```bash
curl -X POST https://api.paywithlocus.com/api/wrapped/parse-belastingdienst-nl-api-5a2cd83e/get_corporate_tax_rates \
  -H "Authorization: Bearer YOUR_LOCUS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"year":"<string>"}'
```

### get_dividend_withholding_tax

Retrieve the Dutch dividend withholding tax (dividendbelasting) rate and applicable information about treaty exemptions.

**Estimated cost:** Metered

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `year` | string | No | Tax year (e.g. '2025'). The standard rate of 15% applies across years. |

```bash
curl -X POST https://api.paywithlocus.com/api/wrapped/parse-belastingdienst-nl-api-5a2cd83e/get_dividend_withholding_tax \
  -H "Authorization: Bearer YOUR_LOCUS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"year":"<string>"}'
```

### get_energy_tax_rates

Retrieve Dutch energy tax (energiebelasting) rates per unit across consumption tiers for gas (€/m³) and electricity (€/kWh). Includes ODE surcharges and reduced rates.

**Estimated cost:** Metered

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `year` | string | No | Tax year to filter (e.g. '2023'). Omitting returns all available years (2019-2026). |

```bash
curl -X POST https://api.paywithlocus.com/api/wrapped/parse-belastingdienst-nl-api-5a2cd83e/get_energy_tax_rates \
  -H "Authorization: Bearer YOUR_LOCUS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"year":"<string>"}'
```

### get_income_tax_brackets

Retrieve Dutch Box 1 income tax brackets with lower/upper bounds and rates per band. Returns data for multiple years (currently 2025 and 2026) from the official Belastingdienst page. Filter by year to get brackets for a specific tax year.

**Estimated cost:** Metered

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `year` | string | No | Tax year to filter results (e.g. '2025', '2026'). Omitting returns all available years. |

```bash
curl -X POST https://api.paywithlocus.com/api/wrapped/parse-belastingdienst-nl-api-5a2cd83e/get_income_tax_brackets \
  -H "Authorization: Bearer YOUR_LOCUS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"year":"<string>"}'
```

### get_inheritance_gift_tax_brackets

Retrieve Dutch inheritance tax (erfbelasting) brackets by relationship category (partner/children, grandchildren, others). Includes rate percentages and threshold amounts.

**Estimated cost:** Metered

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `year` | string | No | Tax year (e.g. '2025', '2026'). Defaults to 2025. |

```bash
curl -X POST https://api.paywithlocus.com/api/wrapped/parse-belastingdienst-nl-api-5a2cd83e/get_inheritance_gift_tax_brackets \
  -H "Authorization: Bearer YOUR_LOCUS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"year":"<string>"}'
```

### get_motor_vehicle_tax_rates

Retrieve Dutch motor vehicle tax information: BPM (one-time registration tax based on CO2 emissions) rate tables and motorrijtuigenbelasting (recurring tax) information. Optionally filter to only one tax type.

**Estimated cost:** Metered

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `tax_type` | string | No | Filter to a specific motor vehicle tax: 'bpm' for the one-time registration tax or 'mrb' for the recurring vehicle tax. Omitting returns both. |
| `year` | string | No | Tax year (e.g. '2025'). Currently returns the latest published BPM rates. |

```bash
curl -X POST https://api.paywithlocus.com/api/wrapped/parse-belastingdienst-nl-api-5a2cd83e/get_motor_vehicle_tax_rates \
  -H "Authorization: Bearer YOUR_LOCUS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"tax_type":"<string>","year":"<string>"}'
```

### get_page

Fetch the full content of a Belastingdienst information page. Returns the page title, structured content sections (headings and paragraphs), and internal/external links. The path is the page identifier from search results (the portion after '/wps/wcm/connect/').

**Estimated cost:** Metered

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `path` | string | Yes | Page path segment after '/wps/wcm/connect/' (e.g. 'nl/btw/content/ik-moet-btw-aangifte-doen-hoe-vul-ik-die-in'). Can also be a full belastingdienst.nl URL from search results. |

```bash
curl -X POST https://api.paywithlocus.com/api/wrapped/parse-belastingdienst-nl-api-5a2cd83e/get_page \
  -H "Authorization: Bearer YOUR_LOCUS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"path":"<string>"}'
```

### get_payroll_tax_info

Retrieve Dutch payroll tax information including werkkostenregeling (WKR) vrije ruimte percentages, reiskostenvergoeding (travel allowance) per km, and 30%-ruling salary thresholds.

**Estimated cost:** Metered

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `year` | string | No | Tax year to filter results (e.g. '2025', '2026'). Omitting returns all available years. |

```bash
curl -X POST https://api.paywithlocus.com/api/wrapped/parse-belastingdienst-nl-api-5a2cd83e/get_payroll_tax_info \
  -H "Authorization: Bearer YOUR_LOCUS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"year":"<string>"}'
```

### get_tax_credits

Retrieve Dutch tax credits (heffingskortingen) including algemene heffingskorting and arbeidskorting. Each credit includes income thresholds, amounts, and phase-out formulas as published by the Belastingdienst.

**Estimated cost:** Metered

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `year` | string | No | Tax year to filter results (e.g. '2025', '2026'). Omitting returns all available years. |

```bash
curl -X POST https://api.paywithlocus.com/api/wrapped/parse-belastingdienst-nl-api-5a2cd83e/get_tax_credits \
  -H "Authorization: Bearer YOUR_LOCUS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"year":"<string>"}'
```

### get_transfer_tax_rates

Retrieve Dutch transfer tax (overdrachtsbelasting) rates: residential (2%), commercial (10.4%), and first-time buyer exemption details.

**Estimated cost:** Metered

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `year` | string | No | Tax year (e.g. '2025'). Omitting returns current rates. |

```bash
curl -X POST https://api.paywithlocus.com/api/wrapped/parse-belastingdienst-nl-api-5a2cd83e/get_transfer_tax_rates \
  -H "Authorization: Bearer YOUR_LOCUS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"year":"<string>"}'
```

### get_vat_rates

Retrieve Dutch BTW (VAT) rate categories: standard 21%, reduced 9%, zero 0%, and exemptions. Each category includes a description of which goods/services fall under that rate.

**Estimated cost:** Metered

_No parameters required._

```bash
curl -X POST https://api.paywithlocus.com/api/wrapped/parse-belastingdienst-nl-api-5a2cd83e/get_vat_rates \
  -H "Authorization: Bearer YOUR_LOCUS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{}'
```

### search

Full-text search over all Dutch tax information pages. Returns ranked results with title, description, and URL. Each item is a summary with enough context to decide which page to fetch in full.

**Estimated cost:** Metered

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `count` | integer | No | Number of results to return (1-100). |
| `query` | string | Yes | Search terms in Dutch (e.g. 'btw aangifte', 'inkomstenbelasting'). |

```bash
curl -X POST https://api.paywithlocus.com/api/wrapped/parse-belastingdienst-nl-api-5a2cd83e/search \
  -H "Authorization: Bearer YOUR_LOCUS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"count":"<integer>","query":"<string>"}'
```