Bookings & Meeting Types

Read your workspace's meeting types, query open slots, and create/cancel/reschedule/reassign bookings. Meeting types themselves are configured in the app — the API surface for them is read-only.

All endpoints require authentication.

Plan feature required: every route on this page (bookings and meeting-types) requires the Booking feature on the workspace's plan, in addition to API access. Without it, all calls return 403 with error_code: "FEATURE_NOT_INCLUDED_IN_PLAN" — see feature-gated resource groups.

Meeting types

Meeting type object:

{
  "id": "mt-1a2b3c4d-…",
  "name": "Intro call",
  "slug": "intro-call",
  "description": "30-minute discovery call",
  "duration_minutes": 30,
  "location_type": "zoom",
  "is_active": true,
  "scheduling_kind": "round_robin",
  "host": { "id": null, "name": "Sales team" },
  "hosts": [
    { "user_id": "u-1111…", "name": "Avi Cohen" },
    { "user_id": "u-2222…", "name": "Noa Bar" }
  ],
  "created_at": "2026-05-01T08:00:00.000Z"
}

• scheduling_kind — single (default; one host), or a team kind such as round-robin/collective. hosts lists the configured host pool (exactly one entry for single); host is a back-compat convenience (its id is null for team kinds).
• Internal configuration (schedules, booking-page questions, buffers, etc.) is not exposed.

GET /api/v1/meeting-types

Standard list conventions (filter, sort default -created_at, limit default 50 / cap 500, offset, search). Mistyped filter values return 400 — see filter-value validation.

curl -G "https://app.otok.io/api/v1/meeting-types" \
  -H "Authorization: Bearer otok_live_abc123..." \
  --data-urlencode 'filter={"is_active":true}'

Response 200 — { data, total, limit, offset }.

GET /api/v1/meeting-types/:id

Response 200 — a meeting type object. 404 when unknown in this workspace. Non-UUID id → 400.

GET /api/v1/meeting-types/:id/slots

Returns the open start instants for the meeting type — the same availability the public booking page offers.

curl -G "https://app.otok.io/api/v1/meeting-types/mt-1a2b3c4d-5e6f-7081-92a3-b4c5d6e7f809/slots" \
  -H "Authorization: Bearer otok_live_abc123..." \
  --data-urlencode 'from=2026-07-20T00:00:00Z' \
  --data-urlencode 'to=2026-07-27T00:00:00Z'

Response 200:

{
  "meeting_type_id": "mt-1a2b3c4d-…",
  "timezone": "Asia/Jerusalem",
  "duration_minutes": 30,
  "slots": [
    { "start": "2026-07-20T06:00:00.000Z", "end": "2026-07-20T06:30:00.000Z" },
    { "start": "2026-07-20T06:30:00.000Z", "end": "2026-07-20T07:00:00.000Z" }
  ]
}

timezone is the host schedule's IANA zone; slot instants are UTC ISO timestamps.

Embedding the booking calendar

GET /api/v1/meeting-types/:id/embed

Everything needed to put the booking calendar on your own website — the same embed code the oToK app shows when editing a meeting type (Booking page → Share); key management lives under Settings → Booking.

curl "https://app.otok.io/api/v1/meeting-types/mt-1a2b3c4d-5e6f-7081-92a3-b4c5d6e7f809/embed" \
  -H "Authorization: Bearer otok_live_abc123..."

Response 200:

404 when the meeting type is unknown in this workspace; non-UUID id → 400.

The embed key is publishable by design. embed_key (bk_…) is meant to appear in your page's HTML — it is not the secret API key (otok_live_…), grants no API access, and must never be swapped for it in the snippet. It is workspace-level and rotatable: rotation, the allowed-origins list, and the embed on/off switch live in the oToK app under Settings → Booking. Rotating the key invalidates previously pasted snippets — re-fetch this endpoint (or copy the new snippet from the app) after a rotation.

Bookings made through the embed carry source: "embed" — the booking webhook events distinguish them from public_page, manual, and api bookings.

Bookings

Booking object (all read and write routes):

{
  "id": "bk-9f8e7d6c-…",
  "meeting_type_id": "mt-1a2b3c4d-…",
  "contact_id": "9c2f1a4e-…",
  "host_user_id": "u-1111…",
  "hosts": [ { "user_id": "u-1111…", "name": "Avi Cohen", "role": "assigned" } ],
  "status": "confirmed",
  "start_at": "2026-07-20T06:00:00.000Z",
  "end_at": "2026-07-20T06:30:00.000Z",
  "host_timezone": "Asia/Jerusalem",
  "invitee_timezone": "Europe/Berlin",
  "invitee_name": "Dana Levi",
  "invitee_email": "dana@example.com",
  "invitee_phone": "+972501234567",
  "join_url": "https://zoom.us/j/000000000",
  "notes": null,
  "source": "api",
  "cancelled_at": null,
  "cancelled_by": null,
  "cancellation_reason": null,
  "rescheduled_at": null,
  "previous_start_at": null,
  "reschedule_count": 0,
  "created_at": "2026-07-14T10:00:00.000Z",
  "updated_at": "2026-07-14T10:00:00.000Z"
}

hosts lists the assigned host first, then any co-hosts. status is one of confirmed, cancelled, completed, no_show. Internal fields (calendar ids, invitee management tokens, booking-page answers) are never exposed.

GET /api/v1/bookings

All filters are optional and combined with AND. Malformed values → 400.

Response 200 — { data, total, limit, offset }.

GET /api/v1/bookings/:id

Response 200 — a booking object. 404 when unknown in this workspace. Non-UUID id → 400.

POST /api/v1/bookings

Books a slot. The slot must be open at booking time; slot-taking is race-safe.

curl -X POST "https://app.otok.io/api/v1/bookings" \
  -H "Authorization: Bearer otok_live_abc123..." \
  -H "Content-Type: application/json" \
  -d '{
    "meeting_type_id": "mt-1a2b3c4d-5e6f-7081-92a3-b4c5d6e7f809",
    "start_at": "2026-07-20T06:00:00.000Z",
    "timezone": "Europe/Berlin",
    "invitee": { "name": "Dana Levi", "email": "dana@example.com", "phone": "+972501234567" }
  }'

Response 201 — the booking object with its hosts roster, plus a top-level boolean duplicate field (false on a fresh create, true on a replay — see below). The usual booking side effects run (confirmation email, calendar/Zoom setup where configured).

Idempotency is server-derived — you do not send a key. A double submit of the same slot + meeting type + contact (+ pinned host, when used) returns the existing confirmed booking as a success instead of failing or double-booking: still 201, with duplicate: true. For round-robin types, a pinned create can never silently replay onto a different host than the one pinned.

POST /api/v1/bookings/:id/cancel

Response 201 — the booking with status: "cancelled" and cancelled_at / cancelled_by / cancellation_reason set. API cancellations are attributed to the host side.

POST /api/v1/bookings/:id/reschedule

Response 201 — the booking with previous_start_at, rescheduled_at, and an incremented reschedule_count.

POST /api/v1/bookings/:id/reassign

Change which host owns a confirmed booking. Reassignment is pre-start only and not available for collective meeting types (where every pool host attends).

Response 201 — the booking with its new hosts roster.

409 handling summary