Register a new user and organisation

POST https://app.speybooks.com/api/v1/registration/register

Register a new user and provision their organisation. This is a multi-step atomic operation:

  1. Validate input and check email uniqueness
  2. Determine trial length (first 50 signups: 90 days, then 30)
  3. Create organisation with UUID, slug, and default UK settings
  4. Create user with Argon2id-hashed password
  5. Link user to organisation as owner
  6. Seed chart of accounts (Sole Trader or Limited Company variant)
  7. Seed default categorisation rules (TMADD Phase 4c)
  8. Create default financial period (current UK tax year)
  9. Create default invoice settings
  10. Commit transaction
  11. Create Stripe customer and checkout session (non-blocking)
  12. Send verification and welcome emails (non-blocking)

Returns a JWT for immediate authentication (token) and optionally a Stripe checkout URL for payment setup (checkoutUrl, present when Stripe is configured). The user object includes emailVerified: false and createdAt for immediate UI hydration.

Public endpoint with rate limiting. Returns 409 if the email is already registered (without revealing which email).

Body parameters

email string required
Email address for the new account. Must be unique across all users.
email
fullName string required
Full name of the user (1-255 characters).
organisationName string required
Name of the organisation to create (1-255 characters).
password string required
min length: 8
plan string optional
Business type. Determines the chart of accounts seeded and the Stripe plan. Defaults to limited-company.
sole-traderlimited-company

Response

201 User and organisation created successfully. Returns a JWT token for immediate authentication and optionally a Stripe Checkout URL.
Show response fields
checkoutUrl string
Stripe Checkout URL to collect payment. Null if Stripe setup failed (user can complete later).
organisation object
The newly created organisation.
Show child attributes
id string
Organisation UUID.
name string
Organisation name.
slug string
URL-friendly slug derived from the organisation name.
token string
JWT authentication token. Use in Authorization: Bearer header.
user object
The newly created user.
Show child attributes
createdAt string date-time
ISO 8601 creation timestamp.
email string
User email address.
emailVerified boolean
Always false at registration. Verification email is sent automatically.
fullName string
User full name.
id integer
Internal user ID.

Error codes

400 Validation error. Check the details field for per-field errors.
409 Email address already registered.
429 Rate limit exceeded. Try again later.