SwiftBooksPro API v1

Quickstart

Three steps to your first API call:

1. Generate a key at Settings → API Access.
2. Copy the key (shown once at creation).
3. Send it as a Bearer token in the Authorization header.

# Fetch your organisation profile + active plan
curl "https://www.swiftbookspro.co.uk/api/v1/me" \
     -H "Authorization: Bearer sbp_live_••••••••••••••"

# Returns:
{
  "data": {
    "organization": { "id": 42, "name": "Acme Ltd", "currency": "GBP" },
    "api_key":      { "prefix": "sbp_live_aBc4", "scopes": ["read:*"] },
    "plan":         { "slug": "basic", "requests_per_minute": 300 }
  },
  "meta": { "request_id": "req_a1b2c3d4e5f6g7h8", "timestamp": "2026-06-03T14:23:00Z" }
}

Authentication

Every endpoint under /api/v1 requires a Bearer token. Keys are issued per organisation from your Settings → API Access page.

Authorization: Bearer sbp_live_aBc4d5E6f7G8h9I0j1K2l3M4n5O6p7

Keys come in two flavours:

• sbp_live_… — issued from a live organisation; affects production data.
• sbp_test_… — read-only by convention; useful for staging / integration tests.

Base URL & Versioning

https://www.swiftbookspro.co.uk/api/v1

The version is encoded in the URL. Breaking changes will ship as /api/v2 alongside /api/v1, with a 12-month deprecation window. Backwards-compatible additions (new endpoints, optional fields) happen inline and are listed in the changelog.

Rate limits & subscription plans

Every request counts towards four concurrent windows — per-minute, per-hour, per-day and per-month — on your plan. The most-constrained window wins. Limits live in the database so super-admins can tune them per deployment.

Every response carries headers describing the tightest active window:

X-RateLimit-Window:    minute
X-RateLimit-Limit:     300
X-RateLimit-Remaining: 287
X-RateLimit-Reset:     1717423200   # unix timestamp

If you exceed a limit, you get HTTP 429 Too Many Requests with a Retry-After header (seconds) and a JSON body explaining which window tripped:

{
  "error": {
    "code": "rate_limit_exceeded",
    "message": "Rate limit exceeded — minutely quota of 60 requests reached.",
    "details": {
      "window": "minute", "limit": 60, "used": 60,
      "retry_after": 23, "plan": "free"
    }
  }
}

Scopes

Scopes are verb:resource pairs. A request must satisfy the scope on both the API key AND the plan:

Errors

Every error follows the same envelope:

{ "error": { "code": "<stable_code>", "message": "<human text>", "details": { ... } } }

Pagination

List endpoints accept ?page (default 1) and ?per_page (default 25, max 100). Responses include a meta.pagination block:

"pagination": {
  "page": 2, "per_page": 25,
  "total": 143, "total_pages": 6, "has_more": true
}

Endpoint reference

Meta

Customers

Vendors

Products / services

Invoices

Bills

Expenses

Payments

VAT returns

Bulk export (migration)

For one-shot migrations into another system. Streams CSV row-by-row; JSON returns the entire result set. The plan's max_export_rows caps each call — narrow with from/to/status filters or upgrade your plan.

# Stream every invoice in 2025 as CSV
curl "https://www.swiftbookspro.co.uk/api/v1/export/invoices/csv?from=2025-01-01&to=2025-12-31" \
     -H "Authorization: Bearer sbp_live_••••••••" \
     -o invoices_2025.csv

Changelog