API Documentatie — Betaalkenmerk Belastingdienst

Endpoint

Methode	URL	Omschrijving
GET	/api/{betaalkenmerk}	Betaalkenmerk ontcijferen via URL — eenvoudigste aanroep
POST	/api/	Betaalkenmerk ontcijferen via JSON body
GET	/api/	Deze documentatiepagina

Tip: gebruik GET /api/{betaalkenmerk} voor de eenvoudigste integratie — geen JSON body nodig, gewoon een URL.
https://betalingskenmerk-belastingdienst.nl/api/4813600531501210

Geen API-sleutel of authenticatie nodig. CORS is open voor alle origins.

Verzoek

Headers

Content-Type: application/json

Body (JSON)

Veld	Type	Verplicht	Beschrijving
betaalkenmerk	string	Ja	16-cijferig betaalkenmerk van de Belastingdienst. Spaties worden automatisch genegeerd.

Voorbeeld body

{
  "betaalkenmerk": "1100076700090012"
}

Antwoord

Bij succes geeft de API HTTP 200 terug met onderstaande JSON-structuur.

Veld	Type	Beschrijving
aanslagnummer	string	Volledig aanslagnummer inclusief BSN en belastingsoort
bsn	string	Geformatteerd BSN of RSIN (bijv. `123.45.678`)
soort	object	Belastingsoort — zie soort enum voor alle mogelijke waarden
soort.code	string (enum)	Machine-leesbare enum-waarde (bijv. `INCOME_TAX`)
soort.lettercode	string	Enkele letter uit de Belastingdienst-codering (bijv. `H`)
soort.label	string	Nederlandse naam van de belastingsoort (bijv. `Inkomstenbelasting`)
tijdvak	string	Belastingperiode (bijv. `Januari`, `1e kwartaal`). Kan leeg zijn.
jaartal	string	Belastingjaar als viercijferig getal (bijv. `2025`)
omschrijving	string	Volledige leesbare omschrijving (bijv. `Inkomstenbelasting Januari 2025`)
rgs	object	RGS 3.8 grootboekrekening voor boekhoudkundige verwerking — zie sub-velden hieronder
rgs.code	string	RGS-code (bijv. `BSchBepLhe`)
rgs.nr	string	RGS-referentienummer (bijv. `1201020`)
rgs.label	string	Nederlandse naam van de RGS-rekening
rgs.type	string	`schuld` (te betalen aan Belastingdienst) of `vordering` (te ontvangen van Belastingdienst)
rgs.toelichting	string	Korte uitleg over de boeking van deze belastingsoort. Zie RGS kennispagina.

Voorbeeld antwoord (HTTP 200)

{
  "aanslagnummer": "760.00.761.H.6009",
  "bsn": "760.00.761",
  "soort": {
    "code": "INCOME_TAX",
    "lettercode": "H",
    "label": "Inkomstenbelasting"
  },
  "tijdvak": "",
  "jaartal": "2026",
  "omschrijving": "Inkomstenbelasting 2026",
  "rgs": {
    "code": "BSchBepOvbOvb",
    "nr": "1201060",
    "label": "Overige belastingen",
    "type": "schuld",
    "toelichting": "Te betalen inkomstenbelasting"
  }
}

Soort — mogelijke waarden

Alle mogelijke waarden voor het veld soort.code:

code (enum)	lettercode	label (NL)
ADDITIONAL_PAYROLL_TAX	A	Loonheffing naheffing
SALES_TAX	B	Omzetbelasting
DIVIDEND_TAX	D	Dividendbelasting
ADVERTISING_TAX	E	Reclamebelasting
ADDITIONAL_SALES_TAX	F	Omzetbelasting naheffing
INCOME_TAX	H	Inkomstenbelasting
REFUND_PAYROLL_TAX	J	Loonheffing teruggaaf
CAPITAL_RETURN_TAX	K	Vermogensrendementsheffing
PAYROLL_TAX	L	Loonheffing
MOTOR_VEHICLE_TAX	M	Motorrijtuigenbelasting
UNKNOWN	N	Onbekend
SALES_TAX_REFUND	O	Omzetbelasting teruggaaf
PREMIUM_SELF_EMPLOYED_HEALTH	S	Premie ziekenfondswet zelfstandigen (t/m 2005)
SURCHARGES	T	Toeslagen
CORPORATION_TAX	V	Vennootschapsbelasting
HEALTH_INSURANCE_ACT	W	Zorgverzekeringswet
ADDITIONAL_MOTOR_VEHICLE_TAX	Y	Motorrijtuigenbelasting naheffing
OTHERS	Z	Overige

Foutcodes

Bij een fout geeft de API een 4xx-statuscode terug met onderstaande JSON-structuur:

{
  "error": {
    "code":    "INVALID_PAYMENT_REFERENCE",
    "message": "The betaalkenmerk failed checksum validation..."
  }
}

HTTP	error.code	Wanneer
400	INVALID_JSON	Body is geen geldige JSON
400	MISSING_FIELD	Veld `betaalkenmerk` ontbreekt of is leeg
405	METHOD_NOT_ALLOWED	Andere HTTP-methode dan POST gebruikt (bijv. PUT)
422	NON_NUMERIC	Betaalkenmerk bevat niet-cijfer tekens
422	INVALID_LENGTH	Betaalkenmerk heeft niet precies 16 cijfers
422	INVALID_PAYMENT_REFERENCE	Controlesom klopt niet of belastingsoort is onbekend

Codevoorbeelden

cURL GET (eenvoudigst)

curl https://betalingskenmerk-belastingdienst.nl/api/4813600531501210

cURL POST

curl -X POST https://betalingskenmerk-belastingdienst.nl/api/ \
  -H "Content-Type: application/json" \
  -d '{"betaalkenmerk": "4813600531501210"}'

JavaScript

const response = await fetch("https://betalingskenmerk-belastingdienst.nl/api/", {
  method: "POST",
  headers: { "Content-Type": "application/json" },
  body: JSON.stringify({ betaalkenmerk: "1100076700090012" }),
});

const data = await response.json();

if (data.error) {
  console.error(data.error.message);
} else {
  console.log(data.aanslagnummer);    // "760.00.761.H.6009"
  console.log(data.soort.code);        // "INCOME_TAX"
  console.log(data.omschrijving);      // "Inkomstenbelasting 2026"
}

Python

import requests

response = requests.post(
    "https://betalingskenmerk-belastingdienst.nl/api/",
    json={"betaalkenmerk": "1100076700090012"},
)

if response.status_code == 200:
    data = response.json()
    print(data["aanslagnummer"])        # "760.00.761.H.6009"
    print(data["soort"]["code"])      # "INCOME_TAX"
    print(data["omschrijving"])        # "Inkomstenbelasting 2026"
else:
    err = response.json()["error"]
    print(err["code"], err["message"])

PHP

<?php
$response = file_get_contents("https://betalingskenmerk-belastingdienst.nl/api/", false,
    stream_context_create(["http" => [
        "method"  => "POST",
        "header"  => "Content-Type: application/json\r\n",
        "content" => json_encode(["betaalkenmerk" => "1100076700090012"]),
    ]])
);
$data = json_decode($response, true);
echo $data["aanslagnummer"];   // "760.00.761.H.6009"

Gebruiksvoorwaarden

Door gebruik te maken van deze API gaat u akkoord met de volgende voorwaarden:

De API mag uitsluitend worden gebruikt voor wettige doeleinden.
De API mag niet worden gebruikt voor geautomatiseerde massamassale verwerking van gevoelige persoonsgegevens.
Gebruikers zijn zelf verantwoordelijk voor de naleving van de Algemene Verordening Gegevensbescherming (AVG/GDPR) en andere toepasselijke wet- en regelgeving.
Het is niet toegestaan om de API te gebruiken op een wijze die de werking van de dienst verstoort of overbelast.
Wij behouden ons het recht voor om de API zonder voorafgaande kennisgeving te wijzigen, beperken of stopzetten.
Deze voorwaarden kunnen op elk moment worden gewijzigd. Voortgezet gebruik na wijziging impliceert aanvaarding van de nieuwe voorwaarden.

Dit is een hobbyproject zonder commercieel oogmerk. Er wordt geen SLA of enige dienstverlening aangeboden.

Disclaimer

De uitvoer van deze API is informatief van aard en kan onjuist zijn. Het algoritme is gebaseerd op openbaar beschikbare informatie over de structuur van betaalkenmerken van de Belastingdienst, maar is niet officieel gecertificeerd of goedgekeurd door de Belastingdienst of enige andere overheidsinstantie.

Wij aanvaarden geen enkele aansprakelijkheid voor directe of indirecte schade, financieel nadeel of andere gevolgen die voortvloeien uit het gebruik van de API-uitvoer. Controleer altijd de originele belastingdocumenten voor officiële gegevens.

Gebruik de API-resultaten niet als enige basis voor financiële, juridische of fiscale beslissingen. Raadpleeg bij twijfel altijd een belastingadviseur of de Belastingdienst zelf.

Fair use & beschikbaarheid

Gratis en open

De API is gratis beschikbaar zonder registratie of API-sleutel. CORS is open zodat u hem ook vanuit de browser kunt aanroepen.

Redelijk gebruik

We vragen u de API op een eerlijke manier te gebruiken. Beperk geautomatiseerde verzoeken tot maximaal enkele honderden per dag. Bij misbruik of overbelasting kunnen IP-adressen geblokkeerd worden zonder kennisgeving.

Geen uptime- of beschikbaarheidsgarantie

Dit is een hobbyproject. We bieden geen SLA, geen garantie van uptime en geen support. De API kan op elk moment tijdelijk of permanent offline gaan zonder kennisgeving. Bouw geen bedrijfskritische systemen op basis van deze API.

Geen ondersteuning

Er wordt geen technische ondersteuning geboden. Vragen over de API worden niet beantwoord. Use at your own risk.

Copyright & licentie

Het algoritme en de API-documentatie zijn auteursrechtelijk beschermd. Gebruik van de API-uitvoer is vrij voor eigen doeleinden, mits u de disclaimer respecteert en geen aansprakelijkheidsclaims indient.

Het is niet toegestaan om het algoritme, de broncode of de documentatie te kopiëren, distribueren of commercieel te exploiteren zonder schriftelijke toestemming.

Betaalkenmerk, BSN en Belastingdienst zijn begrippen van de Nederlandse overheid en vallen onder hun eigen regelgeving. Dit project heeft geen officiële band met de Belastingdienst.

Betaalkenmerk API