API Reference: Simply Spaces Bookings

Check availability, browse bookable slots, quote pricing, and submit bookings through public Simply Spaces booking links, plus the source-connection booking channel APIs.

Overview

Simply Spaces is the Simply360 surface for reservable spaces — rooms, courts, venues, and equipment modeled as data records. The booking APIs come in two groups, all standard tier:

Public booking-link endpoints — the runtime behind shareable booking links. They are guarded by a per-link public access token rather than a Simply360 account, so a booking page can check availability, render a calendar, and quote pricing for visitors.
Source-connection endpoints — the configuration and internal booking surface for a team's Simply Spaces source connection: snapshot reads, booking-channel management, internal availability/quote/run calls, booking lifecycle updates, and live-update webhook registration.

Key Concepts

Source connection — The team integration that maps existing data collections (spaces, events, people) into the Simply Spaces model. Identified by sourceConnectionSimplyId.
Booking channel — A configured way to book: which spaces are bookable, the availability policy (lead time, advance limit, weekly windows, slot increments, buffers), pricing, and how booking records are written. Identified by bookingChannelSimplyId.
Booking link — A shareable entry point into a channel with its own audience, payment, and outcome policies. Identified by bookingLinkSimplyId.
Public access token — A secret issued when a booking channel is provisioned. Public booking-link requests must present it; there is no user login on the public surface.
Quote — Server-computed pricing in minor currency units (for example cents), broken into line items.
Diagnostics — Structured advisories returned by every booking endpoint (code, message, optional path) explaining why something is unavailable or blocked.

Authentication

The two groups authenticate differently:

Booking-link endpoints do not use the Authorization header. Send the link's public access token in the X-S360-Public-Token header (the x-booking-public-token header, a publicAccessToken query parameter, or a publicAccessToken body field are also accepted). These routes are rate limited per caller IP.
Source-connection endpoints require an OAuth access token issued to a Simply Spaces first-party client, sent as Authorization: Bearer ...; other credentials (including team API keys such as s360_live_...) receive 403 SIMPLY_SPACES_OAUTH_CLIENT_REQUIRED. Callers also need the SIMPLY_SPACES_VIEW or SIMPLY_SPACES_MANAGE feature permission (manage for provisioning and webhook registration) and read access to the mapped collections and fields. A teamSimplyId query parameter selects the team.

See Authentication for general token handling and Error Handling for the error envelope.

Endpoints

Method	Path	Description
`POST`	`/v1/simply-spaces/booking-links/{bookingLinkSimplyId}/availability`	Check availability for a time range.
`POST`	`/v1/simply-spaces/booking-links/{bookingLinkSimplyId}/slots`	List bookable slots inside a time range.
`POST`	`/v1/simply-spaces/booking-links/{bookingLinkSimplyId}/slot-grid`	Calendar slot-grid availability per local day.
`POST`	`/v1/simply-spaces/booking-links/{bookingLinkSimplyId}/quote`	Quote pricing for selected spaces and times.
`POST`	`/v1/simply-spaces/booking-links/{bookingLinkSimplyId}/run`	Booking submission guard (see below).
`GET`	`/v1/simply-spaces/source-connections/{sourceConnectionSimplyId}/snapshot`	Get the mapped Simply Spaces snapshot.
`GET`	`/v1/simply-spaces/source-connections/{sourceConnectionSimplyId}/booking-channels`	List configured booking channels with validation.
`POST`	`/v1/simply-spaces/source-connections/{sourceConnectionSimplyId}/booking-channels/provision`	Create or update a booking channel.
`POST`	`/v1/simply-spaces/source-connections/{sourceConnectionSimplyId}/booking-availability`	Internal availability check.
`POST`	`/v1/simply-spaces/source-connections/{sourceConnectionSimplyId}/booking-quotes`	Internal quote.
`POST`	`/v1/simply-spaces/source-connections/{sourceConnectionSimplyId}/booking-runs`	Create a booking record (internal).
`PATCH`	`/v1/simply-spaces/source-connections/{sourceConnectionSimplyId}/bookings/{bookingRecordSimplyId}`	Edit, cancel, approve, or deny a booking.
`POST`	`/v1/simply-spaces/source-connections/{sourceConnectionSimplyId}/webhook-subscriptions`	Register live-update webhooks.

The Booking-Link Flow

A booking page built on a public link follows three steps: check availability → quote → run. All three POST to the link and identify the channel automatically from the link, so request bodies stay small. Times are ISO 8601 with a UTC offset.

1. Check Availability

curl -s -X POST "https://api.simply360.app/v1/simply-spaces/booking-links/BLNK-1234-ABCD/availability" \
  -H "X-S360-Public-Token: $S360_BOOKING_LINK_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "startsAt": "2026-07-10T14:00:00-05:00",
    "endsAt": "2026-07-10T16:00:00-05:00"
  }'

{
  "data": {
    "bookingChannelSimplyId": "BCHN-5678-EFGH",
    "bookingLinkSimplyId": "BLNK-1234-ABCD",
    "startsAt": "2026-07-10T14:00:00-05:00",
    "endsAt": "2026-07-10T16:00:00-05:00",
    "spaces": [
      {
        "spaceRecordSimplyId": "SPCE-9012-IJKL",
        "displayName": "Main Hall",
        "capacity": 120,
        "publicDetails": { "rateLabel": "$80 / hour", "highlights": "Stage, AV system" },
        "isAvailable": true,
        "conflicts": []
      }
    ],
    "diagnostics": [],
    "generatedAt": "2026-07-07T15:20:00.000Z"
  }
}

Each space reports isAvailable plus any conflicts; on the public surface conflict details are suppressed and only availability is exposed. When something blocks the whole request (bad time range, lead-time violation, link policy), it appears in diagnostics.

2. Quote

Add the selected spaces. spaceRecordSimplyIds requires at least one entry; packageRecordSimplyId optionally selects a package rate.

curl -s -X POST "https://api.simply360.app/v1/simply-spaces/booking-links/BLNK-1234-ABCD/quote" \
  -H "X-S360-Public-Token: $S360_BOOKING_LINK_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "startsAt": "2026-07-10T14:00:00-05:00",
    "endsAt": "2026-07-10T16:00:00-05:00",
    "spaceRecordSimplyIds": ["SPCE-9012-IJKL"]
  }'

{
  "data": {
    "bookingChannelSimplyId": "BCHN-5678-EFGH",
    "startsAt": "2026-07-10T14:00:00-05:00",
    "endsAt": "2026-07-10T16:00:00-05:00",
    "currencyCode": "USD",
    "amountMinorUnits": 16000,
    "lineItems": [
      { "label": "Main Hall (2 hours)", "amountMinorUnits": 16000 }
    ],
    "diagnostics": [],
    "generatedAt": "2026-07-07T15:20:04.000Z"
  }
}

Amounts are always minor units (16000 = $160.00). Quotes are computed server-side; never trust client-side price math.

3. Run (Submit the Booking)

POST /v1/simply-spaces/booking-links/{bookingLinkSimplyId}/run takes the quote body plus title (required) and optional notes and requesterRecordSimplyId, and returns 201 with the created booking:

{
  "data": {
    "bookingRecordSimplyId": "BOOK-3456-MNOP",
    "status": "Pending Approval",
    "quote": { "currencyCode": "USD", "amountMinorUnits": 16000, "lineItems": [ { "label": "Main Hall (2 hours)", "amountMinorUnits": 16000 } ], "startsAt": "2026-07-10T14:00:00-05:00", "endsAt": "2026-07-10T16:00:00-05:00", "bookingChannelSimplyId": "BCHN-5678-EFGH", "diagnostics": [], "generatedAt": "2026-07-07T15:21:00.000Z" },
    "diagnostics": []
  }
}

Important: this endpoint is a fail-closed submission guard. Direct anonymous submissions are rejected with 403 BOOKING_LINK_VERIFICATION_REQUIRED; a public booking only completes when it is executed through the booking link's hosted DataWizard booking action, which runs with a verified session. In practice you use the public endpoints for browsing and quoting, and hand the visitor to the link's hosted booking wizard for the final submission — see Data Wizards and Embedding. The final availability check and booking insert are serialized per channel, so two concurrent submissions cannot double-book the same slot.

Slots and the Calendar Slot Grid

Two endpoints turn the availability policy into pickable times:

POST .../slots — body: startsAt, endsAt, optional durationMinutes and spaceRecordSimplyIds. Returns concrete slots, each with startsAt, endsAt, and the spaces available in that slot. Availability is re-checked per candidate slot.
POST .../slot-grid — month-calendar view: bookable slot starts per local day (channel timezone) for one space over a bounded date range, honoring lead time, advance limit, weekly windows, increments, and buffers. Computed from one conflict window per request, so calendar UIs stay cheap.

curl -s -X POST "https://api.simply360.app/v1/simply-spaces/booking-links/BLNK-1234-ABCD/slot-grid" \
  -H "X-S360-Public-Token: $S360_BOOKING_LINK_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "spaceRecordSimplyId": "SPCE-9012-IJKL",
    "fromDate": "2026-07-01",
    "toDate": "2026-07-31",
    "durationMinutes": 120
  }'

{
  "data": {
    "bookingChannelSimplyId": "BCHN-5678-EFGH",
    "spaceRecordSimplyId": "SPCE-9012-IJKL",
    "timezone": "America/Chicago",
    "fromDate": "2026-07-01",
    "toDate": "2026-07-31",
    "durationMinutes": 120,
    "slotIncrementMinutes": 30,
    "defaultDurationMinutes": 60,
    "days": [
      { "date": "2026-07-10", "slots": [ { "startsAt": "2026-07-10T09:00:00-05:00", "endsAt": "2026-07-10T11:00:00-05:00" } ] },
      { "date": "2026-07-11", "slots": [] }
    ],
    "diagnostics": [],
    "generatedAt": "2026-07-07T15:22:00.000Z"
  }
}

Slot-grid rules: fromDate/toDate use YYYY-MM-DD, toDate must not be before fromDate, and spaceRecordSimplyId is required unless you pass includeSpaces: true, which returns the bookable space list (with public presentation details) instead of — or alongside — computed slots. The response also echoes policy values (minimumDurationMinutes, maximumDurationMinutes, maximumAdvanceDays, pricingMode) so the UI can constrain inputs. An empty slots array means no availability that day.

Audience and Payment Policies

Each booking link enforces its policies on every public call:

INTERNAL_TEAM links are not public — public routes return 404 BOOKING_LINK_NOT_FOUND.
AUTHORIZED_CONSTITUENT links require identity verification before anything — including availability — is exposed.
Public links may allow anonymous availability browsing; if the link disables it, availability and quotes also require a verified session (403 BOOKING_LINK_VERIFICATION_REQUIRED).
Submissions (run) always require a verified session, as described above.
Links whose payment policy is anything other than NONE currently reject runs with 409 BOOKING_PAYMENT_NOT_SUPPORTED.

Booking Diagnostics

Booking responses and errors carry structured diagnostics: { "code", "message", "path"? }. Frequently seen codes:

Code	Meaning
`INVALID_BOOKING_TIME_RANGE`	The start/end pair is invalid.
`BOOKING_LEAD_TIME_VIOLATION`	The start is sooner than the channel's minimum lead time.
`BOOKING_ADVANCE_LIMIT_EXCEEDED`	The start is further out than the channel allows.
`BOOKING_OUTSIDE_AVAILABILITY_WINDOW`	The time falls outside the channel's weekly windows.
`BOOKING_DURATION_OUT_OF_RANGE`	Duration violates the channel's minimum/maximum.
`BOOKING_SLOT_INCREMENT_MISMATCH`	The start does not align to the slot increment.
`BOOKING_SPACE_UNAVAILABLE`	A selected space is already booked or blocked.
`BOOKING_SPACE_OUT_OF_SCOPE`	A selected space is not bookable through this link.
`BOOKING_SLOT_CONTENTION`	Another booking claimed the slot during submission; re-check availability.
`BOOKING_LINK_VERIFICATION_REQUIRED`	The link requires a verified session for this operation.

Source-Connection Booking APIs

These operate on the team's Simply Spaces source connection and require the Simply Spaces OAuth client credentials described under Authentication, plus a teamSimplyId query parameter.

Snapshot — GET .../snapshot returns the mapped spaces/events/people model for the connection. Returns 400 SIMPLY_SPACES_MAPPING_NOT_CONFIGURED until mapping is set up.
Booking channels — GET .../booking-channels returns { "bookingChannels": [...], "validation": {...} }, where validation reports configuration diagnostics against the live schema.
Provision a channel — POST .../booking-channels/provision with body { "bookingChannel": { ... } } validates and stores the channel, generates or repairs its hosted booking DataWizards, and returns { "bookingChannel", "wizardDiagnostics", "publicAccessTokens", "validation" }. The publicAccessTokens array contains the raw public booking-link token secrets only in this response — store them immediately; they are not persisted in readable form. Requires SIMPLY_SPACES_MANAGE, and generating wizards additionally requires DataWizard admin permission.
Internal availability / quotes — POST .../booking-availability and POST .../booking-quotes take the same request shapes as the public endpoints but with bookingChannelSimplyId required in the body (and optional bookingLinkSimplyId).
Internal runs — POST .../booking-runs creates the booking record directly (201). The caller must be able to create records in the booking collection and write every mapped booking field; otherwise 403 SIMPLY_SPACES_BOOKING_UNAUTHORIZED.
Booking lifecycle — PATCH .../bookings/{bookingRecordSimplyId} with body { "action": "EDIT" | "CANCEL" | "APPROVE" | "DENY", "bookingChannelSimplyId": "..." }. EDIT must change at least one field (startsAt/endsAt together, spaceRecordSimplyIds, title, notes, requesterRecordSimplyId); the other actions accept no field changes. Reassigning requesterRecordSimplyId requires manage-bookings or manage permission; manage-own and verified public requester flows cannot change that relation. Schedule and space edits re-check availability under the same per-channel lock as runs. The response reports updatedFieldSimplyIds and, for re-priced edits, a fresh quote.
Live-update webhooks — POST .../webhook-subscriptions with body { "targetUrl": "..." } registers subscriptions for the four record event types over the mapped collections and returns { "secret", "subscriptions": [...] } with a shared HMAC signing secret. The target URL must be the Simply Spaces webhook receiver for this source connection on api.simplyspaces.app or api.dev.simplyspaces.app, including the source connection simplyId in the receiver path. Signature verification works exactly like team webhooks — see Webhooks.

Usage Notes

Public booking-link tokens are secrets for a link's audience, not general API keys; scope them to the booking UI that needs them.
Always re-quote before submitting — runs recompute the quote server-side and reject stale selections with diagnostics such as BOOKING_SLOT_CONTENTION.
All timestamps are ISO 8601 with offsets; slot-grid dates are local calendar dates in the channel's timezone.
Bookings are ordinary data records in the mapped booking collection, so they are also readable through the Data Records API subject to normal permissions.
Validation failures return 400 SIMPLY_SPACES_BOOKING_REQUEST_INVALID with Zod issue details; see Error Handling for the envelope.
Questions or gaps in this reference? Use the feedback page or email developers@simply360.app.