{ "openapi": "3.1.1", "info": { "title": "Octbooks.Api | v1", "version": "1.0.0" }, "servers": [ { "url": "https://api.octbooks.co.uk/" } ], "paths": { "/api/reconciliation/institutions": { "get": { "tags": [ "Reconciliation" ], "summary": "The banks a connection can be made to.", "operationId": "ListBankInstitutions", "responses": { "200": { "description": "OK" } } } }, "/api/reconciliation/consent/start": { "post": { "tags": [ "Reconciliation" ], "summary": "Begins a bank connection and returns the URL to send the user to.", "operationId": "StartBankConsent", "parameters": [ { "name": "institutionId", "in": "query", "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK" } } } }, "/api/reconciliation/consent/callback": { "get": { "tags": [ "Reconciliation" ], "summary": "Where the aggregator returns the user after they consent.", "operationId": "BankConsentCallback", "parameters": [ { "name": "code", "in": "query", "schema": { "type": "string" } }, { "name": "consent", "in": "query", "schema": { "type": "string" } }, { "name": "state", "in": "query", "schema": { "type": "string" } }, { "name": "error", "in": "query", "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK" } } } }, "/api/reports/ask": { "post": { "tags": [ "Reporting" ], "summary": "Answers a question about the accounts, citing the reports it read.", "operationId": "AskAboutTheBooks", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AskRequest" } } }, "required": true }, "responses": { "200": { "description": "OK" } } } }, "/api/tenant/provision": { "post": { "tags": [ "Tenant" ], "summary": "Creates the chart of accounts, subscription and entitlements for the caller's tenant.", "operationId": "ProvisionTenant", "responses": { "200": { "description": "OK" } } } }, "/api/tenant/registration": { "get": { "tags": [ "Tenant" ], "summary": "Whether this tenant has been registered, and what as.", "operationId": "GetTenantRegistration", "responses": { "200": { "description": "OK" } } } }, "/api/companies/search": { "get": { "tags": [ "Tenant" ], "summary": "Companies matching a name, from the register.", "operationId": "SearchCompanies", "parameters": [ { "name": "q", "in": "query", "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK" } } } }, "/api/companies/{companyNumber}": { "get": { "tags": [ "Tenant" ], "summary": "A company's register entry, its filing deadlines, and the template it implies.", "operationId": "GetCompany", "parameters": [ { "name": "companyNumber", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK" } } } }, "/api/tenant/register": { "post": { "tags": [ "Tenant" ], "summary": "Verifies the business, creates its books, and starts checkout.", "operationId": "RegisterTenant", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RegisterTenantRequest" } } }, "required": true }, "responses": { "200": { "description": "OK" } } } }, "/api/plans": { "get": { "tags": [ "Billing" ], "summary": "The plans offered on the pricing page, with their limits.", "operationId": "ListPlans", "responses": { "200": { "description": "OK" } } } }, "/api/signup/workspace": { "post": { "tags": [ "Tenant" ], "summary": "Creates an Auth0 organisation and tenant for a new business.", "operationId": "CreateSignupWorkspace", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateWorkspaceRequest" } } }, "required": true }, "responses": { "200": { "description": "OK" } } } }, "/api/ledger/accounts": { "get": { "tags": [ "Ledger" ], "summary": "The chart of accounts for the current tenant.", "operationId": "ListAccounts", "parameters": [ { "name": "includeInactive", "in": "query", "schema": { "type": "boolean" } } ], "responses": { "200": { "description": "OK" } } }, "post": { "tags": [ "Ledger" ], "operationId": "CreateAccount", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateAccountRequest" } } }, "required": true }, "responses": { "200": { "description": "OK" } } } }, "/api/ledger/journal-entries": { "post": { "tags": [ "Ledger" ], "summary": "Posts a balanced double-entry journal.", "operationId": "PostJournalEntry", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PostJournalEntryRequest" } } }, "required": true }, "responses": { "200": { "description": "OK" } } } }, "/api/ledger/trial-balance": { "get": { "tags": [ "Ledger" ], "operationId": "GetTrialBalance", "parameters": [ { "name": "asOf", "in": "query", "schema": { "type": "string", "format": "date" } } ], "responses": { "200": { "description": "OK" } } } }, "/api/invoices": { "get": { "tags": [ "Invoicing" ], "operationId": "ListInvoices", "parameters": [ { "name": "status", "in": "query", "schema": { "$ref": "#/components/schemas/InvoiceStatus" } } ], "responses": { "200": { "description": "OK" } } }, "post": { "tags": [ "Invoicing" ], "operationId": "CreateInvoice", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateInvoiceRequest" } } }, "required": true }, "responses": { "200": { "description": "OK" } } } }, "/api/invoices/{id}": { "get": { "tags": [ "Invoicing" ], "operationId": "GetInvoice", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "OK" } } } }, "/api/invoices/{id}/issue": { "post": { "tags": [ "Invoicing" ], "summary": "Issues a draft invoice and publishes it to the ledger.", "operationId": "IssueInvoice", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "OK" } } } }, "/api/reconciliation/connections": { "get": { "tags": [ "Reconciliation" ], "operationId": "ListBankConnections", "responses": { "200": { "description": "OK" } } } }, "/api/reconciliation/connections/{id}/sync": { "post": { "tags": [ "Reconciliation" ], "summary": "Queues a bank feed pull for the given window.", "operationId": "RequestBankSync", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SyncRequest" } } }, "required": true }, "responses": { "200": { "description": "OK" } } } }, "/api/reconciliation/transactions/unmatched": { "get": { "tags": [ "Reconciliation" ], "operationId": "ListUnmatchedTransactions", "parameters": [ { "name": "connectionId", "in": "query", "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "OK" } } } }, "/api/reconciliation/transactions/search": { "get": { "tags": [ "Reconciliation" ], "summary": "Searches all transactions, matched or not.", "description": "The q parameter is a query string, not just text: bare words are ANDed against the description and merchant, \"quoted phrases\" stay together, -word excludes, and amount:>100, amount:100..500, after:2026-08-01, before:, on:, month:2026-08, status:matched, is:out and merchant: narrow further. Anything it cannot read is treated as text rather than rejected.", "operationId": "SearchTransactions", "parameters": [ { "name": "q", "in": "query", "schema": { "type": "string" } }, { "name": "connectionId", "in": "query", "schema": { "type": "string", "format": "uuid" } }, { "name": "page", "in": "query", "schema": { "pattern": "^-?(?:0|[1-9]\\d*)$", "type": [ "integer", "string" ], "format": "int32" } }, { "name": "pageSize", "in": "query", "schema": { "pattern": "^-?(?:0|[1-9]\\d*)$", "type": [ "integer", "string" ], "format": "int32" } } ], "responses": { "200": { "description": "OK" } } } }, "/api/reconciliation/transactions/{id}/match": { "post": { "tags": [ "Reconciliation" ], "operationId": "MatchTransaction", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MatchRequest" } } }, "required": true }, "responses": { "200": { "description": "OK" } } } }, "/api/reconciliation/transactions/{id}/ignore": { "post": { "tags": [ "Reconciliation" ], "operationId": "IgnoreTransaction", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "OK" } } } }, "/api/platform/impersonations": { "get": { "tags": [ "Platform" ], "summary": "Who has acted as a customer's tenant, most recent first.", "operationId": "ListImpersonations", "parameters": [ { "name": "tenantId", "in": "query", "schema": { "type": "string", "format": "uuid" } }, { "name": "take", "in": "query", "schema": { "pattern": "^-?(?:0|[1-9]\\d*)$", "type": [ "integer", "string" ], "format": "int32" } } ], "responses": { "200": { "description": "OK" } } } }, "/api/platform/subscriptions": { "get": { "tags": [ "Platform" ], "summary": "Billing state across every tenant. Lapsed accounts first.", "operationId": "ListPlatformSubscriptions", "parameters": [ { "name": "status", "in": "query", "schema": { "type": "string" } }, { "name": "unpaidOnly", "in": "query", "schema": { "type": "boolean" } } ], "responses": { "200": { "description": "OK" } } } }, "/api/platform/emails": { "post": { "tags": [ "Platform" ], "summary": "Sends an HTML message as the platform.", "operationId": "SendPlatformEmail", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SendEmailRequest" } } }, "required": true }, "responses": { "200": { "description": "OK" } } } }, "/api/platform/emails/suppressions": { "get": { "tags": [ "Platform" ], "summary": "Addresses that have opted out of marketing.", "operationId": "ListEmailSuppressions", "responses": { "200": { "description": "OK" } } } }, "/api/tax/vat/obligations": { "get": { "tags": [ "Tax / MTD" ], "operationId": "ListVatObligations", "parameters": [ { "name": "openOnly", "in": "query", "required": true, "schema": { "type": "boolean" } } ], "responses": { "200": { "description": "OK" } } } }, "/api/tax/vat/returns/{periodKey}/build": { "post": { "tags": [ "Tax / MTD" ], "summary": "Recalculates the nine boxes for a period from the ledger.", "operationId": "BuildVatReturn", "parameters": [ { "name": "periodKey", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK" } } } }, "/api/tax/vat/returns/{periodKey}": { "get": { "tags": [ "Tax / MTD" ], "operationId": "GetVatReturn", "parameters": [ { "name": "periodKey", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK" } } } }, "/api/tax/vat/returns/{periodKey}/submit": { "post": { "tags": [ "Tax / MTD" ], "summary": "Finalises a return and queues it for filing with HMRC.", "operationId": "SubmitVatReturn", "parameters": [ { "name": "periodKey", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SubmitVatReturnRequest" } } }, "required": true }, "responses": { "200": { "description": "OK" } } } }, "/api/reports/trial-balance": { "get": { "tags": [ "Reporting" ], "operationId": "TrialBalanceReport", "parameters": [ { "name": "asOf", "in": "query", "schema": { "type": "string", "format": "date" } } ], "responses": { "200": { "description": "OK" } } } }, "/api/reports/profit-and-loss": { "get": { "tags": [ "Reporting" ], "operationId": "ProfitAndLossReport", "parameters": [ { "name": "from", "in": "query", "required": true, "schema": { "type": "string", "format": "date" } }, { "name": "to", "in": "query", "required": true, "schema": { "type": "string", "format": "date" } } ], "responses": { "200": { "description": "OK" } } } }, "/api/reports/balance-sheet": { "get": { "tags": [ "Reporting" ], "operationId": "BalanceSheetReport", "parameters": [ { "name": "asOf", "in": "query", "schema": { "type": "string", "format": "date" } } ], "responses": { "200": { "description": "OK" } } } }, "/api/reports/excel/trial-balance": { "get": { "tags": [ "Excel feed" ], "operationId": "TrialBalanceExcelFeed", "parameters": [ { "name": "asOf", "in": "query", "schema": { "type": "string", "format": "date" } } ], "responses": { "200": { "description": "OK" } } } }, "/api/reports/excel/profit-and-loss": { "get": { "tags": [ "Excel feed" ], "operationId": "ProfitAndLossExcelFeed", "parameters": [ { "name": "from", "in": "query", "required": true, "schema": { "type": "string", "format": "date" } }, { "name": "to", "in": "query", "required": true, "schema": { "type": "string", "format": "date" } } ], "responses": { "200": { "description": "OK" } } } }, "/api/reports/excel/balance-sheet": { "get": { "tags": [ "Excel feed" ], "operationId": "BalanceSheetExcelFeed", "parameters": [ { "name": "asOf", "in": "query", "schema": { "type": "string", "format": "date" } } ], "responses": { "200": { "description": "OK" } } } }, "/api/billing/subscription": { "get": { "tags": [ "Billing" ], "operationId": "GetSubscription", "responses": { "200": { "description": "OK" } } } }, "/api/billing/entitlements": { "get": { "tags": [ "Billing" ], "operationId": "ListEntitlements", "responses": { "200": { "description": "OK" } } } }, "/api/billing/preferences": { "get": { "tags": [ "Billing" ], "summary": "Which metered features this tenant has switched on or off.", "operationId": "ListFeaturePreferences", "responses": { "200": { "description": "OK" } } } }, "/api/billing/preferences/{featureCode}": { "put": { "tags": [ "Billing" ], "summary": "Switches a metered feature on or off for this tenant.", "operationId": "SetFeaturePreference", "parameters": [ { "name": "featureCode", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SetFeaturePreferenceRequest" } } }, "required": true }, "responses": { "200": { "description": "OK" } } } } }, "components": { "schemas": { "AccountType": { "enum": [ "Asset", "Liability", "Equity", "Income", "Expense" ] }, "AskRequest": { "required": [ "question" ], "type": "object", "properties": { "question": { "type": "string" } } }, "CreateAccountRequest": { "required": [ "code", "name", "type", "currencyCode" ], "type": "object", "properties": { "code": { "type": "string" }, "name": { "type": "string" }, "type": { "$ref": "#/components/schemas/AccountType" }, "currencyCode": { "type": [ "null", "string" ] } } }, "CreateInvoiceLineRequest": { "required": [ "description", "quantity", "unitPrice", "vatTreatment" ], "type": "object", "properties": { "description": { "type": "string" }, "quantity": { "pattern": "^-?(?:0|[1-9]\\d*)(?:\\.\\d+)?$", "type": [ "number", "string" ], "format": "double" }, "unitPrice": { "pattern": "^-?(?:0|[1-9]\\d*)(?:\\.\\d+)?$", "type": [ "number", "string" ], "format": "double" }, "vatTreatment": { "$ref": "#/components/schemas/VatTreatment" } } }, "CreateInvoiceRequest": { "required": [ "customerName", "issuedOn", "dueOn", "lines", "customerEmail", "currencyCode" ], "type": "object", "properties": { "customerName": { "type": "string" }, "issuedOn": { "type": "string", "format": "date" }, "dueOn": { "type": "string", "format": "date" }, "lines": { "type": "array", "items": { "$ref": "#/components/schemas/CreateInvoiceLineRequest" } }, "customerEmail": { "type": [ "null", "string" ] }, "currencyCode": { "type": [ "null", "string" ] } } }, "CreateWorkspaceRequest": { "required": [ "businessName" ], "type": "object", "properties": { "businessName": { "type": "string" } } }, "InvoiceStatus": { "enum": [ "Draft", "Issued", "PartPaid", "Paid", "Void", null ] }, "JournalLineRequest": { "required": [ "accountId", "debit", "credit", "description" ], "type": "object", "properties": { "accountId": { "type": "string", "format": "uuid" }, "debit": { "pattern": "^-?(?:0|[1-9]\\d*)(?:\\.\\d+)?$", "type": [ "number", "string" ], "format": "double" }, "credit": { "pattern": "^-?(?:0|[1-9]\\d*)(?:\\.\\d+)?$", "type": [ "number", "string" ], "format": "double" }, "description": { "type": [ "null", "string" ] } } }, "MatchRequest": { "required": [ "nominalAccountId" ], "type": "object", "properties": { "nominalAccountId": { "type": "string", "format": "uuid" } } }, "PostJournalEntryRequest": { "required": [ "postedOn", "narrative", "lines", "currencyCode" ], "type": "object", "properties": { "postedOn": { "type": "string", "format": "date" }, "narrative": { "type": "string" }, "lines": { "type": "array", "items": { "$ref": "#/components/schemas/JournalLineRequest" } }, "currencyCode": { "type": [ "null", "string" ] } } }, "RegisterTenantRequest": { "required": [ "fullName", "email", "legalForm", "sector", "companyNumber", "priceId", "successUrl", "cancelUrl" ], "type": "object", "properties": { "fullName": { "type": "string" }, "email": { "type": [ "null", "string" ] }, "legalForm": { "type": [ "null", "string" ] }, "sector": { "type": [ "null", "string" ] }, "companyNumber": { "type": [ "null", "string" ] }, "priceId": { "type": [ "null", "string" ] }, "successUrl": { "type": [ "null", "string" ] }, "cancelUrl": { "type": [ "null", "string" ] } } }, "SendEmailRequest": { "required": [ "subject", "htmlBody", "recipients", "kind" ], "type": "object", "properties": { "subject": { "type": "string" }, "htmlBody": { "type": "string" }, "recipients": { "type": "array", "items": { "type": "string" } }, "kind": { "type": [ "null", "string" ] } } }, "SetFeaturePreferenceRequest": { "required": [ "enabled" ], "type": "object", "properties": { "enabled": { "type": "boolean" } } }, "SubmitVatReturnRequest": { "required": [ "vatRegistrationNumber", "declarationAccepted" ], "type": "object", "properties": { "vatRegistrationNumber": { "type": "string" }, "declarationAccepted": { "type": "boolean" } } }, "SyncRequest": { "required": [ "from", "to" ], "type": "object", "properties": { "from": { "type": "string", "format": "date" }, "to": { "type": "string", "format": "date" } } }, "VatTreatment": { "enum": [ "Standard", "Reduced", "Zero", "Exempt", "OutsideScope", "ReverseCharge" ] } } }, "tags": [ { "name": "Reconciliation" }, { "name": "Reporting" }, { "name": "Tenant" }, { "name": "Billing" }, { "name": "Ledger" }, { "name": "Invoicing" }, { "name": "Platform" }, { "name": "Tax / MTD" }, { "name": "Excel feed" } ] }