Open API & Docs

Simple Scheduler exposes a tenant-scoped REST API at /api/v1/*. Authenticate with an sk_live_* key generated from your workspace's settings, send JSON, get JSON back. The full spec lives at /api-docs/openapi.json.

Generate your first key

Authentication

Pass your key as a Bearer token in the Authorization header. The key value is shown once at issuance — store it in your secret manager. Never put a key in a URL; query parameters land in CDN logs and proxy logs.

Capabilities

Each key carries a set of capability scopes. Endpoints declare their requirement via the x-required-capability OpenAPI extension. The capabilities available in v1:

  • customers:read Read customer records and recent appointment summaries.
  • customers:write Create or update customer records (alias of `leads:write` with converted status).
  • leads:write Push new leads/contacts via POST /api/v1/leads.
  • appointments:read Read appointments. (v1: 501 Not Implemented; spec only.)
  • appointments:write Create or update appointments. (v1: 501 Not Implemented; spec only.)
  • webhooks:manage Manage outbound webhook subscriptions for this tenant.

Quick start: ingest a lead

The priority endpoint is POST /api/v1/leads. It inserts a customer record with lead_status='new'. Set Idempotency-Key to a UUID and you can safely retry within 24 hours.

curl -X POST https://app.simplescheduler.com/api/v1/leads \
  -H "Authorization: Bearer sk_live_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{
    "email": "jane@example.com",
    "first_name": "Jane",
    "last_name": "Doe",
    "phone": "+15555550100",
    "notes": "Webflow contact form"
  }'

Rate limits

Defaults: 60 requests/minute, 1,000/hour per key. Both limits are enforced; the smaller window denies first under burst traffic. Per-key overrides are configurable from the key's settings page.

Outbound webhooks

Subscribe to events like customer.created, appointment.completed, and payment.received via your Webhooks settings. Deliveries are HMAC-SHA256-signed; verify before trusting.