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)

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, `status=claimed` = couple says it's sent, awaiting DJ confirmation) 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