Quickstart — Bokko Docs

What is this guide for?#

This guide is for developers who want to try out the Bokko Public API quickly. It walks you through a complete booking flow: listing services, searching for available slots, creating a booking, and then querying the booking status. Every step includes copy-pasteable curl commands.

Prerequisites#

Bokko Pro subscription — the Public API is only available on the Pro plan (see auth.plan_insufficient).
API key with the following 4 capabilities:
services.read — Step 1: list services
availability.read — Step 2: search availability
booking.create — Step 3: create booking
booking.read — Step 4: query booking status

Tipp

Don't have an API key yet? You can create one in the dashboard under Integrations → API keys. Detailed UI guide: Help: Managing API keys.

Step 1: List Services#

bash

curl -X GET "https://api.bokko.io/v1/services?salonSlug=example-salon" \
  -H "Authorization: Bearer bk_live_..."

Example Response (200):

json

{
  "ok": true,
  "data": {
    "services": [
      {
        "id": "svc_haircut_01",
        "name": "Haircut",
        "durationMinutes": 45,
        "priceType": "fixed",
        "pricingVersion": "a1b2c3d4e5f6",
        "price": {
          "amount": 4500,
          "currency": "HUF"
        }
      }
    ]
  },
  "meta": {
    "requestId": "req_abc123",
    "v": "1"
  }
}

Make a note of the id value — you will need it in the next step.

Step 2: Search Availability#

Search for availability using a POST request — parameters are sent in the request body, not as a query string.

bash

curl -X POST "https://api.bokko.io/v1/availability/search" \
  -H "Authorization: Bearer bk_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "salonSlug": "example-salon",
    "serviceId": "svc_haircut_01",
    "dateRange": {
      "from": "2026-05-12",
      "to": "2026-05-18"
    }
  }'

dateRange.from and dateRange.to are dates in YYYY-MM-DD format, interpreted in the salon's local timezone (max 31-day range).

Example Response (200):

json

{
  "ok": true,
  "data": {
    "slots": [
      {
        "date": "2026-05-12",
        "startTime": "10:00",
        "endTime": "10:45",
        "serviceId": "svc_haircut_01",
        "staffId": "staff_anna_01"
      },
      {
        "date": "2026-05-12",
        "startTime": "14:00",
        "endTime": "14:45",
        "serviceId": "svc_haircut_01",
        "staffId": "staff_anna_01"
      }
    ],
    "snapshotAt": "2026-05-11T08:00:00.000Z"
  },
  "meta": {
    "requestId": "req_def456",
    "v": "1"
  }
}

The date, startTime, and endTime fields are in the salon's local timezone (not UTC). In contrast, snapshotAt is a UTC ISO 8601 timestamp. Note the desired date, startTime, and staffId values.

Step 3: Create a Booking#

For mutating operations (POST), an Idempotency-Key header is required. Generate the UUID once into a shell variable — in case of a retry, send exactly the same key again.

bash

IDEMPOTENCY_KEY="$(uuidgen)"
curl -X POST "https://api.bokko.io/v1/bookings" \
  -H "Authorization: Bearer bk_live_..." \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: ${IDEMPOTENCY_KEY}" \
  -d '{
    "salonSlug": "example-salon",
    "serviceId": "svc_haircut_01",
    "expectedPricingVersion": "a1b2c3d4e5f6",
    "staffId": "staff_anna_01",
    "slot": {
      "date": "2026-05-12",
      "startTime": "10:00"
    },
    "guest": {
      "name": "Test Guest",
      "phone": "+36301234567"
    }
  }'

Figyelmeztetés

The Idempotency-Key should be THE SAME for every retry — otherwise you risk a duplicate booking. In the example, the IDEMPOTENCY_KEY shell variable is generated once and reused for every retry. The backend validates RFC 4122 UUID v1–v5 formats (UUID v4 recommended).

Example Response (201):

json

{
  "ok": true,
  "data": {
    "booking": {
      "bookingId": "bkg_789xyz",
      "status": "requested",
      "serviceId": "svc_haircut_01",
      "serviceName": "Haircut",
      "staffId": "staff_anna_01",
      "staffName": "Anna",
      "guestName": "Test Guest",
      "requestedSlot": {
        "date": "2026-05-12",
        "startTime": "10:00",
        "timezone": "Europe/Budapest"
      },
      "confirmedSlot": null,
      "createdAt": "2026-05-11T08:00:00.000Z"
    }
  },
  "meta": {
    "requestId": "req_ghi789",
    "v": "1"
  }
}

Make a note of the bookingId value.

Step 4: Query Booking Status#

bash

curl -X GET "https://api.bokko.io/v1/bookings/{bookingId}?salonSlug=example-salon" \
  -H "Authorization: Bearer bk_live_..."

Replace {bookingId} with the identifier received in the previous step (e.g., bkg_789xyz).

Possible statuses: requested, confirmed, declined, cancelled, completed, noShow.

Step 5 (optional): Webhooks#

If you want real-time notifications about booking status changes (e.g., booking.confirmed, booking.cancelled), set up a webhook. This requires the webhook.manage capability on your key.

Detailed guide: Webhooks →

What comes next?#

Booking flow — full lifecycle, error handling, monitoring
Error codes — all error codes, retry strategies
Webhooks — HMAC signature verification, delivery audit
API Reference — interactive OpenAPI reference

Tipp

The example-salon, svc_haircut_01, staff_anna_01, bk_live_... values used in the examples above are illustrative placeholders — they are not real backend identifiers. You can find your own values in the Bokko dashboard.