Developers

Using the SpinBook API

Read and update clients, events, checklists, and planning over a simple REST API authenticated with an org API key.

Updated Mon Aug 03 2026 00:00:00 GMT+0000 (Coordinated Universal Time)View as Markdown

SpinBook has a REST API for reading and updating your clients, events, checklists, and planning forms — handy for integrations, automations, or syncing with another system.

Get an API key

Each key is scoped to a single organization. Ask us to issue one for your workspace. Treat it like a password — it's shown once and grants full access to your org's data.

Authenticate

Send your key as a Bearer token on every request:

curl https://spinbook.io/api/v1/me \
  -H "Authorization: Bearer YOUR_API_KEY"

GET /api/v1/me returns the org your key belongs to — a quick way to confirm it works.

What you can do

Resource	Operations
Clients	list, create, get, update, delete
Events	list (filter by status / client / date), create, get, update, delete
Checklist	list, add, update, delete items
Planning	get, upsert the planning form
Planning-form config	get, replace the org's planning-form customization
Timeline	list, bulk-replace, add, update, delete reception-timeline items
Playlist	trigger a sync of the couple's playlist (see Playlist Generator)
Quote config	get, replace the org's instant-quote pricing
Call bookings	list booked calls (filter by date/status) — see Call scheduling
Payments	list every payment (filter by status / due / paid dates — `status=pending` = all outstanding) plus a per-month summary at `/payments/summary` for financial exports

Responses are wrapped as { "data": … }; errors as { "error": { "code", "message" } }.

Checklist completion over the API

A bound checklist item (contract, deposit, planning…) reports completed: true when its real task is done — even if it was never ticked by hand. The completed_at field reflects only a manual override. See Checklists & forms for the model.

Import a reception timeline

The timeline endpoints let an external tool — for example an AI that read a couple's run sheet, PDF, or emailed schedule — push the parsed rows straight onto an event. A timeline item is just a time, an activity, and an optional detail; times are free-form strings the app formats as e.g. 6:00 PM, so send whatever you parsed.

Each item has a stable id, so you can address a single row after the fact.

Bulk-replace the whole timeline in one call (the usual move after parsing a document):

curl -X PUT https://spinbook.io/api/v1/events/EVENT_ID/timeline \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "items": [
      { "time": "5:00 PM", "activity": "Cocktail Hour" },
      { "time": "6:00 PM", "activity": "Dinner Served", "detail": "Buffet opens" },
      { "time": "7:30 PM", "activity": "First Dances" }
    ]
  }'

Or work row by row:

GET /api/v1/events/{id}/timeline — list items (each with its id)
POST /api/v1/events/{id}/timeline — append one item ({ "time", "activity", "detail?" })
PATCH /api/v1/events/{id}/timeline/{itemId} — update a single item's fields
DELETE /api/v1/events/{id}/timeline/{itemId} — remove one item

The timeline shows up on the couple's Timeline page and prints on the DJ's run sheet — the API writes the same rows the in-app builder does. Couples who'd rather not retype a timeline can instead attach the document itself on that page.

Full reference

The complete, interactive API reference (every endpoint, request/response shapes, and a "try it" console) lives at spinbook.io/docs, generated from the live OpenAPI spec at /api/v1/openapi.json.

Checklist

Request an API key for your workspace
Confirm it with GET /api/v1/me
Explore the full reference at /docs
Build your integration