API Documentation
Integrate termine.lol into your own application.
Authentication
The embed endpoints (Calendar & Slots) require an API key in the header. API keys are created per calendar and can be managed in the dashboard under the "API Keys" tab. The booking endpoints (Reserve & Submit) are public and do not require an API key — they are protected by rate limiting.
Send your API key in the x-api-key header:
x-api-key: your_api_key
Base URL
All endpoints use the following base URL:
https://termine.lol
Times
startAt and endAt of an appointment are the local time on site — in the time zone of the calendar (field timezone). They are written in ISO format with a trailing Z, but they are not UTC: "2026-10-01T09:00:00.000Z" means 9:00 in the calendar, wherever the server is. The same goes for time and slotIndex of free slots (slotIndex counts quarter hours from midnight, 36 = 09:00).
Real moments in UTC, by contrast, are createdAt, submittedAt, confirmedAt and reservationExpiresAt.
Error Handling
All errors are returned as JSON with an `error` field:
{
"error": "Ungültiger API-Key"
}HTTP Status Codes
- 400 — Bad request (missing parameters)
- 401 — Invalid or missing API key
- 403 — API key not authorized for this calendar / limit reached
- 404 — Resource not found
- 409 — Conflict (slot already taken)
- 410 — reservation expired (when completing a booking)
- 429 — Too many requests (rate limit)
- 500 — Internal server error
- For invalid input (400), error is an object with a list of messages per field, not a text.
- 429 also carries retryAfter (seconds) and the Retry-After header.
- Error messages are German. Reserving and completing answer in the language given by Accept-Language or ?lang= (de, en, fr, es, it, tr).
{
"error": { "customerEmail": ["Ungültige E-Mail-Adresse"] }
}
{ "error": "rate_limited", "retryAfter": 42 }Booking Flow
The typical flow of a booking via the API:
- 1. Get calendar → Receive members and appointment types
- 2. Get slots → Load available time slots for a day
- 3. Reserve slot → Create a 10-minute reservation
- 4. Complete booking → Submit customer data, confirmation email is sent
- 5. Customer confirms → Clicking the email link confirms the booking
Get Calendar
Returns the basic information of a calendar, including active members and appointment types.
curl -H "x-api-key: your_api_key" \ https://termine.lol/api/embed/calendars/CALENDAR_ID
Path Parameters
| Parameter | Description |
|---|---|
id* | The calendar ID |
Response
{
"data": {
"id": "...",
"title": "My Calendar",
"timezone": "Europe/Berlin",
"members": [
{ "id": "...", "name": "Max Mustermann" }
],
"appointmentTypes": [
{
"id": "...",
"name": "Beratung",
"description": "30-Minuten-Beratungsgespräch",
"durationMin": 30,
"mode": "online",
"memberIds": ["..."]
}
]
}
}Get Available Slots
Returns the available time slots for a specific day and appointment type. Without `personUserId`, all members are queried and results are merged (`byPerson` contains the breakdown).
curl -H "x-api-key: your_api_key" \ "https://termine.lol/api/embed/calendars/CALENDAR_ID/slots?date=2026-03-15&appointmentTypeId=TYPE_ID"
Query Parameters
| Parameter | Description |
|---|---|
id* | The calendar ID (string) |
date* | Date in YYYY-MM-DD format (string) |
appointmentTypeId* | Appointment type ID (string) |
personUserId | Member ID (string, optional — default: "any" = all members) |
Response
{
"data": {
"date": "2026-03-15",
"personUserId": "any",
"availableSlots": [
{ "slotIndex": 36, "time": "09:00" },
{ "slotIndex": 37, "time": "09:15" },
{ "slotIndex": 38, "time": "09:30" }
],
"byPerson": [
{
"date": "2026-03-15",
"personUserId": "member_id_1",
"availableSlots": [
{ "slotIndex": 36, "time": "09:00" },
{ "slotIndex": 37, "time": "09:15" }
]
}
]
}
}Reserve Slot
Reserves a time slot for 10 minutes. The booking must be completed within this time. This endpoint does not require an API key — it is public and protected by rate limiting (20 requests/min).
curl -X POST https://termine.lol/api/public/bookings/reserve \
-H "Content-Type: application/json" \
-d '{
"calendarId": "CALENDAR_ID",
"appointmentTypeId": "TYPE_ID",
"date": "2026-03-15",
"startSlot": 36
}'Request Body (JSON)
| Parameter | Description |
|---|---|
calendarId* | Calendar ID (string) |
appointmentTypeId* | Appointment type ID (string) |
date* | Date in YYYY-MM-DD format (string) |
startSlot* | Slot index 0–95, each 15 min (number) |
personUserId | Member ID (string, optional — omit for auto-assignment) |
appointmentMode | Appointment mode: "online" or "in_person" (string, optional — only for hybrid appointment types) |
Response (201 Created)
{
"data": {
"bookingId": "abc123...",
"reservationExpiresAt": "2026-03-15T10:10:00.000Z",
"fields": [
{ "key": "email", "label": "E-Mail", "type": "email", "required": true },
{ "key": "name", "label": "Name", "type": "text", "required": true },
{ "key": "phone", "label": "Telefon", "type": "tel", "required": false }
]
}
}Complete Booking
Submits the customer data for a reserved booking. The customer will receive a confirmation email with a confirmation link. This endpoint does not require an API key — it is public and protected by rate limiting (5 requests/min).
curl -X POST https://termine.lol/api/public/bookings/submit \
-H "Content-Type: application/json" \
-d '{
"bookingId": "abc123...",
"customerEmail": "kunde@beispiel.de",
"customerData": {
"email": "kunde@beispiel.de",
"name": "Max Mustermann",
"phone": "+49 170 1234567"
}
}'Request Body (JSON)
| Parameter | Description |
|---|---|
bookingId* | Booking ID from the reservation (string) |
customerEmail* | Customer email (string) |
customerData* | Customer data as object — keys correspond to the `key` values from the reservation `fields` (object) |
Response (200 OK)
{
"data": {
"success": true,
"message": "Bestätigungs-E-Mail gesendet"
}
}POST /api/public/bookings/abandon
Frees a reservation at once when the customer gives up. Body: { "bookingId": "…" }. Without this call it lapses by itself after 10 minutes.
Rate Limiting
API endpoints are rate-limited. Limits vary by endpoint:
- 120 requests / minute per key (calendar & slots)
- 20 reservations and 5 completed bookings / minute per IP address
Permissions (scopes)
Every API key carries permissions. Keys without stored permissions (all keys created before scopes existed) count as "embed". If a key lacks the required permission, the API answers 403 with `insufficient_scope`.
- embed — calendar, appointment types and free slots (embed endpoints)
- bookings:read — list and read bookings, including customer data
- bookings:write — cancel, reschedule, set status and note, resend the confirmation
{
"error": "insufficient_scope",
"required": "bookings:read",
"granted": ["embed"]
}Which scope each endpoint needs
- embed — GET /api/embed/calendars/:id, …/slots and GET /api/partner/calendar
- bookings:read — GET /api/partner/bookings and GET /api/partner/bookings/:id
- bookings:write — PATCH /api/partner/bookings/:id, GET …/available-slots and POST …/email
Partner API
Endpoints for integrations that show and manage appointments (e.g. the WordPress plugin). All live under /api/partner/, expect the API key in the x-api-key header and always refer to the calendar the key belongs to — there is no calendar id in the path.
GET /api/partner/calendar
The calendar behind the key: title, timezone, members, appointment types, form fields and the key's permissions.
curl -H "x-api-key: your_api_key" https://termine.lol/api/partner/calendar
{
"data": {
"id": "665f1c2e9b1d4a0012345678",
"title": "Salon Demo",
"slug": "salon-demo",
"timezone": "Europe/Berlin",
"confirmationMode": "double_opt_in",
"members": [{ "id": "…", "name": "Alice" }],
"appointmentTypes": [
{ "id": "…", "name": "Beratung", "description": "", "durationMin": 30, "mode": "online",
"priceCents": 4200, "currency": "EUR", "category": "", "memberIds": [] }
],
"fields": [{ "key": "name", "label": "Name", "type": "text", "required": true, "options": null }],
"scopes": ["embed", "bookings:read"]
}
}GET /api/partner/bookings
List bookings. Default: every status except reserved and expired, 25 per page.
curl -H "x-api-key: your_api_key" "https://termine.lol/api/partner/bookings?direction=future&limit=25&offset=0"
Query parameters
- from, to — ISO date, range over startAt
- status — repeatable: reserved, pending_confirmation, confirmed, cancelled, expired, completed, no_show
- direction — past or future
- limit (1–100, default 25), offset (default 0)
- q — search over e-mail address and name
{
"data": {
"bookings": [
{
"id": "665f1c2e9b1d4a0012345678",
"startAt": "2026-10-01T09:00:00.000Z",
"endAt": "2026-10-01T09:30:00.000Z",
"status": "confirmed",
"appointmentType": { "id": "…", "name": "Beratung" },
"member": { "id": "…", "name": "Alice" },
"customer": { "email": "kunde@example.com", "name": "Max", "fields": { "phone": "…" } },
"appointmentMode": "online",
"meetLink": null,
"internalNote": null,
"anonymized": false,
"createdAt": "2026-09-20T10:12:00.000Z",
"submittedAt": "2026-09-20T10:13:10.000Z",
"confirmedAt": "2026-09-20T10:15:42.000Z"
}
],
"total": 1,
"limit": 25,
"offset": 0
}
}GET /api/partner/bookings/:id
One booking with all details. If it does not belong to the key's calendar, the API answers 404.
PATCH /api/partner/bookings/:id
Change a booking, with the same payload as the dashboard.
{ "status": "cancelled", "message": "Leider verhindert" }
{ "status": "completed" }
{ "status": "no_show" }
{ "internalNote": "Rückruf vereinbart" }
{ "reschedule": { "date": "2026-10-02", "startSlot": 40 } }- Exactly one change is carried out per request, in this order of precedence: status, reschedule, internalNote, message. The response is the changed booking.
- completed and no_show are only possible from confirmed (and from each other); cancelled works from any status. Moving to a time that is not free answers 400.
GET /api/partner/bookings/:id/available-slots?date=YYYY-MM-DD
Free slots for moving a booking on one day (?date=YYYY-MM-DD).
{
"data": {
"date": "2026-10-02",
"availableSlots": [
{ "slotIndex": 36, "time": "09:00" },
{ "slotIndex": 38, "time": "09:30" }
]
}
}POST /api/partner/bookings/:id/email
Resend the confirmation e-mail: for confirmed bookings with a new cancellation link, for pending ones with a new confirmation link.
{ "data": { "sent": true, "kind": "confirmed" } }Connect flow (OAuth with PKCE)
Instead of copying a key by hand, a partner app can connect the user at the push of a button. Public clients (e.g. a plugin on foreign domains) need no secret; they secure the flow with PKCE (S256).
- 1. Generate code_verifier (43–128 characters) and state; code_challenge = base64url(sha256(code_verifier))
- 2. Send the user to /connect with client_id, redirect_uri, state, code_challenge, code_challenge_method=S256 and scope
- 3. The user sees the target domain and the permissions, picks a calendar and approves. Back comes ?code=…&state=… (or ?error=access_denied).
- 4. Redeem the code server-side: POST /api/connect/token with client_id, code, code_verifier and redirect_uri. Response: calendarId, apiKey, scopes.
- 5. On disconnect call POST /api/connect/revoke with client_id and apiKey so no key is left behind.
https://termine.lol/en/connect?client_id=wordpress&redirect_uri=https%3A%2F%2Fexample.com%2Fwp-admin%2Fadmin.php%3Fpage%3Dtermine-lol&state=…&code_challenge=…&code_challenge_method=S256&scope=embed+bookings%3Aread+bookings%3Awrite
POST /api/connect/token
{
"client_id": "wordpress",
"code": "…",
"code_verifier": "…",
"redirect_uri": "https://example.com/wp-admin/admin.php?page=termine-lol"
}
→ { "data": { "calendarId": "…", "apiKey": "…", "scopes": ["embed", "bookings:read", "bookings:write"] } }POST /api/connect/revoke
{ "client_id": "wordpress", "apiKey": "…" }