Organisation

Every SpeyBooks tenant is an organisation. The organisation record holds the company identity (name, VAT number, company number, address) and the operational settings that govern how the platform behaves (currency, VAT scheme, fiscal year, invoice/quote numbering).

Structure

Organisation data is split across two storage layers:

  • Profile columns — name, address, VAT number, company number, business type. Updated via PUT /organisation.
  • Settings JSON — currency, VAT scheme, fiscal year start. Stored in the settings JSONB column on the organisations table, plus per-resource settings in the settings key-value table (invoice prefix/numbering, quote prefix/numbering). Updated via PUT /organisation/settings.

Address: GET vs. PUT asymmetry

The GET /organisation response returns the address as a nested object (address: { line1, city, ... }) for display convenience. However, PUT /organisation expects flat fields (addressLine1, addressLine2, city, region, postalCode, country). Do not submit the nested address object to the PUT endpoint — it will result in a validation error.

Multi-tenancy

All queries are scoped to request.organisationId, enforced by RLS. The organisation ID is a UUID (not prefixed).

VAT schemes

SpeyBooks supports three VAT modes:

  • not_registered — no VAT tracking
  • standard — standard VAT accounting (output VAT − input VAT)
  • flat_rate — Flat Rate Scheme (gross turnover × flat rate %)

The scheme affects dashboard tax set-aside calculations, VAT return generation, and invoice line VAT handling.

→ The Organisation object

Endpoints

GET https://app.speybooks.com/api/v1/organisation/ Get organisation details and settings PUT https://app.speybooks.com/api/v1/organisation/ Update organisation profile PUT https://app.speybooks.com/api/v1/organisation/settings Update organisation settings