Zimun: Appointment Scheduling & Booking Service: 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.

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.