Booking API Guide

The Booking API is available now for public scheduling workflows.

What this guide covers

• How to authenticate and call booking endpoints safely.
• How to discover locations, list services, read availability, and complete booking flow.
• When to use Booking API directly vs MCP integration.

Booking API vs MCP

• Use Booking API when you build your own backend/client integration and want direct HTTP control.
• Use MCP when your client is MCP-native and should call tools like list_services and get_availability.
• Both paths are designed around the same booking logic and conflict checks.

If you want a ready-to-embed conversational flow for customer booking, review Booking Chat Agent.

Authentication

1. Create API credentials in Settings → API Clients.
2. Request a token from /oauth/token using client credentials.
3. Call Booking API with Authorization: Bearer <token>.

Scopes used by booking workflows: org:read, availability:read, appointments:write.

Endpoint map

• GET /api/v1/locations - List active booking locations for your organization.
• GET /api/v1/services - List services for your organization, including location_ids.
• GET /api/v1/availability - Read available slots by service and date, with location_id when required.
• POST /api/v1/appointments/hold - Create a temporary hold before confirmation, using the same location_id when required.
• POST /api/v1/appointments/confirm - Confirm a hold and create the appointment.
• POST /api/v1/appointments/reschedule - Reschedule an existing appointment by booking_id.
• POST /api/v1/appointments/cancel - Cancel an existing appointment by booking_id.

Reservations (fixed-price services). A hold or booking made through this interface for a service or resource with a fixed price is an appointment reservation within the meaning of the Terms (Part C, Section 13 (2)), not a contract for the service. The hold response and the booking response then carry kind: "reservation", contract: "on_site", the price in price_cents with price_label reading exactly „Preis der Organisation, zahlbar vor Ort; Preis und Vertrag werden vor Ort geregelt“ (the organisation's price, payable on site; price and contract are settled on site), and notice with this fixed text: „Terminreservierung: Mit dieser Reservierung ist noch kein Vertrag über die Leistung geschlossen. Preis der Organisation, zahlbar vor Ort; Preis und Vertrag werden vor Ort geregelt.“ (English: "Appointment reservation: this reservation does not yet conclude a contract for the service. The organisation's price, payable on site; price and contract are settled on site.") Your interface must show this notice to the end-customer, at the latest with the booking result; that is your duty under Part B, Section 8 (5) letter c of the Terms. The hold response carries it so that it can be shown before the end-customer submits the booking; a rendering in another language must be complete and faithful. Zimun neither obtains nor records any end-customer acceptance of its own terms on this interface, takes no online payment and no card, and sends a reservation notice, not a booking confirmation, to the e-mail address submitted with the booking.

Recommended sequence

1. List locations if the organization can book in more than one place.
2. Let the user choose a location when required.
3. List services and keep only services that cover that location.
4. Fetch availability with service_id, date, and location_id when needed.
5. Create hold with the same location_id.
6. Confirm booking with contact details.
7. Store booking_id so you can reschedule or cancel later.

Reliability notes

• Use idempotency for create/confirm calls to avoid duplicates on retries.
• Treat holds as temporary and confirm quickly.
• Handle 401/403/404 and conflict responses explicitly in client UX.

Scope note

Current public APIs focus on booking operations. Management APIs are planned for a later phase.