REST API · v1

Spanr API Reference

JSON over HTTPS. Org-scoped. Auth via Bearer tokens — JWT for dashboard sessions, API keys for server integrations. Every endpoint below is rate-limited per token.

All systems operational· Status →

Base URL

https://api.spanr.uk

Getting started

  1. Sign up for a Spanr account and start a 14-day trial.
  2. Upgrade to the Company plan to unlock API access.
  3. Mint an API key under Settings → API Access. You'll see the full secret once — store it in your secret manager.
  4. Send the key on every request as Authorization: Bearer ak_live_….
Authenticate (JWT for dashboards)
curl -X POST https://api.spanr.uk/auth/login \
  -H "Content-Type: application/json" \
  -d '{"email":"you@example.com","password":"…"}'

Authentication

Every endpoint (except /auth/*) requires a Bearer token. JWT access tokens expire after 15 minutes — refresh with POST /auth/refresh. API keys do not expire (revoke from settings).

Rate limits

60 req/min per API key for read endpoints. 10 req/min for AI endpoints. On 429, the response includes Retry-After in seconds. Burst is allowed within short windows.

Generate a quote with AI
curl -X POST https://api.spanr.uk/quotes/generate \
  -H "Authorization: Bearer ak_live_…" \
  -H "Content-Type: application/json" \
  -d '{"description":"Replace 16-way consumer unit","tradeType":"ELECTRICAL"}'

Endpoints

Authentication

JWT for the dashboard, API keys for server-to-server.

POST/auth/register
POST/auth/login
POST/auth/refresh
GET/auth/me

Jobs

Create, update, and progress jobs through the lifecycle.

GET/jobs
POST/jobs
GET/jobs/:id
PATCH/jobs/:id
PATCH/jobs/:id/status
POST/jobs/:id/notes

Quotes

AI-powered quote generation with manual override.

POST/quotes/generate
POST/quotes/generate/stream
GET/quotes
POST/quotes
GET/quotes/:id
POST/quotes/:id/send
POST/quotes/:id/convert

Invoices

Stripe payment links + branded PDFs.

GET/invoices
POST/invoices
GET/invoices/:id
PATCH/invoices/:id
POST/invoices/:id/send

Customers

Org-scoped customer CRM.

GET/customers
POST/customers
GET/customers/:id
PATCH/customers/:id

Certificates

EICRs, MWCs, CP12s, and gate service records — all with branded PDFs.

GET/certificates
GET/electrical/eicrs/:id/pdf
GET/electrical/mwcs/:id/pdf
GET/gas/cp12s/:id/pdf
GET/gate/service-records/:id/pdf

Scheduling

Smart AI route suggestions — falls back to deterministic ordering when AI is offline.

POST/ai/smart-schedule
GET/jobs?scheduledFrom&scheduledTo

AI

Job summaries, customer snapshots, follow-up drafts, materials suggestions.

GET/ai/health
GET/ai/features
POST/ai/job-summary
POST/ai/customer-summary
POST/ai/follow-up
POST/ai/materials
POST/ai/transcribe

API keys

Mint and revoke programmatic access tokens (Company plan).

GET/api-keys
POST/api-keys
DELETE/api-keys/:id

Webhooks (Stripe)

Stripe events update subscription state in real time.

POST/webhooks/stripe

Webhooks

Stripe events drive subscription state changes. Stripe webhooks must be configured with the live signing secret (we verify every payload).

Webhook endpoint
# Stripe sends signed events to this endpoint.
# Configure under Stripe Dashboard → Developers → Webhooks
# Endpoint URL: https://api.spanr.uk/webhooks/stripe
# Select events:
#   - customer.subscription.created
#   - customer.subscription.updated
#   - customer.subscription.deleted
#   - invoice.payment_failed

SDKs (coming soon)

Native TypeScript and Python clients ship Q3 2026. Until then, the JSON HTTP API is stable — every successful response is parseable, errors return { statusCode, error, message }.

Be notified when SDKs ship →

Changelog

2026-05-10

Streaming quotes

Added /quotes/generate/stream (SSE) — progressive line items + confidence score.

2026-05-08

Voice-to-quote

Added /ai/transcribe — multipart Whisper transcription with trade inference.

2026-05-04

Job & customer AI summaries

New /ai/job-summary, /ai/customer-summary, /ai/follow-up, /ai/materials.

2026-04-29

Plan-gated features

/ai/features endpoint returns per-plan availability for every AI feature.

Building something on Spanr?

Email the API team — we love seeing what people build.

hello@spanr.uksupport@spanr.uk