Beschikbaar — REST API v1
REST API v1
Programmatische toegang tot Boekbaar-data voor automatisering, rapportages en integraties met Make, Zapier, n8n, Google Sheets of eigen software.
1. Overzicht
De Boekbaar REST API v1 is een JSON API met Bearer-authenticatie. Elke API-sleutel hoort bij één organisatie — tenant-isolatie is ingebouwd. Gebruik webhooks voor push-events en de REST API voor opvragen en wijzigingen.
2. Base URL
https://app.boekbaar.nu/api/v1Alle endpoints hieronder zijn relatief aan deze base URL.
3. Authenticatie
Authorization: Bearer bk_live_xxxxxBelangrijk
- API-sleutels worden slechts één keer getoond bij aanmaken.
- Bewaar sleutels veilig in een secrets manager.
- Gebruik API-sleutels nooit in frontend-code of publieke repositories.
4. API-sleutel aanmaken
- Dashboard → Ontwikkelaars → API-sleutels
- Klik op Nieuwe API-sleutel
- Kies scopes en optionele vervaldatum
- Kopieer de sleutel direct — daarna niet meer zichtbaar
Directe link: /dashboard/developers/api-keys
5. Scopes
Elke API-sleutel heeft een set scopes. Ontbrekende scope geeft HTTP 403 met code missing_scope.
| Scope | Gebruikt door | Toegang | Voorbeeld |
|---|---|---|---|
| organization:read | Rapportages, sync | Organisatie en vestigingen lezen | GET /organization |
| organization:write | Setup-automatisering | Organisatievelden bijwerken | PATCH /organization |
| customers:read | CRM, Sheets | Klanten ophalen | GET /customers |
| customers:write | CRM-import | Klanten aanmaken/bijwerken | POST /customers |
| appointments:read | Agenda-sync | Afspraken ophalen | GET /appointments |
| appointments:write | Status-updates | Afspraken wijzigen (geen POST) | PATCH /appointments/{id} |
| services:read | Catalogus-sync | Diensten lezen | GET /services |
| services:write | Prijzenbeheer | Diensten aanmaken/bijwerken | POST /services |
| staff:read | Planning | Medewerkers lezen | GET /staff |
| staff:write | HR-sync | Medewerkers beheren | POST /staff |
| packages:read | Credits | Pakketten lezen | GET /packages |
| packages:write | Credits (dashboard) | Pakketten toewijzen | Dashboard |
| benefits:read | Loyalty | Voordelen lezen | GET /benefits |
| benefits:write | Loyalty (dashboard) | Voordelen beheren | Dashboard |
| reviews:read | Reputatie | Reviews lezen | GET /reviews |
| reviews:write | Review-workflows | Reviews bijwerken | PATCH /reviews/{id} |
| trust:read | Trust-profiel | Trust-data lezen | GET /trust-profile |
| trust:write | Trust-workflows | Trust-profiel bijwerken | PATCH /trust-profile |
| widgets:read | Marketing | Widgets en events lezen | GET /widgets/events |
| analytics:read | BI, dashboards | Statistieken ophalen | GET /analytics |
| subscription:read | Billing-sync | Abonnement lezen | GET /subscription |
| webhooks:manage | Dashboard | Webhooks configureren | Dashboard |
| api_keys:manage | Dashboard | API-sleutels beheren | Dashboard |
6. Endpoints
| Methode | Pad | Scope | Beschrijving |
|---|---|---|---|
| GET | /organization | organization:read | Organisatiegegevens ophalen |
| PATCH | /organization | organization:write | Veilige organisatievelden bijwerken |
| GET | /customers | customers:read | Klantenlijst (cursor-paginering) |
| POST | /customers | customers:write | Nieuwe klant aanmaken |
| GET | /customers/{id} | customers:read | Klantdetails ophalen |
| PATCH | /customers/{id} | customers:write | Klant bijwerken |
| GET | /appointments | appointments:read | Afspraken filteren en ophalen |
| GET | /appointments/{id} | appointments:read | Afspraakdetails ophalen |
| PATCH | /appointments/{id} | appointments:write | Afspraakstatus of velden wijzigen |
| GET | /services | services:read | Diensten ophalen |
| POST | /services | services:write | Dienst aanmaken |
| GET | /services/{id} | services:read | Dienst ophalen |
| PATCH | /services/{id} | services:write | Dienst bijwerken |
| GET | /staff | staff:read | Medewerkers ophalen |
| POST | /staff | staff:write | Medewerker aanmaken |
| GET | /staff/{id} | staff:read | Medewerker ophalen |
| PATCH | /staff/{id} | staff:write | Medewerker bijwerken |
| GET | /packages | packages:read | Pakketten ophalen |
| GET | /benefits | benefits:read | Klantvoordelen ophalen |
| GET | /reviews | reviews:read | Reviews ophalen |
| PATCH | /reviews/{id} | reviews:write | Review publiceren, verbergen of beantwoorden |
| GET | /trust-profile | trust:read | Trust-profiel ophalen |
| PATCH | /trust-profile | trust:write | Trust-profiel bijwerken |
| GET | /widgets | widgets:read | Widget-configuratie ophalen |
| GET | /widgets/events | widgets:read | Widget-events ophalen |
| GET | /analytics | analytics:read | Geaggregeerde statistieken |
| GET | /analytics/advanced | analytics:read | Analytics+ statistieken |
| GET | /subscription | subscription:read | Abonnementsstatus (alleen-lezen) |
| GET | /locations | organization:read | Vestigingen ophalen |
| GET | /locations/{id} | organization:read | Vestiging ophalen |
| GET | /openapi.json | — | OpenAPI 3-specificatie (publiek) |
POST /appointments.7. Paginering
Lijst-endpoints gebruiken cursor-paginering:
limit— standaard 50, maximum 100cursor— ID van laatst geziene item- Response bevat
pagination.nextCursorvoor de volgende pagina
Voorbeeld
GET https://app.boekbaar.nu/api/v1/customers?limit=50&cursor=clx1238. Filtering
Veel lijst-endpoints ondersteunen query-parameters. Voorbeelden:
GET /appointments?status=CONFIRMED&from=2026-06-01GET /appointments?customerId=…&staffId=…GET /analytics?preset=last30
Zie OpenAPI voor het volledige filteroverzicht per resource.
9. Idempotency
Stuur header Idempotency-Key mee bij POST, PATCH en DELETE:
Header
Idempotency-Key: unique-key-123- Zelfde key + zelfde body → zelfde response (24 uur geldig)
- Zelfde key + andere body → HTTP 409 idempotency_conflict
10. Rate limits
Per API-sleutel: 120 verzoeken per minuut en 10.000 per dag. Bij overschrijding: HTTP 429 met code rate_limited.
11. Foutcodes
| HTTP | Code | Betekenis | Actie |
|---|---|---|---|
| 401 | invalid_api_key | Ongeldige of ingetrokken sleutel | Controleer Authorization header; maak een nieuwe sleutel aan indien nodig. |
| 403 | missing_scope | Scope ontbreekt op API-sleutel | Voeg de vereiste scope toe in API-sleutels. |
| 403 | feature_not_available | API add-on niet actief | Activeer de Developer/API add-on voor je organisatie. |
| 404 | not_found | Resource bestaat niet | Controleer ID en tenant-isolatie (org komt uit sleutel). |
| 400 | validation_error | Ongeldige invoer | Lees error.details en corrigeer het request body. |
| 409 | idempotency_conflict | Zelfde Idempotency-Key, andere body | Gebruik een nieuwe key of dezelfde body. |
| 429 | rate_limited | Rate limit bereikt | Wacht en retry met backoff; respecteer 120/min en 10.000/dag. |
| 500 | internal_error | Serverfout | Retry later; neem contact op bij herhaald falen. |
| 405 | method_not_allowed | HTTP-methode niet ondersteund | Controleer endpoint en methode in deze documentatie. |
12. OpenAPI
OpenAPI 3 JSON-specificatie:
/api/v1/openapi.jsonImporteer /api/v1/openapi.json in Postman, Insomnia, Make (HTTP-module) of n8n (OpenAPI-import) voor request-voorbeelden.
13. cURL-voorbeelden
Organisatie ophalen
curl -H "Authorization: Bearer bk_live_xxxxx" \
https://app.boekbaar.nu/api/v1/organizationKlantenlijst
curl -H "Authorization: Bearer bk_live_xxxxx" \
"https://app.boekbaar.nu/api/v1/customers?limit=50"Klant aanmaken
curl -X POST -H "Authorization: Bearer bk_live_xxxxx" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: create-customer-001" \
-d '{"name":"Voorbeeld Klant","email":"klant@voorbeeld.nl"}' \
https://app.boekbaar.nu/api/v1/customersAfspraken ophalen (filter)
curl -H "Authorization: Bearer bk_live_xxxxx" \
"https://app.boekbaar.nu/api/v1/appointments?status=CONFIRMED&limit=25"Afspraakstatus wijzigen
curl -X PATCH -H "Authorization: Bearer bk_live_xxxxx" \
-H "Content-Type: application/json" \
-d '{"status":"COMPLETED"}' \
https://app.boekbaar.nu/api/v1/appointments/clx123exampleDienst aanmaken
curl -X POST -H "Authorization: Bearer bk_live_xxxxx" \
-H "Content-Type: application/json" \
-d '{"name":"Intake","durationMinutes":60,"priceCents":7500}' \
https://app.boekbaar.nu/api/v1/servicesVestigingen ophalen
curl -H "Authorization: Bearer bk_live_xxxxx" \
https://app.boekbaar.nu/api/v1/locationsAnalytics ophalen
curl -H "Authorization: Bearer bk_live_xxxxx" \
"https://app.boekbaar.nu/api/v1/analytics?preset=last30"14. JSON-voorbeelden
Organisatie (200)
{
"data": {
"id": "org_example",
"name": "Voorbeeld Salon",
"slug": "voorbeeld-salon",
"timezone": "Europe/Amsterdam",
"country": "NL"
}
}Klant (200)
{
"data": {
"id": "cus_example",
"name": "Voorbeeld Klant",
"email": "klant@voorbeeld.nl",
"phone": null,
"createdAt": "2026-06-01T10:00:00.000Z"
}
}Afspraak (200)
{
"data": {
"id": "apt_example",
"status": "CONFIRMED",
"startsAt": "2026-06-15T09:00:00.000Z",
"endsAt": "2026-06-15T10:00:00.000Z",
"customerId": "cus_example",
"serviceId": "svc_example",
"staffId": "stf_example"
}
}Paginering (200)
{
"data": [
{ "id": "cus_001", "name": "Klant A" },
{ "id": "cus_002", "name": "Klant B" }
],
"pagination": {
"limit": 50,
"cursor": null,
"nextCursor": "cus_002"
}
}Fout (403 missing_scope)
{
"error": {
"code": "missing_scope",
"message": "Missing required scope: customers:write."
}
}15. Automatisering
Make: Webhook → Boekbaar API → boekhoudpakket
- Maak een webhook-endpoint in Make als trigger.
- Configureer een Boekbaar webhook voor appointment.completed.
- Voeg een HTTP-module toe met GET /customers/{id} of GET /appointments.
- Map velden naar je boekhoud- of CRM-module (HTTP Request).
Er is nog geen officiële Make-app. Gebruik Webhooks + HTTP Request modules.
Zapier: Webhook → Boekbaar API → Google Sheets
- Gebruik Webhooks by Zapier als trigger (Catch Hook).
- Stel Boekbaar in op customer.created of appointment.created.
- Voeg een Webhooks POST/GET stap toe naar de Boekbaar API.
- Schrijf rijen naar Google Sheets met Zapier Formatter.
Er is nog geen officiële Zapier-app. Gebruik Webhooks + Webhooks by Zapier.
n8n: Boekbaar webhook → HTTP Request → accounting
- Start met een Webhook-node (POST) of poll Boekbaar via Schedule + HTTP Request.
- Verifieer X-Boekbaar-Signature in een Function-node.
- Haal extra data op via HTTP Request naar /api/v1/appointments/{id}.
- Stuur naar je boekhoudpakket via HTTP Request of e-mail.
Er is nog geen officiële n8n-node. Gebruik HTTP Request + Webhook nodes.
16. Huidige beperkingen
- Nieuwe afspraken aanmaken via API is bewust beperkt; gebruik de publieke boekingsflow om conflictcontrole en beschikbaarheid te behouden.
- POST /appointments bestaat niet in API v1 — alleen GET en PATCH op bestaande afspraken.
- Tenant-isolatie: organizationId komt altijd uit de API-sleutel, nooit uit query of body.
- Geen officiële SDK's — gebruik REST, OpenAPI en standaard HTTP-clients.
- packages:write en benefits:write zijn primair dashboard-scopes; controleer scopes per endpoint.
17. Versioning
Huidige versie: v1 onder /api/v1. Breaking changes krijgen een nieuw major pad; v1 blijft ondersteund zolang gedocumenteerd.
18. Beveiliging
- API-sleutels worden één keer getoond bij aanmaken. Sla ze veilig op in een secrets manager.
- Gebruik API-sleutels nooit in frontend-code, mobiele apps of publieke repositories.
- Beperk scopes tot het minimum dat je automatisering nodig heeft.
- Trek sleutels in zodra een integratie wordt stopgezet.
- Gebruik HTTPS voor alle verzoeken; de base URL is altijd https://app.boekbaar.nu/api/v1.