Dynamic (Instant Booking)

Scale Plan Required

Dynamic booking is a Scale plan exclusive (€129/mo). All other plans return 402 Payment Required when calling /v1/dynamic/ endpoints. View plans →

Dynamic mode replaces fixed time slots with real-time resource availability. Customers pick any time — the API answers whether something is free right now and books it immediately. No grid, no schedule, no operating hours.

How It's Different

	Scheduled (default)	Dynamic
Time model	Fixed grid — slots every N minutes	Continuous — any start time
Availability	Pre-generated slot list	Point-check: "is this time free?"
Booking validation	Must match a slot	Direct resource conflict check
Use case	Appointments, reservations	Live seating, walk-ins, real-time spots

When to Use Dynamic Mode

Restaurant — Live Floor Management

A busy restaurant wants guests to see which tables are free right now before they walk over. The host stand manages tables via the dashboard. Guests browse a live floor plan built by the restaurant's developer, see open tables, and book one immediately.

Guest opens app → sees real-time table grid → picks an open table → booked instantly

Gym — Spot Booking

A gym caps attendance per time window. Members check the app: "are there spots open at 6 PM?" If yes, they grab one. The gym sets resources as the available spots (one resource per spot), and members book them in real-time.

Member opens app → "Any spots at 6 PM for 60 min?" → yes, 3 left → books one

Co-Working Space, Clinic Walk-Ins, Tennis Courts...

Any scenario where the customer picks an arbitrary time and needs to know is something free? — dynamic mode fits.

How It Works

Dynamic mode is a separate API surface at /v1/dynamic/. It doesn't touch the scheduled endpoints — you can even run both modes side-by-side for different parts of the same business.

Enable It

Set booking_mode to "dynamic" in business settings:

curl -X PATCH https://api.availengine.com/v1/manage/settings \
  -H "Authorization: Bearer YOUR_JWT" \
  -H "Content-Type: application/json" \
  -d '{"booking_mode": "dynamic"}'

Or toggle it in the dashboard under Settings → Booking Mode → Dynamic.

Add Resources

Resources are whatever you're booking — tables, treadmills, tennis courts, spots. Create them via the management API or dashboard:

curl -X POST https://api.availengine.com/v1/manage/resources \
  -H "Authorization: Bearer YOUR_JWT" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Table 1",
    "resource_type": "table",
    "capacity_min": 1,
    "capacity_max": 4,
    "section": "Main floor"
  }'

Check Availability

Ask whether a resource is free at a given time for a given party size:

curl "https://api.availengine.com/v1/dynamic/availability/{business_id}?booking_date=2026-06-20&start_time=08:15&duration_minutes=45&capacity=2"

Response:

{
  "available": true,
  "remaining_resources": 3,
  "free_resources": ["Table 1", "Table 3", "Table 5"]
}

Parameter	Type	Required	Description
business_id	UUID	yes	Path — the business to check
booking_date	date	yes	ISO date (YYYY-MM-DD)
start_time	string	yes	HH:MM, 24-hour format
duration_minutes	int	no	How long the booking lasts (default: 60, min: 5, max: 480)
capacity	int	no	Party size (default: 1, max: 50)

Create a Booking

curl -X POST https://api.availengine.com/v1/dynamic/bookings \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "business_id": "uuid",
    "booking_date": "2026-06-20",
    "start_time": "08:15",
    "duration_minutes": 45,
    "capacity": 2,
    "first_name": "Maria",
    "last_name": "Garcia",
    "email": "maria@example.com",
    "phone": "+1234567890"
  }'

Response:

{
  "booking": {
    "id": "uuid",
    "status": "confirmed",
    "booking_date": "2026-06-20",
    "start_time": "08:15:00",
    "end_time": "09:00:00",
    "duration_minutes": 45,
    "capacity": 2,
    "resource_id": "uuid",
    "confirmation_code": "AB12CD34"
  }
}

Field	Type	Required	Description
business_id	UUID	yes	The business
booking_date	date	yes	ISO date
start_time	string	yes	HH:MM, 24-hour format
duration_minutes	int	no	Booking length (default: 60, min: 5, max: 480)
capacity	int	yes	Party size (1–50)
first_name	string	yes	Customer first name (1–100 chars)
last_name	string	yes	Customer last name (1–100 chars)
email	email	yes	Customer email
phone	string	yes	Customer phone (7–20 chars)
customer_notes	string	no	Optional notes (max 1000 chars)

Conflict Response

If no resource is free at the requested time, the API returns 409 Conflict:

{
  "detail": "No resource available at the requested time."
}

Your frontend should handle this — show the guest that the spot was taken and suggest a nearby time.

Developer Integration Pattern

Here's a typical flow for building a live availability UI:

┌─────────────────┐     GET /v1/dynamic/availability/{id}     ┌──────────────┐
│                 │ ────────────────▶─────────────────────    │              │
│  Your Frontend  │    {available, remaining, free_names}     │  AvailEngine │
│                 │ ◀───────────────────────────────────────   │              │
│  (React, Vue,   │                                           │              │
│   native app,   │     POST /v1/dynamic/bookings             │              │
│   IPTV, kiosk)  │ ────────────────▶─────────────────────    │              │
│                 │    {booking, confirmation_code}           │              │
│                 │ ◀────────────────────────────────────────   │              │
└─────────────────┘                                           └──────────────┘

Step-by-Step

1. Poll for availability — call the availability endpoint whenever the guest changes time, duration, or party size. The response is instant (no heavy computation) so you can call it on every keystroke if you want.

2. Show free resources — the free_resources list tells you exactly which resources are open. Use it to render a live floor plan, a grid of available spots, or a simple count.

3. Book on tap — when the guest confirms, call the bookings endpoint. It re-validates availability atomically — if someone else grabbed the spot in the meantime, you'll get a 409 and can refresh.

4. Staff manages resources — staff add, remove, or deactivate resources through the dashboard. Deactivated resources disappear from availability instantly.

Tips

• No polling needed for the dashboard — staff changes (new table, deactivated spot) take effect on the next availability check. No WebSocket required.
• Use duration_minutes per booking — a guest staying 30 minutes at a table vs 90 minutes changes availability. Always send the intended duration.
• Handle 409 gracefully — show a "just taken" message and offer the next available time. The remaining_resources count tells you if any alternatives exist.
• Auth works the same — use an API key (avail_live_... or avail_test_...) scoped to the business. Rate limits apply per key.

Combining Scheduled and Dynamic

A business can use both modes. For example, a restaurant might:

• Use scheduled for dinner reservations (guests book days ahead, fixed time slots)
• Use dynamic for walk-in seating (host stand checks live table availability)

Just toggle booking_mode when you need to switch, or create separate businesses — one scheduled, one dynamic — and route accordingly.

Reference

Endpoint	Method	Auth
/v1/dynamic/availability/{business_id}	GET	API key or JWT
/v1/dynamic/bookings	POST	API key or JWT

Both endpoints respect your API key's rate limit and scopes. Set booking_mode to "scheduled" to disable dynamic endpoints — they'll return 400 until re-enabled.