---
title: Using the SpinBook API
id: using-the-api
description: Read and update clients, events, checklists, and planning over a simple REST API authenticated with an org API key.
category: Developers
order: 40
tags: [api, integrations, developers]
related: [checklist-and-forms, planning-form]
updated: 2026-08-03
---

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:

```bash
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](/planning-form) |
| Timeline | list, bulk-replace, add, update, delete reception-timeline items |
| Playlist | trigger a sync of the couple's playlist (see [Playlist Generator](/playlist-generator)) |
| Quote config | get, replace the org's [instant-quote](/instant-quotes) pricing |
| Call bookings | list booked calls (filter by date/status) — see [Call scheduling](/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](/payments) |

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](/checklist-and-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):

```bash
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](/planning-form) 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](/planning-form) 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](https://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