← Back to home

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
API access is available from the Pro plan.
All endpoints under /api/embed/ and /api/partner/ need a key. Locked and revoked keys are treated like unknown ones (401). Use keys on your server only: the API sends no CORS headers, so calls from a browser on another domain fail.

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.

from and to of the booking list are read as local time too. Send them without a time zone, e.g. 2026-10-01 or 2026-10-01T09:00:00.

Error Handling

All errors are returned as JSON with an `error` field:

{
  "error": "Ungültiger API-Key"
}

HTTP Status Codes

{
  "error": { "customerEmail": ["Ungültige E-Mail-Adresse"] }
}

{ "error": "rate_limited", "retryAfter": 42 }

Booking Flow

The typical flow of a booking via the API:

  1. 1. Get calendar → Receive members and appointment types
  2. 2. Get slots → Load available time slots for a day
  3. 3. Reserve slot → Create a 10-minute reservation
  4. 4. Complete booking → Submit customer data, confirmation email is sent
  5. 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.

GET/api/embed/calendars/:id
curl -H "x-api-key: your_api_key" \
  https://termine.lol/api/embed/calendars/CALENDAR_ID

Path Parameters

ParameterDescription
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": ["..."]
      }
    ]
  }
}
Both calendar endpoints also return confirmationMode ("instant" or "double_opt_in") and, per appointment type, priceCents (price in cents or null), currency and category.

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).

GET/api/embed/calendars/:id/slots
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

ParameterDescription
id*The calendar ID (string)
date*Date in YYYY-MM-DD format (string)
appointmentTypeId*Appointment type ID (string)
personUserIdMember 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).

POST/api/public/bookings/reserve
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)

ParameterDescription
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)
personUserIdMember ID (string, optional — omit for auto-assignment)
appointmentModeAppointment 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 }
    ]
  }
}
The `fields` contain the form fields that must be filled in during booking. Use the `key` values as keys in the `customerData` object when submitting.
Optional: extraAppointmentTypeIds (up to 4 further appointment types in the same appointment). calendarId may also be the slug of the calendar.

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).

POST/api/public/bookings/submit
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)

ParameterDescription
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"
  }
}
The response carries confirmed: for calendars with confirmationMode "instant" the booking is confirmed at once (confirmed: true, no confirmation e-mail needed); otherwise the customer confirms through the link in the e-mail (confirmed: false).

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:


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`.

{
  "error": "insufficient_scope",
  "required": "bookings:read",
  "granted": ["embed"]
}
bookings:write does not include bookings:read. Permissions are chosen when the key is created in the dashboard.

Which scope each endpoint needs


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"]
  }
}
Both calendar endpoints also return confirmationMode ("instant" or "double_opt_in") and, per appointment type, priceCents (price in cents or null), currency and category.

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

{
  "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
  }
}
Anonymised bookings come back without customer data (anonymized: true).

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 } }

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" } }
kind is "confirmed" (confirmation with a cancellation link) or "confirmation_request" (a new confirmation link).
Rate limit per key: 120 read and 30 write requests per minute.

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. 1. Generate code_verifier (43–128 characters) and state; code_challenge = base64url(sha256(code_verifier))
  2. 2. Send the user to /connect with client_id, redirect_uri, state, code_challenge, code_challenge_method=S256 and scope
  3. 3. The user sees the target domain and the permissions, picks a calendar and approves. Back comes ?code=…&state=… (or ?error=access_denied).
  4. 4. Redeem the code server-side: POST /api/connect/token with client_id, code, code_verifier and redirect_uri. Response: calendarId, apiKey, scopes.
  5. 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": "…" }
Codes are valid for 10 minutes and can be redeemed once. For public clients redirect_uri must use https (http only for localhost). Registered partners with a secret send client_secret instead of code_verifier.