REST-API

Mit der REST-API liest und erstellst du Buchungen aus eigenen Systemen: CRM, Kassensystem, App oder Automatisierung. Die API ist im Pro-Tarif enthalten. Alle Endpunkte findest du in der API-Referenz, die maschinenlesbare Spezifikation unter /api/v1/openapi.json.

Basis-URL

https://bookbaseapi.com/api/v1

Alle Anfragen und Antworten verwenden JSON. Zeitpunkte sind ISO-8601 in UTC, zum Beispiel 2026-10-05T07:00:00.000Z. Datumsangaben ohne Uhrzeit haben das Format YYYY-MM-DD.

Authentifizierung

Erstelle einen Schlüssel unter Integrationen → API-Schlüssel und sende ihn als Bearer-Token:

curl https://bookbaseapi.com/api/v1/workspace \
  -H "Authorization: Bearer bb_live_…"

Der Schlüssel wird nur einmal angezeigt. Wir speichern ausschließlich einen Hash. Ein widerrufener Schlüssel funktioniert sofort nicht mehr.

Berechtigungen (Scopes)

Scope	Erlaubt
services:read	Leistungen lesen
services:write	Leistungen anlegen, ändern, löschen
availability:read	Arbeitszeiten und freie Termine lesen
availability:write	Wochenzeiten ersetzen
bookings:read	Buchungen lesen
bookings:write	Buchungen anlegen, verschieben, absagen, bestätigen
customers:read	Kunden lesen
webhooks:write	Webhook-Endpunkte verwalten

Gib jedem Schlüssel nur die Rechte, die er braucht.

Beispiel: freie Termine und Buchung

curl "https://bookbaseapi.com/api/v1/slots?serviceId=SERVICE_ID&from=2026-10-05&to=2026-10-11&timeZone=Europe/Berlin" \
  -H "Authorization: Bearer $BOOKBASE_KEY"

curl https://bookbaseapi.com/api/v1/bookings \
  -H "Authorization: Bearer $BOOKBASE_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "serviceId": "SERVICE_ID",
    "startAt": "2026-10-05T07:00:00.000Z",
    "timeZone": "Europe/Berlin",
    "name": "Anna Weber",
    "email": "anna@example.com"
  }'

Ist der Zeitpunkt nicht mehr frei, antwortet die API mit 409 slot_unavailable.

Beispiel in JavaScript

const response = await fetch("https://bookbaseapi.com/api/v1/bookings?view=upcoming&limit=50", {
  headers: { Authorization: `Bearer ${process.env.BOOKBASE_KEY}` },
});
const { data, pagination } = await response.json();

Paginierung

Listen-Endpunkte akzeptieren page (ab 1) und limit (1 bis 100, Standard 25) und liefern ein Objekt pagination mit page, limit, total und pages.

Fehler

Fehler haben immer dieses Format:

{ "error": { "code": "validation_failed", "message": "…", "details": [] } }

Status	Code	Bedeutung
401	unauthorized, invalid_api_key	Kein oder ungültiger Schlüssel
402	plan_required, plan_limit	Tarif enthält die Funktion nicht oder ein Limit ist erreicht
403	insufficient_scope	Dem Schlüssel fehlt eine Berechtigung
404	not_found	Objekt existiert nicht oder gehört nicht zu deinem Konto
409	slot_unavailable, invalid_state	Termin belegt oder Statuswechsel nicht möglich
422	validation_failed	Ungültige Eingabe, Details in details
429	rate_limited	Zu viele Anfragen, siehe Retry-After

Limits

Pro Schlüssel sind 600 Anfragen pro Minute erlaubt. Die Header X-RateLimit-Limit und X-RateLimit-Remaining zeigen den aktuellen Stand.

Benachrichtigungen bei API-Buchungen

Bei POST /bookings sendet BookBase standardmäßig eine Bestätigung an den Kunden. Mit "sendNotifications": false unterdrückst du sie, etwa beim Import. Mit "status": "pending" legst du eine Anfrage an, die du später mit POST /bookings/{id}/confirm bestätigst.

Webhooks

Statt regelmäßig abzufragen, kannst du dich über Webhooks in Echtzeit benachrichtigen lassen.