Conventions
The SpeyBooks API follows a consistent set of conventions across all endpoints. Understanding these patterns will help you integrate quickly and avoid common pitfalls.
Base URL
All API requests are made to:
https://api.speybooks.com/v1/
Response envelope
Every response follows the same structure. For success: { "success": true, "data": { } }. For errors: { "success": false, "error": { "code": "...", "message": "..." } }.
Always check the success field before accessing data. See Errors for the complete list of error codes.
Prefixed IDs
SpeyBooks uses prefixed string IDs for all resources. The prefix indicates the resource type, making IDs self-describing and reducing the risk of passing an ID to the wrong endpoint.
| Resource | Prefix | Example |
|---|---|---|
| Invoice | inv_ |
inv_42 |
| Quote | quo_ |
quo_17 |
| Contact | cont_ |
cont_3 |
| Transaction | txn_ |
txn_891 |
| Account | acc_ |
acc_1200 |
| User | usr_ |
usr_5 |
| Line item | line_ |
line_203 |
| Data import | dimp_ |
dimp_1 |
| Organisation | — | UUID format |
Passing an ID with the wrong prefix returns a 400 invalid_id error.
Monetary values
All monetary values in the API are represented as integers in minor units (pence for GBP). This avoids floating-point precision issues in financial calculations.
| Display value | API value | Unit |
|---|---|---|
| £15.00 | 1500 |
pence |
| £1,500.00 | 150000 |
pence |
| £0.01 | 1 |
pence |
| -£250.00 | -25000 |
pence |
When creating or updating resources, always send monetary values as integers. The API rejects floating-point numbers in monetary fields.
Dates and timestamps
All dates are ISO 8601 strings. Date-only fields use YYYY-MM-DD format. Timestamps include the full datetime in UTC. The API does not accept or return timestamps in other timezones.
Custom metadata
Invoices, contacts, transactions, and quotes support a metadata field — a flat key-value object for storing your own data alongside SpeyBooks resources.
Maximum 50 keys per resource. Keys and values must be strings. Keys prefixed with _sb_ are reserved. Updates use merge semantics — set a key to null to remove it. Existing keys not included in the update are preserved.
Idempotency keys
For POST, PUT, and PATCH requests made with API key authentication, include an Idempotency-Key header to ensure the request is processed only once. If you send the same key with the same parameters, the API returns the original response without reprocessing. Keys expire after 24 hours. Failed 5xx requests release the key for retry.
Content type
All request bodies must be JSON with Content-Type: application/json. The API does not accept form-encoded data, except for file upload endpoints (e.g. bank statement import) which accept multipart/form-data.
Versioning
The API is versioned through the URL path (/v1/). Breaking changes will be introduced in a new version. Non-breaking additions — new response fields, new optional parameters, new endpoints, new enum values — are added to the current version without a version bump.