{ "openapi": "3.1.0", "info": { "title": "Financial IQ Financial Data API v1", "version": "v1-2026-07", "summary": "Implementation contract for the current versioned Financial IQ API routes.", "description": "This contract intentionally covers only currently implemented v1 routes. Future business, personal, agent and webhook routes should be added here only after the implementation and tests exist." }, "servers": [ { "url": "https://api.financialiq.co.uk", "description": "Public production API gateway; DNS and TLS are verified" }, { "url": "https://business.financialiq.co.uk", "description": "Compatibility gateway retained for existing controlled users" }, { "url": "https://{project_ref}.supabase.co/functions/v1/financial-data-api", "description": "Current Supabase Edge Function transition path", "variables": { "project_ref": { "default": "PROJECT_REF", "description": "Supabase project reference" } } } ], "tags": [ { "name": "Agent", "description": "Agent-facing discovery, safety and contract routes." }, { "name": "Business", "description": "Business company discovery and company-scoped resources." }, { "name": "Invoices", "description": "Versioned invoice actions safe for agent use." }, { "name": "Evidence", "description": "Read-only evidence bundles for explaining ledger resources." }, { "name": "Personal", "description": "User-authorised personal finance routes. API keys cannot access these routes." } ], "paths": { "/v1/agent/capabilities": { "get": { "tags": [ "Agent" ], "operationId": "getAgentCapabilities", "summary": "Get agent capability manifest", "description": "Returns a read-only capability manifest for agents, including auth modes, current API-key permission shape, capability groups, approval boundaries, blocked high-risk actions and links to the machine-readable OpenAPI contract. This route does not inspect company records, create records, approve actions, file returns, mutate providers or move money.", "security": [ { "ApiKeyAuth": [] } ], "parameters": [ { "$ref": "#/components/parameters/RequestId" } ], "responses": { "200": { "description": "Agent capability manifest returned.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "data", "meta" ], "properties": { "data": { "type": "object", "required": [ "object", "api_version", "current_connection", "machine_readable_contract", "capability_groups", "safety_boundaries", "blocked_actions" ], "properties": { "object": { "type": "string", "const": "agent_capability_manifest" }, "api_version": { "type": "string", "const": "v1-2026-07" }, "current_connection": { "type": "object", "additionalProperties": true }, "machine_readable_contract": { "type": "object", "required": [ "openapi_path", "docs_path", "safety_extension" ], "properties": { "openapi_path": { "type": "string", "const": "/api/financial-data-api-v1.openapi.json" }, "docs_path": { "type": "string", "const": "/api/financial-data-api-v1.md" }, "safety_extension": { "type": "string", "const": "x-financial-iq-safety" }, "note": { "type": "string" } } }, "capability_groups": { "type": "array", "items": { "type": "object", "additionalProperties": true } }, "safety_boundaries": { "type": "array", "items": { "type": "string" } }, "blocked_actions": { "type": "array", "items": { "type": "object", "additionalProperties": true } } } }, "meta": { "$ref": "#/components/schemas/V1Meta" } } } } } }, "401": { "description": "Missing, invalid, expired or inactive API key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LegacyErrorResponse" } } } }, "405": { "description": "Only GET is supported.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1ErrorResponse" } } } } }, "x-financial-iq-safety": { "auditedEndpoint": "v1/business/companies/{company_id}/dividend-declarations", "requiresApiKey": true, "scope": "agent.capabilities.read", "businessMutation": false, "directFinancialMutation": false, "writeLevel": "read", "requiresIdempotencyKey": false, "auditedEndpoint": "v1/agent/capabilities", "doesNot": [ "create_records", "approve_actions", "file_tax_returns", "mutate_external_providers", "move_money", "return_secrets" ] }, "x-implementation": { "edgeFunction": "supabase/functions/financial-data-api/index.ts", "handler": "handleV1AgentCapabilities", "tests": [ "supabase/functions/financial-data-api/invoice_idempotency.test.ts", "supabase/functions/financial-data-api/v1_openapi_contract.test.ts" ] } } }, "/v1/agent/mcp-tools": { "get": { "tags": [ "Agent" ], "operationId": "getAgentMcpTools", "summary": "Get MCP-style agent tool descriptors", "description": "Returns descriptor-only MCP-style tool metadata for the implemented Financial IQ HTTP API surface, including tool names, route patterns, input schema hints, required API-key permissions or personal OAuth scopes, approval flags and safety boundaries. This route does not execute tools, inspect company books, create records, approve actions, issue tokens, file returns, mutate external providers, move money or return secrets.", "security": [ { "ApiKeyAuth": [] } ], "parameters": [ { "$ref": "#/components/parameters/RequestId" } ], "responses": { "200": { "description": "MCP-style tool descriptor catalogue returned.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "data", "meta" ], "properties": { "data": { "type": "object", "required": [ "object", "api_version", "protocol", "transport", "tool_count", "tools", "safety_boundaries", "blocked_actions" ], "properties": { "object": { "type": "string", "const": "agent_mcp_tool_descriptor_catalogue" }, "api_version": { "type": "string", "const": "v1-2026-07" }, "protocol": { "type": "object", "required": [ "style", "execution" ], "properties": { "style": { "type": "string", "const": "mcp_tool_descriptors" }, "execution": { "type": "string", "const": "not_implemented_in_v1" }, "summary": { "type": "string" } }, "additionalProperties": true }, "transport": { "type": "object", "additionalProperties": true }, "tool_count": { "type": "integer", "minimum": 0 }, "tools": { "type": "array", "items": { "type": "object", "required": [ "name", "title", "description", "surface", "auth_mode", "endpoint_patterns", "input_schema", "write_level", "requires_approval", "requires_idempotency_key", "current_key_access", "safety" ], "properties": { "name": { "type": "string" }, "title": { "type": "string" }, "description": { "type": "string" }, "surface": { "type": "string", "enum": [ "business", "personal", "webhooks", "system" ] }, "auth_mode": { "type": "string", "enum": [ "api_key", "user_oauth" ] }, "endpoint_patterns": { "type": "array", "items": { "type": "string" } }, "input_schema": { "type": "object", "additionalProperties": true }, "required_all_permissions": { "type": "array", "items": { "type": "string" } }, "required_any_permissions": { "type": "array", "items": { "type": "string" } }, "required_scopes": { "type": "array", "items": { "type": "string" } }, "write_level": { "type": "string" }, "requires_approval": { "type": "boolean" }, "requires_idempotency_key": { "type": "boolean" }, "current_key_access": { "type": "object", "additionalProperties": true }, "safety": { "type": "object", "additionalProperties": true } }, "additionalProperties": true } }, "safety_boundaries": { "type": "array", "items": { "type": "string" } }, "blocked_actions": { "type": "array", "items": { "type": "object", "additionalProperties": true } } } }, "meta": { "$ref": "#/components/schemas/V1Meta" } } } } } }, "401": { "description": "Missing, invalid, expired or inactive API key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LegacyErrorResponse" } } } }, "405": { "description": "Only GET is supported.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1ErrorResponse" } } } } }, "x-financial-iq-safety": { "requiresApiKey": true, "scope": "agent.mcp_tools.read", "businessMutation": false, "directFinancialMutation": false, "writeLevel": "read", "requiresIdempotencyKey": false, "auditedEndpoint": "v1/agent/mcp-tools", "doesNot": [ "execute_tools", "issue_tokens", "grant_consent", "create_records", "approve_actions", "file_tax_returns", "mutate_external_providers", "move_money", "return_secrets" ] }, "x-implementation": { "edgeFunction": "supabase/functions/financial-data-api/index.ts", "handler": "handleV1AgentMcpTools", "tests": [ "supabase/functions/financial-data-api/invoice_idempotency.test.ts", "supabase/functions/financial-data-api/v1_openapi_contract.test.ts" ] } } }, "/v1/agent/mcp": { "post": { "tags": ["Agent"], "operationId": "executeAgentMcpRequest", "summary": "Execute a guarded MCP request", "description": "MCP-compatible JSON-RPC transport for one allowlisted Financial IQ API request tool. Business calls use the supplied API key; personal and platform-admin calls use the supplied user-authorised bearer token. The underlying v1 route still enforces its normal permissions, consent scopes, idempotency, company boundaries and approval gates.", "security": [{"ApiKeyAuth": []}, {"BearerAuth": []}], "parameters": [{"$ref": "#/components/parameters/RequestId"}], "requestBody": {"required": true, "content": {"application/json": {"schema": {"type": "object", "additionalProperties": true}}}}, "responses": { "200": {"description": "MCP JSON-RPC response."}, "400": {"description": "Invalid JSON or MCP request."}, "401": {"description": "Missing or invalid business API key or personal bearer token. Without an API key, every MCP method (initialize and tools/list included) needs a valid bearer token, and the 401 carries WWW-Authenticate: Bearer resource_metadata=\"https://api.financialiq.co.uk/.well-known/oauth-protected-resource/v1/agent/mcp\" so an MCP client can start OAuth."}, "405": {"description": "Only POST is supported."} }, "x-financial-iq-safety": { "requiresApiKey": false, "requiresUserBearerToken": false, "scope": "agent.mcp.execute", "businessMutation": true, "directFinancialMutation": false, "writeLevel": "delegated_to_v1_route", "requiresIdempotencyKey": false, "auditedEndpoint": "v1/agent/mcp", "doesNot": ["bypass_route_authorization", "bypass_consent_scopes", "bypass_idempotency", "move_money_unless_future_route_allows_it", "return_secrets"] }, "x-implementation": { "edgeFunction": "supabase/functions/financial-data-api/index.ts", "handler": "handleV1AgentMcp", "tests": ["supabase/functions/financial-data-api/invoice_idempotency.test.ts", "supabase/functions/financial-data-api/v1_openapi_contract.test.ts"] } } }, "/v1/admin/test-entities/{company_id}/hard-delete": {"post":{"tags":["Agent"],"operationId":"hardDeleteAdminTestEntity","summary":"Permanently delete a disposable test entity","description":"Irreversibly deletes one disposable test or failed-import company through the platform-admin override. Requires a live signed-in platform-admin session, an idempotency key, explicit test-data acknowledgement, the exact entity name, the fixed PERMANENTLY DELETE phrase and an approved fixed reason. Ordinary API keys and personal API access tokens cannot call this route.","security":[{"UserSessionBearerAuth":[]}],"parameters":[{"name":"company_id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}},{"$ref":"#/components/parameters/IdempotencyKey"},{"$ref":"#/components/parameters/RequestId"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"required":["confirmation_name","confirmation_phrase","purge_reason","test_data_acknowledged"],"properties":{"confirmation_name":{"type":"string","minLength":1,"maxLength":200,"description":"Exact current entity name."},"confirmation_phrase":{"type":"string","const":"PERMANENTLY DELETE"},"purge_reason":{"type":"string","enum":["test_setup","failed_import","duplicate_test_entity"]},"test_data_acknowledged":{"type":"boolean","const":true}}}}}},"responses":{"200":{"description":"The disposable test entity and its company-scoped data were permanently deleted; a metadata-only purge receipt remains.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/V1MetaEnvelope"}}}},"400":{"description":"Invalid identifier, idempotency key or destructive confirmation.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/V1ErrorResponse"}}}},"401":{"description":"Missing or invalid signed-in user token.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/V1ErrorResponse"}}}},"403":{"description":"The signed-in user is not a platform administrator, or a personal/API key credential was used.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/V1ErrorResponse"}}}},"409":{"description":"The entity is ineligible, including the protected accounting-firm entity.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/V1ErrorResponse"}}}},"500":{"description":"The purge did not complete.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/V1ErrorResponse"}}}},"502":{"description":"The canonical lifecycle service could not be reached.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/V1ErrorResponse"}}}}},"x-financial-iq-safety":{"requiresApiKey":false,"requiresUserBearerToken":true,"scope":"admin.test_entity_purge","businessMutation":true,"directFinancialMutation":true,"providerMutation":false,"writeLevel":"irreversible_test_data_deletion","requiresIdempotencyKey":true,"approvalRequired":true,"destructive":true,"irreversible":true,"auditedEndpoint":"v1/admin/test-entities/{company_id}/hard-delete","returnsSecrets":false,"doesNot":["accept_api_keys","accept_personal_access_tokens","bypass_platform_admin_check","delete_accounting_firm","accept_free_form_audit_reasons","alter_normal_retention_lifecycle","move_money","file_tax_returns","mutate_external_providers","return_secrets"]},"x-implementation":{"edgeFunction":"supabase/functions/financial-data-api/index.ts","handler":"handleV1AdminTestEntityHardDelete","tests":["supabase/functions/financial-data-api/v1_admin_test_purge_contract.test.ts","src/services/__tests__/agentTestEntityPurgeBoundary.test.ts"]}}}, "/v1/auth/scopes": { "get": { "tags": [ "Agent" ], "operationId": "getAuthScopes", "summary": "Get supported API permissions and OAuth consent scopes", "description": "Returns a read-only catalogue of the business API-key permissions and personal OAuth consent scopes currently enforced by v1. This route helps agents and developers plan permission requests, but it does not issue API keys, bearer tokens, refresh tokens, consent grants, records, filings, provider mutations or payments.", "security": [ { "ApiKeyAuth": [] } ], "parameters": [ { "$ref": "#/components/parameters/RequestId" } ], "responses": { "200": { "description": "Supported permission and consent scope catalogue returned.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "data", "meta" ], "properties": { "data": { "type": "object", "required": [ "object", "api_version", "business_api_key_permissions", "personal_oauth_scopes", "personal_composite_requirements", "consent_model", "safety_boundaries" ], "properties": { "object": { "type": "string", "const": "auth_scope_catalogue" }, "api_version": { "type": "string", "const": "v1-2026-07" }, "current_connection": { "type": "object", "additionalProperties": true }, "business_api_key_permissions": { "type": "array", "items": { "type": "object", "additionalProperties": true } }, "personal_oauth_scopes": { "type": "array", "items": { "type": "object", "additionalProperties": true } }, "personal_composite_requirements": { "type": "array", "items": { "type": "object", "additionalProperties": true } }, "consent_model": { "type": "object", "additionalProperties": true }, "safety_boundaries": { "type": "array", "items": { "type": "string" } } } }, "meta": { "$ref": "#/components/schemas/V1Meta" } } } } } }, "401": { "description": "Missing, invalid, expired or inactive API key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LegacyErrorResponse" } } } }, "405": { "description": "Only GET is supported.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1ErrorResponse" } } } } }, "x-financial-iq-safety": { "requiresApiKey": true, "scope": "auth.scopes.read", "businessMutation": false, "directFinancialMutation": false, "writeLevel": "read", "requiresIdempotencyKey": false, "auditedEndpoint": "v1/auth/scopes", "doesNot": [ "issue_tokens", "grant_consent", "create_api_keys", "create_records", "mutate_business_books", "mutate_personal_records", "file_tax_returns", "mutate_external_providers", "move_money", "return_secrets" ] }, "x-implementation": { "edgeFunction": "supabase/functions/financial-data-api/index.ts", "handler": "handleV1AuthScopes", "tests": [ "supabase/functions/financial-data-api/invoice_idempotency.test.ts", "supabase/functions/financial-data-api/v1_openapi_contract.test.ts" ] } } }, "/v1/auth/api-keys": {"post":{"tags":["Agent"],"operationId":"createBusinessApiKey","summary":"Create a company-scoped business API key","description":"Creates a non-master business API key for an authorised signed-in company owner or administrator. The plaintext key is returned once and is never returned again.","security":[{"UserSessionBearerAuth":[]}],"parameters":[{"$ref":"#/components/parameters/RequestId"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"required":["company_id"],"properties":{"company_id":{"type":"string","format":"uuid"},"key_name":{"type":"string","maxLength":100},"permissions":{"type":"object","additionalProperties":{"type":"boolean"}},"expires_at":{"type":"string","format":"date-time"}}}}}},"responses":{"201":{"description":"Business API key created; plaintext key is returned once.","content":{"application/json":{"schema":{"type":"object","required":["data","meta"],"properties":{"data":{"type":"object","required":["api_key","warning"],"properties":{"api_key":{"type":"string"},"key_name":{"type":"string"},"permissions":{"type":"object"},"expires_at":{"type":["string","null"],"format":"date-time"},"warning":{"type":"string"}}},"meta":{"$ref":"#/components/schemas/V1Meta"}}}}}},"400":{"description":"Invalid request or idempotency key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/V1ErrorResponse"}}}},"401":{"description":"Missing or invalid signed-in user token.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/V1ErrorResponse"}}}},"403":{"description":"The user lacks API-key management authority.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/V1ErrorResponse"}}}},"500":{"description":"Key creation failed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/V1ErrorResponse"}}}}},"x-financial-iq-safety":{"requiresApiKey":false,"requiresUserBearerToken":true,"scope":"auth.business_api_keys.create","businessMutation":false,"directFinancialMutation":false,"providerMutation":false,"writeLevel":"credential_issuance","requiresIdempotencyKey":true,"auditedEndpoint":"v1/auth/api-keys","returnsSecrets":true,"doesNot":["create_master_api_keys","return_api_key_again","read_financial_records","mutate_business_books","file_tax_returns","mutate_external_providers","move_money"]},"x-implementation":{"edgeFunction":"supabase/functions/financial-data-api/index.ts","handler":"handleV1AuthApiKeyCreate","tests":["supabase/functions/financial-data-api/invoice_idempotency.test.ts"]}},"get":{"tags":["Agent"],"operationId":"listBusinessApiKeys","summary":"List safe business API key metadata","description":"Lists metadata for non-master business API keys created by the signed-in user. Raw API keys and hashes are never returned.","security":[{"UserSessionBearerAuth":[]}],"parameters":[{"$ref":"#/components/parameters/RequestId"}],"responses":{"200":{"description":"Safe business API key metadata list.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/V1MetaEnvelope"}}}},"401":{"description":"Missing or invalid signed-in user token.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/V1ErrorResponse"}}}},"405":{"description":"Only GET is supported.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/V1ErrorResponse"}}}}},"x-financial-iq-safety":{"requiresApiKey":false,"requiresUserBearerToken":true,"scope":"auth.business_api_keys.read","businessMutation":false,"directFinancialMutation":false,"providerMutation":false,"writeLevel":"read","requiresIdempotencyKey":false,"auditedEndpoint":"v1/auth/api-keys","doesNot":["return_raw_api_keys","return_api_key_hashes","create_master_api_keys","read_financial_records","mutate_business_books","move_money"]},"x-implementation":{"edgeFunction":"supabase/functions/financial-data-api/index.ts","handler":"handleV1AuthApiKeysList","tests":["supabase/functions/financial-data-api/invoice_idempotency.test.ts"]}}}, "/v1/auth/api-keys/{api_key_id}": {"delete":{"tags":["Agent"],"operationId":"revokeBusinessApiKey","summary":"Revoke a business API key","description":"Soft-revokes a non-master business API key created by the signed-in user. The key record remains available as safe metadata.","security":[{"UserSessionBearerAuth":[]}],"parameters":[{"name":"api_key_id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}},{"$ref":"#/components/parameters/RequestId"}],"responses":{"200":{"description":"Business API key revoked.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/V1MetaEnvelope"}}}},"400":{"description":"Invalid API key id or idempotency key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/V1ErrorResponse"}}}},"401":{"description":"Missing or invalid signed-in user token.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/V1ErrorResponse"}}}},"404":{"description":"Business API key not found.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/V1ErrorResponse"}}}},"500":{"description":"Key revocation failed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/V1ErrorResponse"}}}}},"x-financial-iq-safety":{"requiresApiKey":false,"requiresUserBearerToken":true,"scope":"auth.business_api_keys.revoke","businessMutation":false,"directFinancialMutation":false,"providerMutation":false,"writeLevel":"credential_revocation","requiresIdempotencyKey":true,"auditedEndpoint":"v1/auth/api-keys/{api_key_id}","doesNot":["return_raw_api_keys","return_api_key_hashes","create_master_api_keys","read_financial_records","mutate_business_books","move_money"]},"x-implementation":{"edgeFunction":"supabase/functions/financial-data-api/index.ts","handler":"handleV1AuthApiKeyRevoke","tests":["supabase/functions/financial-data-api/invoice_idempotency.test.ts"]}}}, "/v1/auth/api-keys/{api_key_id}/rotate": {"post":{"tags":["Agent"],"operationId":"rotateBusinessApiKey","summary":"Rotate a business API key","description":"Issues a replacement for a user-owned non-master business API key and disables the old key atomically. The replacement plaintext key is returned once.","security":[{"UserSessionBearerAuth":[]}],"parameters":[{"name":"api_key_id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}},{"$ref":"#/components/parameters/RequestId"}],"requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"properties":{"key_name":{"type":"string","maxLength":100},"permissions":{"type":"object","additionalProperties":{"type":"boolean"}},"expires_at":{"type":"string","format":"date-time"}}}}}},"responses":{"201":{"description":"Business API key rotated; replacement plaintext key is returned once.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/V1MetaEnvelope"}}}},"400":{"description":"Invalid request or idempotency key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/V1ErrorResponse"}}}},"401":{"description":"Missing or invalid signed-in user token.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/V1ErrorResponse"}}}},"403":{"description":"The user lacks authority to rotate this key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/V1ErrorResponse"}}}},"404":{"description":"Business API key not found.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/V1ErrorResponse"}}}},"500":{"description":"Key rotation failed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/V1ErrorResponse"}}}}},"x-financial-iq-safety":{"requiresApiKey":false,"requiresUserBearerToken":true,"scope":"auth.business_api_keys.rotate","businessMutation":false,"directFinancialMutation":false,"providerMutation":false,"writeLevel":"credential_rotation","requiresIdempotencyKey":true,"auditedEndpoint":"v1/auth/api-keys/{api_key_id}/rotate","returnsSecrets":true,"doesNot":["return_old_api_key_again","return_api_key_hashes","create_master_api_keys","read_financial_records","mutate_business_books","file_tax_returns","mutate_external_providers","move_money"]},"x-implementation":{"edgeFunction":"supabase/functions/financial-data-api/index.ts","handler":"handleV1AuthApiKeyRotate","tests":["supabase/functions/financial-data-api/invoice_idempotency.test.ts"]}}}, "/v1/auth/consent-requests/preview": { "post": { "tags": [ "Agent" ], "operationId": "previewPersonalConsentRequest", "summary": "Preview a personal OAuth consent request", "description": "Validates requested personal OAuth scopes and returns a user-facing consent preview package for agents and applications. This route does not create a consent grant, issue bearer tokens, issue refresh tokens, create API keys, read personal finance records, mutate business books, move money, file returns or mutate external providers.", "security": [ { "ApiKeyAuth": [] } ], "parameters": [ { "$ref": "#/components/parameters/RequestId" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "requested_scopes" ], "properties": { "client_name": { "type": "string", "maxLength": 120, "description": "Display name to show on the consent screen." }, "purpose": { "type": "string", "maxLength": 280, "description": "Short explanation of why the app is requesting access." }, "redirect_uri": { "type": "string", "format": "uri", "maxLength": 2048, "description": "Future OAuth callback URI. Must be HTTPS, except HTTP localhost is accepted for development previews." }, "requested_scopes": { "type": "array", "minItems": 1, "maxItems": 24, "items": { "type": "string" }, "description": "Personal OAuth scopes from GET /v1/auth/scopes." }, "state": { "type": "string", "maxLength": 512, "description": "Opaque caller state. Presence is reported, but the value is not needed to create this preview." } }, "additionalProperties": false } } } }, "responses": { "200": { "description": "Consent preview returned. No grant or token has been created.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "data", "meta" ], "properties": { "data": { "type": "object", "required": [ "object", "api_version", "status", "requested_scopes", "consent_screen", "oauth", "safety_boundaries" ], "properties": { "object": { "type": "string", "const": "personal_consent_request_preview" }, "api_version": { "type": "string", "const": "v1-2026-07" }, "status": { "type": "string", "const": "preview_only" }, "current_connection": { "type": "object", "additionalProperties": true }, "requested_client": { "type": "object", "additionalProperties": true }, "requested_scopes": { "type": "array", "items": { "type": "string" } }, "consent_screen": { "type": "object", "additionalProperties": true }, "oauth": { "type": "object", "required": [ "consent_request_created", "consent_url", "user_authorisation_required", "token_issuing", "refresh_tokens" ], "properties": { "consent_request_created": { "type": "boolean", "const": false }, "consent_url": { "type": "null" }, "user_authorisation_required": { "type": "boolean", "const": true }, "token_issuing": { "type": "string", "const": "available_after_user_approval" }, "refresh_tokens": { "type": "string", "const": "available_after_user_approval" } } }, "safety_boundaries": { "type": "array", "items": { "type": "string" } } } }, "meta": { "$ref": "#/components/schemas/V1Meta" } } } } } }, "400": { "description": "Invalid preview request or unsupported scope.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1ErrorResponse" } } } }, "401": { "description": "Missing, invalid, expired or inactive API key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LegacyErrorResponse" } } } }, "405": { "description": "Only POST is supported.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1ErrorResponse" } } } } }, "x-financial-iq-safety": { "requiresApiKey": true, "scope": "auth.consent_requests.preview", "businessMutation": false, "directFinancialMutation": false, "writeLevel": "read", "requiresIdempotencyKey": false, "auditedEndpoint": "v1/auth/consent-requests/preview", "doesNot": [ "issue_tokens", "grant_consent", "create_api_keys", "create_records", "read_personal_records", "mutate_business_books", "mutate_personal_records", "file_tax_returns", "mutate_external_providers", "move_money", "return_secrets" ] }, "x-implementation": { "edgeFunction": "supabase/functions/financial-data-api/index.ts", "handler": "handleV1AuthConsentRequestPreview", "tests": [ "supabase/functions/financial-data-api/invoice_idempotency.test.ts", "supabase/functions/financial-data-api/v1_openapi_contract.test.ts" ] } } }, "/v1/auth/consent-requests": { "post": { "tags": [ "Agent" ], "operationId": "createPersonalConsentRequest", "summary": "Create a pending personal OAuth consent request", "description": "Creates a durable pending personal OAuth consent request from supported personal scopes. This route stores a request for future user approval, but it does not grant consent, issue bearer tokens, issue refresh tokens, create API keys, read personal finance records, mutate business books, move money, file returns or mutate external providers.", "security": [ { "ApiKeyAuth": [] } ], "parameters": [ { "$ref": "#/components/parameters/RequestId" }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "requested_scopes" ], "properties": { "client_name": { "type": "string", "maxLength": 120, "description": "Display name to show on the consent screen." }, "purpose": { "type": "string", "maxLength": 280, "description": "Short explanation of why the app is requesting access." }, "redirect_uri": { "type": "string", "format": "uri", "maxLength": 2048, "description": "Future OAuth callback URI. Must be HTTPS, except HTTP localhost is accepted for development previews." }, "requested_scopes": { "type": "array", "minItems": 1, "maxItems": 24, "items": { "type": "string" }, "description": "Personal OAuth scopes from GET /v1/auth/scopes." }, "state": { "type": "string", "maxLength": 512, "description": "Opaque caller state. The raw value is not stored; only its presence and hash are retained." } }, "additionalProperties": false } } } }, "responses": { "200": { "description": "Existing pending consent request replayed for the same Idempotency-Key and body.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" }, "X-FIQ-Idempotency-Replayed": { "$ref": "#/components/headers/IdempotencyReplayed" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PersonalConsentRequestResponse" } } } }, "201": { "description": "Pending consent request created. No grant or token has been created.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PersonalConsentRequestResponse" } } } }, "400": { "description": "Invalid request, unsupported scope or missing Idempotency-Key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1ErrorResponse" } } } }, "401": { "description": "Missing, invalid, expired or inactive API key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LegacyErrorResponse" } } } }, "405": { "description": "Only POST is supported.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1ErrorResponse" } } } }, "409": { "description": "Idempotency key conflict.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1ErrorResponse" } } } } }, "x-financial-iq-safety": { "requiresApiKey": true, "scope": "auth.consent_requests.create", "businessMutation": false, "directFinancialMutation": false, "writeLevel": "auth_request", "requiresIdempotencyKey": true, "auditedEndpoint": "v1/auth/consent-requests", "doesNot": [ "issue_tokens", "grant_consent", "create_api_keys", "read_personal_records", "mutate_business_books", "mutate_personal_records", "file_tax_returns", "mutate_external_providers", "move_money", "return_secrets" ] }, "x-implementation": { "edgeFunction": "supabase/functions/financial-data-api/index.ts", "handler": "handleV1AuthConsentRequests", "tests": [ "supabase/functions/financial-data-api/invoice_idempotency.test.ts", "supabase/functions/financial-data-api/v1_openapi_contract.test.ts" ] } } }, "/v1/auth/consent-requests/{consent_request_id}": { "get": { "tags": [ "Agent" ], "operationId": "getPersonalConsentRequest", "summary": "Get a pending personal OAuth consent request", "description": "Returns one personal OAuth consent request created by the current API key. This route is read-only and does not grant consent, issue bearer tokens, issue refresh tokens, read personal finance records, mutate business books, move money, file returns or mutate external providers.", "security": [ { "ApiKeyAuth": [] } ], "parameters": [ { "$ref": "#/components/parameters/RequestId" }, { "name": "consent_request_id", "in": "path", "required": true, "description": "Pending personal consent request id.", "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Pending consent request returned.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PersonalConsentRequestResponse" } } } }, "400": { "description": "Invalid consent request id.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1ErrorResponse" } } } }, "401": { "description": "Missing, invalid, expired or inactive API key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LegacyErrorResponse" } } } }, "404": { "description": "No consent request visible to this API key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1ErrorResponse" } } } }, "405": { "description": "Only GET is supported.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1ErrorResponse" } } } } }, "x-financial-iq-safety": { "requiresApiKey": true, "scope": "auth.consent_requests.read", "businessMutation": false, "directFinancialMutation": false, "writeLevel": "read", "requiresIdempotencyKey": false, "auditedEndpoint": "v1/auth/consent-requests/{consent_request_id}", "doesNot": [ "issue_tokens", "grant_consent", "create_api_keys", "read_personal_records", "mutate_business_books", "mutate_personal_records", "file_tax_returns", "mutate_external_providers", "move_money", "return_secrets" ] }, "x-implementation": { "edgeFunction": "supabase/functions/financial-data-api/index.ts", "handler": "handleV1AuthConsentRequestDetail", "tests": [ "supabase/functions/financial-data-api/invoice_idempotency.test.ts", "supabase/functions/financial-data-api/v1_openapi_contract.test.ts" ] } } }, "/v1/auth/consent-requests/{consent_request_id}/approve": { "post": { "tags": [ "Agent" ], "operationId": "approvePersonalConsentRequest", "summary": "Approve a personal consent request with a one-time code for the app", "description": "Approves one pending personal consent request as the signed-in person. It never returns a token to the person approving. The body must repeat the app's redirect_uri and state exactly (when the request had them) and may narrow scopes to some of those requested (a write scope needs its read scope). The response carries redirect_to: the app's redirect with a one-time fiq_cod_ code (5 minutes) and the state. The app redeems the code with POST /v1/auth/consent-requests/{consent_request_id}/token using the same x-api-key, which issues the access token and a rotating refresh token; the grant lasts 90 days from approval and refreshing never extends it. POST /v1/auth/consent-requests/{consent_request_id}/deny declines and returns redirect_to with error=access_denied.", "security": [ { "UserSessionBearerAuth": [] } ], "parameters": [ { "$ref": "#/components/parameters/RequestId" }, { "name": "consent_request_id", "in": "path", "required": true, "description": "Pending personal consent request id to approve.", "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Consent approved. redirect_to carries the one-time code to the app's redirect; no token is returned.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PersonalAccessTokenResponse" } } } }, "400": { "description": "Invalid consent request id.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1ErrorResponse" } } } }, "401": { "description": "Missing, invalid or expired signed-in user token.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1ErrorResponse" } } } }, "403": { "description": "A personal API access token attempted to approve a new consent request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1ErrorResponse" } } } }, "404": { "description": "Consent request not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1ErrorResponse" } } } }, "405": { "description": "Only POST is supported.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1ErrorResponse" } } } }, "409": { "description": "Consent request is no longer pending or already issued a token.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1ErrorResponse" } } } }, "410": { "description": "Consent request has expired.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1ErrorResponse" } } } } }, "x-financial-iq-safety": { "requiresApiKey": false, "requiresUserBearerToken": true, "scope": "auth.consent_requests.approve", "businessMutation": false, "directFinancialMutation": false, "writeLevel": "auth_grant", "requiresIdempotencyKey": false, "auditedEndpoint": "v1/auth/consent-requests/{consent_request_id}/approve", "doesNot": [ "store_raw_tokens", "create_api_keys", "read_personal_records", "mutate_business_books", "mutate_personal_records", "file_tax_returns", "mutate_external_providers", "move_money" ] }, "x-implementation": { "edgeFunction": "supabase/functions/financial-data-api/index.ts", "handler": "handleV1AuthConsentRequestApprove", "tests": [ "supabase/functions/financial-data-api/invoice_idempotency.test.ts", "supabase/functions/financial-data-api/v1_openapi_contract.test.ts" ] } } }, "/v1/auth/personal-access-tokens": { "get": { "tags": [ "Agent" ], "operationId": "listPersonalAccessTokens", "summary": "List personal API access token records for the signed-in user", "description": "Lists safe metadata for personal API access tokens approved by the signed-in user. Raw access tokens, raw refresh tokens and token hashes are never returned.", "security": [ { "UserSessionBearerAuth": [] } ], "parameters": [ { "$ref": "#/components/parameters/RequestId" } ], "responses": { "200": { "description": "Safe personal API token metadata list.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PersonalAccessTokenListResponse" } } } }, "401": { "description": "Missing, invalid or expired signed-in user token.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1ErrorResponse" } } } }, "403": { "description": "A personal API access token attempted to manage token records.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1ErrorResponse" } } } }, "405": { "description": "Only GET is supported.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1ErrorResponse" } } } } }, "x-financial-iq-safety": { "requiresApiKey": false, "requiresUserBearerToken": true, "scope": "auth.personal_access_tokens.read", "businessMutation": false, "directFinancialMutation": false, "writeLevel": "read", "requiresIdempotencyKey": false, "auditedEndpoint": "v1/auth/personal-access-tokens", "doesNot": [ "return_raw_tokens", "return_token_hashes", "create_api_keys", "read_personal_records", "mutate_business_books", "mutate_personal_records", "file_tax_returns", "mutate_external_providers", "move_money" ] }, "x-implementation": { "edgeFunction": "supabase/functions/financial-data-api/index.ts", "handler": "handleV1AuthPersonalAccessTokensList", "tests": [ "supabase/functions/financial-data-api/invoice_idempotency.test.ts", "supabase/functions/financial-data-api/v1_openapi_contract.test.ts" ] } }, "post": { "tags": [ "Agent" ], "operationId": "createPersonalAccessToken", "summary": "Create a personal API access token for the signed-in user", "description": "Issues a fiq_usr_ personal API token that the signed-in person gives to their own tool (for example Claude Code). Requires a signed-in user session and the Personal API. Scopes must come from the personal scope catalogue and every write scope needs its read scope. Expiry is 30, 90 (default) or 365 days; at most 25 self-issued tokens can be active at once. The raw token is returned once with Cache-Control: no-store; Financial IQ stores only its SHA-256 hash and last four characters. Self-issued tokens have no refresh token.", "security": [ { "UserSessionBearerAuth": [] } ], "parameters": [ { "$ref": "#/components/parameters/RequestId" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "name", "scopes" ], "additionalProperties": false, "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 80 }, "scopes": { "type": "array", "minItems": 1, "maxItems": 24, "items": { "type": "string" } }, "expires_in_days": { "type": "integer", "enum": [ 30, 90, 365 ], "default": 90 } } } } } }, "responses": { "201": { "description": "Token created. The raw token is returned once.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "data", "meta" ], "properties": { "data": { "type": "object", "properties": { "object": { "type": "string", "enum": [ "personal_access_token" ] }, "id": { "type": "string", "format": "uuid" }, "name": { "type": "string" }, "source": { "type": "string", "enum": [ "self" ] }, "token": { "type": "object", "properties": { "access_token": { "type": "string" }, "token_type": { "type": "string", "enum": [ "Bearer" ] }, "expires_at": { "type": "string", "format": "date-time" } } }, "token_last4": { "type": "string" }, "granted_scopes": { "type": "array", "items": { "type": "string" } }, "expires_at": { "type": "string", "format": "date-time" } } }, "meta": { "type": "object" } } } } } }, "400": { "description": "Invalid name, scopes or expiry.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1ErrorResponse" } } } }, "401": { "description": "Missing, invalid or expired signed-in user token.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1ErrorResponse" } } } }, "403": { "description": "The person does not have the Personal API, or a personal API token tried to create another token.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1ErrorResponse" } } } }, "409": { "description": "25 self-issued tokens are already active.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1ErrorResponse" } } } }, "503": { "description": "The Personal API entitlement could not be confirmed; nothing was issued.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1ErrorResponse" } } } } }, "x-financial-iq-safety": { "requiresApiKey": false, "requiresUserBearerToken": true, "scope": "auth.personal_access_tokens.create", "businessMutation": false, "directFinancialMutation": false, "writeLevel": "auth_issue", "requiresIdempotencyKey": false, "auditedEndpoint": "v1/auth/personal-access-tokens", "doesNot": [ "store_raw_tokens", "create_api_keys", "read_personal_records", "mutate_business_books", "mutate_personal_records", "file_tax_returns", "mutate_external_providers", "move_money" ] }, "x-implementation": { "edgeFunction": "supabase/functions/financial-data-api/index.ts", "handler": "handleV1PersonalAccessTokenCreate", "tests": [ "supabase/functions/financial-data-api/personal_access_tokens_self_issue.test.ts", "supabase/functions/financial-data-api/v1_openapi_contract.test.ts" ] } } }, "/v1/auth/personal-access-tokens/refresh": { "post": { "tags": [ "Agent" ], "operationId": "refreshPersonalAccessToken", "summary": "Rotate a personal API access token", "description": "Rotates an existing user-approved personal API access token using its current raw refresh token. The old access token and refresh token are invalid after a successful refresh. Financial IQ stores only SHA-256 token hashes.", "security": [], "parameters": [ { "$ref": "#/components/parameters/RequestId" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PersonalAccessTokenRefreshRequest" } } } }, "responses": { "200": { "description": "Access token and refresh token rotated. Raw replacement tokens are returned once.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PersonalAccessTokenRefreshResponse" } } } }, "400": { "description": "Invalid JSON body or refresh token format.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1ErrorResponse" } } } }, "401": { "description": "Refresh token is invalid, expired, revoked or already rotated.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1ErrorResponse" } } } }, "405": { "description": "Only POST is supported.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1ErrorResponse" } } } }, "409": { "description": "Refresh token was already used during a concurrent rotation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1ErrorResponse" } } } } }, "x-financial-iq-safety": { "requiresApiKey": false, "requiresUserBearerToken": false, "scope": "auth.personal_access_tokens.refresh", "businessMutation": false, "directFinancialMutation": false, "writeLevel": "auth_refresh", "requiresIdempotencyKey": false, "auditedEndpoint": "v1/auth/personal-access-tokens/refresh", "doesNot": [ "store_raw_tokens", "create_api_keys", "read_personal_records", "mutate_business_books", "mutate_personal_records", "file_tax_returns", "mutate_external_providers", "move_money" ] }, "x-implementation": { "edgeFunction": "supabase/functions/financial-data-api/index.ts", "handler": "handleV1AuthPersonalAccessTokenRefresh", "tests": [ "supabase/functions/financial-data-api/invoice_idempotency.test.ts", "supabase/functions/financial-data-api/v1_openapi_contract.test.ts" ] } } }, "/v1/auth/personal-access-tokens/{token_id}": { "delete": { "tags": [ "Agent" ], "operationId": "revokePersonalAccessToken", "summary": "Revoke one personal API access token for the signed-in user", "description": "Soft revokes a personal API access token record owned by the signed-in user. The token history is retained and the raw token is never returned.", "security": [ { "UserSessionBearerAuth": [] } ], "parameters": [ { "$ref": "#/components/parameters/RequestId" }, { "name": "token_id", "in": "path", "required": true, "description": "Personal API access token record id to revoke.", "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Token revoked or already revoked.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PersonalAccessTokenLifecycleResponse" } } } }, "400": { "description": "Invalid token id.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1ErrorResponse" } } } }, "401": { "description": "Missing, invalid or expired signed-in user token.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1ErrorResponse" } } } }, "403": { "description": "A personal API access token attempted to revoke token records.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1ErrorResponse" } } } }, "404": { "description": "Token record not found for the signed-in user.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1ErrorResponse" } } } }, "405": { "description": "Only DELETE is supported.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1ErrorResponse" } } } } }, "x-financial-iq-safety": { "requiresApiKey": false, "requiresUserBearerToken": true, "scope": "auth.personal_access_tokens.revoke", "businessMutation": false, "directFinancialMutation": false, "writeLevel": "auth_revoke", "requiresIdempotencyKey": false, "auditedEndpoint": "v1/auth/personal-access-tokens/{token_id}", "doesNot": [ "delete_records", "return_raw_tokens", "return_token_hashes", "issue_refresh_tokens", "create_api_keys", "read_personal_records", "mutate_business_books", "mutate_personal_records", "file_tax_returns", "mutate_external_providers", "move_money" ] }, "x-implementation": { "edgeFunction": "supabase/functions/financial-data-api/index.ts", "handler": "handleV1AuthPersonalAccessTokenRevoke", "tests": [ "supabase/functions/financial-data-api/invoice_idempotency.test.ts", "supabase/functions/financial-data-api/v1_openapi_contract.test.ts" ] } } }, "/v1/business/companies": { "post": { "tags": [ "Business" ], "operationId": "createBusinessCompany", "summary": "Create an initialised business company", "description": "Creates a business company, owner membership, default chart of accounts, optional authorised firm linkage and audit evidence atomically. This operation is restricted to master API keys with company_management permission.", "security": [ { "ApiKeyAuth": [] } ], "parameters": [ { "$ref": "#/components/parameters/RequestId" }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1BusinessCompanyCreateRequest" } } } }, "responses": { "201": { "description": "Business company created and initialised.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1BusinessCompanyCreateResponse" } } } }, "400": { "description": "Invalid request body or missing Idempotency-Key.", "content": { "application/json": { "$ref": "#/components/schemas/V1ErrorEnvelope" } } }, "403": { "description": "The API key is not authorised for company management.", "content": { "application/json": { "$ref": "#/components/schemas/V1ErrorEnvelope" } } }, "409": { "description": "The request conflicts with an existing company or idempotency record.", "content": { "application/json": { "$ref": "#/components/schemas/V1ErrorEnvelope" } } }, "500": { "description": "Generic server failure.", "content": { "application/json": { "$ref": "#/components/schemas/V1ErrorEnvelope" } } } }, "x-financial-iq-safety": { "requiresApiKey": true, "scope": "business.company_management", "directFinancialMutation": true, "writeLevel": "tenant_onboarding", "requiresIdempotencyKey": true, "auditedEndpoint": "v1/business/companies" }, "x-implementation": { "edgeFunction": "supabase/functions/financial-data-api/index.ts", "handler": "handleV1BusinessCompanies", "tests": [ "supabase/functions/financial-data-api/invoice_idempotency.test.ts" ] } }, "get": { "tags": [ "Business" ], "operationId": "listBusinessCompanies", "summary": "List accessible business companies", "description": "Lists the business companies this API key can access. Standard keys return their single company. Master keys return only companies in their configured allowlist. This route is read-only and is intended as the discovery step before company-scoped calls.", "security": [ { "ApiKeyAuth": [] } ], "parameters": [ { "$ref": "#/components/parameters/RequestId" }, { "name": "limit", "in": "query", "required": false, "description": "Maximum number of companies to return. Values are clamped between 1 and 200.", "schema": { "type": "integer", "minimum": 1, "maximum": 200, "default": 100 } }, { "name": "offset", "in": "query", "required": false, "description": "Zero-based offset for paginating company discovery results.", "schema": { "type": "integer", "minimum": 0, "default": 0 } } ], "responses": { "200": { "description": "Accessible business companies returned.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1BusinessCompanyListResponse" } } } }, "401": { "description": "Missing, invalid, expired or inactive API key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LegacyErrorResponse" } } } }, "403": { "description": "The master API key has no configured company allowlist.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1ErrorEnvelope" } } } }, "405": { "description": "Only GET is allowed for this route.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1ErrorEnvelope" } } } }, "500": { "description": "Generic server failure. Internal database details must not be returned.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1ErrorEnvelope" } } } } }, "x-financial-iq-safety": { "requiresApiKey": true, "scope": "business.companies.read", "directFinancialMutation": false, "writeLevel": "read", "requiresIdempotencyKey": false, "auditedEndpoint": "v1/business/companies" }, "x-implementation": { "edgeFunction": "supabase/functions/financial-data-api/index.ts", "handler": "handleV1BusinessCompanies", "tests": [ "supabase/functions/financial-data-api/invoice_idempotency.test.ts" ] } } }, "/v1/business/companies/{company_id}": { "get": { "tags": [ "Business" ], "operationId": "getBusinessCompany", "summary": "Get one accessible business company", "description": "Returns one business company by id when the API key is allowed to access it. Inaccessible companies are returned as not found to avoid leaking tenant existence.", "security": [ { "ApiKeyAuth": [] } ], "parameters": [ { "name": "company_id", "in": "path", "required": true, "description": "Business company id to fetch.", "schema": { "type": "string", "format": "uuid" } }, { "$ref": "#/components/parameters/RequestId" } ], "responses": { "200": { "description": "Business company returned.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1BusinessCompanyResponse" } } } }, "400": { "description": "The company_id path parameter is not a valid UUID.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1ErrorEnvelope" } } } }, "401": { "description": "Missing, invalid, expired or inactive API key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LegacyErrorResponse" } } } }, "403": { "description": "The requested company is not in the master API key allowlist.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LegacyErrorResponse" } } } }, "404": { "description": "Business company not found.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1ErrorEnvelope" } } } }, "405": { "description": "Only GET is allowed for this route.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1ErrorEnvelope" } } } }, "500": { "description": "Generic server failure. Internal database details must not be returned.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1ErrorEnvelope" } } } } }, "x-financial-iq-safety": { "requiresApiKey": true, "scope": "business.companies.read", "directFinancialMutation": false, "writeLevel": "read", "requiresIdempotencyKey": false, "auditedEndpoint": "v1/business/companies/{company_id}" }, "x-implementation": { "edgeFunction": "supabase/functions/financial-data-api/index.ts", "handler": "handleV1BusinessCompanyDetail", "tests": [ "supabase/functions/financial-data-api/invoice_idempotency.test.ts" ] } } }, "/v1/business/companies/{company_id}/customers": { "get": { "tags": [ "Business" ], "operationId": "listBusinessCustomers", "summary": "List business customers", "description": "Lists customers for an accessible business company. This route is read-only and is intended to let agents find the customer_id needed for draft invoice creation.", "security": [ { "ApiKeyAuth": [] } ], "parameters": [ { "name": "company_id", "in": "path", "required": true, "description": "Business company id.", "schema": { "type": "string", "format": "uuid" } }, { "$ref": "#/components/parameters/RequestId" }, { "name": "search", "in": "query", "required": false, "description": "Optional case-insensitive name search.", "schema": { "type": "string", "minLength": 1, "maxLength": 200 } }, { "name": "q", "in": "query", "required": false, "description": "Alias for search.", "schema": { "type": "string", "minLength": 1, "maxLength": 200 } }, { "name": "limit", "in": "query", "required": false, "description": "Maximum number of customers to return. Values are clamped between 1 and 200.", "schema": { "type": "integer", "minimum": 1, "maximum": 200, "default": 100 } }, { "name": "offset", "in": "query", "required": false, "description": "Zero-based offset for paginating customer discovery results.", "schema": { "type": "integer", "minimum": 0, "default": 0 } } ], "responses": { "200": { "description": "Accessible business customers returned.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1BusinessCustomerListResponse" } } } }, "400": { "description": "The company_id path parameter is not a valid UUID.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1ErrorEnvelope" } } } }, "401": { "description": "Missing, invalid, expired or inactive API key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LegacyErrorResponse" } } } }, "403": { "description": "The API key does not have customer read permission, or the master key is not allowed to access the company.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1ErrorEnvelope" } } } }, "404": { "description": "Business company not found.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1ErrorEnvelope" } } } }, "405": { "description": "Only GET and POST are allowed for this route.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1ErrorEnvelope" } } } }, "500": { "description": "Generic server failure. Internal database details must not be returned.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1ErrorEnvelope" } } } } }, "x-financial-iq-safety": { "requiresApiKey": true, "scope": "business.customers.read", "requiredPermission": "customers", "directFinancialMutation": false, "writeLevel": "read", "requiresIdempotencyKey": false, "auditedEndpoint": "v1/business/companies/{company_id}/customers" }, "x-implementation": { "edgeFunction": "supabase/functions/financial-data-api/index.ts", "handler": "handleV1BusinessCustomers", "tests": [ "supabase/functions/financial-data-api/invoice_idempotency.test.ts" ] } }, "post": { "tags": [ "Business" ], "operationId": "createBusinessCustomer", "summary": "Create business customer", "description": "Creates a customer record for an accessible business company. This is a master-data write used by agents before creating draft invoices; it does not create or issue invoices.", "security": [ { "ApiKeyAuth": [] } ], "parameters": [ { "name": "company_id", "in": "path", "required": true, "description": "Business company id.", "schema": { "type": "string", "format": "uuid" } }, { "$ref": "#/components/parameters/RequestId" }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BusinessCustomerCreateRequest" } } } }, "responses": { "201": { "description": "Business customer created.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1BusinessCustomerCreateResponse" } } } }, "400": { "description": "The request body, idempotency key or company_id path parameter is invalid.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1ErrorEnvelope" } } } }, "401": { "description": "Missing, invalid, expired or inactive API key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LegacyErrorResponse" } } } }, "403": { "description": "The API key does not have customer permission.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1ErrorEnvelope" } } } }, "404": { "description": "Business company not found.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1ErrorEnvelope" } } } }, "405": { "description": "Only GET and POST are allowed for this route.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1ErrorEnvelope" } } } }, "409": { "description": "The idempotency key conflicts with a different request body.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1ErrorEnvelope" } } } }, "500": { "description": "Generic server failure. Internal database details must not be returned.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1ErrorEnvelope" } } } } }, "x-financial-iq-safety": { "requiresApiKey": true, "scope": "business.customers.create", "requiredPermission": "customers", "directFinancialMutation": false, "writeLevel": "configuration", "requiresIdempotencyKey": true, "auditedEndpoint": "v1/business/companies/{company_id}/customers" }, "x-implementation": { "edgeFunction": "supabase/functions/financial-data-api/index.ts", "handler": "createV1BusinessCustomer", "tests": [ "supabase/functions/financial-data-api/invoice_idempotency.test.ts" ] } } }, "/v1/business/companies/{company_id}/customers/{customer_id}": { "get": { "tags": [ "Business" ], "operationId": "getBusinessCustomer", "summary": "Get one business customer", "description": "Returns one customer for an accessible business company. Inaccessible customer IDs are returned as not found to avoid leaking tenant data.", "security": [ { "ApiKeyAuth": [] } ], "parameters": [ { "name": "company_id", "in": "path", "required": true, "description": "Business company id.", "schema": { "type": "string", "format": "uuid" } }, { "name": "customer_id", "in": "path", "required": true, "description": "Business customer id to fetch.", "schema": { "type": "string", "format": "uuid" } }, { "$ref": "#/components/parameters/RequestId" } ], "responses": { "200": { "description": "Business customer returned.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1BusinessCustomerResponse" } } } }, "400": { "description": "The company_id or customer_id path parameter is not a valid UUID.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1ErrorEnvelope" } } } }, "401": { "description": "Missing, invalid, expired or inactive API key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LegacyErrorResponse" } } } }, "403": { "description": "The API key does not have customer read permission, or the master key is not allowed to access the company.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1ErrorEnvelope" } } } }, "404": { "description": "Business customer not found.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1ErrorEnvelope" } } } }, "405": { "description": "Only GET and PATCH are allowed for this route.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1ErrorEnvelope" } } } }, "500": { "description": "Generic server failure. Internal database details must not be returned.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1ErrorEnvelope" } } } } }, "x-financial-iq-safety": { "requiresApiKey": true, "scope": "business.customers.read", "requiredPermission": "customers", "directFinancialMutation": false, "writeLevel": "read", "requiresIdempotencyKey": false, "auditedEndpoint": "v1/business/companies/{company_id}/customers/{customer_id}" }, "x-implementation": { "edgeFunction": "supabase/functions/financial-data-api/index.ts", "handler": "handleV1BusinessCustomerDetail", "tests": [ "supabase/functions/financial-data-api/invoice_idempotency.test.ts" ] } }, "patch": { "tags": [ "Business" ], "operationId": "updateBusinessCustomer", "summary": "Update business customer master data", "description": "Updates safe customer master data for an accessible business company. This route requires customer permission and an Idempotency-Key. It cannot move the customer to another company, create or issue invoices, change balances, post ledger entries, file tax returns, or move money.", "security": [ { "ApiKeyAuth": [] } ], "parameters": [ { "name": "company_id", "in": "path", "required": true, "description": "Business company id.", "schema": { "type": "string", "format": "uuid" } }, { "name": "customer_id", "in": "path", "required": true, "description": "Business customer id to fetch.", "schema": { "type": "string", "format": "uuid" } }, { "$ref": "#/components/parameters/RequestId" }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BusinessCustomerUpdateRequest" } } } }, "responses": { "200": { "description": "Business customer master data updated.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" }, "X-FIQ-Idempotency-Replayed": { "$ref": "#/components/headers/IdempotencyReplayed" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1BusinessCustomerUpdateResponse" } } } }, "400": { "description": "Invalid request body, invalid UUID, or missing Idempotency-Key.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1ErrorEnvelope" } } } }, "401": { "description": "Missing, invalid, expired or inactive API key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LegacyErrorResponse" } } } }, "403": { "description": "The API key does not have customer update permission, or has no owner for audited writes.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1ErrorEnvelope" } } } }, "404": { "description": "Business customer not found.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1ErrorEnvelope" } } } }, "405": { "description": "Only GET and PATCH are allowed for this route.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1ErrorEnvelope" } } } }, "409": { "description": "The idempotency key conflicts with a different request body.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1ErrorEnvelope" } } } }, "500": { "description": "Generic server failure. Internal database details must not be returned.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1ErrorEnvelope" } } } } }, "x-financial-iq-safety": { "requiresApiKey": true, "scope": "business.customers.update", "requiredPermission": "customers", "directFinancialMutation": false, "businessMutation": true, "writeLevel": "customer_master_data", "requiresIdempotencyKey": true, "auditedEndpoint": "v1/business/companies/{company_id}/customers/{customer_id}", "forbiddenFields": [ "id", "company_id", "created_at", "updated_at", "total_outstanding", "average_days_to_pay", "last_invoice_date", "invoice_ids", "payment_ids", "ledger_entries", "balance", "credit_limit" ], "doesNot": [ "move_customer_between_companies", "create_invoices", "issue_invoices", "change_invoice_balances", "post_ledger_entries", "file_tax_returns", "move_money" ] }, "x-implementation": { "edgeFunction": "supabase/functions/financial-data-api/index.ts", "handler": "updateV1BusinessCustomer", "tests": [ "supabase/functions/financial-data-api/invoice_idempotency.test.ts" ] } } }, "/v1/business/companies/{company_id}/customer-volumes": { "get": { "tags": [ "Business" ], "operationId": "listBusinessCustomerVolumes", "summary": "List business customer revenue volumes", "description": "Returns revenue totals by customer for one accessible business company and explicit date range. This route is read-only and uses the existing server-side branch-aware customer volume aggregation.", "security": [ { "ApiKeyAuth": [] } ], "parameters": [ { "$ref": "#/components/parameters/BusinessCompanyId" }, { "$ref": "#/components/parameters/RequestId" }, { "name": "from_date", "in": "query", "required": true, "description": "Inclusive period start date in YYYY-MM-DD format.", "schema": { "type": "string", "format": "date", "pattern": "^\\d{4}-\\d{2}-\\d{2}$" } }, { "name": "to_date", "in": "query", "required": true, "description": "Inclusive period end date in YYYY-MM-DD format.", "schema": { "type": "string", "format": "date", "pattern": "^\\d{4}-\\d{2}-\\d{2}$" } }, { "name": "branch", "in": "query", "required": false, "description": "Optional branch or cost-centre name understood by the existing aggregation.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Customer revenue volumes returned.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1BusinessCustomerVolumeListResponse" } } } }, "400": { "description": "The company_id or date filter is invalid.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1ErrorEnvelope" } } } }, "401": { "description": "Missing, invalid, expired or inactive API key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LegacyErrorResponse" } } } }, "403": { "description": "The API key does not have customer or invoice permission, or the master key is not allowed to access the company.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1ErrorEnvelope" } } } }, "404": { "description": "Business company not found.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1ErrorEnvelope" } } } }, "405": { "description": "Only GET is allowed for this route.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1ErrorEnvelope" } } } }, "500": { "description": "Generic server failure. Internal database details must not be returned.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1ErrorEnvelope" } } } } }, "x-financial-iq-safety": { "scope": "business.customer_volumes.read", "businessMutation": false, "directFinancialMutation": false, "writeLevel": "read", "requiresIdempotencyKey": false, "auditedEndpoint": "v1/business/companies/{company_id}/customer-volumes", "requiredAnyPermission": [ "customers", "invoices" ], "serverSideAggregation": true }, "x-implementation": { "edgeFunction": "supabase/functions/financial-data-api/index.ts", "handler": "handleV1BusinessCustomerVolumes", "tests": [ "supabase/functions/financial-data-api/invoice_idempotency.test.ts" ] } } }, "/v1/business/companies/{company_id}/suppliers": { "get": { "tags": [ "Business" ], "operationId": "listBusinessSuppliers", "summary": "List business suppliers", "description": "Lists suppliers for an accessible business company. This route is read-only and is intended to let agents find the supplier_id needed for purchase and bill workflows.", "security": [ { "ApiKeyAuth": [] } ], "parameters": [ { "name": "company_id", "in": "path", "required": true, "description": "Business company id.", "schema": { "type": "string", "format": "uuid" } }, { "$ref": "#/components/parameters/RequestId" }, { "name": "search", "in": "query", "required": false, "description": "Optional case-insensitive name search.", "schema": { "type": "string", "minLength": 1, "maxLength": 200 } }, { "name": "q", "in": "query", "required": false, "description": "Alias for search.", "schema": { "type": "string", "minLength": 1, "maxLength": 200 } }, { "name": "is_active", "in": "query", "required": false, "description": "Optional active-status filter.", "schema": { "type": "boolean" } }, { "name": "limit", "in": "query", "required": false, "description": "Maximum number of suppliers to return. Values are clamped between 1 and 200.", "schema": { "type": "integer", "minimum": 1, "maximum": 200, "default": 100 } }, { "name": "offset", "in": "query", "required": false, "description": "Zero-based offset for paginating supplier discovery results.", "schema": { "type": "integer", "minimum": 0, "default": 0 } } ], "responses": { "200": { "description": "Accessible business suppliers returned.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1BusinessSupplierListResponse" } } } }, "400": { "description": "The company_id path parameter is not a valid UUID.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1ErrorEnvelope" } } } }, "401": { "description": "Missing, invalid, expired or inactive API key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LegacyErrorResponse" } } } }, "403": { "description": "The API key does not have supplier read permission, or the master key is not allowed to access the company.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1ErrorEnvelope" } } } }, "404": { "description": "Business company not found.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1ErrorEnvelope" } } } }, "405": { "description": "Only GET is allowed for this route.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1ErrorEnvelope" } } } }, "500": { "description": "Generic server failure. Internal database details must not be returned.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1ErrorEnvelope" } } } } }, "x-financial-iq-safety": { "requiresApiKey": true, "apiKeysAllowed": true, "requiresUserBearerToken": false, "scope": "business.suppliers.read", "businessMutation": false, "directFinancialMutation": false, "writeLevel": "read", "requiresIdempotencyKey": false, "auditedEndpoint": "v1/business/companies/{company_id}/suppliers", "redactedFields": [ "bank_account_number", "bank_account_number_ct", "bank_account_number_encrypted", "bank_sort_code", "bank_sort_code_ct", "bank_sort_code_encrypted", "bank_account_name", "contact_email_ct", "contact_email_encrypted", "contact_phone_ct", "contact_phone_encrypted", "vat_number_ct", "vat_number_encrypted" ] }, "x-implementation": { "edgeFunction": "supabase/functions/financial-data-api/index.ts", "handler": "handleV1BusinessSuppliers", "tests": [ "supabase/functions/financial-data-api/invoice_idempotency.test.ts" ] } }, "post": { "tags": [ "Business" ], "operationId": "createBusinessSupplier", "summary": "Create business supplier", "description": "Creates a supplier record for an accessible business company. This is a master-data write used by agents before creating bills or purchases; it does not create bills, payments or ledger postings.", "security": [ { "ApiKeyAuth": [] } ], "parameters": [ { "name": "company_id", "in": "path", "required": true, "description": "Business company id.", "schema": { "type": "string", "format": "uuid" } }, { "$ref": "#/components/parameters/RequestId" }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BusinessSupplierCreateRequest" } } } }, "responses": { "201": { "description": "Business supplier created.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1BusinessSupplierCreateResponse" } } } }, "400": { "description": "The request body, idempotency key or company_id path parameter is invalid.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1ErrorEnvelope" } } } }, "401": { "description": "Missing, invalid, expired or inactive API key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LegacyErrorResponse" } } } }, "403": { "description": "The API key does not have supplier permission.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1ErrorEnvelope" } } } }, "404": { "description": "Business company not found.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1ErrorEnvelope" } } } }, "405": { "description": "Only GET and POST are allowed for this route.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1ErrorEnvelope" } } } }, "409": { "description": "The idempotency key conflicts with a different request body.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1ErrorEnvelope" } } } }, "500": { "description": "Generic server failure. Internal database details must not be returned.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1ErrorEnvelope" } } } } }, "x-financial-iq-safety": { "requiresApiKey": true, "scope": "business.suppliers.create", "requiredPermission": "suppliers", "directFinancialMutation": false, "writeLevel": "configuration", "requiresIdempotencyKey": true, "auditedEndpoint": "v1/business/companies/{company_id}/suppliers", "redactedFields": [ "bank_account_number", "bank_account_number_ct", "bank_account_number_encrypted", "bank_sort_code", "bank_sort_code_ct", "bank_sort_code_encrypted", "bank_account_name", "contact_email_ct", "contact_email_encrypted", "contact_phone_ct", "contact_phone_encrypted", "vat_number_ct", "vat_number_encrypted" ] }, "x-implementation": { "edgeFunction": "supabase/functions/financial-data-api/index.ts", "handler": "createV1BusinessSupplier", "tests": [ "supabase/functions/financial-data-api/invoice_idempotency.test.ts" ] } } }, "/v1/business/companies/{company_id}/suppliers/{supplier_id}": { "get": { "tags": [ "Business" ], "operationId": "getBusinessSupplier", "summary": "Get one business supplier", "description": "Returns one supplier for an accessible business company. Inaccessible suppliers are returned as not found.", "security": [ { "ApiKeyAuth": [] } ], "parameters": [ { "name": "company_id", "in": "path", "required": true, "description": "Business company id.", "schema": { "type": "string", "format": "uuid" } }, { "name": "supplier_id", "in": "path", "required": true, "description": "Business supplier id to fetch.", "schema": { "type": "string", "format": "uuid" } }, { "$ref": "#/components/parameters/RequestId" } ], "responses": { "200": { "description": "Accessible business supplier returned.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1BusinessSupplierResponse" } } } }, "400": { "description": "The company_id or supplier_id path parameter is not a valid UUID.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1ErrorEnvelope" } } } }, "401": { "description": "Missing, invalid, expired or inactive API key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LegacyErrorResponse" } } } }, "403": { "description": "The API key does not have supplier read permission, or the master key is not allowed to access the company.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1ErrorEnvelope" } } } }, "404": { "description": "Business supplier not found.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1ErrorEnvelope" } } } }, "405": { "description": "Only GET and PATCH are allowed for this route.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1ErrorEnvelope" } } } }, "500": { "description": "Generic server failure. Internal database details must not be returned.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1ErrorEnvelope" } } } } }, "x-financial-iq-safety": { "requiresApiKey": true, "apiKeysAllowed": true, "requiresUserBearerToken": false, "scope": "business.suppliers.read", "businessMutation": false, "directFinancialMutation": false, "writeLevel": "read", "requiresIdempotencyKey": false, "auditedEndpoint": "v1/business/companies/{company_id}/suppliers/{supplier_id}", "redactedFields": [ "bank_account_number", "bank_account_number_ct", "bank_account_number_encrypted", "bank_sort_code", "bank_sort_code_ct", "bank_sort_code_encrypted", "bank_account_name", "contact_email_ct", "contact_email_encrypted", "contact_phone_ct", "contact_phone_encrypted", "vat_number_ct", "vat_number_encrypted" ] }, "x-implementation": { "edgeFunction": "supabase/functions/financial-data-api/index.ts", "handler": "handleV1BusinessSupplierDetail", "tests": [ "supabase/functions/financial-data-api/invoice_idempotency.test.ts" ] } }, "patch": { "tags": [ "Business" ], "operationId": "updateBusinessSupplier", "summary": "Update business supplier master data", "description": "Updates safe supplier master-data fields for an accessible business company. This route does not update supplier bank details, create bills, pay suppliers, post ledger entries, file tax returns or move money.", "security": [ { "ApiKeyAuth": [] } ], "parameters": [ { "name": "company_id", "in": "path", "required": true, "description": "Business company id.", "schema": { "type": "string", "format": "uuid" } }, { "name": "supplier_id", "in": "path", "required": true, "description": "Business supplier id to fetch.", "schema": { "type": "string", "format": "uuid" } }, { "$ref": "#/components/parameters/RequestId" }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BusinessSupplierUpdateRequest" } } } }, "responses": { "200": { "description": "Business supplier updated.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1BusinessSupplierUpdateResponse" } } } }, "400": { "description": "The request body, idempotency key, company_id path parameter or supplier_id path parameter is invalid.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1ErrorEnvelope" } } } }, "401": { "description": "Missing, invalid, expired or inactive API key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LegacyErrorResponse" } } } }, "403": { "description": "The API key does not have supplier permission, or has no owner for audit attribution.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1ErrorEnvelope" } } } }, "404": { "description": "Business supplier not found.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1ErrorEnvelope" } } } }, "405": { "description": "Only GET and PATCH are allowed for this route.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1ErrorEnvelope" } } } }, "409": { "description": "The idempotency key conflicts with a different request body.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1ErrorEnvelope" } } } }, "500": { "description": "Generic server failure. Internal database details must not be returned.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1ErrorEnvelope" } } } } }, "x-financial-iq-safety": { "requiresApiKey": true, "apiKeysAllowed": true, "requiresUserBearerToken": false, "scope": "business.suppliers.update", "requiredPermission": "suppliers", "businessMutation": true, "directFinancialMutation": false, "writeLevel": "supplier_master_data", "requiresIdempotencyKey": true, "auditedEndpoint": "v1/business/companies/{company_id}/suppliers/{supplier_id}", "forbiddenFields": [ "id", "company_id", "created_at", "updated_at", "total_outstanding", "average_days_to_pay", "last_invoice_date", "purchase_invoice_ids", "payment_ids", "ledger_entries", "bank_account_number", "bank_account_number_ct", "bank_account_number_encrypted", "bank_sort_code", "bank_sort_code_ct", "bank_sort_code_encrypted", "bank_account_name", "contact_email_ct", "contact_email_encrypted", "contact_phone_ct", "contact_phone_encrypted", "vat_number_ct", "vat_number_encrypted" ], "doesNot": [ "move_supplier_between_companies", "create_bills", "approve_bills", "pay_suppliers", "change_bill_balances", "post_ledger_entries", "file_tax_returns", "move_money", "update_supplier_bank_details" ], "redactedFields": [ "bank_account_number", "bank_account_number_ct", "bank_account_number_encrypted", "bank_sort_code", "bank_sort_code_ct", "bank_sort_code_encrypted", "bank_account_name", "contact_email_ct", "contact_email_encrypted", "contact_phone_ct", "contact_phone_encrypted", "vat_number_ct", "vat_number_encrypted" ] }, "x-implementation": { "edgeFunction": "supabase/functions/financial-data-api/index.ts", "handler": "updateV1BusinessSupplier", "tests": [ "supabase/functions/financial-data-api/invoice_idempotency.test.ts" ] } } }, "/v1/business/companies/{company_id}/supplier-volumes": { "get": { "tags": [ "Business" ], "operationId": "listBusinessSupplierVolumes", "summary": "List business supplier spend volumes", "description": "Returns purchase spend totals by supplier for one accessible business company and explicit date range. This route is read-only and uses the existing server-side branch-aware supplier volume aggregation.", "security": [ { "ApiKeyAuth": [] } ], "parameters": [ { "$ref": "#/components/parameters/BusinessCompanyId" }, { "$ref": "#/components/parameters/RequestId" }, { "name": "from_date", "in": "query", "required": true, "description": "Inclusive period start date in YYYY-MM-DD format.", "schema": { "type": "string", "format": "date", "pattern": "^\\d{4}-\\d{2}-\\d{2}$" } }, { "name": "to_date", "in": "query", "required": true, "description": "Inclusive period end date in YYYY-MM-DD format.", "schema": { "type": "string", "format": "date", "pattern": "^\\d{4}-\\d{2}-\\d{2}$" } }, { "name": "branch", "in": "query", "required": false, "description": "Optional branch or cost-centre name understood by the existing aggregation.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Supplier spend volumes returned.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1BusinessSupplierVolumeListResponse" } } } }, "400": { "description": "The company_id or date filter is invalid.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1ErrorEnvelope" } } } }, "401": { "description": "Missing, invalid, expired or inactive API key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LegacyErrorResponse" } } } }, "403": { "description": "The API key does not have supplier or transaction permission, or the master key is not allowed to access the company.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1ErrorEnvelope" } } } }, "404": { "description": "Business company not found.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1ErrorEnvelope" } } } }, "405": { "description": "Only GET is allowed for this route.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1ErrorEnvelope" } } } }, "500": { "description": "Generic server failure. Internal database details must not be returned.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1ErrorEnvelope" } } } } }, "x-financial-iq-safety": { "scope": "business.supplier_volumes.read", "businessMutation": false, "directFinancialMutation": false, "writeLevel": "read", "requiresIdempotencyKey": false, "auditedEndpoint": "v1/business/companies/{company_id}/supplier-volumes", "requiredAnyPermission": [ "suppliers", "transactions" ], "serverSideAggregation": true }, "x-implementation": { "edgeFunction": "supabase/functions/financial-data-api/index.ts", "handler": "handleV1BusinessSupplierVolumes", "tests": [ "supabase/functions/financial-data-api/invoice_idempotency.test.ts" ] } } }, "/v1/business/bank-feed-institutions": { "get": { "tags": [ "Business" ], "operationId": "listBusinessBankFeedInstitutions", "summary": "List business bank-feed institutions", "description": "Lists banks available for business bank-feed connection. This route is read-only and does not create a requisition, connect an account or expose account credentials.", "security": [ { "ApiKeyAuth": [] } ], "parameters": [ { "$ref": "#/components/parameters/RequestId" }, { "name": "country", "in": "query", "required": false, "description": "Two-letter ISO country code for the institution catalogue. Defaults to GB.", "schema": { "type": "string", "minLength": 2, "maxLength": 2, "pattern": "^[A-Z]{2}$", "default": "GB" } } ], "responses": { "200": { "description": "Available bank-feed institutions returned.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1BusinessBankFeedInstitutionListResponse" } } } }, "400": { "description": "The country query parameter is invalid.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1ErrorEnvelope" } } } }, "403": { "description": "The API key does not have bank-account permission.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1ErrorEnvelope" } } } }, "405": { "description": "Only GET is allowed for this endpoint.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1ErrorEnvelope" } } } }, "500": { "description": "GoCardless is not configured or the institution catalogue could not be fetched.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1ErrorEnvelope" } } } } }, "x-financial-iq-safety": { "scope": "business.bank_feed_institutions.read", "businessMutation": false, "directFinancialMutation": false, "writeLevel": "read", "requiresIdempotencyKey": false, "auditedEndpoint": "v1/business/bank-feed-institutions", "requiredPermission": "bank_accounts", "externalProviderRead": true }, "x-implementation": { "handler": "handleV1BusinessBankFeedInstitutions" } } }, "/v1/business/companies/{company_id}/bank-accounts": { "get": { "tags": [ "Business" ], "operationId": "listBusinessBankAccounts", "summary": "List business bank accounts", "description": "Lists bank accounts for an accessible business company. This route is read-only and omits account numbers, sort codes, bank-feed tokens, provider IDs and consent references.", "security": [ { "ApiKeyAuth": [] } ], "parameters": [ { "name": "company_id", "in": "path", "required": true, "description": "Business company id.", "schema": { "type": "string", "format": "uuid" } }, { "$ref": "#/components/parameters/RequestId" }, { "name": "search", "in": "query", "required": false, "description": "Search bank accounts by account name.", "schema": { "type": "string", "minLength": 1, "maxLength": 200 } }, { "name": "q", "in": "query", "required": false, "description": "Alias for search.", "schema": { "type": "string", "minLength": 1, "maxLength": 200 } }, { "name": "is_active", "in": "query", "required": false, "description": "Optional active-state filter.", "schema": { "type": "boolean" } }, { "name": "connection_status", "in": "query", "required": false, "description": "Optional bank-feed connection status filter.", "schema": { "type": "string" } }, { "name": "feed_status", "in": "query", "required": false, "description": "Optional bank-feed sync status filter.", "schema": { "type": "string" } }, { "name": "account_type", "in": "query", "required": false, "description": "Optional bank account type filter.", "schema": { "type": "string" } }, { "name": "account_category", "in": "query", "required": false, "description": "Optional bank account category filter.", "schema": { "type": "string" } }, { "name": "limit", "in": "query", "required": false, "description": "Maximum number of bank accounts to return. Values are clamped between 1 and 200.", "schema": { "type": "integer", "minimum": 1, "maximum": 200, "default": 100 } }, { "name": "offset", "in": "query", "required": false, "description": "Zero-based offset for paginating bank account results.", "schema": { "type": "integer", "minimum": 0, "default": 0 } } ], "responses": { "200": { "description": "Accessible business bank accounts returned.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1BusinessBankAccountListResponse" } } } }, "400": { "description": "The company_id path parameter is not a valid UUID.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1ErrorEnvelope" } } } }, "401": { "description": "Missing, invalid, expired or inactive API key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LegacyErrorResponse" } } } }, "403": { "description": "The API key does not have bank account read permission, or the master key is not allowed to access the company.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1ErrorEnvelope" } } } }, "404": { "description": "Business company not found.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1ErrorEnvelope" } } } }, "405": { "description": "Only GET and POST are allowed for this route.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1ErrorEnvelope" } } } }, "500": { "description": "Generic server failure. Internal database details must not be returned.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1ErrorEnvelope" } } } } }, "x-financial-iq-safety": { "requiresApiKey": true, "apiKeysAllowed": true, "requiresUserBearerToken": false, "scope": "business.bank_accounts.read", "requiredPermission": "bank_accounts", "businessMutation": false, "directFinancialMutation": false, "writeLevel": "read", "requiresIdempotencyKey": false, "auditedEndpoint": "v1/business/companies/{company_id}/bank-accounts", "redactedFields": [ "account_number", "account_number_ct", "account_number_hash", "sort_code", "sort_code_ct", "sort_code_hash", "access_token", "refresh_token", "token_expires_at", "provider_id", "provider_consent_id", "gocardless_account_id", "gocardless_requisition_id" ] }, "x-implementation": { "edgeFunction": "supabase/functions/financial-data-api/index.ts", "handler": "handleV1BusinessBankAccounts", "tests": [ "supabase/functions/financial-data-api/invoice_idempotency.test.ts" ] } }, "post": { "tags": [ "Business" ], "operationId": "createBusinessBankAccount", "summary": "Create a manual business bank account", "description": "Creates a manual business bank account for an accessible company. This route requires bank_accounts permission and an Idempotency-Key. It does not connect a bank feed, import transactions, store account numbers or sort codes, reconcile statements, move money, create journal entries, or post to the ledger.", "security": [ { "ApiKeyAuth": [] } ], "parameters": [ { "name": "company_id", "in": "path", "required": true, "description": "Business company id.", "schema": { "type": "string", "format": "uuid" } }, { "$ref": "#/components/parameters/RequestId" }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1BusinessBankAccountCreateRequest" } } } }, "responses": { "201": { "description": "Manual business bank account created.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1BusinessBankAccountCreateResponse" } } } }, "400": { "description": "Invalid request body, invalid company id, invalid chart_of_accounts_id, or missing Idempotency-Key.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1ErrorEnvelope" } } } }, "401": { "description": "Missing, invalid, expired or inactive API key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LegacyErrorResponse" } } } }, "403": { "description": "The API key does not have bank account permission.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1ErrorEnvelope" } } } }, "404": { "description": "Business company not found.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1ErrorEnvelope" } } } }, "405": { "description": "Only GET and POST are allowed for this route.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1ErrorEnvelope" } } } }, "409": { "description": "The Idempotency-Key is currently processing or was used with a different request body.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1ErrorEnvelope" } } } }, "500": { "description": "Generic server failure. Internal database details must not be returned.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1ErrorEnvelope" } } } } }, "x-financial-iq-safety": { "requiresApiKey": true, "apiKeysAllowed": true, "requiresUserBearerToken": false, "scope": "business.bank_accounts.create", "requiredPermission": "bank_accounts", "businessMutation": true, "directFinancialMutation": false, "writeLevel": "configuration", "requiresIdempotencyKey": true, "auditedEndpoint": "v1/business/companies/{company_id}/bank-accounts", "forbiddenFields": [ "account_number", "account_number_ct", "account_number_hash", "sort_code", "sort_code_ct", "sort_code_hash", "access_token", "refresh_token", "token_expires_at", "provider_id", "provider_consent_id", "gocardless_account_id", "gocardless_requisition_id", "transactions", "journal_entries", "statement_lines" ], "doesNot": [ "connect_bank_feed", "import_transactions", "store_account_numbers", "reconcile_statements", "move_money", "create_journal_entries", "post_to_ledger" ] }, "x-implementation": { "edgeFunction": "supabase/functions/financial-data-api/index.ts", "handler": "handleV1BusinessBankAccounts", "tests": [ "supabase/functions/financial-data-api/invoice_idempotency.test.ts" ] } } }, "/v1/business/companies/{company_id}/bank-accounts/{bank_account_id}": { "get": { "tags": [ "Business" ], "operationId": "getBusinessBankAccount", "summary": "Get one business bank account", "description": "Returns one bank account for an accessible business company. Inaccessible account IDs are returned as not found to avoid leaking tenant data.", "security": [ { "ApiKeyAuth": [] } ], "parameters": [ { "name": "company_id", "in": "path", "required": true, "description": "Business company id.", "schema": { "type": "string", "format": "uuid" } }, { "name": "bank_account_id", "in": "path", "required": true, "description": "Business bank account id to fetch.", "schema": { "type": "string", "format": "uuid" } }, { "$ref": "#/components/parameters/RequestId" } ], "responses": { "200": { "description": "Accessible business bank account returned.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1BusinessBankAccountResponse" } } } }, "400": { "description": "The company_id or bank_account_id path parameter is not a valid UUID.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1ErrorEnvelope" } } } }, "401": { "description": "Missing, invalid, expired or inactive API key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LegacyErrorResponse" } } } }, "403": { "description": "The API key does not have bank account read permission, or the master key is not allowed to access the company.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1ErrorEnvelope" } } } }, "404": { "description": "Business bank account not found.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1ErrorEnvelope" } } } }, "405": { "description": "Only GET and PATCH are allowed for this route.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1ErrorEnvelope" } } } }, "500": { "description": "Generic server failure. Internal database details must not be returned.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1ErrorEnvelope" } } } } }, "x-financial-iq-safety": { "requiresApiKey": true, "apiKeysAllowed": true, "requiresUserBearerToken": false, "scope": "business.bank_accounts.read", "requiredPermission": "bank_accounts", "businessMutation": false, "directFinancialMutation": false, "writeLevel": "read", "requiresIdempotencyKey": false, "auditedEndpoint": "v1/business/companies/{company_id}/bank-accounts/{bank_account_id}", "redactedFields": [ "account_number", "account_number_ct", "account_number_hash", "sort_code", "sort_code_ct", "sort_code_hash", "access_token", "refresh_token", "token_expires_at", "provider_id", "provider_consent_id", "gocardless_account_id", "gocardless_requisition_id" ] }, "x-implementation": { "edgeFunction": "supabase/functions/financial-data-api/index.ts", "handler": "handleV1BusinessBankAccountDetail", "tests": [ "supabase/functions/financial-data-api/invoice_idempotency.test.ts" ] } }, "patch": { "tags": [ "Business" ], "operationId": "updateBusinessBankAccount", "summary": "Update business bank account metadata", "description": "Updates safe metadata fields for one business bank account in an accessible company. This route requires bank_accounts permission and an Idempotency-Key. It can change account_name, bank_name, account_type, account_category, chart_of_accounts_id and is_active only; it does not change balances, currency, account numbers, sort codes, bank-feed credentials, provider IDs, sync state, reconciliation state, transactions, journal entries, ledger postings or move money.", "security": [ { "ApiKeyAuth": [] } ], "parameters": [ { "$ref": "#/components/parameters/BusinessCompanyId" }, { "name": "bank_account_id", "in": "path", "required": true, "description": "Business bank account id to fetch.", "schema": { "type": "string", "format": "uuid" } }, { "$ref": "#/components/parameters/RequestId" }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1BusinessBankAccountUpdateRequest" } } } }, "responses": { "200": { "description": "Business bank account metadata updated.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" }, "X-FIQ-Idempotency-Replayed": { "$ref": "#/components/headers/IdempotencyReplayed" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1BusinessBankAccountUpdateResponse" } } } }, "400": { "description": "Invalid request body, missing Idempotency-Key, invalid company_id/bank_account_id path parameter, or invalid chart_of_accounts_id.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1ErrorEnvelope" } } } }, "401": { "description": "Missing, invalid, expired or inactive API key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LegacyErrorResponse" } } } }, "403": { "description": "The API key does not grant bank account write permission.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1ErrorEnvelope" } } } }, "404": { "description": "Business bank account not found.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1ErrorEnvelope" } } } }, "405": { "description": "Only GET and PATCH are allowed for this route.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1ErrorEnvelope" } } } }, "409": { "description": "The idempotency key conflicts with another request.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1ErrorEnvelope" } } } }, "500": { "description": "Generic server failure. Internal database details must not be returned.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1ErrorEnvelope" } } } } }, "x-financial-iq-safety": { "requiresApiKey": true, "apiKeysAllowed": true, "requiresUserBearerToken": false, "scope": "business.bank_accounts.update", "requiredPermission": "bank_accounts", "businessMutation": true, "directFinancialMutation": false, "writeLevel": "metadata", "requiresIdempotencyKey": true, "auditedEndpoint": "v1/business/companies/{company_id}/bank-accounts/{bank_account_id}", "forbiddenFields": [ "id", "company_id", "currency", "current_balance", "available_balance", "actual_balance", "book_balance", "reconciliation_difference", "reconciliation_status", "last_reconciled_at", "last_sync_at", "last_sync_attempt_at", "last_sync_error", "last_sync_result", "connection_status", "feed_status", "first_connected_at", "account_number", "account_number_ct", "account_number_hash", "account_number_kid", "sort_code", "sort_code_ct", "sort_code_hash", "sort_code_kid", "iban", "access_token", "access_token_ct", "refresh_token", "refresh_token_ct", "token_expires_at", "provider_id", "provider_consent_id", "provider_name", "gocardless_account_id", "gocardless_requisition_id", "gocardless_agreement_id", "gocardless_institution_id", "yapily_institution_id", "truelayer_account_id", "payments_enabled", "payments_enabled_at", "statement_lines", "transactions", "journal_entries", "created_at", "updated_at", "user_id" ], "doesNot": [ "connect_bank_feed", "import_transactions", "store_account_numbers", "store_sort_codes", "change_balance", "change_currency", "reconcile_statement", "change_sync_state", "create_transaction", "create_journal_entry", "post_to_ledger", "move_money" ], "redactedFields": [ "account_number", "account_number_ct", "account_number_hash", "sort_code", "sort_code_ct", "sort_code_hash", "access_token", "refresh_token", "token_expires_at", "provider_id", "provider_consent_id", "gocardless_account_id", "gocardless_requisition_id" ] }, "x-implementation": { "edgeFunction": "supabase/functions/financial-data-api/index.ts", "handler": "updateV1BusinessBankAccount", "tests": [ "supabase/functions/financial-data-api/invoice_idempotency.test.ts" ] } } }, "/v1/business/companies/{company_id}/bank-feed-authorization-requests": { "post": { "tags": ["Business"], "operationId": "createBusinessBankFeedAuthorizationRequest", "summary": "Create a short-lived bank-feed approval request", "description": "Creates a durable, one-use handoff for a signed-in Financial IQ user to approve a business bank-feed connection. The API does not connect the provider, import transactions or expose banking credentials.", "security": [{"ApiKeyAuth": []}], "parameters": [ {"name": "company_id", "in": "path", "required": true, "schema": {"type": "string", "format": "uuid"}}, {"$ref": "#/components/parameters/RequestId"}, {"name": "Idempotency-Key", "in": "header", "required": true, "schema": {"type": "string", "minLength": 1}} ], "requestBody": { "required": true, "content": {"application/json": {"schema": {"type": "object", "required": ["institution_id"], "properties": { "institution_id": {"type": "string", "maxLength": 200}, "sync_from_date": {"type": "string", "format": "date"}, "max_historical_days": {"type": "integer", "minimum": 1, "maximum": 3650, "default": 730}, "reauthorizing_account_id": {"type": "string", "format": "uuid"} }}}} }, "responses": {"201": {"description": "Approval request created."}, "400": {"description": "Invalid request or missing idempotency key."}, "403": {"description": "Missing bank account permission."}, "404": {"description": "Company not found."}}, "x-financial-iq-safety": { "requiresApiKey": true, "apiKeysAllowed": true, "requiresUserBearerToken": false, "scope": "business.bank_feed_authorization_requests.create", "requiredPermission": "bank_accounts", "businessMutation": true, "directFinancialMutation": false, "writeLevel": "auth_request", "requiresIdempotencyKey": true, "auditedEndpoint": "v1/business/companies/{company_id}/bank-feed-authorization-requests", "doesNot": ["connect_bank_feed", "import_transactions", "expose_provider_credentials", "move_money"] }, "x-implementation": {"edgeFunction": "supabase/functions/financial-data-api/index.ts", "handler": "handleV1BusinessBankFeedAuthorizationRequests", "databaseMigration": "supabase/migrations/20260711150000_api_business_bank_feed_authorization_request.sql", "tests": ["supabase/functions/financial-data-api/invoice_idempotency.test.ts"]} } }, "/v1/business/companies/{company_id}/bank-feed-authorization-requests/{request_id}": { "get": { "tags": ["Business"], "operationId": "getBusinessBankFeedAuthorizationRequest", "summary": "Get a bank-feed approval request status", "description": "Returns the safe status of a business bank-feed approval handoff. Provider credentials and internal ownership fields are never returned.", "security": [{"ApiKeyAuth": []}], "parameters": [ {"name": "company_id", "in": "path", "required": true, "schema": {"type": "string", "format": "uuid"}}, {"name": "request_id", "in": "path", "required": true, "schema": {"type": "string", "format": "uuid"}}, {"$ref": "#/components/parameters/RequestId"} ], "responses": {"200": {"description": "Approval request status."}, "404": {"description": "Approval request not found."}}, "x-financial-iq-safety": { "requiresApiKey": true, "apiKeysAllowed": true, "requiresUserBearerToken": false, "scope": "business.bank_feed_authorization_requests.read", "requiredPermission": "bank_accounts", "businessMutation": false, "directFinancialMutation": false, "writeLevel": "read", "requiresIdempotencyKey": false, "auditedEndpoint": "v1/business/companies/{company_id}/bank-feed-authorization-requests/{request_id}", "redactedFields": ["api_key_id", "created_by", "provider_credentials"] }, "x-implementation": {"edgeFunction": "supabase/functions/financial-data-api/index.ts", "handler": "handleV1BusinessBankFeedAuthorizationRequestDetail", "tests": ["supabase/functions/financial-data-api/invoice_idempotency.test.ts"]} } }, "/v1/business/companies/{company_id}/bank-statement-lines": { "get": { "tags": [ "Business" ], "operationId": "listBusinessBankStatementLines", "summary": "List business bank statement lines", "description": "Lists imported bank statement lines for one accessible business company. This route is read-only: it does not import statements, create statement lines, match transactions, post bank journals, sign off reconciliations, close accounting periods or move money.", "security": [ { "ApiKeyAuth": [] } ], "parameters": [ { "name": "company_id", "in": "path", "required": true, "description": "Business company id.", "schema": { "type": "string", "format": "uuid" } }, { "$ref": "#/components/parameters/RequestId" }, { "name": "bank_account_id", "in": "query", "required": false, "description": "Filter statement lines by bank account.", "schema": { "type": "string", "format": "uuid" } }, { "name": "statement_upload_id", "in": "query", "required": false, "description": "Filter statement lines by source upload.", "schema": { "type": "string", "format": "uuid" } }, { "name": "from_date", "in": "query", "required": false, "description": "Inclusive lower bound for statement line date.", "schema": { "type": "string", "format": "date" } }, { "name": "to_date", "in": "query", "required": false, "description": "Inclusive upper bound for statement line date.", "schema": { "type": "string", "format": "date" } }, { "name": "min_amount", "in": "query", "required": false, "description": "Inclusive lower bound for signed statement amount.", "schema": { "type": "number" } }, { "name": "max_amount", "in": "query", "required": false, "description": "Inclusive upper bound for signed statement amount.", "schema": { "type": "number" } }, { "name": "unmatched_only", "in": "query", "required": false, "description": "Return only lines that have not been matched to a bank transaction.", "schema": { "type": "boolean", "default": false } }, { "name": "search", "in": "query", "required": false, "description": "Case-insensitive statement description search. Alias: q.", "schema": { "type": "string", "maxLength": 120 } }, { "name": "q", "in": "query", "required": false, "description": "Alias for search.", "schema": { "type": "string", "maxLength": 120 } }, { "name": "limit", "in": "query", "required": false, "description": "Maximum records to return, capped at 100.", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 50 } }, { "name": "offset", "in": "query", "required": false, "description": "Zero-based pagination offset.", "schema": { "type": "integer", "minimum": 0, "default": 0 } } ], "responses": { "200": { "description": "Business bank statement lines returned.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1BusinessBankStatementLineListResponse" } } } }, "400": { "description": "The path or query parameters are invalid.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1ErrorEnvelope" } } } }, "401": { "description": "Missing, invalid, expired or inactive API key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LegacyErrorResponse" } } } }, "403": { "description": "The API key does not have bank_accounts or transactions permission, or the master key is not allowed to access the company.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1ErrorEnvelope" } } } }, "404": { "description": "Business company not found.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1ErrorEnvelope" } } } }, "405": { "description": "Only GET is allowed for this route.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1ErrorEnvelope" } } } }, "500": { "description": "Generic server failure. Internal database details must not be returned.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1ErrorEnvelope" } } } } }, "x-financial-iq-safety": { "requiresApiKey": true, "apiKeysAllowed": true, "requiresUserBearerToken": false, "scope": "business.bank_statement_lines.read", "requiredAnyPermission": [ "bank_accounts", "transactions" ], "businessMutation": false, "directFinancialMutation": false, "writeLevel": "read", "requiresIdempotencyKey": false, "auditedEndpoint": "v1/business/companies/{company_id}/bank-statement-lines", "doesNot": [ "import_bank_statement", "create_statement_line", "match_transaction", "post_bank_journal", "sign_off_reconciliation", "close_accounting_period", "move_money" ] }, "x-implementation": { "edgeFunction": "supabase/functions/financial-data-api/index.ts", "handler": "handleV1BusinessBankStatementLines", "tests": [ "supabase/functions/financial-data-api/invoice_idempotency.test.ts" ] } } }, "/v1/business/companies/{company_id}/bank-statement-lines/{statement_line_id}": { "get": { "tags": [ "Business" ], "operationId": "getBusinessBankStatementLine", "summary": "Get business bank statement line", "description": "Returns one imported bank statement line for an accessible business company. This route is read-only: it does not import statements, create statement lines, match transactions, post bank journals, sign off reconciliations, close accounting periods or move money.", "security": [ { "ApiKeyAuth": [] } ], "parameters": [ { "name": "company_id", "in": "path", "required": true, "description": "Business company id.", "schema": { "type": "string", "format": "uuid" } }, { "name": "statement_line_id", "in": "path", "required": true, "description": "Business bank statement line id.", "schema": { "type": "string", "format": "uuid" } }, { "$ref": "#/components/parameters/RequestId" } ], "responses": { "200": { "description": "Business bank statement line returned.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1BusinessBankStatementLineResponse" } } } }, "400": { "description": "The path or query parameters are invalid.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1ErrorEnvelope" } } } }, "401": { "description": "Missing, invalid, expired or inactive API key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LegacyErrorResponse" } } } }, "403": { "description": "The API key does not have bank_accounts or transactions permission, or the master key is not allowed to access the company.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1ErrorEnvelope" } } } }, "404": { "description": "Business bank statement line not found.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1ErrorEnvelope" } } } }, "405": { "description": "Only GET is allowed for this route.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1ErrorEnvelope" } } } }, "500": { "description": "Generic server failure. Internal database details must not be returned.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1ErrorEnvelope" } } } } }, "x-financial-iq-safety": { "requiresApiKey": true, "apiKeysAllowed": true, "requiresUserBearerToken": false, "scope": "business.bank_statement_lines.read", "requiredAnyPermission": [ "bank_accounts", "transactions" ], "businessMutation": false, "directFinancialMutation": false, "writeLevel": "read", "requiresIdempotencyKey": false, "auditedEndpoint": "v1/business/companies/{company_id}/bank-statement-lines/{statement_line_id}", "doesNot": [ "import_bank_statement", "create_statement_line", "match_transaction", "post_bank_journal", "sign_off_reconciliation", "close_accounting_period", "move_money" ] }, "x-implementation": { "edgeFunction": "supabase/functions/financial-data-api/index.ts", "handler": "handleV1BusinessBankStatementLineDetail", "tests": [ "supabase/functions/financial-data-api/invoice_idempotency.test.ts" ] } } }, "/v1/business/companies/{company_id}/bank-reconciliations": { "get": { "tags": [ "Business" ], "operationId": "listBusinessBankReconciliations", "summary": "List business bank reconciliations", "description": "Lists bank reconciliation status records for one accessible business company. This route is read-only: it does not create reconciliations, update reconciliation status, match transactions, post bank journals, sign off reconciliations, close accounting periods or move money.", "security": [ { "ApiKeyAuth": [] } ], "parameters": [ { "name": "company_id", "in": "path", "required": true, "description": "Business company id.", "schema": { "type": "string", "format": "uuid" } }, { "$ref": "#/components/parameters/RequestId" }, { "name": "bank_account_id", "in": "query", "required": false, "description": "Filter reconciliation records by bank account.", "schema": { "type": "string", "format": "uuid" } }, { "name": "status", "in": "query", "required": false, "description": "Filter reconciliation records by status.", "schema": { "type": "string", "enum": [ "unreconciled", "reconciled" ] } }, { "name": "period_from", "in": "query", "required": false, "description": "Inclusive lower bound for reconciliation period end date.", "schema": { "type": "string", "format": "date" } }, { "name": "period_to", "in": "query", "required": false, "description": "Inclusive upper bound for reconciliation period end date.", "schema": { "type": "string", "format": "date" } }, { "name": "limit", "in": "query", "required": false, "description": "Maximum records to return, capped at 100.", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 50 } }, { "name": "offset", "in": "query", "required": false, "description": "Zero-based pagination offset.", "schema": { "type": "integer", "minimum": 0, "default": 0 } } ], "responses": { "200": { "description": "Business bank reconciliation records returned.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1BusinessBankReconciliationListResponse" } } } }, "400": { "description": "The path or query parameters are invalid.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1ErrorEnvelope" } } } }, "401": { "description": "Missing, invalid, expired or inactive API key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LegacyErrorResponse" } } } }, "403": { "description": "The API key does not have bank_accounts or transactions permission, or the master key is not allowed to access the company.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1ErrorEnvelope" } } } }, "404": { "description": "Business company not found.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1ErrorEnvelope" } } } }, "405": { "description": "Only GET is allowed for this route.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1ErrorEnvelope" } } } }, "500": { "description": "Generic server failure. Internal database details must not be returned.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1ErrorEnvelope" } } } } }, "x-financial-iq-safety": { "requiresApiKey": true, "apiKeysAllowed": true, "requiresUserBearerToken": false, "scope": "business.bank_reconciliations.read", "requiredAnyPermission": [ "bank_accounts", "transactions" ], "businessMutation": false, "directFinancialMutation": false, "writeLevel": "read", "requiresIdempotencyKey": false, "auditedEndpoint": "v1/business/companies/{company_id}/bank-reconciliations", "doesNot": [ "create_reconciliation", "update_reconciliation_status", "match_transaction", "post_bank_journal", "sign_off_reconciliation", "close_accounting_period", "move_money" ] }, "x-implementation": { "edgeFunction": "supabase/functions/financial-data-api/index.ts", "handler": "handleV1BusinessBankReconciliations", "tests": [ "supabase/functions/financial-data-api/invoice_idempotency.test.ts" ] } } }, "/v1/business/companies/{company_id}/bank-reconciliations/{bank_reconciliation_id}": { "get": { "tags": [ "Business" ], "operationId": "getBusinessBankReconciliation", "summary": "Get business bank reconciliation", "description": "Returns one bank reconciliation status record for an accessible business company. This route is read-only: it does not create reconciliations, update reconciliation status, match transactions, post bank journals, sign off reconciliations, close accounting periods or move money.", "security": [ { "ApiKeyAuth": [] } ], "parameters": [ { "name": "company_id", "in": "path", "required": true, "description": "Business company id.", "schema": { "type": "string", "format": "uuid" } }, { "name": "bank_reconciliation_id", "in": "path", "required": true, "description": "Business bank reconciliation id.", "schema": { "type": "string", "format": "uuid" } }, { "$ref": "#/components/parameters/RequestId" } ], "responses": { "200": { "description": "Business bank reconciliation record returned.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1BusinessBankReconciliationResponse" } } } }, "400": { "description": "The path or query parameters are invalid.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1ErrorEnvelope" } } } }, "401": { "description": "Missing, invalid, expired or inactive API key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LegacyErrorResponse" } } } }, "403": { "description": "The API key does not have bank_accounts or transactions permission, or the master key is not allowed to access the company.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1ErrorEnvelope" } } } }, "404": { "description": "Business bank reconciliation not found.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1ErrorEnvelope" } } } }, "405": { "description": "Only GET is allowed for this route.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1ErrorEnvelope" } } } }, "500": { "description": "Generic server failure. Internal database details must not be returned.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1ErrorEnvelope" } } } } }, "x-financial-iq-safety": { "requiresApiKey": true, "apiKeysAllowed": true, "requiresUserBearerToken": false, "scope": "business.bank_reconciliations.read", "requiredAnyPermission": [ "bank_accounts", "transactions" ], "businessMutation": false, "directFinancialMutation": false, "writeLevel": "read", "requiresIdempotencyKey": false, "auditedEndpoint": "v1/business/companies/{company_id}/bank-reconciliations/{bank_reconciliation_id}", "doesNot": [ "create_reconciliation", "update_reconciliation_status", "match_transaction", "post_bank_journal", "sign_off_reconciliation", "close_accounting_period", "move_money" ] }, "x-implementation": { "edgeFunction": "supabase/functions/financial-data-api/index.ts", "handler": "handleV1BusinessBankReconciliationDetail", "tests": [ "supabase/functions/financial-data-api/invoice_idempotency.test.ts" ] } } }, "/v1/business/companies/{company_id}/balance-sheet-reconciliations": { "get": { "tags": [ "Business" ], "operationId": "listBusinessBalanceSheetReconciliations", "summary": "List business balance-sheet reconciliations", "description": "Lists balance-sheet reconciliation workbook summaries for one accessible business company. This route is read-only: it does not refresh workspaces, update statement balances, add reconciliation lines, attach files, sign off workbooks, approve exceptions, lock periods, post journals, file tax returns or move money.", "security": [ { "ApiKeyAuth": [] } ], "parameters": [ { "name": "company_id", "in": "path", "required": true, "description": "Business company id.", "schema": { "type": "string", "format": "uuid" } }, { "$ref": "#/components/parameters/RequestId" }, { "name": "accounting_period_id", "in": "query", "required": false, "description": "Filter workbooks by accounting period.", "schema": { "type": "string", "format": "uuid" } }, { "name": "reconciliation_period_id", "in": "query", "required": false, "description": "Filter workbooks by reconciliation period.", "schema": { "type": "string", "format": "uuid" } }, { "name": "status", "in": "query", "required": false, "description": "Filter workbooks by status.", "schema": { "type": "string", "enum": [ "not_started", "in_progress", "prepared", "in_review", "needs_rework", "approved", "locked" ] } }, { "name": "workbook_type", "in": "query", "required": false, "description": "Filter workbooks by workbook type.", "schema": { "type": "string", "enum": [ "generic", "bank", "fixed_asset", "trade_debtors", "trade_creditors", "hmrc_taxes" ] } }, { "name": "difference_only", "in": "query", "required": false, "description": "Return only workbooks with a non-zero difference.", "schema": { "type": "boolean", "default": false } }, { "name": "open_items_only", "in": "query", "required": false, "description": "Return only workbooks with open reconciliation items.", "schema": { "type": "boolean", "default": false } }, { "name": "search", "in": "query", "required": false, "description": "Search account code or account name. Only letters, numbers, spaces, dots, dashes, underscores and slashes are accepted.", "schema": { "type": "string", "maxLength": 120, "pattern": "^[A-Za-z0-9 ._/-]+$" } }, { "name": "limit", "in": "query", "required": false, "description": "Maximum records to return, capped at 100.", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 50 } }, { "name": "offset", "in": "query", "required": false, "description": "Zero-based pagination offset.", "schema": { "type": "integer", "minimum": 0, "default": 0 } } ], "responses": { "200": { "description": "Business balance-sheet reconciliation summaries returned.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1BusinessBalanceSheetReconciliationListResponse" } } } }, "400": { "description": "The path or query parameters are invalid.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1ErrorEnvelope" } } } }, "401": { "description": "Missing, invalid, expired or inactive API key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LegacyErrorResponse" } } } }, "403": { "description": "The API key does not have reports permission, or the master key is not allowed to access the company.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1ErrorEnvelope" } } } }, "404": { "description": "Business company not found.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1ErrorEnvelope" } } } }, "405": { "description": "Only GET is allowed for this route.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1ErrorEnvelope" } } } }, "500": { "description": "Generic server failure. Internal database details must not be returned.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1ErrorEnvelope" } } } } }, "x-financial-iq-safety": { "requiresApiKey": true, "apiKeysAllowed": true, "requiresUserBearerToken": false, "scope": "business.balance_sheet_reconciliations.read", "requiredPermission": "reports", "businessMutation": false, "directFinancialMutation": false, "writeLevel": "read", "requiresIdempotencyKey": false, "auditedEndpoint": "v1/business/companies/{company_id}/balance-sheet-reconciliations", "doesNot": [ "refresh_reconciliation_workspace", "update_statement_balance", "create_reconciliation_line", "update_reconciliation_line", "delete_reconciliation_line", "attach_file", "sign_off_reconciliation", "approve_exception", "lock_accounting_period", "post_journal", "file_tax_return", "move_money" ] }, "x-implementation": { "edgeFunction": "supabase/functions/financial-data-api/index.ts", "handler": "handleV1BusinessBalanceSheetReconciliations", "tables": [ "reconciliation_workspace_rows", "api_usage_logs" ], "tests": [ "supabase/functions/financial-data-api/invoice_idempotency.test.ts" ] } } }, "/v1/business/companies/{company_id}/balance-sheet-reconciliations/{reconciliation_id}": { "get": { "tags": [ "Business" ], "operationId": "getBusinessBalanceSheetReconciliation", "summary": "Get business balance-sheet reconciliation", "description": "Returns one balance-sheet reconciliation workbook for an accessible business company, including the header, period, lines, attachments, comments, signoffs and recent events. This route is read-only and does not change reconciliation state, post journals, file returns or move money.", "security": [ { "ApiKeyAuth": [] } ], "parameters": [ { "name": "company_id", "in": "path", "required": true, "description": "Business company id.", "schema": { "type": "string", "format": "uuid" } }, { "name": "reconciliation_id", "in": "path", "required": true, "description": "Balance-sheet reconciliation workbook id.", "schema": { "type": "string", "format": "uuid" } }, { "$ref": "#/components/parameters/RequestId" } ], "responses": { "200": { "description": "Business balance-sheet reconciliation workbook returned.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1BusinessBalanceSheetReconciliationResponse" } } } }, "400": { "description": "The path or query parameters are invalid.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1ErrorEnvelope" } } } }, "401": { "description": "Missing, invalid, expired or inactive API key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LegacyErrorResponse" } } } }, "403": { "description": "The API key does not have reports permission, or the master key is not allowed to access the company.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1ErrorEnvelope" } } } }, "404": { "description": "Business balance-sheet reconciliation not found.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1ErrorEnvelope" } } } }, "405": { "description": "Only GET is allowed for this route.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1ErrorEnvelope" } } } }, "500": { "description": "Generic server failure. Internal database details must not be returned.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1ErrorEnvelope" } } } } }, "x-financial-iq-safety": { "requiresApiKey": true, "apiKeysAllowed": true, "requiresUserBearerToken": false, "scope": "business.balance_sheet_reconciliations.read", "requiredPermission": "reports", "businessMutation": false, "directFinancialMutation": false, "writeLevel": "read", "requiresIdempotencyKey": false, "auditedEndpoint": "v1/business/companies/{company_id}/balance-sheet-reconciliations/{reconciliation_id}", "doesNot": [ "refresh_reconciliation_workspace", "update_statement_balance", "create_reconciliation_line", "update_reconciliation_line", "delete_reconciliation_line", "attach_file", "sign_off_reconciliation", "approve_exception", "lock_accounting_period", "post_journal", "file_tax_return", "move_money" ] }, "x-implementation": { "edgeFunction": "supabase/functions/financial-data-api/index.ts", "handler": "handleV1BusinessBalanceSheetReconciliationDetail", "tables": [ "reconciliations", "reconciliation_periods", "reconciliation_lines", "reconciliation_attachments", "reconciliation_comments", "reconciliation_signoffs", "reconciliation_events", "api_usage_logs" ], "tests": [ "supabase/functions/financial-data-api/invoice_idempotency.test.ts" ] } } }, "/v1/business/companies/{company_id}/chart-of-accounts": { "get": { "tags": [ "Business" ], "operationId": "listBusinessChartOfAccounts", "summary": "List business chart of accounts", "description": "Lists chart of accounts entries for an accessible business company. This read-only route helps agents find the account/category IDs used for transaction coding and financial reporting.", "security": [ { "ApiKeyAuth": [] } ], "parameters": [ { "name": "company_id", "in": "path", "required": true, "description": "Business company id.", "schema": { "type": "string", "format": "uuid" } }, { "$ref": "#/components/parameters/RequestId" }, { "name": "search", "in": "query", "required": false, "description": "Search chart accounts by name.", "schema": { "type": "string", "minLength": 1, "maxLength": 200 } }, { "name": "q", "in": "query", "required": false, "description": "Alias for search.", "schema": { "type": "string", "minLength": 1, "maxLength": 200 } }, { "name": "account_type", "in": "query", "required": false, "description": "Optional account type filter.", "schema": { "type": "string" } }, { "name": "financial_statement", "in": "query", "required": false, "description": "Optional financial statement filter.", "schema": { "type": "string" } }, { "name": "is_active", "in": "query", "required": false, "description": "Optional active-state filter.", "schema": { "type": "boolean" } }, { "name": "is_system_account", "in": "query", "required": false, "description": "Optional system-account filter.", "schema": { "type": "boolean" } }, { "name": "limit", "in": "query", "required": false, "description": "Maximum number of chart accounts to return. Values are clamped between 1 and 200.", "schema": { "type": "integer", "minimum": 1, "maximum": 200, "default": 100 } }, { "name": "offset", "in": "query", "required": false, "description": "Zero-based offset for paginating chart account results.", "schema": { "type": "integer", "minimum": 0, "default": 0 } } ], "responses": { "200": { "description": "Accessible business chart accounts returned.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1BusinessChartOfAccountListResponse" } } } }, "400": { "description": "The company_id path parameter is not a valid UUID.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1ErrorEnvelope" } } } }, "401": { "description": "Missing, invalid, expired or inactive API key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LegacyErrorResponse" } } } }, "403": { "description": "The API key does not have chart of accounts read permission, or the master key is not allowed to access the company.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1ErrorEnvelope" } } } }, "404": { "description": "Business company not found.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1ErrorEnvelope" } } } }, "405": { "description": "Only GET is allowed for this route.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1ErrorEnvelope" } } } }, "500": { "description": "Generic server failure. Internal database details must not be returned.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1ErrorEnvelope" } } } } }, "x-financial-iq-safety": { "requiresApiKey": true, "apiKeysAllowed": true, "requiresUserBearerToken": false, "scope": "business.chart_of_accounts.read", "requiredAnyPermission": [ "chart_of_accounts", "transactions" ], "businessMutation": false, "directFinancialMutation": false, "writeLevel": "read", "requiresIdempotencyKey": false, "auditedEndpoint": "v1/business/companies/{company_id}/chart-of-accounts" }, "x-implementation": { "edgeFunction": "supabase/functions/financial-data-api/index.ts", "handler": "handleV1BusinessChartOfAccounts", "tests": [ "supabase/functions/financial-data-api/invoice_idempotency.test.ts" ] } }, "post": { "tags": [ "Business" ], "operationId": "createBusinessChartOfAccount", "summary": "Create business chart of accounts entry", "description": "Creates one setup-only chart of accounts entry for an accessible business company. This route changes account structure only: it does not create transactions, journals, opening balances, bank movement or tax submissions.", "security": [ { "ApiKeyAuth": [] } ], "parameters": [ { "$ref": "#/components/parameters/BusinessCompanyId" }, { "$ref": "#/components/parameters/RequestId" }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BusinessChartOfAccountCreateRequest" } } } }, "responses": { "201": { "description": "Business chart of accounts entry created.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BusinessChartOfAccountCreateResponse" } } } }, "400": { "description": "The request body, idempotency key or company_id path parameter is invalid.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1ErrorEnvelope" } } } }, "401": { "description": "Missing or invalid API key.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1ErrorEnvelope" } } } }, "403": { "description": "The API key does not have chart of accounts write permission.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1ErrorEnvelope" } } } }, "404": { "description": "The company is not accessible to this API key.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1ErrorEnvelope" } } } }, "405": { "description": "Only GET and POST are allowed for this route.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1ErrorEnvelope" } } } }, "409": { "description": "The account code already exists for this company, or the idempotency key conflicts with another request.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1ErrorEnvelope" } } } }, "500": { "description": "Generic server failure. Internal database details must not be returned.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1ErrorEnvelope" } } } } }, "x-financial-iq-safety": { "requiresApiKey": true, "apiKeysAllowed": true, "requiresUserBearerToken": false, "scope": "business.chart_of_accounts.create", "requiredPermission": "chart_of_accounts", "businessMutation": true, "directFinancialMutation": false, "writeLevel": "configuration", "requiresIdempotencyKey": true, "auditedEndpoint": "v1/business/companies/{company_id}/chart-of-accounts", "forbiddenInThisRoute": [ "set opening balance", "post to ledger", "create journal entry", "create bank transaction", "change bank transaction matching state", "file VAT return", "file CT600 return", "submit anything to HMRC", "close accounting period" ] }, "x-implementation": { "edgeFunction": "supabase/functions/financial-data-api/index.ts", "handler": "createV1BusinessChartOfAccount", "tests": [ "supabase/functions/financial-data-api/invoice_idempotency.test.ts" ] } } }, "/v1/business/companies/{company_id}/chart-of-accounts/{account_id}": { "get": { "tags": [ "Business" ], "operationId": "getBusinessChartOfAccount", "summary": "Get one business chart account", "description": "Returns one chart of accounts entry for an accessible business company. Inaccessible account IDs are returned as not found to avoid leaking tenant data.", "security": [ { "ApiKeyAuth": [] } ], "parameters": [ { "name": "company_id", "in": "path", "required": true, "description": "Business company id.", "schema": { "type": "string", "format": "uuid" } }, { "name": "account_id", "in": "path", "required": true, "description": "Chart of accounts entry id to fetch.", "schema": { "type": "string", "format": "uuid" } }, { "$ref": "#/components/parameters/RequestId" } ], "responses": { "200": { "description": "Accessible business chart account returned.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1BusinessChartOfAccountResponse" } } } }, "400": { "description": "The company_id or account_id path parameter is not a valid UUID.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1ErrorEnvelope" } } } }, "401": { "description": "Missing, invalid, expired or inactive API key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LegacyErrorResponse" } } } }, "403": { "description": "The API key does not have chart of accounts read permission, or the master key is not allowed to access the company.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1ErrorEnvelope" } } } }, "404": { "description": "Business chart of accounts entry not found.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1ErrorEnvelope" } } } }, "405": { "description": "Only GET and PATCH are allowed for this route.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1ErrorEnvelope" } } } }, "500": { "description": "Generic server failure. Internal database details must not be returned.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1ErrorEnvelope" } } } } }, "x-financial-iq-safety": { "requiresApiKey": true, "apiKeysAllowed": true, "requiresUserBearerToken": false, "scope": "business.chart_of_accounts.read", "requiredAnyPermission": [ "chart_of_accounts", "transactions" ], "businessMutation": false, "directFinancialMutation": false, "writeLevel": "read", "requiresIdempotencyKey": false, "auditedEndpoint": "v1/business/companies/{company_id}/chart-of-accounts/{account_id}" }, "x-implementation": { "edgeFunction": "supabase/functions/financial-data-api/index.ts", "handler": "handleV1BusinessChartOfAccountDetail", "tests": [ "supabase/functions/financial-data-api/invoice_idempotency.test.ts" ] } }, "patch": { "tags": [ "Business" ], "operationId": "updateBusinessChartOfAccount", "summary": "Update business chart account", "description": "Updates safe metadata fields for one chart of accounts entry in an accessible company. This route requires chart_of_accounts permission and an Idempotency-Key. It can change name, description, area, management category fields, parent_code and active state only; it does not change account codes, reclassify accounts, change balances, create transactions, post journals, submit tax returns or move money.", "security": [ { "ApiKeyAuth": [] } ], "parameters": [ { "$ref": "#/components/parameters/BusinessCompanyId" }, { "name": "account_id", "in": "path", "required": true, "description": "Chart of accounts entry id to fetch.", "schema": { "type": "string", "format": "uuid" } }, { "$ref": "#/components/parameters/RequestId" }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BusinessChartOfAccountUpdateRequest" } } } }, "responses": { "200": { "description": "Business chart of accounts entry updated.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" }, "X-FIQ-Idempotency-Replayed": { "$ref": "#/components/headers/IdempotencyReplayed" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BusinessChartOfAccountUpdateResponse" } } } }, "400": { "description": "Invalid request body, missing Idempotency-Key, or invalid company_id/account_id path parameter.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1ErrorEnvelope" } } } }, "401": { "description": "Missing, invalid, expired or inactive API key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LegacyErrorResponse" } } } }, "403": { "description": "The API key does not grant chart of accounts write permission.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1ErrorEnvelope" } } } }, "404": { "description": "Business chart of accounts entry not found.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1ErrorEnvelope" } } } }, "405": { "description": "Only GET and PATCH are allowed for this route.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1ErrorEnvelope" } } } }, "409": { "description": "The idempotency key conflicts with another request.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1ErrorEnvelope" } } } }, "500": { "description": "Generic server failure. Internal database details must not be returned.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1ErrorEnvelope" } } } } }, "x-financial-iq-safety": { "requiresApiKey": true, "apiKeysAllowed": true, "requiresUserBearerToken": false, "scope": "business.chart_of_accounts.update", "requiredPermission": "chart_of_accounts", "businessMutation": true, "directFinancialMutation": false, "writeLevel": "metadata", "requiresIdempotencyKey": true, "auditedEndpoint": "v1/business/companies/{company_id}/chart-of-accounts/{account_id}", "forbiddenFields": [ "id", "company_id", "code", "account_type", "financial_statement", "standard_category_code", "tax_treatment", "statutory_category", "statutory_subcategory", "balance", "opening_balance", "current_balance", "book_balance", "actual_balance", "available_balance", "last_reconciled_date", "is_system_account", "is_deletable", "archived_at", "created_at", "updated_at", "legacy_code", "xero_code", "ixbrl_tag", "sub_category", "requires_beneficiary", "journal_entries", "transactions" ], "doesNot": [ "change_account_code", "reclassify_account", "set_opening_balance", "change_balance", "create_transaction", "create_journal_entry", "post_to_ledger", "file_vat_return", "file_ct600_return", "submit_to_hmrc", "move_money" ] }, "x-implementation": { "edgeFunction": "supabase/functions/financial-data-api/index.ts", "handler": "updateV1BusinessChartOfAccount", "tests": [ "supabase/functions/financial-data-api/invoice_idempotency.test.ts" ] } } }, "/v1/business/companies/{company_id}/projects": { "get": { "tags": [ "Business" ], "operationId": "listBusinessProjects", "summary": "List business projects", "description": "Lists projects for one accessible business company. This route is read-only and cannot create or update projects.", "security": [ { "ApiKeyAuth": [] } ], "parameters": [ { "$ref": "#/components/parameters/BusinessCompanyId" }, { "$ref": "#/components/parameters/RequestId" }, { "name": "search", "in": "query", "required": false, "description": "Search projects by name.", "schema": { "type": "string", "minLength": 1, "maxLength": 200 } }, { "name": "q", "in": "query", "required": false, "description": "Alias for search.", "schema": { "type": "string", "minLength": 1, "maxLength": 200 } }, { "name": "code", "in": "query", "required": false, "description": "Optional exact project code filter.", "schema": { "type": "string" } }, { "name": "is_active", "in": "query", "required": false, "description": "Optional active-state filter.", "schema": { "type": "boolean" } }, { "name": "active", "in": "query", "required": false, "description": "Legacy alias for is_active.", "schema": { "type": "boolean" } }, { "name": "limit", "in": "query", "required": false, "description": "Maximum number of projects to return. Values are clamped between 1 and 200.", "schema": { "type": "integer", "minimum": 1, "maximum": 200, "default": 100 } }, { "name": "offset", "in": "query", "required": false, "description": "Zero-based offset for paginating projects.", "schema": { "type": "integer", "minimum": 0, "default": 0 } } ], "responses": { "200": { "description": "Business projects returned.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1BusinessProjectListResponse" } } } }, "400": { "description": "A path or filter parameter is invalid.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1ErrorEnvelope" } } } }, "403": { "description": "The API key does not grant project or transaction access.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1ErrorEnvelope" } } } }, "404": { "description": "Business company not found or inaccessible.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1ErrorEnvelope" } } } }, "405": { "description": "Only GET and POST are allowed for this route.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1ErrorEnvelope" } } } }, "500": { "description": "Generic server failure. Internal database details must not be returned.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1ErrorEnvelope" } } } } }, "x-financial-iq-safety": { "scope": "business.projects.read", "requiredAnyPermission": [ "projects", "transactions" ], "businessMutation": false, "directFinancialMutation": false, "writeLevel": "read", "requiresIdempotencyKey": false, "auditedEndpoint": "v1/business/companies/{company_id}/projects" }, "x-implementation": { "edgeFunction": "supabase/functions/financial-data-api/index.ts", "handler": "handleV1BusinessProjects", "tests": [ "supabase/functions/financial-data-api/invoice_idempotency.test.ts" ] } }, "post": { "tags": [ "Business" ], "operationId": "createBusinessProject", "summary": "Create business project", "description": "Creates a business project for the company. This route requires projects permission and an Idempotency-Key. It creates setup data only and does not post ledger entries, create transactions, send documents, move money, or submit tax.", "security": [ { "ApiKeyAuth": [] } ], "parameters": [ { "$ref": "#/components/parameters/RequestId" }, { "$ref": "#/components/parameters/IdempotencyKey" }, { "$ref": "#/components/parameters/CompanyId" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BusinessProjectCreateRequest" } } } }, "responses": { "201": { "description": "Business project created.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BusinessProjectCreateResponse" } } } }, "400": { "description": "The request body or idempotency key is invalid.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1ErrorEnvelope" } } } }, "401": { "description": "Missing or invalid API key.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1ErrorEnvelope" } } } }, "403": { "description": "The API key does not have projects permission.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1ErrorEnvelope" } } } }, "404": { "description": "The company is not accessible to this API key.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1ErrorEnvelope" } } } }, "405": { "description": "Only GET and POST are allowed for this route.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1ErrorEnvelope" } } } }, "409": { "description": "The idempotency key conflicts with a different request body or an in-progress request.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1ErrorEnvelope" } } } }, "500": { "description": "Generic server failure. Internal database details must not be returned.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1ErrorEnvelope" } } } } }, "x-financial-iq-safety": { "requiresApiKey": true, "apiKeysAllowed": true, "requiresUserBearerToken": false, "requiredPermission": "projects", "businessMutation": true, "directFinancialMutation": false, "writeLevel": "configuration", "requiresIdempotencyKey": true, "auditedEndpoint": "v1/business/companies/{company_id}/projects", "scope": "business.projects.create" }, "x-implementation": { "edgeFunction": "supabase/functions/financial-data-api/index.ts", "handler": "createV1BusinessProject", "tests": [ "supabase/functions/financial-data-api/invoice_idempotency.test.ts" ] } } }, "/v1/business/companies/{company_id}/projects/{project_id}": { "get": { "tags": [ "Business" ], "operationId": "getBusinessProject", "summary": "Get one business project", "description": "Returns one project for an accessible business company. Inaccessible project IDs are returned as not found to avoid tenant leakage.", "security": [ { "ApiKeyAuth": [] } ], "parameters": [ { "$ref": "#/components/parameters/BusinessCompanyId" }, { "name": "project_id", "in": "path", "required": true, "description": "Project id to fetch.", "schema": { "type": "string", "format": "uuid" } }, { "$ref": "#/components/parameters/RequestId" } ], "responses": { "200": { "description": "Business project returned.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1BusinessProjectResponse" } } } }, "400": { "description": "The company_id or project_id path parameter is invalid.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1ErrorEnvelope" } } } }, "403": { "description": "The API key does not grant project or transaction access.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1ErrorEnvelope" } } } }, "404": { "description": "Business project not found.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1ErrorEnvelope" } } } }, "405": { "description": "Only GET and PATCH are allowed for this route.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1ErrorEnvelope" } } } }, "500": { "description": "Generic server failure. Internal database details must not be returned.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1ErrorEnvelope" } } } } }, "x-financial-iq-safety": { "scope": "business.projects.read", "requiredAnyPermission": [ "projects", "transactions" ], "businessMutation": false, "directFinancialMutation": false, "writeLevel": "read", "requiresIdempotencyKey": false, "auditedEndpoint": "v1/business/companies/{company_id}/projects/{project_id}" }, "x-implementation": { "edgeFunction": "supabase/functions/financial-data-api/index.ts", "handler": "handleV1BusinessProjectDetail", "tests": [ "supabase/functions/financial-data-api/invoice_idempotency.test.ts" ] } }, "patch": { "tags": [ "Business" ], "operationId": "updateBusinessProject", "summary": "Update business project", "description": "Updates safe setup fields for one business project in an accessible company. This route requires projects permission and an Idempotency-Key. It does not create transactions, post ledger entries, send documents, move money, or submit tax.", "security": [ { "ApiKeyAuth": [] } ], "parameters": [ { "name": "company_id", "in": "path", "required": true, "description": "Business company id the API key is allowed to access.", "schema": { "type": "string", "format": "uuid" } }, { "name": "project_id", "in": "path", "required": true, "description": "Business project id to update.", "schema": { "type": "string", "format": "uuid" } }, { "$ref": "#/components/parameters/RequestId" }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BusinessProjectUpdateRequest" } } } }, "responses": { "200": { "description": "Business project updated.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" }, "X-FIQ-Idempotency-Replayed": { "$ref": "#/components/headers/IdempotencyReplayed" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BusinessProjectUpdateResponse" } } } }, "400": { "description": "Invalid request body, missing Idempotency-Key, or invalid company_id/project_id path parameter.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1ErrorEnvelope" } } } }, "401": { "description": "Missing, invalid, expired or inactive API key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LegacyErrorResponse" } } } }, "403": { "description": "The API key does not grant projects permission.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1ErrorEnvelope" } } } }, "404": { "description": "Business project not found.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1ErrorEnvelope" } } } }, "405": { "description": "Only GET and PATCH are allowed for this route.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1ErrorEnvelope" } } } }, "409": { "description": "The idempotency key conflicts with a different request body.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1ErrorEnvelope" } } } }, "500": { "description": "Generic server failure. Internal database details must not be returned.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1ErrorEnvelope" } } } } }, "x-financial-iq-safety": { "requiresApiKey": true, "scope": "business.projects.update", "requiredPermission": "projects", "directFinancialMutation": false, "businessMutation": true, "writeLevel": "project_configuration", "requiresIdempotencyKey": true, "auditedEndpoint": "v1/business/companies/{company_id}/projects/{project_id}", "forbiddenFields": [ "id", "company_id", "created_at", "updated_at", "invoice_ids", "purchase_invoice_ids", "transaction_ids", "ledger_entries", "actual_income", "actual_costs" ], "doesNot": [ "move_project_between_companies", "create_transactions", "post_ledger_entries", "send_documents", "file_tax_returns", "move_money" ] }, "x-implementation": { "edgeFunction": "supabase/functions/financial-data-api/index.ts", "handler": "updateV1BusinessProject", "tests": [ "supabase/functions/financial-data-api/invoice_idempotency.test.ts" ] } } }, "/v1/business/companies/{company_id}/funds": { "get": { "tags": [ "Business" ], "operationId": "listBusinessFunds", "summary": "List business funds", "description": "Lists funds for one accessible business company. This route is read-only and helps agents pick valid fund dimensions before categorising or creating records.", "security": [ { "ApiKeyAuth": [] } ], "parameters": [ { "$ref": "#/components/parameters/BusinessCompanyId" }, { "$ref": "#/components/parameters/RequestId" }, { "name": "search", "in": "query", "required": false, "description": "Search funds by name.", "schema": { "type": "string", "minLength": 1, "maxLength": 200 } }, { "name": "q", "in": "query", "required": false, "description": "Alias for search.", "schema": { "type": "string", "minLength": 1, "maxLength": 200 } }, { "name": "code", "in": "query", "required": false, "description": "Optional exact fund code filter.", "schema": { "type": "string" } }, { "name": "fund_type", "in": "query", "required": false, "description": "Optional fund type filter.", "schema": { "type": "string" } }, { "name": "fund_class", "in": "query", "required": false, "description": "Optional reporting fund class filter.", "schema": { "type": "string" } }, { "name": "is_default", "in": "query", "required": false, "description": "Optional default-fund filter.", "schema": { "type": "boolean" } }, { "name": "is_active", "in": "query", "required": false, "description": "Optional active-state filter.", "schema": { "type": "boolean" } }, { "name": "active", "in": "query", "required": false, "description": "Legacy alias for is_active.", "schema": { "type": "boolean" } }, { "name": "is_closed", "in": "query", "required": false, "description": "Optional closed-state filter.", "schema": { "type": "boolean" } }, { "name": "limit", "in": "query", "required": false, "description": "Maximum number of funds to return. Values are clamped between 1 and 200.", "schema": { "type": "integer", "minimum": 1, "maximum": 200, "default": 100 } }, { "name": "offset", "in": "query", "required": false, "description": "Zero-based offset for paginating fund results.", "schema": { "type": "integer", "minimum": 0, "default": 0 } } ], "responses": { "200": { "description": "Business funds returned.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1BusinessFundListResponse" } } } }, "400": { "description": "A path or filter parameter is invalid.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1ErrorEnvelope" } } } }, "401": { "description": "Missing, invalid, expired or inactive API key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LegacyErrorResponse" } } } }, "403": { "description": "The API key does not grant funds, transaction or report access.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1ErrorEnvelope" } } } }, "404": { "description": "Business company not found or inaccessible.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1ErrorEnvelope" } } } }, "405": { "description": "Only GET and POST are allowed for this route.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1ErrorEnvelope" } } } }, "500": { "description": "Generic server failure. Internal database details must not be returned.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1ErrorEnvelope" } } } } }, "x-financial-iq-safety": { "scope": "business.funds.read", "businessMutation": false, "directFinancialMutation": false, "writeLevel": "read", "requiresIdempotencyKey": false, "auditedEndpoint": "v1/business/companies/{company_id}/funds", "requiredAnyPermission": [ "funds", "transactions", "reports" ] }, "x-implementation": { "edgeFunction": "supabase/functions/financial-data-api/index.ts", "handler": "handleV1BusinessFunds", "tests": [ "supabase/functions/financial-data-api/invoice_idempotency.test.ts" ] } }, "post": { "tags": [ "Business" ], "operationId": "createBusinessFund", "summary": "Create business fund", "description": "Creates a fund record for an accessible business company. This route requires funds permission and an Idempotency-Key. It creates setup data only and does not create transactions, post ledger entries, change the default fund, close funds, submit Gift Aid claims or move money.", "security": [ { "ApiKeyAuth": [] } ], "parameters": [ { "$ref": "#/components/parameters/BusinessCompanyId" }, { "$ref": "#/components/parameters/RequestId" }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BusinessFundCreateRequest" } } } }, "responses": { "201": { "description": "Business fund created.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BusinessFundCreateResponse" } } } }, "400": { "description": "The request body, idempotency key or company_id path parameter is invalid.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1ErrorEnvelope" } } } }, "401": { "description": "Missing or invalid API key.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1ErrorEnvelope" } } } }, "403": { "description": "The API key does not have funds permission.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1ErrorEnvelope" } } } }, "404": { "description": "The company is not accessible to this API key.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1ErrorEnvelope" } } } }, "405": { "description": "Only GET and POST are allowed for this route.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1ErrorEnvelope" } } } }, "409": { "description": "The fund name or code already exists, or the idempotency key conflicts with another request.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1ErrorEnvelope" } } } }, "500": { "description": "Generic server failure. Internal database details must not be returned.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1ErrorEnvelope" } } } } }, "x-financial-iq-safety": { "requiresApiKey": true, "apiKeysAllowed": true, "requiresUserBearerToken": false, "scope": "business.funds.create", "requiredPermission": "funds", "businessMutation": true, "directFinancialMutation": false, "writeLevel": "configuration", "requiresIdempotencyKey": true, "auditedEndpoint": "v1/business/companies/{company_id}/funds" }, "x-implementation": { "edgeFunction": "supabase/functions/financial-data-api/index.ts", "handler": "createV1BusinessFund", "tests": [ "supabase/functions/financial-data-api/invoice_idempotency.test.ts" ] } } }, "/v1/business/companies/{company_id}/funds/{fund_id}": { "get": { "tags": [ "Business" ], "operationId": "getBusinessFund", "summary": "Get one business fund", "description": "Returns one fund for an accessible business company. Inaccessible fund IDs are returned as not found to avoid tenant leakage.", "security": [ { "ApiKeyAuth": [] } ], "parameters": [ { "$ref": "#/components/parameters/BusinessCompanyId" }, { "name": "fund_id", "in": "path", "required": true, "description": "Fund id to fetch.", "schema": { "type": "string", "format": "uuid" } }, { "$ref": "#/components/parameters/RequestId" } ], "responses": { "200": { "description": "Business fund returned.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1BusinessFundResponse" } } } }, "400": { "description": "The company_id or fund_id path parameter is invalid.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1ErrorEnvelope" } } } }, "401": { "description": "Missing, invalid, expired or inactive API key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LegacyErrorResponse" } } } }, "403": { "description": "The API key does not grant funds, transaction or report access.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1ErrorEnvelope" } } } }, "404": { "description": "Business fund not found.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1ErrorEnvelope" } } } }, "405": { "description": "Only GET is allowed for this route.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1ErrorEnvelope" } } } }, "500": { "description": "Generic server failure. Internal database details must not be returned.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1ErrorEnvelope" } } } } }, "x-financial-iq-safety": { "scope": "business.funds.read", "businessMutation": false, "directFinancialMutation": false, "writeLevel": "read", "requiresIdempotencyKey": false, "auditedEndpoint": "v1/business/companies/{company_id}/funds/{fund_id}", "requiredAnyPermission": [ "funds", "transactions", "reports" ] }, "x-implementation": { "edgeFunction": "supabase/functions/financial-data-api/index.ts", "handler": "handleV1BusinessFundDetail", "tests": [ "supabase/functions/financial-data-api/invoice_idempotency.test.ts" ] } }, "patch": { "tags": [ "Business" ], "operationId": "updateBusinessFund", "summary": "Update business fund", "description": "Updates safe setup fields for one business fund in an accessible company. This route requires funds permission and an Idempotency-Key. It does not create transactions, post ledger entries, change the default fund, close funds, reclassify funds, submit Gift Aid claims, file tax returns or move money.", "security": [ { "ApiKeyAuth": [] } ], "parameters": [ { "$ref": "#/components/parameters/BusinessCompanyId" }, { "name": "fund_id", "in": "path", "required": true, "description": "Business fund id to update.", "schema": { "type": "string", "format": "uuid" } }, { "$ref": "#/components/parameters/RequestId" }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BusinessFundUpdateRequest" } } } }, "responses": { "200": { "description": "Business fund updated.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" }, "X-FIQ-Idempotency-Replayed": { "$ref": "#/components/headers/IdempotencyReplayed" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BusinessFundUpdateResponse" } } } }, "400": { "description": "Invalid request body, missing Idempotency-Key, or invalid company_id/fund_id path parameter.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1ErrorEnvelope" } } } }, "401": { "description": "Missing, invalid, expired or inactive API key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LegacyErrorResponse" } } } }, "403": { "description": "The API key does not grant funds permission.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1ErrorEnvelope" } } } }, "404": { "description": "Business fund not found.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1ErrorEnvelope" } } } }, "405": { "description": "Only GET and PATCH are allowed for this route.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1ErrorEnvelope" } } } }, "409": { "description": "The idempotency key conflicts with a different request body, or the fund name/code already exists.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1ErrorEnvelope" } } } }, "500": { "description": "Generic server failure. Internal database details must not be returned.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1ErrorEnvelope" } } } } }, "x-financial-iq-safety": { "requiresApiKey": true, "scope": "business.funds.update", "requiredPermission": "funds", "directFinancialMutation": false, "businessMutation": true, "writeLevel": "fund_configuration", "requiresIdempotencyKey": true, "auditedEndpoint": "v1/business/companies/{company_id}/funds/{fund_id}", "forbiddenFields": [ "id", "company_id", "created_at", "updated_at", "fund_class", "fund_type", "unrestricted_subtype", "endowment_subtype", "is_default", "is_closed", "closed_on", "transaction_ids", "ledger_entries", "actual_balances" ], "doesNot": [ "move_fund_between_companies", "change_default_fund", "close_funds", "reclassify_funds", "create_transactions", "post_ledger_entries", "submit_gift_aid_claims", "file_tax_returns", "move_money" ] }, "x-implementation": { "edgeFunction": "supabase/functions/financial-data-api/index.ts", "handler": "updateV1BusinessFund", "tests": [ "supabase/functions/financial-data-api/invoice_idempotency.test.ts" ] } } }, "/v1/business/companies/{company_id}/gift-aid-donors": { "get": { "tags": [ "Business" ], "operationId": "listBusinessGiftAidDonors", "summary": "List business Gift Aid donors", "description": "Lists Gift Aid donor records for an accessible business company. This route is read-only and contains donor contact data.", "security": [ { "ApiKeyAuth": [] } ], "parameters": [ { "name": "company_id", "in": "path", "required": true, "description": "Business company id.", "schema": { "type": "string", "format": "uuid" } }, { "$ref": "#/components/parameters/RequestId" }, { "name": "status", "in": "query", "required": false, "description": "Optional active-state filter.", "schema": { "type": "string", "enum": [ "active", "inactive" ] } }, { "name": "external_id", "in": "query", "required": false, "description": "Optional external donor reference filter.", "schema": { "type": "string", "minLength": 1, "maxLength": 200 } }, { "name": "search", "in": "query", "required": false, "description": "Search donors by last name.", "schema": { "type": "string", "minLength": 1, "maxLength": 200 } }, { "name": "q", "in": "query", "required": false, "description": "Alias for search.", "schema": { "type": "string", "minLength": 1, "maxLength": 200 } }, { "name": "limit", "in": "query", "required": false, "description": "Maximum number of donors to return. Values are clamped between 1 and 200.", "schema": { "type": "integer", "minimum": 1, "maximum": 200, "default": 100 } }, { "name": "offset", "in": "query", "required": false, "description": "Zero-based offset for paginating donor results.", "schema": { "type": "integer", "minimum": 0, "default": 0 } } ], "responses": { "200": { "description": "Accessible Gift Aid donors returned.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1BusinessGiftAidDonorListResponse" } } } }, "400": { "description": "Invalid path or query parameter.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1ErrorEnvelope" } } } }, "403": { "description": "The API key does not have Gift Aid permission.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1ErrorEnvelope" } } } }, "404": { "description": "The business company is not accessible.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1ErrorEnvelope" } } } }, "405": { "description": "Only GET and POST are allowed for this route.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1ErrorEnvelope" } } } }, "500": { "description": "Gift Aid donors could not be fetched.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1ErrorEnvelope" } } } } }, "x-financial-iq-safety": { "scope": "business.gift_aid_donors.read", "businessMutation": false, "directFinancialMutation": false, "writeLevel": "read", "requiresIdempotencyKey": false, "auditedEndpoint": "v1/business/companies/{company_id}/gift-aid-donors", "requiredPermission": "gift_aid", "containsPersonalData": true }, "x-implementation": { "handler": "handleV1BusinessGiftAidDonors" } }, "post": { "tags": [ "Business" ], "operationId": "createBusinessGiftAidDonor", "summary": "Create business Gift Aid donor", "description": "Creates a Gift Aid donor record for an accessible business company. This route stores personal contact data, requires gift_aid permission and an Idempotency-Key, and does not create declarations, donations, claim batches, bank transactions or HMRC submissions.", "security": [ { "ApiKeyAuth": [] } ], "parameters": [ { "$ref": "#/components/parameters/BusinessCompanyId" }, { "$ref": "#/components/parameters/RequestId" }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BusinessGiftAidDonorCreateRequest" } } } }, "responses": { "201": { "description": "Business Gift Aid donor created.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BusinessGiftAidDonorCreateResponse" } } } }, "400": { "description": "The request body, idempotency key or company_id path parameter is invalid.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1ErrorEnvelope" } } } }, "401": { "description": "Missing or invalid API key.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1ErrorEnvelope" } } } }, "403": { "description": "The API key does not have Gift Aid permission.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1ErrorEnvelope" } } } }, "404": { "description": "The company is not accessible to this API key.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1ErrorEnvelope" } } } }, "405": { "description": "Only GET and POST are allowed for this route.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1ErrorEnvelope" } } } }, "409": { "description": "The donor external_id already exists, or the idempotency key conflicts with another request.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1ErrorEnvelope" } } } }, "500": { "description": "Generic server failure. Internal database details must not be returned.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1ErrorEnvelope" } } } } }, "x-financial-iq-safety": { "requiresApiKey": true, "apiKeysAllowed": true, "requiresUserBearerToken": false, "scope": "business.gift_aid_donors.create", "requiredPermission": "gift_aid", "containsPersonalData": true, "businessMutation": true, "directFinancialMutation": false, "writeLevel": "configuration", "requiresIdempotencyKey": true, "auditedEndpoint": "v1/business/companies/{company_id}/gift-aid-donors" }, "x-implementation": { "edgeFunction": "supabase/functions/financial-data-api/index.ts", "handler": "createV1BusinessGiftAidDonor", "tests": [ "supabase/functions/financial-data-api/invoice_idempotency.test.ts" ] } } }, "/v1/business/companies/{company_id}/gift-aid-donors/{donor_id}": { "get": { "tags": [ "Business" ], "operationId": "getBusinessGiftAidDonor", "summary": "Get a business Gift Aid donor", "description": "Returns one Gift Aid donor for an accessible business company. Inaccessible donor ids return not found.", "security": [ { "ApiKeyAuth": [] } ], "parameters": [ { "name": "company_id", "in": "path", "required": true, "description": "Business company id.", "schema": { "type": "string", "format": "uuid" } }, { "name": "donor_id", "in": "path", "required": true, "description": "Gift Aid donor id.", "schema": { "type": "string", "format": "uuid" } }, { "$ref": "#/components/parameters/RequestId" } ], "responses": { "200": { "description": "Accessible Gift Aid donor returned.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1BusinessGiftAidDonorResponse" } } } }, "400": { "description": "The company_id or donor_id path parameter is not a valid UUID.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1ErrorEnvelope" } } } }, "403": { "description": "The API key does not have Gift Aid permission.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1ErrorEnvelope" } } } }, "404": { "description": "The Gift Aid donor is not accessible.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1ErrorEnvelope" } } } }, "405": { "description": "Only GET and PATCH are allowed for this route.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1ErrorEnvelope" } } } }, "500": { "description": "The Gift Aid donor could not be fetched.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1ErrorEnvelope" } } } } }, "x-financial-iq-safety": { "scope": "business.gift_aid_donors.read", "businessMutation": false, "directFinancialMutation": false, "writeLevel": "read", "requiresIdempotencyKey": false, "auditedEndpoint": "v1/business/companies/{company_id}/gift-aid-donors/{donor_id}", "requiredPermission": "gift_aid", "containsPersonalData": true }, "x-implementation": { "handler": "handleV1BusinessGiftAidDonorDetail" } }, "patch": { "tags": [ "Business" ], "operationId": "updateBusinessGiftAidDonor", "summary": "Update business Gift Aid donor", "description": "Updates safe profile fields for one Gift Aid donor in an accessible business company. Requires Gift Aid API-key permission and Idempotency-Key. The route does not create declarations, donations, claim batches, ledger entries or HMRC submissions.", "security": [ { "ApiKeyAuth": [] } ], "parameters": [ { "name": "company_id", "in": "path", "required": true, "description": "Business company id.", "schema": { "type": "string", "format": "uuid" } }, { "name": "donor_id", "in": "path", "required": true, "description": "Gift Aid donor id.", "schema": { "type": "string", "format": "uuid" } }, { "$ref": "#/components/parameters/RequestId" }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BusinessGiftAidDonorUpdateRequest" } } } }, "responses": { "200": { "description": "Gift Aid donor updated.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" }, "X-FIQ-Idempotency-Replayed": { "$ref": "#/components/headers/IdempotencyReplayed" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BusinessGiftAidDonorUpdateResponse" } } } }, "400": { "description": "Invalid request body, missing Idempotency-Key, or invalid company_id/donor_id path parameter.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1ErrorEnvelope" } } } }, "401": { "description": "Missing, invalid, expired or inactive API key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LegacyErrorResponse" } } } }, "403": { "description": "The API key does not grant Gift Aid permission.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1ErrorEnvelope" } } } }, "404": { "description": "Gift Aid donor not found.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1ErrorEnvelope" } } } }, "405": { "description": "Only GET and PATCH are allowed for this route.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1ErrorEnvelope" } } } }, "409": { "description": "Gift Aid donor external_id already exists.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1ErrorEnvelope" } } } }, "500": { "description": "Generic server failure. Internal database details must not be returned.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1ErrorEnvelope" } } } } }, "x-financial-iq-safety": { "requiresApiKey": true, "apiKeysAllowed": true, "requiresUserBearerToken": false, "scope": "business.gift_aid_donors.update", "requiredPermission": "gift_aid", "containsPersonalData": true, "businessMutation": true, "directFinancialMutation": false, "writeLevel": "configuration", "requiresIdempotencyKey": true, "auditedEndpoint": "v1/business/companies/{company_id}/gift-aid-donors/{donor_id}", "forbiddenFields": [ "id", "company_id", "created_at", "updated_at", "declaration_date", "declaration_type", "donation_date", "gross_amount", "claim_batch_id", "hmrc_submission_id", "ledger_entries", "bank_transaction_ids", "spouse_donor_id", "gift_aid_split" ], "doesNot": [ "create_gift_aid_declarations", "create_gift_aid_donations", "create_claim_batches", "submit_hmrc_claims", "create_bank_transactions", "post_ledger_entries", "move_money", "delete_donors" ] }, "x-implementation": { "handler": "updateV1BusinessGiftAidDonor", "sourceFile": "supabase/functions/financial-data-api/v1.ts" } } }, "/v1/business/companies/{company_id}/gift-aid-declarations": { "get": { "tags": [ "Business" ], "operationId": "listBusinessGiftAidDeclarations", "summary": "List business Gift Aid declarations", "description": "Lists Gift Aid declaration records for an accessible business company. This route is read-only and contains donor contact and declaration evidence data.", "security": [ { "ApiKeyAuth": [] } ], "parameters": [ { "name": "company_id", "in": "path", "required": true, "description": "Business company id.", "schema": { "type": "string", "format": "uuid" } }, { "$ref": "#/components/parameters/RequestId" }, { "name": "donor_id", "in": "query", "required": false, "description": "Optional donor id filter.", "schema": { "type": "string", "format": "uuid" } }, { "name": "status", "in": "query", "required": false, "description": "Optional declaration status filter.", "schema": { "type": "string", "enum": [ "active", "expired", "cancelled" ] } }, { "name": "declaration_type", "in": "query", "required": false, "description": "Optional declaration type filter.", "schema": { "type": "string", "enum": [ "single", "ongoing", "retrospective_ongoing" ] } }, { "name": "channel", "in": "query", "required": false, "description": "Optional collection channel filter.", "schema": { "type": "string", "enum": [ "paper", "online", "phone", "email" ] } }, { "name": "date_from", "in": "query", "required": false, "description": "Only return declarations made on or after this date.", "schema": { "type": "string", "format": "date" } }, { "name": "date_to", "in": "query", "required": false, "description": "Only return declarations made on or before this date.", "schema": { "type": "string", "format": "date" } }, { "name": "limit", "in": "query", "required": false, "description": "Maximum number of declarations to return. Values are clamped between 1 and 200.", "schema": { "type": "integer", "minimum": 1, "maximum": 200, "default": 100 } }, { "name": "offset", "in": "query", "required": false, "description": "Zero-based offset for paginating declaration results.", "schema": { "type": "integer", "minimum": 0, "default": 0 } } ], "responses": { "200": { "description": "Accessible Gift Aid declarations returned.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1BusinessGiftAidDeclarationListResponse" } } } }, "400": { "description": "Invalid path or query parameter.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1ErrorEnvelope" } } } }, "403": { "description": "The API key does not have Gift Aid permission.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1ErrorEnvelope" } } } }, "404": { "description": "The business company is not accessible.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1ErrorEnvelope" } } } }, "405": { "description": "Only GET and POST are allowed for this endpoint.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1ErrorEnvelope" } } } }, "500": { "description": "Gift Aid donors could not be fetched.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1ErrorEnvelope" } } } } }, "x-financial-iq-safety": { "scope": "business.gift_aid_declarations.read", "businessMutation": false, "directFinancialMutation": false, "writeLevel": "read", "requiresIdempotencyKey": false, "auditedEndpoint": "v1/business/companies/{company_id}/gift-aid-declarations", "requiredPermission": "gift_aid", "containsPersonalData": true }, "x-implementation": { "handler": "handleV1BusinessGiftAidDeclarations" } }, "post": { "tags": [ "Business" ], "operationId": "createBusinessGiftAidDeclaration", "summary": "Create business Gift Aid declaration", "description": "Creates one setup-only Gift Aid declaration for an existing donor. This stores declaration evidence but does not create donations, bank transactions, claim batches, HMRC submissions, cancellations or replacement declarations.", "security": [ { "ApiKeyAuth": [] } ], "parameters": [ { "name": "company_id", "in": "path", "required": true, "description": "Business company id.", "schema": { "type": "string", "format": "uuid" } }, { "$ref": "#/components/parameters/RequestId" }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BusinessGiftAidDeclarationCreateRequest" } } } }, "responses": { "201": { "description": "Gift Aid declaration created.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BusinessGiftAidDeclarationCreateResponse" } } } }, "400": { "description": "Invalid declaration payload, path parameter, donor reference or idempotency key.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1ErrorEnvelope" } } } }, "401": { "description": "The API key is missing or invalid.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1ErrorEnvelope" } } } }, "403": { "description": "The API key does not have Gift Aid permission.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1ErrorEnvelope" } } } }, "404": { "description": "The business company is not accessible.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1ErrorEnvelope" } } } }, "405": { "description": "Only GET and POST are allowed for this endpoint.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1ErrorEnvelope" } } } }, "409": { "description": "The idempotency key is already in use for a different request.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1ErrorEnvelope" } } } }, "500": { "description": "The Gift Aid declaration could not be created.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1ErrorEnvelope" } } } } }, "x-financial-iq-safety": { "scope": "business.gift_aid_declarations.create", "businessMutation": true, "directFinancialMutation": false, "writeLevel": "configuration", "requiresIdempotencyKey": true, "auditedEndpoint": "v1/business/companies/{company_id}/gift-aid-declarations", "requiredPermission": "gift_aid", "containsPersonalData": true }, "x-implementation": { "handler": "createV1BusinessGiftAidDeclaration", "tests": [ "supabase/functions/financial-data-api/invoice_idempotency.test.ts" ] } } }, "/v1/business/companies/{company_id}/gift-aid-declarations/{declaration_id}": { "get": { "tags": [ "Business" ], "operationId": "getBusinessGiftAidDeclaration", "summary": "Get business Gift Aid declaration", "description": "Returns one Gift Aid declaration for an accessible business company. Inaccessible declaration ids return not found.", "security": [ { "ApiKeyAuth": [] } ], "parameters": [ { "name": "company_id", "in": "path", "required": true, "description": "Business company id.", "schema": { "type": "string", "format": "uuid" } }, { "name": "declaration_id", "in": "path", "required": true, "description": "Gift Aid declaration id.", "schema": { "type": "string", "format": "uuid" } }, { "$ref": "#/components/parameters/RequestId" } ], "responses": { "200": { "description": "Accessible Gift Aid declaration returned.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1BusinessGiftAidDeclarationResponse" } } } }, "400": { "description": "The company_id or donor_id path parameter is not a valid UUID.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1ErrorEnvelope" } } } }, "403": { "description": "The API key does not have Gift Aid permission.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1ErrorEnvelope" } } } }, "404": { "description": "The Gift Aid declaration was not found or is not accessible.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1ErrorEnvelope" } } } }, "405": { "description": "Only GET is allowed for this endpoint.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1ErrorEnvelope" } } } }, "500": { "description": "The Gift Aid donor could not be fetched.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1ErrorEnvelope" } } } } }, "x-financial-iq-safety": { "scope": "business.gift_aid_declarations.read", "businessMutation": false, "directFinancialMutation": false, "writeLevel": "read", "requiresIdempotencyKey": false, "auditedEndpoint": "v1/business/companies/{company_id}/gift-aid-declarations/{declaration_id}", "requiredPermission": "gift_aid", "containsPersonalData": true }, "x-implementation": { "handler": "handleV1BusinessGiftAidDeclarationDetail" } } }, "/v1/business/companies/{company_id}/gift-aid-donations": { "get": { "tags": [ "Business" ], "operationId": "listBusinessGiftAidDonations", "summary": "List business Gift Aid donations", "description": "Lists Gift Aid donation records for an accessible business company. This route is read-only and contains donor contact data and donation amounts.", "security": [ { "ApiKeyAuth": [] } ], "parameters": [ { "name": "company_id", "in": "path", "required": true, "description": "Business company id.", "schema": { "type": "string", "format": "uuid" } }, { "$ref": "#/components/parameters/RequestId" }, { "name": "donor_id", "in": "query", "required": false, "description": "Optional donor id filter.", "schema": { "type": "string", "format": "uuid" } }, { "name": "declaration_id", "in": "query", "required": false, "description": "Optional Gift Aid declaration id filter.", "schema": { "type": "string", "format": "uuid" } }, { "name": "bank_transaction_id", "in": "query", "required": false, "description": "Optional linked bank transaction id filter.", "schema": { "type": "string", "format": "uuid" } }, { "name": "fund_id", "in": "query", "required": false, "description": "Optional fund id filter.", "schema": { "type": "string", "format": "uuid" } }, { "name": "claim_status", "in": "query", "required": false, "description": "Optional Gift Aid claim status filter.", "schema": { "type": "string", "enum": [ "pending", "submitted", "accepted", "rejected", "rejected_fixable" ] } }, { "name": "gift_aid_eligible", "in": "query", "required": false, "description": "Optional eligibility filter.", "schema": { "type": "boolean" } }, { "name": "date_from", "in": "query", "required": false, "description": "Only return donations made on or after this date.", "schema": { "type": "string", "format": "date" } }, { "name": "date_to", "in": "query", "required": false, "description": "Only return donations made on or before this date.", "schema": { "type": "string", "format": "date" } }, { "name": "limit", "in": "query", "required": false, "description": "Maximum number of donations to return. Values are clamped between 1 and 200.", "schema": { "type": "integer", "minimum": 1, "maximum": 200, "default": 100 } }, { "name": "offset", "in": "query", "required": false, "description": "Zero-based offset for paginating donation results.", "schema": { "type": "integer", "minimum": 0, "default": 0 } } ], "responses": { "200": { "description": "Accessible Gift Aid donations returned.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1BusinessGiftAidDonationListResponse" } } } }, "400": { "description": "Invalid path or query parameter.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1ErrorEnvelope" } } } }, "403": { "description": "The API key does not have Gift Aid permission.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1ErrorEnvelope" } } } }, "404": { "description": "The business company is not accessible.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1ErrorEnvelope" } } } }, "405": { "description": "Only GET and POST are allowed for this endpoint.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1ErrorEnvelope" } } } }, "500": { "description": "Gift Aid donors could not be fetched.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1ErrorEnvelope" } } } } }, "x-financial-iq-safety": { "scope": "business.gift_aid_donations.read", "businessMutation": false, "directFinancialMutation": false, "writeLevel": "read", "requiresIdempotencyKey": false, "auditedEndpoint": "v1/business/companies/{company_id}/gift-aid-donations", "requiredPermission": "gift_aid", "containsPersonalData": true }, "x-implementation": { "handler": "handleV1BusinessGiftAidDonations" } }, "post": { "tags": [ "Business" ], "operationId": "createBusinessGiftAidDonation", "summary": "Create business Gift Aid donation", "description": "Creates one pending Gift Aid donation record for an existing donor. The route validates company-owned donor, declaration, fund and bank transaction references before writing. It does not create bank transactions, claim batches, claim items, HMRC submissions or accepted/rejected claim outcomes.", "security": [ { "ApiKeyAuth": [] } ], "parameters": [ { "name": "company_id", "in": "path", "required": true, "description": "Business company id.", "schema": { "type": "string", "format": "uuid" } }, { "$ref": "#/components/parameters/RequestId" }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BusinessGiftAidDonationCreateRequest" } } } }, "responses": { "201": { "description": "Gift Aid donation created as pending.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BusinessGiftAidDonationCreateResponse" } } } }, "400": { "description": "Invalid donation payload, path parameter, reference or idempotency key.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1ErrorEnvelope" } } } }, "401": { "description": "The API key is missing or invalid.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1ErrorEnvelope" } } } }, "403": { "description": "The API key does not have Gift Aid permission.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1ErrorEnvelope" } } } }, "404": { "description": "The business company is not accessible.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1ErrorEnvelope" } } } }, "405": { "description": "Only GET and POST are allowed for this endpoint.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1ErrorEnvelope" } } } }, "409": { "description": "The idempotency key is already in use for a different request.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1ErrorEnvelope" } } } }, "500": { "description": "The Gift Aid donation could not be created.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1ErrorEnvelope" } } } } }, "x-financial-iq-safety": { "scope": "business.gift_aid_donations.create", "businessMutation": true, "directFinancialMutation": true, "writeLevel": "ledger_write", "requiresIdempotencyKey": true, "auditedEndpoint": "v1/business/companies/{company_id}/gift-aid-donations", "requiredPermission": "gift_aid", "containsPersonalData": true, "forbiddenInThisRoute": [ "create bank transaction", "change bank transaction matching state", "create Gift Aid claim batch", "create Gift Aid claim item", "submit Gift Aid claim to HMRC", "set submitted, accepted or rejected claim status", "post to ledger", "make bank payment", "close accounting period" ] }, "x-implementation": { "handler": "createV1BusinessGiftAidDonation", "tests": [ "supabase/functions/financial-data-api/invoice_idempotency.test.ts" ] } } }, "/v1/business/companies/{company_id}/gift-aid-donations/{donation_id}": { "get": { "tags": [ "Business" ], "operationId": "getBusinessGiftAidDonation", "summary": "Get business Gift Aid donation", "description": "Returns one Gift Aid donation for an accessible business company. Inaccessible donation ids return not found.", "security": [ { "ApiKeyAuth": [] } ], "parameters": [ { "name": "company_id", "in": "path", "required": true, "description": "Business company id.", "schema": { "type": "string", "format": "uuid" } }, { "name": "donation_id", "in": "path", "required": true, "description": "Gift Aid donation id.", "schema": { "type": "string", "format": "uuid" } }, { "$ref": "#/components/parameters/RequestId" } ], "responses": { "200": { "description": "Accessible Gift Aid donation returned.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1BusinessGiftAidDonationResponse" } } } }, "400": { "description": "The company_id or donor_id path parameter is not a valid UUID.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1ErrorEnvelope" } } } }, "403": { "description": "The API key does not have Gift Aid permission.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1ErrorEnvelope" } } } }, "404": { "description": "The Gift Aid donation was not found or is not accessible.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1ErrorEnvelope" } } } }, "405": { "description": "Only GET is allowed for this endpoint.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1ErrorEnvelope" } } } }, "500": { "description": "The Gift Aid donor could not be fetched.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1ErrorEnvelope" } } } } }, "x-financial-iq-safety": { "scope": "business.gift_aid_donations.read", "businessMutation": false, "directFinancialMutation": false, "writeLevel": "read", "requiresIdempotencyKey": false, "auditedEndpoint": "v1/business/companies/{company_id}/gift-aid-donations/{donation_id}", "requiredPermission": "gift_aid", "containsPersonalData": true }, "x-implementation": { "handler": "handleV1BusinessGiftAidDonationDetail" } } }, "/v1/business/companies/{company_id}/gift-aid-claim-batches": { "get": { "tags": [ "Business" ], "operationId": "listBusinessGiftAidClaimBatches", "summary": "List business Gift Aid claim batches", "description": "Lists Gift Aid and GASDS claim batches for an accessible business company. This route is read-only and does not submit claims.", "security": [ { "ApiKeyAuth": [] } ], "parameters": [ { "name": "company_id", "in": "path", "required": true, "description": "Business company id.", "schema": { "type": "string", "format": "uuid" } }, { "$ref": "#/components/parameters/RequestId" }, { "name": "status", "in": "query", "required": false, "description": "Optional claim batch status filter.", "schema": { "type": "string", "enum": [ "draft", "ready", "submitted", "accepted", "rejected", "partially_accepted" ] } }, { "name": "claim_type", "in": "query", "required": false, "description": "Optional claim type filter.", "schema": { "type": "string", "enum": [ "gift_aid", "gasds", "combined" ] } }, { "name": "batch_reference", "in": "query", "required": false, "description": "Optional exact batch reference filter.", "schema": { "type": "string", "minLength": 1, "maxLength": 200 } }, { "name": "date_from", "in": "query", "required": false, "description": "Only return batches whose period starts on or after this date.", "schema": { "type": "string", "format": "date" } }, { "name": "date_to", "in": "query", "required": false, "description": "Only return batches whose period ends on or before this date.", "schema": { "type": "string", "format": "date" } }, { "name": "limit", "in": "query", "required": false, "description": "Maximum number of claim batches to return. Values are clamped between 1 and 200.", "schema": { "type": "integer", "minimum": 1, "maximum": 200, "default": 50 } }, { "name": "offset", "in": "query", "required": false, "description": "Zero-based offset for paginating claim batch results.", "schema": { "type": "integer", "minimum": 0, "default": 0 } } ], "responses": { "200": { "description": "Accessible Gift Aid claim batches returned.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1BusinessGiftAidClaimBatchListResponse" } } } }, "400": { "description": "Invalid path or query parameter.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1ErrorEnvelope" } } } }, "403": { "description": "The API key does not have Gift Aid permission.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1ErrorEnvelope" } } } }, "404": { "description": "The business company is not accessible.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1ErrorEnvelope" } } } }, "405": { "description": "Only GET and POST are allowed for this endpoint.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1ErrorEnvelope" } } } }, "500": { "description": "Gift Aid claim batches could not be fetched.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1ErrorEnvelope" } } } } }, "x-financial-iq-safety": { "scope": "business.gift_aid_claim_batches.read", "businessMutation": false, "directFinancialMutation": false, "writeLevel": "read", "requiresIdempotencyKey": false, "auditedEndpoint": "v1/business/companies/{company_id}/gift-aid-claim-batches", "requiredPermission": "gift_aid", "containsPersonalData": true }, "x-implementation": { "handler": "handleV1BusinessGiftAidClaimBatches" } }, "post": { "tags": [ "Business" ], "operationId": "createBusinessGiftAidClaimBatch", "summary": "Create business Gift Aid claim batch", "description": "Creates one draft Gift Aid or GASDS claim batch for an accessible business company. The route only creates the draft container with zero totals. It does not attach donations, generate HMRC XML, submit or amend a claim, change donation claim statuses, post ledger entries, file tax returns or move money.", "security": [ { "ApiKeyAuth": [] } ], "parameters": [ { "name": "company_id", "in": "path", "required": true, "description": "Business company id.", "schema": { "type": "string", "format": "uuid" } }, { "$ref": "#/components/parameters/RequestId" }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BusinessGiftAidClaimBatchCreateRequest" } } } }, "responses": { "201": { "description": "Gift Aid claim batch created as draft.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BusinessGiftAidClaimBatchCreateResponse" } } } }, "400": { "description": "Invalid claim batch payload, path parameter or idempotency key.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1ErrorEnvelope" } } } }, "401": { "description": "The API key is missing or invalid.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1ErrorEnvelope" } } } }, "403": { "description": "The API key does not have Gift Aid permission.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1ErrorEnvelope" } } } }, "404": { "description": "The business company is not accessible.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1ErrorEnvelope" } } } }, "405": { "description": "Only GET and POST are allowed for this endpoint.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1ErrorEnvelope" } } } }, "409": { "description": "The idempotency key is already in use for a different request.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1ErrorEnvelope" } } } }, "500": { "description": "The Gift Aid claim batch could not be created.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1ErrorEnvelope" } } } } }, "x-financial-iq-safety": { "scope": "business.gift_aid_claim_batches.create", "businessMutation": true, "directFinancialMutation": false, "writeLevel": "supporting_record", "requiresIdempotencyKey": true, "auditedEndpoint": "v1/business/companies/{company_id}/gift-aid-claim-batches", "requiredPermission": "gift_aid", "containsPersonalData": true, "externalProviderCallPerformed": false, "moneyMovementPerformed": false, "paymentRefundPerformed": false, "taxFilingPerformed": false, "forbiddenInThisRoute": [ "attach donations to a claim batch", "create Gift Aid claim item", "calculate Gift Aid claim totals from donations", "generate HMRC XML", "submit Gift Aid claim to HMRC", "amend Gift Aid claim with HMRC", "set submitted, accepted or rejected claim status", "change donation claim statuses", "post to ledger", "file tax return", "move money" ] }, "x-implementation": { "handler": "createV1BusinessGiftAidClaimBatch", "tests": [ "supabase/functions/financial-data-api/invoice_idempotency.test.ts" ] } } }, "/v1/business/companies/{company_id}/gift-aid-claim-batches/{claim_batch_id}/submission-requests": { "post": { "tags": ["Business"], "operationId": "createBusinessGiftAidSubmissionRequest", "summary": "Request business Gift Aid submission approval", "description": "Creates a short-lived, audited handoff for a signed-in Financial IQ user to review and submit a ready Gift Aid claim batch to HMRC. The API key cannot submit directly or bypass Gift Aid filing controls.", "security": [{"ApiKeyAuth": []}], "parameters": [ {"$ref": "#/components/parameters/BusinessCompanyId"}, {"name": "claim_batch_id", "in": "path", "required": true, "description": "Ready Gift Aid claim batch to submit after user approval.", "schema": {"type": "string", "format": "uuid"}}, {"$ref": "#/components/parameters/RequestId"}, {"$ref": "#/components/parameters/IdempotencyKey"} ], "requestBody": {"required": true, "content": {"application/json": {"schema": {"$ref": "#/components/schemas/V1BusinessGiftAidSubmissionRequestCreate"}}}}, "responses": { "201": {"description": "Gift Aid submission approval handoff created.", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/V1BusinessGiftAidSubmissionRequestResponse"}}}}, "400": {"description": "Invalid claim batch or missing idempotency key.", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/V1ErrorEnvelope"}}}}, "401": {"description": "Missing, invalid, expired or inactive API key."}, "403": {"description": "The API key does not grant tax_filings permission.", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/V1ErrorEnvelope"}}}}, "404": {"description": "Business Gift Aid claim batch not found.", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/V1ErrorEnvelope"}}}}, "409": {"description": "The claim batch is not ready or has already been submitted.", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/V1ErrorEnvelope"}}}} }, "x-financial-iq-safety": {"scope": "business.gift_aid_submission_requests.create", "businessMutation": true, "directFinancialMutation": false, "writeLevel": "human_approval", "requiresIdempotencyKey": true, "auditedEndpoint": "v1/business/companies/{company_id}/gift-aid-claim-batches/{claim_batch_id}/submission-requests", "requiredPermission": "tax_filings", "approvalRequired": true, "doesNot": ["submit_directly_to_hmrc", "bypass_gift_aid_filing_access", "bypass_mfa", "post_to_ledger", "move_money"]}, "x-implementation": {"edgeFunction": "supabase/functions/financial-data-api/index.ts", "handler": "handleV1BusinessGiftAidSubmissionRequestCreate", "tests": ["supabase/functions/financial-data-api/invoice_idempotency.test.ts", "supabase/tests/api_business_gift_aid_submission_request.sql"]} } }, "/v1/business/companies/{company_id}/gift-aid-submission-requests/{request_id}": { "get": { "tags": ["Business"], "operationId": "getBusinessGiftAidSubmissionRequest", "summary": "Get business Gift Aid submission approval status", "description": "Returns the status of a Gift Aid submission approval handoff. It never submits, retries or changes the claim batch.", "security": [{"ApiKeyAuth": []}], "parameters": [ {"$ref": "#/components/parameters/BusinessCompanyId"}, {"name": "request_id", "in": "path", "required": true, "description": "Gift Aid submission approval request id.", "schema": {"type": "string", "format": "uuid"}}, {"$ref": "#/components/parameters/RequestId"} ], "responses": { "200": {"description": "Gift Aid submission approval status returned.", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/V1BusinessGiftAidSubmissionRequestResponse"}}}}, "400": {"description": "Invalid path parameter.", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/V1ErrorEnvelope"}}}}, "401": {"description": "Missing, invalid, expired or inactive API key."}, "403": {"description": "The API key does not grant tax_filings permission.", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/V1ErrorEnvelope"}}}}, "404": {"description": "Gift Aid submission request not found.", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/V1ErrorEnvelope"}}}} }, "x-financial-iq-safety": {"scope": "business.gift_aid_submission_requests.read", "businessMutation": false, "directFinancialMutation": false, "writeLevel": "read", "requiresIdempotencyKey": false, "auditedEndpoint": "v1/business/companies/{company_id}/gift-aid-submission-requests/{request_id}", "requiredPermission": "tax_filings", "doesNot": ["submit_to_hmrc", "post_to_ledger", "move_money"]}, "x-implementation": {"edgeFunction": "supabase/functions/financial-data-api/index.ts", "handler": "handleV1BusinessGiftAidSubmissionRequestDetail", "tests": ["supabase/functions/financial-data-api/invoice_idempotency.test.ts", "supabase/tests/api_business_gift_aid_submission_request.sql"]} } }, "/v1/business/companies/{company_id}/gift-aid-claim-batches/{claim_batch_id}": { "get": { "tags": [ "Business" ], "operationId": "getBusinessGiftAidClaimBatch", "summary": "Get business Gift Aid claim batch", "description": "Returns one Gift Aid or GASDS claim batch with its claim items for an accessible business company.", "security": [ { "ApiKeyAuth": [] } ], "parameters": [ { "name": "company_id", "in": "path", "required": true, "description": "Business company id.", "schema": { "type": "string", "format": "uuid" } }, { "name": "claim_batch_id", "in": "path", "required": true, "description": "Gift Aid claim batch id.", "schema": { "type": "string", "format": "uuid" } }, { "$ref": "#/components/parameters/RequestId" } ], "responses": { "200": { "description": "Accessible Gift Aid claim batch returned.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1BusinessGiftAidClaimBatchResponse" } } } }, "400": { "description": "The company_id or donor_id path parameter is not a valid UUID.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1ErrorEnvelope" } } } }, "403": { "description": "The API key does not have Gift Aid permission.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1ErrorEnvelope" } } } }, "404": { "description": "The Gift Aid claim batch was not found or is not accessible.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1ErrorEnvelope" } } } }, "405": { "description": "Only GET is allowed for this endpoint.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1ErrorEnvelope" } } } }, "500": { "description": "The Gift Aid donor could not be fetched.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1ErrorEnvelope" } } } } }, "x-financial-iq-safety": { "scope": "business.gift_aid_claim_batches.read", "businessMutation": false, "directFinancialMutation": false, "writeLevel": "read", "requiresIdempotencyKey": false, "auditedEndpoint": "v1/business/companies/{company_id}/gift-aid-claim-batches/{claim_batch_id}", "requiredPermission": "gift_aid", "containsPersonalData": true }, "x-implementation": { "handler": "handleV1BusinessGiftAidClaimBatchDetail" } } }, "/v1/business/companies/{company_id}/cash-offering-setup": { "get": { "tags": [ "Business" ], "operationId": "getBusinessCashOfferingSetup", "summary": "Get business cash offering setup", "description": "Returns the read-only cash offering setup for an accessible business company, including the configured donation income accounts and whether the setup is ready for cash offering workflows.", "security": [ { "ApiKeyAuth": [] } ], "parameters": [ { "$ref": "#/components/parameters/BusinessCompanyId" }, { "$ref": "#/components/parameters/RequestId" } ], "responses": { "200": { "description": "Business cash offering setup returned.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1BusinessCashOfferingSetupResponse" } } } }, "400": { "description": "The company_id path parameter is invalid.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1ErrorEnvelope" } } } }, "401": { "description": "Missing, invalid, expired or inactive API key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LegacyErrorResponse" } } } }, "403": { "description": "The API key does not grant Gift Aid or transaction access.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1ErrorEnvelope" } } } }, "404": { "description": "Business company not found or inaccessible.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1ErrorEnvelope" } } } }, "405": { "description": "Only GET is allowed for this route.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1ErrorEnvelope" } } } }, "500": { "description": "Generic server failure. Internal database details must not be returned.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1ErrorEnvelope" } } } } }, "x-financial-iq-safety": { "auditedEndpoint": "v1/business/companies/{company_id}/cash-offering-setup", "containsPersonalData": false, "requiredAnyPermission": [ "gift_aid", "transactions" ], "requiresIdempotencyKey": false, "scope": "business.cash_offering_setup.read", "serverSideAggregation": true, "writeLevel": "read" }, "x-implementation": { "handler": "handleV1BusinessCashOfferingSetup", "source": "supabase/functions/financial-data-api/v1.ts" } } }, "/v1/business/companies/{company_id}/cash-offering-batches": { "get": { "tags": [ "Business" ], "operationId": "listBusinessCashOfferingBatches", "summary": "List business cash offering batches", "description": "Lists counted cash offering batches for an accessible business company. This route is read-only; list responses keep lines as null and detail responses include counted lines.", "security": [ { "ApiKeyAuth": [] } ], "parameters": [ { "$ref": "#/components/parameters/BusinessCompanyId" }, { "$ref": "#/components/parameters/RequestId" }, { "name": "branch_id", "in": "query", "required": false, "description": "Optional branch id filter.", "schema": { "type": "string", "minLength": 1, "maxLength": 200 } }, { "name": "branch_ids", "in": "query", "required": false, "description": "Optional comma-separated branch id filter. Ignored when branch_id is supplied.", "schema": { "type": "string", "minLength": 1, "maxLength": 2000 } }, { "name": "status", "in": "query", "required": false, "description": "Optional cash offering batch status filter.", "schema": { "type": "string", "enum": [ "unbanked", "part_banked", "banked", "overdue", "reversed" ] } }, { "name": "external_batch_id", "in": "query", "required": false, "description": "Optional exact external batch id filter.", "schema": { "type": "string", "minLength": 1, "maxLength": 200 } }, { "name": "include_banked", "in": "query", "required": false, "description": "When true, include fully banked batches when no status filter is supplied. Defaults to false.", "schema": { "type": "boolean", "default": false } }, { "name": "date_from", "in": "query", "required": false, "description": "Only return batches counted on or after this date.", "schema": { "type": "string", "format": "date" } }, { "name": "date_to", "in": "query", "required": false, "description": "Only return batches counted on or before this date.", "schema": { "type": "string", "format": "date" } }, { "name": "limit", "in": "query", "required": false, "description": "Maximum number of cash offering batches to return. Values are clamped between 1 and 200.", "schema": { "type": "integer", "minimum": 1, "maximum": 200, "default": 50 } }, { "name": "offset", "in": "query", "required": false, "description": "Zero-based offset for paginating cash offering batches.", "schema": { "type": "integer", "minimum": 0, "default": 0 } } ], "responses": { "200": { "description": "Business cash offering batches returned.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1BusinessCashOfferingBatchListResponse" } } } }, "400": { "description": "A path or filter parameter is invalid.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1ErrorEnvelope" } } } }, "401": { "description": "Missing, invalid, expired or inactive API key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LegacyErrorResponse" } } } }, "403": { "description": "The API key does not grant Gift Aid or transaction access.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1ErrorEnvelope" } } } }, "404": { "description": "Business company not found or inaccessible.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1ErrorEnvelope" } } } }, "405": { "description": "Only GET is allowed for this route.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1ErrorEnvelope" } } } }, "500": { "description": "Generic server failure. Internal database details must not be returned.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1ErrorEnvelope" } } } } }, "x-financial-iq-safety": { "auditedEndpoint": "v1/business/companies/{company_id}/cash-offering-batches", "containsPersonalData": true, "requiredAnyPermission": [ "gift_aid", "transactions" ], "requiresIdempotencyKey": false, "scope": "business.cash_offering_batches.read", "serverSideAggregation": true, "writeLevel": "read" }, "x-implementation": { "handler": "handleV1BusinessCashOfferingBatches", "source": "supabase/functions/financial-data-api/v1.ts" } }, "post": { "tags": [ "Business" ], "operationId": "createBusinessCashOfferingBatch", "summary": "Create a business cash offering batch", "description": "Creates a counted cash offering batch for an accessible business company by calling the guarded create_cash_offering_batch database function. The function validates donors, funds, petty cash account, duplicate external ids and posts the balanced accounting journals. This route does not bank or reverse the batch.", "security": [ { "ApiKeyAuth": [] } ], "parameters": [ { "$ref": "#/components/parameters/BusinessCompanyId" }, { "$ref": "#/components/parameters/RequestId" }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BusinessCashOfferingBatchCreateRequest" } } } }, "responses": { "200": { "description": "A batch with the same external batch id already exists for this company.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1BusinessCashOfferingBatchCreateResponse" } } } }, "201": { "description": "Cash offering batch created.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1BusinessCashOfferingBatchCreateResponse" } } } }, "400": { "description": "The request body, idempotency key or path parameter is invalid.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1ErrorEnvelope" } } } }, "401": { "description": "Missing, invalid, expired or inactive API key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LegacyErrorResponse" } } } }, "403": { "description": "The API key does not grant both Gift Aid and transaction access.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1ErrorEnvelope" } } } }, "404": { "description": "Business company not found or inaccessible.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1ErrorEnvelope" } } } }, "405": { "description": "Only GET and POST are allowed for this route.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1ErrorEnvelope" } } } }, "500": { "description": "Generic server failure. Internal database details must not be returned.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1ErrorEnvelope" } } } } }, "x-financial-iq-safety": { "auditedEndpoint": "v1/business/companies/{company_id}/cash-offering-batches", "containsPersonalData": true, "requiredAllPermissions": [ "gift_aid", "transactions" ], "requiresIdempotencyKey": true, "scope": "business.cash_offering_batches.create", "serverSideAggregation": false, "writeLevel": "ledger_write" }, "x-implementation": { "handler": "createV1BusinessCashOfferingBatch", "source": "supabase/functions/financial-data-api/v1.ts" } } }, "/v1/business/companies/{company_id}/cash-offering-batches/{cash_offering_batch_id}": { "get": { "tags": [ "Business" ], "operationId": "getBusinessCashOfferingBatch", "summary": "Get business cash offering batch", "description": "Returns one counted cash offering batch with its counted lines for an accessible business company. Inaccessible batch ids return not found.", "security": [ { "ApiKeyAuth": [] } ], "parameters": [ { "$ref": "#/components/parameters/BusinessCompanyId" }, { "name": "cash_offering_batch_id", "in": "path", "required": true, "description": "Cash offering batch id.", "schema": { "type": "string", "format": "uuid" } }, { "$ref": "#/components/parameters/RequestId" } ], "responses": { "200": { "description": "Business cash offering batch returned.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1BusinessCashOfferingBatchResponse" } } } }, "400": { "description": "The company_id or cash_offering_batch_id path parameter is invalid.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1ErrorEnvelope" } } } }, "401": { "description": "Missing, invalid, expired or inactive API key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LegacyErrorResponse" } } } }, "403": { "description": "The API key does not grant Gift Aid or transaction access.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1ErrorEnvelope" } } } }, "404": { "description": "The cash offering batch was not found or is not accessible.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1ErrorEnvelope" } } } }, "405": { "description": "Only GET is allowed for this route.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1ErrorEnvelope" } } } }, "500": { "description": "Generic server failure. Internal database details must not be returned.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1ErrorEnvelope" } } } } }, "x-financial-iq-safety": { "auditedEndpoint": "v1/business/companies/{company_id}/cash-offering-batches/{cash_offering_batch_id}", "containsPersonalData": true, "requiredAnyPermission": [ "gift_aid", "transactions" ], "requiresIdempotencyKey": false, "scope": "business.cash_offering_batches.read", "serverSideAggregation": true, "writeLevel": "read" }, "x-implementation": { "handler": "handleV1BusinessCashOfferingBatchDetail", "source": "supabase/functions/financial-data-api/v1.ts" } } }, "/v1/business/companies/{company_id}/cash-deposit-preparations": { "get": { "tags": [ "Business" ], "operationId": "listBusinessCashDepositPreparations", "summary": "List business cash deposit preparations", "description": "Lists prepared cash deposit bundles for an accessible business company. This route is read-only; list responses keep allocations as null and detail responses include allocation lines.", "security": [ { "ApiKeyAuth": [] } ], "parameters": [ { "$ref": "#/components/parameters/BusinessCompanyId" }, { "$ref": "#/components/parameters/RequestId" }, { "name": "branch_id", "in": "query", "required": false, "description": "Optional branch id filter.", "schema": { "type": "string", "minLength": 1, "maxLength": 200 } }, { "name": "branch_ids", "in": "query", "required": false, "description": "Optional comma-separated branch id filter. Ignored when branch_id is supplied.", "schema": { "type": "string", "minLength": 1, "maxLength": 2000 } }, { "name": "bank_account_id", "in": "query", "required": false, "description": "Optional bank account id filter.", "schema": { "type": "string", "format": "uuid" } }, { "name": "status", "in": "query", "required": false, "description": "Optional cash deposit preparation status filter.", "schema": { "type": "string", "enum": [ "prepared", "banked", "cancelled" ] } }, { "name": "external_preparation_id", "in": "query", "required": false, "description": "Optional exact external preparation id filter.", "schema": { "type": "string", "minLength": 1, "maxLength": 200 } }, { "name": "include_cancelled", "in": "query", "required": false, "description": "When true, include cancelled preparations when no status filter is supplied. Defaults to false.", "schema": { "type": "boolean", "default": false } }, { "name": "date_from", "in": "query", "required": false, "description": "Only return preparations with deposit dates on or after this date.", "schema": { "type": "string", "format": "date" } }, { "name": "date_to", "in": "query", "required": false, "description": "Only return preparations with deposit dates on or before this date.", "schema": { "type": "string", "format": "date" } }, { "name": "limit", "in": "query", "required": false, "description": "Maximum number of cash deposit preparations to return. Values are clamped between 1 and 200.", "schema": { "type": "integer", "minimum": 1, "maximum": 200, "default": 50 } }, { "name": "offset", "in": "query", "required": false, "description": "Zero-based offset for paginating cash deposit preparations.", "schema": { "type": "integer", "minimum": 0, "default": 0 } } ], "responses": { "200": { "description": "Business cash deposit preparations returned.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1BusinessCashDepositPreparationListResponse" } } } }, "400": { "description": "A path or filter parameter is invalid.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1ErrorEnvelope" } } } }, "401": { "description": "Missing, invalid, expired or inactive API key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LegacyErrorResponse" } } } }, "403": { "description": "The API key does not grant transaction access.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1ErrorEnvelope" } } } }, "404": { "description": "The business company was not found or is not accessible.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1ErrorEnvelope" } } } }, "405": { "description": "Only GET and POST are allowed for this route.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1ErrorEnvelope" } } } }, "500": { "description": "Generic server failure. Internal database details must not be returned.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1ErrorEnvelope" } } } } }, "x-financial-iq-safety": { "auditedEndpoint": "v1/business/companies/{company_id}/cash-deposit-preparations", "containsPersonalData": true, "requiredAnyPermission": [ "transactions" ], "requiresIdempotencyKey": false, "scope": "business.cash_deposit_preparations.read", "serverSideAggregation": true, "writeLevel": "read" }, "x-implementation": { "handler": "handleV1BusinessCashDepositPreparations" } }, "post": { "tags": [ "Business" ], "operationId": "createBusinessCashDepositPreparation", "summary": "Create business cash deposit preparation", "description": "Creates a cash deposit preparation for an accessible business company using the guarded deposit-preparation workflow. This reserves counted cash batches for a planned bank deposit but does not mark cash as banked or match bank transactions.", "security": [ { "ApiKeyAuth": [] } ], "parameters": [ { "$ref": "#/components/parameters/BusinessCompanyId" }, { "$ref": "#/components/parameters/RequestId" }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BusinessCashDepositPreparationCreateRequest" } } } }, "responses": { "200": { "description": "A preparation with the same external preparation id already exists for this company.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1BusinessCashDepositPreparationCreateResponse" } } }, "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" } } }, "201": { "description": "Cash deposit preparation created.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1BusinessCashDepositPreparationCreateResponse" } } }, "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" } } }, "400": { "description": "The request body, idempotency key or path parameter is invalid.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1ErrorEnvelope" } } }, "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" } } }, "401": { "description": "Missing, invalid, expired or inactive API key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LegacyErrorResponse" } } } }, "403": { "description": "The API key does not grant transaction access.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1ErrorEnvelope" } } }, "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" } } }, "404": { "description": "Business company not found or inaccessible.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1ErrorEnvelope" } } }, "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" } } }, "405": { "description": "Only GET and POST are allowed for this route.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1ErrorEnvelope" } } }, "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" } } }, "500": { "description": "Generic server failure. Internal database details must not be returned.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1ErrorEnvelope" } } }, "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" } } } }, "x-financial-iq-safety": { "auditedEndpoint": "v1/business/companies/{company_id}/cash-deposit-preparations", "containsPersonalData": true, "requiredAnyPermission": [ "transactions" ], "requiresIdempotencyKey": true, "scope": "business.cash_deposit_preparations.create", "serverSideAggregation": false, "writeLevel": "ledger_write" }, "x-implementation": { "handler": "createV1BusinessCashDepositPreparation", "source": "supabase/functions/financial-data-api/v1.ts" } } }, "/v1/business/companies/{company_id}/cash-deposit-preparations/{cash_deposit_preparation_id}": { "get": { "tags": [ "Business" ], "operationId": "getBusinessCashDepositPreparation", "summary": "Get business cash deposit preparation", "description": "Returns one prepared cash deposit bundle with its batch allocations and fund allocations for an accessible business company. Inaccessible preparation ids return not found.", "security": [ { "ApiKeyAuth": [] } ], "parameters": [ { "$ref": "#/components/parameters/BusinessCompanyId" }, { "name": "cash_deposit_preparation_id", "in": "path", "required": true, "description": "Cash deposit preparation id.", "schema": { "type": "string", "format": "uuid" } }, { "$ref": "#/components/parameters/RequestId" } ], "responses": { "200": { "description": "Business cash deposit preparation returned.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1BusinessCashDepositPreparationResponse" } } } }, "400": { "description": "The company_id or cash_deposit_preparation_id path parameter is invalid.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1ErrorEnvelope" } } } }, "401": { "description": "Missing, invalid, expired or inactive API key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LegacyErrorResponse" } } } }, "403": { "description": "The API key does not grant transaction access.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1ErrorEnvelope" } } } }, "404": { "description": "The cash deposit preparation was not found or is not accessible.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1ErrorEnvelope" } } } }, "405": { "description": "Only GET is allowed for this route.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1ErrorEnvelope" } } } }, "500": { "description": "Generic server failure. Internal database details must not be returned.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1ErrorEnvelope" } } } } }, "x-financial-iq-safety": { "auditedEndpoint": "v1/business/companies/{company_id}/cash-deposit-preparations/{cash_deposit_preparation_id}", "containsPersonalData": true, "requiredAnyPermission": [ "transactions" ], "requiresIdempotencyKey": false, "scope": "business.cash_deposit_preparations.read", "serverSideAggregation": true, "writeLevel": "read" }, "x-implementation": { "handler": "handleV1BusinessCashDepositPreparationDetail" } } }, "/v1/business/companies/{company_id}/cash-deposit-preparations/{cash_deposit_preparation_id}/cancel": { "post": { "tags": [ "Business" ], "operationId": "cancelBusinessCashDepositPreparation", "summary": "Cancel business cash deposit preparation", "description": "Cancels a prepared cash deposit preparation for an accessible business company using the guarded cancellation workflow. Banked preparations cannot be cancelled, and records are updated for audit rather than deleted.", "security": [ { "ApiKeyAuth": [] } ], "parameters": [ { "$ref": "#/components/parameters/BusinessCompanyId" }, { "name": "cash_deposit_preparation_id", "in": "path", "required": true, "description": "Cash deposit preparation id.", "schema": { "type": "string", "format": "uuid" } }, { "$ref": "#/components/parameters/RequestId" }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BusinessCashDepositPreparationCancelRequest" } } } }, "responses": { "200": { "description": "Cash deposit preparation cancelled, or an already-cancelled preparation returned.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1BusinessCashDepositPreparationCancelResponse" } } } }, "400": { "description": "The request body, idempotency key or path parameter is invalid.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1ErrorEnvelope" } } } }, "401": { "description": "Missing, invalid, expired or inactive API key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LegacyErrorResponse" } } } }, "403": { "description": "The API key does not grant transaction access.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1ErrorEnvelope" } } } }, "404": { "description": "The cash deposit preparation was not found or is not accessible.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1ErrorEnvelope" } } } }, "405": { "description": "Only POST is allowed for this route.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1ErrorEnvelope" } } } }, "409": { "description": "The cash deposit preparation has already been banked or the idempotency key conflicts with a different body.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1ErrorEnvelope" } } } }, "500": { "description": "Generic server failure. Internal database details must not be returned.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1ErrorEnvelope" } } } } }, "x-financial-iq-safety": { "auditedEndpoint": "v1/business/companies/{company_id}/cash-deposit-preparations/{cash_deposit_preparation_id}/cancel", "containsPersonalData": true, "requiredAnyPermission": [ "transactions" ], "requiresIdempotencyKey": true, "scope": "business.cash_deposit_preparations.cancel", "serverSideAggregation": false, "writeLevel": "ledger_write" }, "x-implementation": { "handler": "cancelV1BusinessCashDepositPreparation", "source": "supabase/functions/financial-data-api/v1.ts" } } }, "/v1/business/companies/{company_id}/donation-bank-inflows": { "get": { "tags": [ "Business" ], "operationId": "listBusinessDonationBankInflows", "summary": "List business donation bank inflows", "description": "Lists positive bank credits that can be reviewed for donation matching. The route is read-only and defaults to unmatched transactions only.", "security": [ { "ApiKeyAuth": [] } ], "parameters": [ { "$ref": "#/components/parameters/BusinessCompanyId" }, { "$ref": "#/components/parameters/RequestId" }, { "name": "from_date", "in": "query", "required": false, "description": "Only return inflows on or after this transaction date.", "schema": { "type": "string", "format": "date" } }, { "name": "to_date", "in": "query", "required": false, "description": "Only return inflows on or before this transaction date.", "schema": { "type": "string", "format": "date" } }, { "name": "min_amount", "in": "query", "required": false, "description": "Only return inflows at or above this gross amount.", "schema": { "type": "number" } }, { "name": "max_amount", "in": "query", "required": false, "description": "Only return inflows at or below this gross amount.", "schema": { "type": "number" } }, { "name": "bank_account_id", "in": "query", "required": false, "description": "Optional bank account id filter.", "schema": { "type": "string", "format": "uuid" } }, { "name": "unmatched_only", "in": "query", "required": false, "description": "When true, return only transactions not already matched. Defaults to true.", "schema": { "type": "boolean", "default": true } }, { "name": "limit", "in": "query", "required": false, "description": "Maximum number of donation bank inflows to return. Values are clamped between 1 and 200.", "schema": { "type": "integer", "minimum": 1, "maximum": 200, "default": 50 } }, { "name": "offset", "in": "query", "required": false, "description": "Zero-based offset for paginating donation bank inflows.", "schema": { "type": "integer", "minimum": 0, "default": 0 } } ], "responses": { "200": { "description": "Business donation bank inflows returned.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1BusinessDonationBankInflowListResponse" } } } }, "400": { "description": "A path or filter parameter is invalid.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1ErrorEnvelope" } } } }, "401": { "description": "Missing, invalid, expired or inactive API key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LegacyErrorResponse" } } } }, "403": { "description": "The API key does not grant transaction access.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1ErrorEnvelope" } } } }, "404": { "description": "The business company was not found or is not accessible.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1ErrorEnvelope" } } } }, "405": { "description": "Only GET is allowed for this route.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1ErrorEnvelope" } } } }, "500": { "description": "Generic server failure. Internal database details must not be returned.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1ErrorEnvelope" } } } } }, "x-financial-iq-safety": { "auditedEndpoint": "v1/business/companies/{company_id}/donation-bank-inflows", "containsPersonalData": true, "requiredAnyPermission": [ "transactions" ], "requiresIdempotencyKey": false, "scope": "business.donation_bank_inflows.read", "serverSideAggregation": false, "writeLevel": "read" }, "x-implementation": { "handler": "handleV1BusinessDonationBankInflows" } } }, "/v1/business/companies/{company_id}/donor-match-queue": { "get": { "tags": [ "Business" ], "operationId": "listBusinessDonorMatchQueue", "summary": "List business donor match queue items", "description": "Lists suggested donor matches for bank credits that may be donations. The route is read-only and defaults to pending queue items only.", "security": [ { "ApiKeyAuth": [] } ], "parameters": [ { "$ref": "#/components/parameters/BusinessCompanyId" }, { "$ref": "#/components/parameters/RequestId" }, { "name": "status", "in": "query", "required": false, "description": "Queue status to return. resolved maps to matched and new_donor rows.", "schema": { "type": "string", "enum": [ "pending", "matched", "skipped", "new_donor", "resolved" ], "default": "pending" } }, { "name": "bank_account_ids", "in": "query", "required": false, "description": "Optional comma-separated list of bank account UUIDs used to scope the embedded bank transaction.", "schema": { "type": "string" } }, { "name": "sort_by", "in": "query", "required": false, "description": "Field used to sort queue items.", "schema": { "type": "string", "enum": [ "transaction_date", "confidence", "amount" ], "default": "transaction_date" } }, { "name": "sort_direction", "in": "query", "required": false, "description": "Sort direction for queue items.", "schema": { "type": "string", "enum": [ "asc", "desc" ], "default": "desc" } }, { "name": "limit", "in": "query", "required": false, "description": "Maximum number of donor match queue items to return. Values are clamped between 1 and 200.", "schema": { "type": "integer", "minimum": 1, "maximum": 200, "default": 50 } }, { "name": "offset", "in": "query", "required": false, "description": "Zero-based offset for paginating donor match queue items.", "schema": { "type": "integer", "minimum": 0, "default": 0 } } ], "responses": { "200": { "description": "Business donor match queue items returned.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1BusinessDonorMatchQueueListResponse" } } } }, "400": { "description": "A path or filter parameter is invalid.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1ErrorEnvelope" } } } }, "401": { "description": "Missing, invalid, expired or inactive API key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LegacyErrorResponse" } } } }, "403": { "description": "The API key does not grant transaction access.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1ErrorEnvelope" } } } }, "404": { "description": "The business company was not found or is not accessible.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1ErrorEnvelope" } } } }, "405": { "description": "Only GET is allowed for this route.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1ErrorEnvelope" } } } }, "500": { "description": "Generic server failure. Internal database details must not be returned.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1ErrorEnvelope" } } } } }, "x-financial-iq-safety": { "auditedEndpoint": "v1/business/companies/{company_id}/donor-match-queue", "containsPersonalData": true, "requiredAnyPermission": [ "transactions" ], "requiresIdempotencyKey": false, "scope": "business.donor_match_queue.read", "serverSideAggregation": false, "writeLevel": "read" }, "x-implementation": { "handler": "handleV1BusinessDonorMatchQueue" } } }, "/v1/business/companies/{company_id}/donor-match-queue/{queue_item_id}": { "get": { "tags": [ "Business" ], "operationId": "getBusinessDonorMatchQueueItem", "summary": "Get business donor match queue item", "description": "Returns one suggested donor match queue item for inspection. The route is read-only and can be scoped by bank account ids.", "security": [ { "ApiKeyAuth": [] } ], "parameters": [ { "$ref": "#/components/parameters/BusinessCompanyId" }, { "name": "queue_item_id", "in": "path", "required": true, "description": "Donor match queue item id.", "schema": { "type": "string", "format": "uuid" } }, { "$ref": "#/components/parameters/RequestId" }, { "name": "bank_account_ids", "in": "query", "required": false, "description": "Optional comma-separated list of bank account UUIDs used to scope the embedded bank transaction.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Business donor match queue item returned.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1BusinessDonorMatchQueueResponse" } } } }, "400": { "description": "A path or filter parameter is invalid.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1ErrorEnvelope" } } } }, "401": { "description": "Missing, invalid, expired or inactive API key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LegacyErrorResponse" } } } }, "403": { "description": "The API key does not grant transaction access.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1ErrorEnvelope" } } } }, "404": { "description": "The business company or donor match queue item was not found or is not accessible.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1ErrorEnvelope" } } } }, "405": { "description": "Only GET is allowed for this route.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1ErrorEnvelope" } } } }, "500": { "description": "Generic server failure. Internal database details must not be returned.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1ErrorEnvelope" } } } } }, "x-financial-iq-safety": { "auditedEndpoint": "v1/business/companies/{company_id}/donor-match-queue/{queue_item_id}", "containsPersonalData": true, "requiredAnyPermission": [ "transactions" ], "requiresIdempotencyKey": false, "scope": "business.donor_match_queue.read", "serverSideAggregation": false, "writeLevel": "read" }, "x-implementation": { "handler": "handleV1BusinessDonorMatchQueueDetail" } } }, "/v1/business/companies/{company_id}/donor-match-queue/stats": { "get": { "tags": [ "Business" ], "operationId": "getBusinessDonorMatchQueueStats", "summary": "Get business donor match queue stats", "description": "Returns status counts for donor match queue items, including total counts and counts grouped by bank account. The route is read-only.", "security": [ { "ApiKeyAuth": [] } ], "parameters": [ { "$ref": "#/components/parameters/BusinessCompanyId" }, { "$ref": "#/components/parameters/RequestId" }, { "name": "bank_account_ids", "in": "query", "required": false, "description": "Optional comma-separated list of bank account UUIDs used to scope the embedded bank transaction.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Business donor match queue stats returned.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1BusinessDonorMatchQueueStatsResponse" } } } }, "400": { "description": "A path or filter parameter is invalid.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1ErrorEnvelope" } } } }, "401": { "description": "Missing, invalid, expired or inactive API key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LegacyErrorResponse" } } } }, "403": { "description": "The API key does not grant transaction access.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1ErrorEnvelope" } } } }, "404": { "description": "The business company was not found or is not accessible.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1ErrorEnvelope" } } } }, "405": { "description": "Only GET is allowed for this route.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1ErrorEnvelope" } } } }, "500": { "description": "Generic server failure. Internal database details must not be returned.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1ErrorEnvelope" } } } } }, "x-financial-iq-safety": { "auditedEndpoint": "v1/business/companies/{company_id}/donor-match-queue/stats", "containsPersonalData": false, "requiredAnyPermission": [ "transactions" ], "requiresIdempotencyKey": false, "scope": "business.donor_match_queue.stats.read", "serverSideAggregation": true, "writeLevel": "read" }, "x-implementation": { "handler": "handleV1BusinessDonorMatchQueueStats" } } }, "/v1/business/companies/{company_id}/cost-centers": { "get": { "tags": [ "Business" ], "operationId": "listBusinessCostCenters", "summary": "List business cost centres", "description": "Lists cost-centre levels and nested options for one accessible business company. This route is read-only and helps agents apply valid branch, department or location dimensions.", "security": [ { "ApiKeyAuth": [] } ], "parameters": [ { "$ref": "#/components/parameters/BusinessCompanyId" }, { "$ref": "#/components/parameters/RequestId" }, { "name": "search", "in": "query", "required": false, "description": "Search cost-centre levels by name.", "schema": { "type": "string", "minLength": 1, "maxLength": 200 } }, { "name": "q", "in": "query", "required": false, "description": "Alias for search.", "schema": { "type": "string", "minLength": 1, "maxLength": 200 } }, { "name": "requirement_type", "in": "query", "required": false, "description": "Optional requirement type filter.", "schema": { "type": "string" } }, { "name": "is_active", "in": "query", "required": false, "description": "Optional level active-state filter.", "schema": { "type": "boolean" } }, { "name": "option_is_active", "in": "query", "required": false, "description": "Optional option active-state filter.", "schema": { "type": "boolean" } }, { "name": "limit", "in": "query", "required": false, "description": "Maximum number of cost-centre levels to return. Values are clamped between 1 and 200.", "schema": { "type": "integer", "minimum": 1, "maximum": 200, "default": 100 } }, { "name": "offset", "in": "query", "required": false, "description": "Zero-based offset for paginating cost-centre levels.", "schema": { "type": "integer", "minimum": 0, "default": 0 } } ], "responses": { "200": { "description": "Business cost centres returned.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1BusinessCostCenterListResponse" } } } }, "400": { "description": "A path or filter parameter is invalid.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1ErrorEnvelope" } } } }, "401": { "description": "Missing, invalid, expired or inactive API key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LegacyErrorResponse" } } } }, "403": { "description": "The API key does not grant cost-centre or transaction access.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1ErrorEnvelope" } } } }, "404": { "description": "Business company not found or inaccessible.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1ErrorEnvelope" } } } }, "405": { "description": "Only GET is allowed for this route.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1ErrorEnvelope" } } } }, "500": { "description": "Generic server failure. Internal database details must not be returned.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1ErrorEnvelope" } } } } }, "x-financial-iq-safety": { "scope": "business.cost_centers.read", "businessMutation": false, "directFinancialMutation": false, "writeLevel": "read", "requiresIdempotencyKey": false, "auditedEndpoint": "v1/business/companies/{company_id}/cost-centers", "requiredAnyPermission": [ "cost_centers", "transactions" ] }, "x-implementation": { "edgeFunction": "supabase/functions/financial-data-api/index.ts", "handler": "handleV1BusinessCostCenters", "tests": [ "supabase/functions/financial-data-api/invoice_idempotency.test.ts" ] } }, "post": { "tags": [ "Business" ], "operationId": "createBusinessCostCenterLevel", "summary": "Create business cost centre level", "description": "Creates one setup-only cost centre level for an accessible business company. This route creates the dimension/level only; it does not create options, budgets, account-specific requirements, transactions or ledger entries.", "security": [ { "ApiKeyAuth": [] } ], "parameters": [ { "$ref": "#/components/parameters/BusinessCompanyId" }, { "$ref": "#/components/parameters/RequestId" }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BusinessCostCenterLevelCreateRequest" } } } }, "responses": { "201": { "description": "Business cost centre level created.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BusinessCostCenterLevelCreateResponse" } } } }, "400": { "description": "The request body, idempotency key or company_id path parameter is invalid.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1ErrorEnvelope" } } } }, "401": { "description": "Missing or invalid API key.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1ErrorEnvelope" } } } }, "403": { "description": "The API key does not have cost centre write permission.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1ErrorEnvelope" } } } }, "404": { "description": "The company is not accessible to this API key.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1ErrorEnvelope" } } } }, "405": { "description": "Only GET and POST are allowed for this route.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1ErrorEnvelope" } } } }, "409": { "description": "The cost centre level name already exists for this company, or the idempotency key conflicts with another request.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1ErrorEnvelope" } } } }, "500": { "description": "Generic server failure. Internal database details must not be returned.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1ErrorEnvelope" } } } } }, "x-financial-iq-safety": { "requiresApiKey": true, "apiKeysAllowed": true, "requiresUserBearerToken": false, "scope": "business.cost_centers.levels.create", "requiredPermission": "cost_centers", "businessMutation": true, "directFinancialMutation": false, "writeLevel": "configuration", "requiresIdempotencyKey": true, "auditedEndpoint": "v1/business/companies/{company_id}/cost-centers", "forbiddenInThisRoute": [ "create cost centre option", "create cost centre budget", "create account-specific requirement", "create bank transaction", "change bank transaction matching state", "post to ledger", "create journal entry", "close accounting period" ] }, "x-implementation": { "edgeFunction": "supabase/functions/financial-data-api/index.ts", "handler": "createV1BusinessCostCenterLevel", "tests": [ "supabase/functions/financial-data-api/invoice_idempotency.test.ts" ] } } }, "/v1/business/companies/{company_id}/cost-centers/{cost_center_level_id}": { "get": { "tags": [ "Business" ], "operationId": "getBusinessCostCenter", "summary": "Get one business cost centre", "description": "Returns one cost-centre level and its options for an accessible business company.", "security": [ { "ApiKeyAuth": [] } ], "parameters": [ { "$ref": "#/components/parameters/BusinessCompanyId" }, { "name": "cost_center_level_id", "in": "path", "required": true, "description": "Cost-centre level id to fetch.", "schema": { "type": "string", "format": "uuid" } }, { "$ref": "#/components/parameters/RequestId" } ], "responses": { "200": { "description": "Business cost centre returned.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1BusinessCostCenterResponse" } } } }, "400": { "description": "The company_id or cost_center_level_id path parameter is invalid.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1ErrorEnvelope" } } } }, "401": { "description": "Missing, invalid, expired or inactive API key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LegacyErrorResponse" } } } }, "403": { "description": "The API key does not grant cost-centre or transaction access.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1ErrorEnvelope" } } } }, "404": { "description": "Business cost centre not found.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1ErrorEnvelope" } } } }, "405": { "description": "Only GET is allowed for this route.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1ErrorEnvelope" } } } }, "500": { "description": "Generic server failure. Internal database details must not be returned.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1ErrorEnvelope" } } } } }, "x-financial-iq-safety": { "scope": "business.cost_centers.read", "businessMutation": false, "directFinancialMutation": false, "writeLevel": "read", "requiresIdempotencyKey": false, "auditedEndpoint": "v1/business/companies/{company_id}/cost-centers/{cost_center_level_id}", "requiredAnyPermission": [ "cost_centers", "transactions" ] }, "x-implementation": { "edgeFunction": "supabase/functions/financial-data-api/index.ts", "handler": "handleV1BusinessCostCenterDetail", "tests": [ "supabase/functions/financial-data-api/invoice_idempotency.test.ts" ] } }, "patch": { "tags": [ "Business" ], "operationId": "updateBusinessCostCenterLevel", "summary": "Update business cost centre level", "description": "Updates safe setup fields for one business cost-centre level in an accessible company. This route requires cost_centers permission and an Idempotency-Key. It does not change requirement rules, create options, create budgets, create account-specific requirements, create transactions, post ledger entries, close accounting periods, submit tax returns or move money.", "security": [ { "ApiKeyAuth": [] } ], "parameters": [ { "$ref": "#/components/parameters/BusinessCompanyId" }, { "name": "cost_center_level_id", "in": "path", "required": true, "description": "Cost-centre level id to update.", "schema": { "type": "string", "format": "uuid" } }, { "$ref": "#/components/parameters/RequestId" }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BusinessCostCenterLevelUpdateRequest" } } } }, "responses": { "200": { "description": "Business cost-centre level updated.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" }, "X-FIQ-Idempotency-Replayed": { "$ref": "#/components/headers/IdempotencyReplayed" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BusinessCostCenterLevelUpdateResponse" } } } }, "400": { "description": "Invalid request body, missing Idempotency-Key, or invalid company_id/cost_center_level_id path parameter.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1ErrorEnvelope" } } } }, "401": { "description": "Missing, invalid, expired or inactive API key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LegacyErrorResponse" } } } }, "403": { "description": "The API key does not grant cost-centre write permission.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1ErrorEnvelope" } } } }, "404": { "description": "Business cost centre not found.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1ErrorEnvelope" } } } }, "405": { "description": "Only GET and PATCH are allowed for this route.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1ErrorEnvelope" } } } }, "409": { "description": "The idempotency key conflicts with a different request body, or the cost-centre level name already exists.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1ErrorEnvelope" } } } }, "500": { "description": "Generic server failure. Internal database details must not be returned.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1ErrorEnvelope" } } } } }, "x-financial-iq-safety": { "requiresApiKey": true, "scope": "business.cost_centers.levels.update", "requiredPermission": "cost_centers", "directFinancialMutation": false, "businessMutation": true, "writeLevel": "configuration", "requiresIdempotencyKey": true, "auditedEndpoint": "v1/business/companies/{company_id}/cost-centers/{cost_center_level_id}", "forbiddenFields": [ "id", "company_id", "cost_center_level_id", "created_at", "updated_at", "requirement_type", "is_mandatory", "options", "budget", "budget_period_id", "actual_amount", "account_requirements", "account_specific_requirements", "transactions", "journal_entries", "ledger_entries" ], "doesNot": [ "change_requirement_rules", "create_cost_center_options", "create_cost_center_budgets", "create_account_specific_requirements", "create_transactions", "post_ledger_entries", "change_bank_transaction_matching_state", "close_accounting_periods", "submit_tax_returns", "move_money" ] }, "x-implementation": { "edgeFunction": "supabase/functions/financial-data-api/index.ts", "handler": "updateV1BusinessCostCenterLevel", "tests": [ "supabase/functions/financial-data-api/invoice_idempotency.test.ts" ] } } }, "/v1/business/companies/{company_id}/cost-center-budgets": { "get": { "tags": [ "Business" ], "operationId": "listBusinessCostCenterBudgets", "summary": "List business cost-centre budgets", "description": "Returns budget-versus-actual rows and per-option rollups for one cost-centre level and budget period.", "security": [ { "ApiKeyAuth": [] } ], "parameters": [ { "$ref": "#/components/parameters/BusinessCompanyId" }, { "$ref": "#/components/parameters/RequestId" }, { "name": "budget_period_id", "in": "query", "required": false, "description": "Budget period id to analyse.", "schema": { "type": "string", "format": "uuid" } }, { "name": "cost_center_level_id", "in": "query", "required": false, "description": "Cost-centre level id to analyse.", "schema": { "type": "string", "format": "uuid" } }, { "name": "date_from", "in": "query", "required": false, "description": "Optional first month/date to include.", "schema": { "type": "string", "format": "date", "pattern": "^\\d{4}-\\d{2}-\\d{2}$" } }, { "name": "date_to", "in": "query", "required": false, "description": "Optional last month/date to include.", "schema": { "type": "string", "format": "date", "pattern": "^\\d{4}-\\d{2}-\\d{2}$" } } ], "responses": { "200": { "description": "Business cost-centre budgets returned.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1BusinessCostCenterBudgetListResponse" } } } }, "400": { "description": "Required budget_period_id, cost_center_level_id or date filter is invalid.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1ErrorEnvelope" } } } }, "401": { "description": "Missing, invalid, expired or inactive API key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LegacyErrorResponse" } } } }, "403": { "description": "The API key does not grant cost-centre or transaction access.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1ErrorEnvelope" } } } }, "404": { "description": "Business company not found or inaccessible.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1ErrorEnvelope" } } } }, "405": { "description": "Only GET and POST are allowed for this route.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1ErrorEnvelope" } } } }, "500": { "description": "Generic server failure. Internal database details must not be returned.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1ErrorEnvelope" } } } } }, "x-financial-iq-safety": { "scope": "business.cost_center_budgets.read", "businessMutation": false, "directFinancialMutation": false, "writeLevel": "read", "requiresIdempotencyKey": false, "auditedEndpoint": "v1/business/companies/{company_id}/cost-center-budgets", "requiredAnyPermission": [ "cost_centers", "transactions" ], "serverSideAggregation": true }, "x-implementation": { "edgeFunction": "supabase/functions/financial-data-api/index.ts", "handler": "handleV1BusinessCostCenterBudgets", "tests": [ "supabase/functions/financial-data-api/invoice_idempotency.test.ts" ] } }, "post": { "tags": [ "Business" ], "operationId": "createBusinessCostCenterBudgetTarget", "summary": "Create business cost-centre budget target", "description": "Creates one setup-only monthly budget target for an accessible cost-centre option. This route writes the budget target only; it does not update actuals, create transactions, create journal entries, post to the ledger or change accounting period locks.", "security": [ { "ApiKeyAuth": [] } ], "parameters": [ { "$ref": "#/components/parameters/BusinessCompanyId" }, { "$ref": "#/components/parameters/RequestId" }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BusinessCostCenterBudgetTargetCreateRequest" } } } }, "responses": { "201": { "description": "Business cost-centre budget target created.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BusinessCostCenterBudgetTargetCreateResponse" } } } }, "400": { "description": "The request body, idempotency key or path parameter is invalid.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1ErrorEnvelope" } } } }, "401": { "description": "Missing or invalid API key.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1ErrorEnvelope" } } } }, "403": { "description": "The API key does not have cost centre budget write permission.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1ErrorEnvelope" } } } }, "404": { "description": "The company, budget period, cost-centre level or cost-centre option is not accessible to this API key.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1ErrorEnvelope" } } } }, "405": { "description": "Only GET and POST are allowed for this route.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1ErrorEnvelope" } } } }, "409": { "description": "The budget target already exists for this option and month, or the idempotency key conflicts with another request.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1ErrorEnvelope" } } } }, "500": { "description": "Generic server failure. Internal database details must not be returned.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1ErrorEnvelope" } } } } }, "x-financial-iq-safety": { "requiresApiKey": true, "apiKeysAllowed": true, "requiresUserBearerToken": false, "scope": "business.cost_center_budgets.create", "requiredPermission": "cost_center_budgets", "businessMutation": true, "directFinancialMutation": false, "writeLevel": "configuration", "requiresIdempotencyKey": true, "auditedEndpoint": "v1/business/companies/{company_id}/cost-center-budgets", "forbiddenInThisRoute": [ "create budget period", "create cost centre level", "create cost centre option", "update actual amount", "create bank transaction", "change bank transaction matching state", "post to ledger", "create journal entry", "create accounting period", "close accounting period", "change accounting period lock" ] }, "x-implementation": { "edgeFunction": "supabase/functions/financial-data-api/index.ts", "handler": "createV1BusinessCostCenterBudgetTarget", "tests": [ "supabase/functions/financial-data-api/invoice_idempotency.test.ts" ] } } }, "/v1/business/companies/{company_id}/cost-center-budgets/{cost_center_budget_target_id}": { "patch": { "tags": [ "Business" ], "operationId": "updateBusinessCostCenterBudgetTarget", "summary": "Update business cost-centre budget target", "description": "Updates safe setup fields for one business cost-centre budget target in an accessible company. This route requires cost_center_budgets permission and an Idempotency-Key. It can change target_amount, target_month and notes only; it does not change budget period, cost-centre assignment, actuals, transactions, journal entries, ledger postings, accounting period locks, tax submissions or money movement.", "security": [ { "ApiKeyAuth": [] } ], "parameters": [ { "$ref": "#/components/parameters/BusinessCompanyId" }, { "name": "cost_center_budget_target_id", "in": "path", "required": true, "description": "Cost-centre budget target id to return.", "schema": { "type": "string", "format": "uuid" } }, { "$ref": "#/components/parameters/RequestId" }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BusinessCostCenterBudgetTargetUpdateRequest" } } } }, "responses": { "200": { "description": "Business cost-centre budget target updated.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" }, "X-FIQ-Idempotency-Replayed": { "$ref": "#/components/headers/IdempotencyReplayed" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BusinessCostCenterBudgetTargetUpdateResponse" } } } }, "400": { "description": "Invalid request body, missing Idempotency-Key, or invalid company_id/cost_center_budget_target_id path parameter.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1ErrorEnvelope" } } } }, "401": { "description": "Missing, invalid, expired or inactive API key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LegacyErrorResponse" } } } }, "403": { "description": "The API key does not grant cost-centre budget write permission.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1ErrorEnvelope" } } } }, "404": { "description": "Business cost-centre budget target not found.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1ErrorEnvelope" } } } }, "405": { "description": "Only GET and PATCH are allowed for this route.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1ErrorEnvelope" } } } }, "409": { "description": "The idempotency key conflicts with a different request body, or the target month already exists for this budget period and cost-centre option.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1ErrorEnvelope" } } } }, "500": { "description": "Generic server failure. Internal database details must not be returned.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1ErrorEnvelope" } } } } }, "x-financial-iq-safety": { "requiresApiKey": true, "scope": "business.cost_center_budgets.update", "requiredPermission": "cost_center_budgets", "directFinancialMutation": false, "businessMutation": true, "writeLevel": "configuration", "requiresIdempotencyKey": true, "auditedEndpoint": "v1/business/companies/{company_id}/cost-center-budgets/{cost_center_budget_target_id}", "forbiddenFields": [ "id", "company_id", "cost_center_budget_target_id", "budget_period_id", "cost_center_level_id", "cost_center_option_id", "budget_category_id", "created_by", "created_at", "updated_at", "actual_amount", "variance_amount", "transactions", "transaction_id", "journal_entries", "ledger_entries", "post_to_ledger" ], "doesNot": [ "change_budget_period", "change_cost_center_assignment", "update_actual_amount", "create_bank_transaction", "change_bank_transaction_matching_state", "post_ledger_entries", "create_journal_entry", "create_accounting_period", "close_accounting_period", "change_accounting_period_lock", "submit_tax_return", "move_money" ] }, "x-implementation": { "edgeFunction": "supabase/functions/financial-data-api/index.ts", "handler": "updateV1BusinessCostCenterBudgetTarget", "tests": [ "supabase/functions/financial-data-api/invoice_idempotency.test.ts" ] } }, "get": { "tags": [ "Business" ], "operationId": "getBusinessCostCenterBudgetTarget", "summary": "Get business cost-centre budget target", "description": "Returns one monthly cost-centre budget target for an accessible business company. This route is read-only and does not return actual transaction rows or post ledger entries.", "security": [ { "ApiKeyAuth": [] } ], "parameters": [ { "$ref": "#/components/parameters/BusinessCompanyId" }, { "name": "cost_center_budget_target_id", "in": "path", "required": true, "description": "Cost-centre budget target id to update.", "schema": { "type": "string", "format": "uuid" } }, { "$ref": "#/components/parameters/RequestId" } ], "responses": { "200": { "description": "Business cost-centre budget target returned.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BusinessCostCenterBudgetTargetResponse" } } } }, "400": { "description": "Invalid company_id or cost_center_budget_target_id path parameter.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1ErrorEnvelope" } } } }, "401": { "description": "Missing, invalid, expired or inactive API key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LegacyErrorResponse" } } } }, "403": { "description": "The API key does not grant cost centre read permission.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1ErrorEnvelope" } } } }, "404": { "description": "Business cost-centre budget target not found.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1ErrorEnvelope" } } } }, "405": { "description": "Only GET and PATCH are allowed for this route.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1ErrorEnvelope" } } } }, "500": { "description": "Generic server failure. Internal database details must not be returned.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1ErrorEnvelope" } } } } }, "x-financial-iq-safety": { "scope": "business.cost_center_budgets.read", "businessMutation": false, "directFinancialMutation": false, "writeLevel": "read", "requiresIdempotencyKey": false, "auditedEndpoint": "v1/business/companies/{company_id}/cost-center-budgets/{cost_center_budget_target_id}", "requiredAnyPermission": [ "cost_centers", "transactions" ], "forbiddenFields": [ "actual_transaction_rows", "ledger_entries", "journal_entries" ], "doesNot": [ "update_actual_amount", "create_bank_transaction", "change_bank_transaction_matching_state", "post_ledger_entries", "create_journal_entry", "create_accounting_period", "close_accounting_period", "change_accounting_period_lock", "submit_tax_return", "move_money" ] }, "x-implementation": { "handler": "handleV1BusinessCostCenterBudgetTargetDetail", "sourceFile": "supabase/functions/financial-data-api/v1.ts" } } }, "/v1/business/companies/{company_id}/accounting-periods": { "get": { "tags": [ "Business" ], "operationId": "listBusinessAccountingPeriods", "summary": "List business accounting periods", "description": "Lists accounting periods for one accessible business company. This route is read-only and helps agents align reports and ledger work to the correct period.", "security": [ { "ApiKeyAuth": [] } ], "parameters": [ { "$ref": "#/components/parameters/BusinessCompanyId" }, { "$ref": "#/components/parameters/RequestId" }, { "name": "period_type", "in": "query", "required": false, "description": "Optional period type filter.", "schema": { "type": "string" } }, { "name": "locked", "in": "query", "required": false, "description": "Optional locked-state filter.", "schema": { "type": "boolean" } }, { "name": "include_monthly", "in": "query", "required": false, "description": "When true, include a generated monthly breakdown for each returned period.", "schema": { "type": "boolean" } }, { "name": "date_from", "in": "query", "required": false, "description": "Optional earliest period start date.", "schema": { "type": "string", "format": "date", "pattern": "^\\d{4}-\\d{2}-\\d{2}$" } }, { "name": "date_to", "in": "query", "required": false, "description": "Optional latest period end date.", "schema": { "type": "string", "format": "date", "pattern": "^\\d{4}-\\d{2}-\\d{2}$" } }, { "name": "limit", "in": "query", "required": false, "description": "Maximum number of accounting periods to return. Values are clamped between 1 and 200.", "schema": { "type": "integer", "minimum": 1, "maximum": 200, "default": 50 } }, { "name": "offset", "in": "query", "required": false, "description": "Zero-based offset for paginating accounting periods.", "schema": { "type": "integer", "minimum": 0, "default": 0 } } ], "responses": { "200": { "description": "Business accounting periods returned.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1BusinessAccountingPeriodListResponse" } } } }, "400": { "description": "A path or filter parameter is invalid.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1ErrorEnvelope" } } } }, "401": { "description": "Missing, invalid, expired or inactive API key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LegacyErrorResponse" } } } }, "403": { "description": "The API key does not grant accounting period, report or transaction access.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1ErrorEnvelope" } } } }, "404": { "description": "Business company not found or inaccessible.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1ErrorEnvelope" } } } }, "405": { "description": "Only GET and POST are allowed for this route.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1ErrorEnvelope" } } } }, "500": { "description": "Generic server failure. Internal database details must not be returned.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1ErrorEnvelope" } } } } }, "x-financial-iq-safety": { "scope": "business.accounting_periods.read", "businessMutation": false, "directFinancialMutation": false, "writeLevel": "read", "requiresIdempotencyKey": false, "auditedEndpoint": "v1/business/companies/{company_id}/accounting-periods", "requiredAnyPermission": [ "accounting_periods", "reports", "transactions" ] }, "x-implementation": { "edgeFunction": "supabase/functions/financial-data-api/index.ts", "handler": "handleV1BusinessAccountingPeriods", "tests": [ "supabase/functions/financial-data-api/invoice_idempotency.test.ts" ] } }, "post": { "tags": [ "Business" ], "operationId": "createBusinessAccountingPeriod", "summary": "Create business accounting period", "description": "Creates one open, active accounting period for an accessible business company. This route writes the period setup only; it does not lock or close periods, change the company lock date, post journals, create year-end adjustments, file statutory accounts or submit CT600.", "security": [ { "ApiKeyAuth": [] } ], "parameters": [ { "$ref": "#/components/parameters/BusinessCompanyId" }, { "$ref": "#/components/parameters/RequestId" }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BusinessAccountingPeriodCreateRequest" } } } }, "responses": { "201": { "description": "Business accounting period created.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1BusinessAccountingPeriodCreateResponse" } } } }, "400": { "description": "The request body, idempotency key or path parameter is invalid.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1ErrorEnvelope" } } } }, "401": { "description": "Missing or invalid API key.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1ErrorEnvelope" } } } }, "403": { "description": "The API key does not have accounting period write permission.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1ErrorEnvelope" } } } }, "404": { "description": "Business company not found or inaccessible.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1ErrorEnvelope" } } } }, "405": { "description": "Only GET and POST are allowed for this route.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1ErrorEnvelope" } } } }, "409": { "description": "The period overlaps an existing active period, the period end date already exists, or the idempotency key conflicts with another request.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1ErrorEnvelope" } } } }, "500": { "description": "Generic server failure. Internal database details must not be returned.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1ErrorEnvelope" } } } } }, "x-financial-iq-safety": { "requiresApiKey": true, "apiKeysAllowed": true, "requiresUserBearerToken": false, "scope": "business.accounting_periods.create", "requiredPermission": "accounting_periods", "businessMutation": true, "directFinancialMutation": false, "writeLevel": "configuration", "requiresIdempotencyKey": true, "auditedEndpoint": "v1/business/companies/{company_id}/accounting-periods", "forbiddenInThisRoute": [ "lock accounting period", "unlock accounting period", "close accounting period", "change company lock date", "post to ledger", "create journal entry", "create year-end adjustment", "file statutory accounts", "submit CT600", "create bank transaction", "change bank transaction matching state" ] }, "x-implementation": { "edgeFunction": "supabase/functions/financial-data-api/index.ts", "handler": "createV1BusinessAccountingPeriod", "tests": [ "supabase/functions/financial-data-api/invoice_idempotency.test.ts" ] } } }, "/v1/business/companies/{company_id}/accounting-periods/{accounting_period_id}": { "get": { "tags": [ "Business" ], "operationId": "getBusinessAccountingPeriod", "summary": "Get one business accounting period", "description": "Returns one accounting period for an accessible business company.", "security": [ { "ApiKeyAuth": [] } ], "parameters": [ { "$ref": "#/components/parameters/BusinessCompanyId" }, { "name": "accounting_period_id", "in": "path", "required": true, "description": "Accounting period id to fetch.", "schema": { "type": "string", "format": "uuid" } }, { "$ref": "#/components/parameters/RequestId" } ], "responses": { "200": { "description": "Business accounting period returned.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1BusinessAccountingPeriodResponse" } } } }, "400": { "description": "The company_id or accounting_period_id path parameter is invalid.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1ErrorEnvelope" } } } }, "401": { "description": "Missing, invalid, expired or inactive API key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LegacyErrorResponse" } } } }, "403": { "description": "The API key does not grant accounting period, report or transaction access.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1ErrorEnvelope" } } } }, "404": { "description": "Business accounting period not found.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1ErrorEnvelope" } } } }, "405": { "description": "Only GET and PATCH are allowed for this route.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1ErrorEnvelope" } } } }, "500": { "description": "Generic server failure. Internal database details must not be returned.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1ErrorEnvelope" } } } } }, "x-financial-iq-safety": { "scope": "business.accounting_periods.read", "businessMutation": false, "directFinancialMutation": false, "writeLevel": "read", "requiresIdempotencyKey": false, "auditedEndpoint": "v1/business/companies/{company_id}/accounting-periods/{accounting_period_id}", "requiredAnyPermission": [ "accounting_periods", "reports", "transactions" ] }, "x-implementation": { "edgeFunction": "supabase/functions/financial-data-api/index.ts", "handler": "handleV1BusinessAccountingPeriodDetail", "tests": [ "supabase/functions/financial-data-api/invoice_idempotency.test.ts" ] } }, "patch": { "tags": [ "Business" ], "operationId": "updateBusinessAccountingPeriod", "summary": "Update business accounting period", "description": "Updates safe setup/date fields for one unlocked accounting period in an accessible company. This route requires accounting_periods permission and an Idempotency-Key. It can change start_date, end_date, period_type and filing_deadline only; it does not lock, close, delete, file accounts, submit tax, create months, create transactions, create journal entries, post to the ledger or move money.", "security": [ { "ApiKeyAuth": [] } ], "parameters": [ { "$ref": "#/components/parameters/BusinessCompanyId" }, { "name": "accounting_period_id", "in": "path", "required": true, "description": "Accounting period id to update.", "schema": { "type": "string", "format": "uuid" } }, { "$ref": "#/components/parameters/RequestId" }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BusinessAccountingPeriodUpdateRequest" } } } }, "responses": { "200": { "description": "Business accounting period updated.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" }, "X-FIQ-Idempotency-Replayed": { "$ref": "#/components/headers/IdempotencyReplayed" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1BusinessAccountingPeriodUpdateResponse" } } } }, "400": { "description": "Invalid request body, missing Idempotency-Key, or invalid company_id/accounting_period_id path parameter.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1ErrorEnvelope" } } } }, "401": { "description": "Missing, invalid, expired or inactive API key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LegacyErrorResponse" } } } }, "403": { "description": "The API key does not grant accounting period write permission.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1ErrorEnvelope" } } } }, "404": { "description": "Business accounting period not found.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1ErrorEnvelope" } } } }, "405": { "description": "Only GET and PATCH are allowed for this route.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1ErrorEnvelope" } } } }, "409": { "description": "The accounting period is locked, overlaps another period, already exists for the company/end date, or the idempotency key conflicts with another request.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1ErrorEnvelope" } } } }, "500": { "description": "Generic server failure. Internal database details must not be returned.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1ErrorEnvelope" } } } } }, "x-financial-iq-safety": { "requiresApiKey": true, "scope": "business.accounting_periods.update", "requiredPermission": "accounting_periods", "businessMutation": true, "directFinancialMutation": false, "writeLevel": "configuration", "requiresIdempotencyKey": true, "auditedEndpoint": "v1/business/companies/{company_id}/accounting-periods/{accounting_period_id}", "forbiddenFields": [ "id", "company_id", "accounting_period_id", "locked", "locked_at", "locked_by", "lock_date", "closed", "closed_at", "status", "is_active", "created_at", "updated_at", "created_by", "monthly_breakdown", "months", "transactions", "journal_entries", "ledger_entries", "year_end_adjustments", "statutory_accounts", "ct600", "submit_to_hmrc", "file_accounts", "close_period", "lock_company", "post_to_ledger" ], "doesNot": [ "lock_accounting_period", "close_accounting_period", "delete_accounting_period", "create_monthly_breakdown", "create_transactions", "create_journal_entries", "post_ledger_entries", "create_year_end_adjustments", "generate_statutory_accounts", "submit_ct600", "submit_tax_return", "file_accounts", "move_money" ] }, "x-implementation": { "edgeFunction": "supabase/functions/financial-data-api/index.ts", "handler": "updateV1BusinessAccountingPeriod", "tests": [ "supabase/functions/financial-data-api/invoice_idempotency.test.ts" ] } } }, "/v1/business/companies/{company_id}/cashflow/line": {"get": {"tags": ["Business"], "operationId": "getBusinessCashflowLine", "summary": "Get the expected cash line", "description": "Returns the expected cash line for one accessible business company at six weeks, thirteen weeks or twelve months: opening cash and where it came from, the buffer, the daily points with the central, on-time and slow cases, the history behind today, the lowest point and its cause, and any buffer breach. The line is a forecast built from booked, planned, detected and estimated events; it is never an accounting record and never a filed figure. Where the engine holds no distribution there is no band and band_note says why.", "security": [{"ApiKeyAuth": []}], "parameters": [{"name": "company_id", "in": "path", "required": true, "description": "Business company id. Company scope comes from this path value only.", "schema": {"type": "string", "format": "uuid"}}, {"$ref": "#/components/parameters/RequestId"}, {"name": "window", "in": "query", "required": false, "description": "Line window. Defaults to 6w.", "schema": {"type": "string", "enum": ["6w", "13w", "12m"]}}, {"name": "scenario_id", "in": "query", "required": false, "description": "Optional saved scenario to draw instead of the primary line.", "schema": {"type": "string", "format": "uuid"}}], "responses": {"200": {"description": "Cash flow line returned.", "headers": {"X-FIQ-API-Version": {"$ref": "#/components/headers/V1ApiVersion"}, "X-FIQ-Request-Id": {"$ref": "#/components/headers/RequestId"}}, "content": {"application/json": {"schema": {"$ref": "#/components/schemas/V1BusinessCashflowLineResponse"}}}}, "400": {"description": "A path, filter or body value is invalid.", "headers": {"X-FIQ-API-Version": {"$ref": "#/components/headers/V1ApiVersion"}, "X-FIQ-Request-Id": {"$ref": "#/components/headers/RequestId"}}, "content": {"application/json": {"schema": {"$ref": "#/components/schemas/V1ErrorEnvelope"}}}}, "401": {"description": "Missing, invalid, expired or inactive API key.", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/LegacyErrorResponse"}}}}, "403": {"description": "The API key lacks the required permission, or its owner has no access to this company cash flow.", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/V1ErrorEnvelope"}}}}, "404": {"description": "Business company, cash flow record or route not found.", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/V1ErrorEnvelope"}}}}, "405": {"description": "The HTTP method is not allowed for this route.", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/V1ErrorEnvelope"}}}}, "500": {"description": "Generic server failure.", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/V1ErrorEnvelope"}}}}}, "x-financial-iq-safety": {"requiresApiKey": true, "scope": "business.cashflow.line.read", "requiredAnyPermission": ["reports", "transactions"], "businessMutation": false, "directFinancialMutation": false, "forecastOnly": true, "writeLevel": "read", "requiresIdempotencyKey": false, "auditedEndpoint": "v1/business/companies/{company_id}/cashflow/line"}, "x-implementation": {"edgeFunction": "supabase/functions/financial-data-api/index.ts", "handler": "handleV1BusinessCashflowRoute", "module": "supabase/functions/financial-data-api/v1/businessCashflow.ts", "atomicRpc": "public.cashflow_api_v1_atomic", "tests": ["supabase/functions/financial-data-api/cashflow_api.test.ts", "supabase/tests/cashflow_api.sql", "supabase/tests/cashflow_engine.sql", "supabase/tests/cashflow_bands.sql"]}}}, "/v1/business/companies/{company_id}/cashflow/movers": {"get": {"tags": ["Business"], "operationId": "listBusinessCashflowMovers", "summary": "List what moves the cash line", "description": "Returns the largest expected cash events in the window, earliest first, each with its provenance, the plain-words reason for its date, and one attached action where the product offers one. Read-only.", "security": [{"ApiKeyAuth": []}], "parameters": [{"name": "company_id", "in": "path", "required": true, "description": "Business company id. Company scope comes from this path value only.", "schema": {"type": "string", "format": "uuid"}}, {"$ref": "#/components/parameters/RequestId"}, {"name": "window", "in": "query", "required": false, "description": "Line window. Defaults to 6w.", "schema": {"type": "string", "enum": ["6w", "13w", "12m"]}}, {"name": "limit", "in": "query", "required": false, "description": "How many movers to return, 1 to 50. Defaults to 5.", "schema": {"type": "integer", "minimum": 1, "maximum": 50, "default": 5}}], "responses": {"200": {"description": "Cash flow movers returned.", "headers": {"X-FIQ-API-Version": {"$ref": "#/components/headers/V1ApiVersion"}, "X-FIQ-Request-Id": {"$ref": "#/components/headers/RequestId"}}, "content": {"application/json": {"schema": {"$ref": "#/components/schemas/V1BusinessCashflowMoverListResponse"}}}}, "400": {"description": "A path, filter or body value is invalid.", "headers": {"X-FIQ-API-Version": {"$ref": "#/components/headers/V1ApiVersion"}, "X-FIQ-Request-Id": {"$ref": "#/components/headers/RequestId"}}, "content": {"application/json": {"schema": {"$ref": "#/components/schemas/V1ErrorEnvelope"}}}}, "401": {"description": "Missing, invalid, expired or inactive API key.", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/LegacyErrorResponse"}}}}, "403": {"description": "The API key lacks the required permission, or its owner has no access to this company cash flow.", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/V1ErrorEnvelope"}}}}, "404": {"description": "Business company, cash flow record or route not found.", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/V1ErrorEnvelope"}}}}, "405": {"description": "The HTTP method is not allowed for this route.", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/V1ErrorEnvelope"}}}}, "500": {"description": "Generic server failure.", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/V1ErrorEnvelope"}}}}}, "x-financial-iq-safety": {"requiresApiKey": true, "scope": "business.cashflow.movers.read", "requiredAnyPermission": ["reports", "transactions"], "businessMutation": false, "directFinancialMutation": false, "forecastOnly": true, "writeLevel": "read", "requiresIdempotencyKey": false, "auditedEndpoint": "v1/business/companies/{company_id}/cashflow/movers"}, "x-implementation": {"edgeFunction": "supabase/functions/financial-data-api/index.ts", "handler": "handleV1BusinessCashflowRoute", "module": "supabase/functions/financial-data-api/v1/businessCashflow.ts", "atomicRpc": "public.cashflow_api_v1_atomic", "tests": ["supabase/functions/financial-data-api/cashflow_api.test.ts", "supabase/tests/cashflow_api.sql"]}}}, "/v1/business/companies/{company_id}/cashflow/events": {"get": {"tags": ["Business"], "operationId": "listBusinessCashflowEvents", "summary": "List expected cash events", "description": "Returns the expected cash event ledger for an inclusive date range of up to one year: direction, amount and any range, the date and why, provenance, source reference and whether a later fact has consumed the row. Read-only.", "security": [{"ApiKeyAuth": []}], "parameters": [{"name": "company_id", "in": "path", "required": true, "description": "Business company id. Company scope comes from this path value only.", "schema": {"type": "string", "format": "uuid"}}, {"$ref": "#/components/parameters/RequestId"}, {"name": "from", "in": "query", "required": true, "description": "Inclusive start date.", "schema": {"type": "string", "format": "date", "pattern": "^\\d{4}-\\d{2}-\\d{2}$"}}, {"name": "to", "in": "query", "required": true, "description": "Inclusive end date, at most 366 days after from.", "schema": {"type": "string", "format": "date", "pattern": "^\\d{4}-\\d{2}-\\d{2}$"}}, {"name": "scenario_id", "in": "query", "required": false, "description": "Optional saved scenario whose events to list.", "schema": {"type": "string", "format": "uuid"}}], "responses": {"200": {"description": "Expected cash events returned.", "headers": {"X-FIQ-API-Version": {"$ref": "#/components/headers/V1ApiVersion"}, "X-FIQ-Request-Id": {"$ref": "#/components/headers/RequestId"}}, "content": {"application/json": {"schema": {"$ref": "#/components/schemas/V1BusinessCashflowEventListResponse"}}}}, "400": {"description": "A path, filter or body value is invalid.", "headers": {"X-FIQ-API-Version": {"$ref": "#/components/headers/V1ApiVersion"}, "X-FIQ-Request-Id": {"$ref": "#/components/headers/RequestId"}}, "content": {"application/json": {"schema": {"$ref": "#/components/schemas/V1ErrorEnvelope"}}}}, "401": {"description": "Missing, invalid, expired or inactive API key.", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/LegacyErrorResponse"}}}}, "403": {"description": "The API key lacks the required permission, or its owner has no access to this company cash flow.", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/V1ErrorEnvelope"}}}}, "404": {"description": "Business company, cash flow record or route not found.", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/V1ErrorEnvelope"}}}}, "405": {"description": "The HTTP method is not allowed for this route.", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/V1ErrorEnvelope"}}}}, "500": {"description": "Generic server failure.", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/V1ErrorEnvelope"}}}}}, "x-financial-iq-safety": {"requiresApiKey": true, "scope": "business.cashflow.events.read", "requiredAnyPermission": ["reports", "transactions"], "businessMutation": false, "directFinancialMutation": false, "forecastOnly": true, "writeLevel": "read", "requiresIdempotencyKey": false, "auditedEndpoint": "v1/business/companies/{company_id}/cashflow/events"}, "x-implementation": {"edgeFunction": "supabase/functions/financial-data-api/index.ts", "handler": "handleV1BusinessCashflowRoute", "module": "supabase/functions/financial-data-api/v1/businessCashflow.ts", "atomicRpc": "public.cashflow_api_v1_atomic", "tests": ["supabase/functions/financial-data-api/cashflow_api.test.ts", "supabase/tests/cashflow_api.sql"]}}}, "/v1/business/companies/{company_id}/cashflow/scores": {"get": {"tags": ["Business"], "operationId": "getBusinessCashflowScores", "summary": "Get how accurate the cash line has been", "description": "Returns the scoring loop's own verdict on the line: absolute error and bias over the horizon, band hit rate, the contribution of each layer, the biggest reasons the line missed in plain words, and what the engine calibrated because of them. The sentence is null until at least four scored weeks exist.", "security": [{"ApiKeyAuth": []}], "parameters": [{"name": "company_id", "in": "path", "required": true, "description": "Business company id. Company scope comes from this path value only.", "schema": {"type": "string", "format": "uuid"}}, {"$ref": "#/components/parameters/RequestId"}, {"name": "horizon_days", "in": "query", "required": false, "description": "Scoring horizon in days, 1 to 365. Defaults to 28.", "schema": {"type": "integer", "minimum": 1, "maximum": 365, "default": 28}}], "responses": {"200": {"description": "Cash flow accuracy scores returned.", "headers": {"X-FIQ-API-Version": {"$ref": "#/components/headers/V1ApiVersion"}, "X-FIQ-Request-Id": {"$ref": "#/components/headers/RequestId"}}, "content": {"application/json": {"schema": {"$ref": "#/components/schemas/V1BusinessCashflowScoresResponse"}}}}, "400": {"description": "A path, filter or body value is invalid.", "headers": {"X-FIQ-API-Version": {"$ref": "#/components/headers/V1ApiVersion"}, "X-FIQ-Request-Id": {"$ref": "#/components/headers/RequestId"}}, "content": {"application/json": {"schema": {"$ref": "#/components/schemas/V1ErrorEnvelope"}}}}, "401": {"description": "Missing, invalid, expired or inactive API key.", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/LegacyErrorResponse"}}}}, "403": {"description": "The API key lacks the required permission, or its owner has no access to this company cash flow.", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/V1ErrorEnvelope"}}}}, "404": {"description": "Business company, cash flow record or route not found.", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/V1ErrorEnvelope"}}}}, "405": {"description": "The HTTP method is not allowed for this route.", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/V1ErrorEnvelope"}}}}, "500": {"description": "Generic server failure.", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/V1ErrorEnvelope"}}}}}, "x-financial-iq-safety": {"requiresApiKey": true, "scope": "business.cashflow.scores.read", "requiredAnyPermission": ["reports", "transactions"], "businessMutation": false, "directFinancialMutation": false, "forecastOnly": true, "writeLevel": "read", "requiresIdempotencyKey": false, "auditedEndpoint": "v1/business/companies/{company_id}/cashflow/scores"}, "x-implementation": {"edgeFunction": "supabase/functions/financial-data-api/index.ts", "handler": "handleV1BusinessCashflowRoute", "module": "supabase/functions/financial-data-api/v1/businessCashflow.ts", "atomicRpc": "public.cashflow_api_v1_atomic", "tests": ["supabase/functions/financial-data-api/cashflow_api.test.ts", "supabase/tests/cashflow_api.sql", "supabase/tests/cashflow_self_healing.sql"]}}}, "/v1/business/companies/{company_id}/cashflow/plans": {"get": {"tags": ["Business"], "operationId": "listBusinessCashflowPlans", "summary": "List projected invoices", "description": "Returns the company's projected invoices with their occurrences, the occurrences whose issue date passed with nothing raised, and the yearly totals. A plan is a plan, not a document.", "security": [{"ApiKeyAuth": []}], "parameters": [{"name": "company_id", "in": "path", "required": true, "description": "Business company id. Company scope comes from this path value only.", "schema": {"type": "string", "format": "uuid"}}, {"$ref": "#/components/parameters/RequestId"}, {"name": "include_closed", "in": "query", "required": false, "description": "Include cancelled plans. Defaults to false.", "schema": {"type": "boolean", "default": false}}], "responses": {"200": {"description": "Projected invoices returned.", "headers": {"X-FIQ-API-Version": {"$ref": "#/components/headers/V1ApiVersion"}, "X-FIQ-Request-Id": {"$ref": "#/components/headers/RequestId"}}, "content": {"application/json": {"schema": {"$ref": "#/components/schemas/V1BusinessCashflowPlanListResponse"}}}}, "400": {"description": "A path, filter or body value is invalid.", "headers": {"X-FIQ-API-Version": {"$ref": "#/components/headers/V1ApiVersion"}, "X-FIQ-Request-Id": {"$ref": "#/components/headers/RequestId"}}, "content": {"application/json": {"schema": {"$ref": "#/components/schemas/V1ErrorEnvelope"}}}}, "401": {"description": "Missing, invalid, expired or inactive API key.", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/LegacyErrorResponse"}}}}, "403": {"description": "The API key lacks the required permission, or its owner has no access to this company cash flow.", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/V1ErrorEnvelope"}}}}, "404": {"description": "Business company, cash flow record or route not found.", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/V1ErrorEnvelope"}}}}, "405": {"description": "The HTTP method is not allowed for this route.", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/V1ErrorEnvelope"}}}}, "500": {"description": "Generic server failure.", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/V1ErrorEnvelope"}}}}}, "x-financial-iq-safety": {"requiresApiKey": true, "scope": "business.cashflow.plans.read", "requiredAnyPermission": ["reports", "transactions"], "businessMutation": false, "directFinancialMutation": false, "forecastOnly": true, "writeLevel": "read", "requiresIdempotencyKey": false, "auditedEndpoint": "v1/business/companies/{company_id}/cashflow/plans"}, "x-implementation": {"edgeFunction": "supabase/functions/financial-data-api/index.ts", "handler": "handleV1BusinessCashflowRoute", "module": "supabase/functions/financial-data-api/v1/businessCashflow.ts", "atomicRpc": "public.cashflow_api_v1_atomic", "tests": ["supabase/functions/financial-data-api/cashflow_api.test.ts", "supabase/tests/cashflow_api.sql", "supabase/tests/cashflow_plans.sql"]}}, "post": {"tags": ["Business"], "operationId": "upsertBusinessCashflowPlan", "summary": "Create or amend a projected invoice", "description": "Creates a projected invoice, or amends one when id and the revision last seen are supplied. A plan never reaches invoice numbering, VAT, the profit and loss account or the ledger. Requires an Idempotency-Key, transactions permission, and the API key owner's own write authority for the company.", "security": [{"ApiKeyAuth": []}], "parameters": [{"name": "company_id", "in": "path", "required": true, "description": "Business company id. Company scope comes from this path value only.", "schema": {"type": "string", "format": "uuid"}}, {"$ref": "#/components/parameters/RequestId"}, {"$ref": "#/components/parameters/IdempotencyKey"}], "requestBody": {"required": true, "content": {"application/json": {"schema": {"$ref": "#/components/schemas/V1BusinessCashflowPlanInput"}}}}, "responses": {"200": {"description": "Projected invoice amended.", "headers": {"X-FIQ-API-Version": {"$ref": "#/components/headers/V1ApiVersion"}, "X-FIQ-Request-Id": {"$ref": "#/components/headers/RequestId"}}, "content": {"application/json": {"schema": {"$ref": "#/components/schemas/V1BusinessCashflowPlanResponse"}}}}, "400": {"description": "A path, filter or body value is invalid.", "headers": {"X-FIQ-API-Version": {"$ref": "#/components/headers/V1ApiVersion"}, "X-FIQ-Request-Id": {"$ref": "#/components/headers/RequestId"}}, "content": {"application/json": {"schema": {"$ref": "#/components/schemas/V1ErrorEnvelope"}}}}, "401": {"description": "Missing, invalid, expired or inactive API key.", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/LegacyErrorResponse"}}}}, "403": {"description": "The API key lacks the required permission, or its owner has no access to this company cash flow.", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/V1ErrorEnvelope"}}}}, "404": {"description": "Business company, cash flow record or route not found.", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/V1ErrorEnvelope"}}}}, "405": {"description": "The HTTP method is not allowed for this route.", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/V1ErrorEnvelope"}}}}, "500": {"description": "Generic server failure.", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/V1ErrorEnvelope"}}}}, "201": {"description": "Projected invoice created.", "headers": {"X-FIQ-API-Version": {"$ref": "#/components/headers/V1ApiVersion"}, "X-FIQ-Request-Id": {"$ref": "#/components/headers/RequestId"}}, "content": {"application/json": {"schema": {"$ref": "#/components/schemas/V1BusinessCashflowPlanResponse"}}}}, "409": {"description": "The Idempotency-Key was reused with a different body, or the plan revision is stale.", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/V1ErrorEnvelope"}}}}}, "x-financial-iq-safety": {"requiresApiKey": true, "scope": "business.cashflow.plan_upsert", "requiredAnyPermission": ["transactions"], "businessMutation": true, "directFinancialMutation": false, "forecastOnly": true, "writeLevel": "forecast_plan", "requiresIdempotencyKey": true, "auditedEndpoint": "v1/business/companies/{company_id}/cashflow/plans"}, "x-implementation": {"edgeFunction": "supabase/functions/financial-data-api/index.ts", "handler": "handleV1BusinessCashflowRoute", "module": "supabase/functions/financial-data-api/v1/businessCashflow.ts", "atomicRpc": "public.cashflow_api_v1_atomic", "tests": ["supabase/functions/financial-data-api/cashflow_api.test.ts", "supabase/tests/cashflow_api.sql", "supabase/tests/cashflow_plans.sql"]}}}, "/v1/business/companies/{company_id}/cashflow/plans/{plan_id}/cancel": {"post": {"tags": ["Business"], "operationId": "cancelBusinessCashflowPlan", "summary": "Cancel a projected invoice", "description": "Cancels one projected invoice using the revision the caller last saw. The plan is marked cancelled; nothing is deleted, and occurrences already linked to a real invoice keep their link.", "security": [{"ApiKeyAuth": []}], "parameters": [{"name": "company_id", "in": "path", "required": true, "description": "Business company id. Company scope comes from this path value only.", "schema": {"type": "string", "format": "uuid"}}, {"name": "plan_id", "in": "path", "required": true, "description": "Projected invoice id.", "schema": {"type": "string", "format": "uuid"}}, {"$ref": "#/components/parameters/RequestId"}, {"$ref": "#/components/parameters/IdempotencyKey"}], "requestBody": {"required": true, "content": {"application/json": {"schema": {"$ref": "#/components/schemas/V1BusinessCashflowPlanCancelInput"}}}}, "responses": {"200": {"description": "Projected invoice cancelled.", "headers": {"X-FIQ-API-Version": {"$ref": "#/components/headers/V1ApiVersion"}, "X-FIQ-Request-Id": {"$ref": "#/components/headers/RequestId"}}, "content": {"application/json": {"schema": {"$ref": "#/components/schemas/V1BusinessCashflowPlanResponse"}}}}, "400": {"description": "A path, filter or body value is invalid.", "headers": {"X-FIQ-API-Version": {"$ref": "#/components/headers/V1ApiVersion"}, "X-FIQ-Request-Id": {"$ref": "#/components/headers/RequestId"}}, "content": {"application/json": {"schema": {"$ref": "#/components/schemas/V1ErrorEnvelope"}}}}, "401": {"description": "Missing, invalid, expired or inactive API key.", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/LegacyErrorResponse"}}}}, "403": {"description": "The API key lacks the required permission, or its owner has no access to this company cash flow.", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/V1ErrorEnvelope"}}}}, "404": {"description": "Business company, cash flow record or route not found.", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/V1ErrorEnvelope"}}}}, "405": {"description": "The HTTP method is not allowed for this route.", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/V1ErrorEnvelope"}}}}, "500": {"description": "Generic server failure.", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/V1ErrorEnvelope"}}}}, "409": {"description": "The Idempotency-Key was reused with a different body, or the plan revision is stale.", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/V1ErrorEnvelope"}}}}}, "x-financial-iq-safety": {"requiresApiKey": true, "scope": "business.cashflow.plan_cancel", "requiredAnyPermission": ["transactions"], "businessMutation": true, "directFinancialMutation": false, "forecastOnly": true, "writeLevel": "forecast_plan", "requiresIdempotencyKey": true, "auditedEndpoint": "v1/business/companies/{company_id}/cashflow/plans/{plan_id}/cancel"}, "x-implementation": {"edgeFunction": "supabase/functions/financial-data-api/index.ts", "handler": "handleV1BusinessCashflowRoute", "module": "supabase/functions/financial-data-api/v1/businessCashflow.ts", "atomicRpc": "public.cashflow_api_v1_atomic", "tests": ["supabase/functions/financial-data-api/cashflow_api.test.ts", "supabase/tests/cashflow_api.sql", "supabase/tests/cashflow_plans.sql"]}}}, "/v1/business/companies/{company_id}/cashflow/plan-occurrences/{occurrence_id}/{action}": {"post": {"tags": ["Business"], "operationId": "decideBusinessCashflowPlanOccurrence", "summary": "Move, drop, restore or detach one projected occurrence", "description": "Applies one decision to a single projected occurrence on the line. move takes expected_issue_date in the body; drop cancels the occurrence; restore returns it to projected; detach unlinks an invoice from it. Converting a projected occurrence into a real invoice is deliberately not available through the API and returns 404: raising an invoice is a person's decision taken in the app.", "security": [{"ApiKeyAuth": []}], "parameters": [{"name": "company_id", "in": "path", "required": true, "description": "Business company id. Company scope comes from this path value only.", "schema": {"type": "string", "format": "uuid"}}, {"name": "occurrence_id", "in": "path", "required": true, "description": "Projected occurrence id.", "schema": {"type": "string", "format": "uuid"}}, {"name": "action", "in": "path", "required": true, "description": "The decision to apply.", "schema": {"type": "string", "enum": ["move", "drop", "restore", "detach"]}}, {"$ref": "#/components/parameters/RequestId"}, {"$ref": "#/components/parameters/IdempotencyKey"}], "requestBody": {"required": true, "content": {"application/json": {"schema": {"$ref": "#/components/schemas/V1BusinessCashflowPlanOccurrenceDecisionInput"}}}}, "responses": {"200": {"description": "Projected occurrence updated.", "headers": {"X-FIQ-API-Version": {"$ref": "#/components/headers/V1ApiVersion"}, "X-FIQ-Request-Id": {"$ref": "#/components/headers/RequestId"}}, "content": {"application/json": {"schema": {"$ref": "#/components/schemas/V1BusinessCashflowPlanOccurrenceResponse"}}}}, "400": {"description": "A path, filter or body value is invalid.", "headers": {"X-FIQ-API-Version": {"$ref": "#/components/headers/V1ApiVersion"}, "X-FIQ-Request-Id": {"$ref": "#/components/headers/RequestId"}}, "content": {"application/json": {"schema": {"$ref": "#/components/schemas/V1ErrorEnvelope"}}}}, "401": {"description": "Missing, invalid, expired or inactive API key.", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/LegacyErrorResponse"}}}}, "403": {"description": "The API key lacks the required permission, or its owner has no access to this company cash flow.", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/V1ErrorEnvelope"}}}}, "404": {"description": "Business company, cash flow record or route not found.", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/V1ErrorEnvelope"}}}}, "405": {"description": "The HTTP method is not allowed for this route.", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/V1ErrorEnvelope"}}}}, "500": {"description": "Generic server failure.", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/V1ErrorEnvelope"}}}}, "409": {"description": "The Idempotency-Key was reused with a different body.", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/V1ErrorEnvelope"}}}}}, "x-financial-iq-safety": {"requiresApiKey": true, "scope": "business.cashflow.plan_occurrence_decide", "requiredAnyPermission": ["transactions"], "businessMutation": true, "directFinancialMutation": false, "forecastOnly": true, "writeLevel": "forecast_plan", "requiresIdempotencyKey": true, "auditedEndpoint": "v1/business/companies/{company_id}/cashflow/plan-occurrences/{occurrence_id}/{action}"}, "x-implementation": {"edgeFunction": "supabase/functions/financial-data-api/index.ts", "handler": "handleV1BusinessCashflowRoute", "module": "supabase/functions/financial-data-api/v1/businessCashflow.ts", "atomicRpc": "public.cashflow_api_v1_atomic", "tests": ["supabase/functions/financial-data-api/cashflow_api.test.ts", "supabase/tests/cashflow_api.sql", "supabase/tests/cashflow_plans.sql"]}}}, "/v1/business/companies/{company_id}/cashflow/scenarios": {"get": {"tags": ["Business"], "operationId": "listBusinessCashflowScenarios", "summary": "List saved cash flow scenarios", "description": "Returns the saved scenarios for one company. A scenario is a set of switches applied to the primary line's events, not a copy of the line.", "security": [{"ApiKeyAuth": []}], "parameters": [{"name": "company_id", "in": "path", "required": true, "description": "Business company id. Company scope comes from this path value only.", "schema": {"type": "string", "format": "uuid"}}, {"$ref": "#/components/parameters/RequestId"}], "responses": {"200": {"description": "Cash flow scenarios returned.", "headers": {"X-FIQ-API-Version": {"$ref": "#/components/headers/V1ApiVersion"}, "X-FIQ-Request-Id": {"$ref": "#/components/headers/RequestId"}}, "content": {"application/json": {"schema": {"$ref": "#/components/schemas/V1BusinessCashflowScenarioListResponse"}}}}, "400": {"description": "A path, filter or body value is invalid.", "headers": {"X-FIQ-API-Version": {"$ref": "#/components/headers/V1ApiVersion"}, "X-FIQ-Request-Id": {"$ref": "#/components/headers/RequestId"}}, "content": {"application/json": {"schema": {"$ref": "#/components/schemas/V1ErrorEnvelope"}}}}, "401": {"description": "Missing, invalid, expired or inactive API key.", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/LegacyErrorResponse"}}}}, "403": {"description": "The API key lacks the required permission, or its owner has no access to this company cash flow.", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/V1ErrorEnvelope"}}}}, "404": {"description": "Business company, cash flow record or route not found.", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/V1ErrorEnvelope"}}}}, "405": {"description": "The HTTP method is not allowed for this route.", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/V1ErrorEnvelope"}}}}, "500": {"description": "Generic server failure.", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/V1ErrorEnvelope"}}}}}, "x-financial-iq-safety": {"requiresApiKey": true, "scope": "business.cashflow.scenarios.read", "requiredAnyPermission": ["reports", "transactions"], "businessMutation": false, "directFinancialMutation": false, "forecastOnly": true, "writeLevel": "read", "requiresIdempotencyKey": false, "auditedEndpoint": "v1/business/companies/{company_id}/cashflow/scenarios"}, "x-implementation": {"edgeFunction": "supabase/functions/financial-data-api/index.ts", "handler": "handleV1BusinessCashflowRoute", "module": "supabase/functions/financial-data-api/v1/businessCashflow.ts", "atomicRpc": "public.cashflow_api_v1_atomic", "tests": ["supabase/functions/financial-data-api/cashflow_api.test.ts", "supabase/tests/cashflow_api.sql", "supabase/tests/cashflow_scenarios.sql"]}}}, "/v1/business/companies/{company_id}/cashflow/scenarios/compare": {"get": {"tags": ["Business"], "operationId": "compareBusinessCashflowScenarios", "summary": "Compare cash flow scenarios", "description": "Returns one row per scenario for the chosen window: its lowest point, its closing figure, how many days sit below the buffer, the first breach date, and the difference from the primary line. Read-only.", "security": [{"ApiKeyAuth": []}], "parameters": [{"name": "company_id", "in": "path", "required": true, "description": "Business company id. Company scope comes from this path value only.", "schema": {"type": "string", "format": "uuid"}}, {"$ref": "#/components/parameters/RequestId"}, {"name": "window", "in": "query", "required": false, "description": "Comparison window. Defaults to 13w.", "schema": {"type": "string", "enum": ["6w", "13w", "12m"]}}], "responses": {"200": {"description": "Scenario comparison returned.", "headers": {"X-FIQ-API-Version": {"$ref": "#/components/headers/V1ApiVersion"}, "X-FIQ-Request-Id": {"$ref": "#/components/headers/RequestId"}}, "content": {"application/json": {"schema": {"$ref": "#/components/schemas/V1BusinessCashflowScenarioComparisonListResponse"}}}}, "400": {"description": "A path, filter or body value is invalid.", "headers": {"X-FIQ-API-Version": {"$ref": "#/components/headers/V1ApiVersion"}, "X-FIQ-Request-Id": {"$ref": "#/components/headers/RequestId"}}, "content": {"application/json": {"schema": {"$ref": "#/components/schemas/V1ErrorEnvelope"}}}}, "401": {"description": "Missing, invalid, expired or inactive API key.", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/LegacyErrorResponse"}}}}, "403": {"description": "The API key lacks the required permission, or its owner has no access to this company cash flow.", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/V1ErrorEnvelope"}}}}, "404": {"description": "Business company, cash flow record or route not found.", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/V1ErrorEnvelope"}}}}, "405": {"description": "The HTTP method is not allowed for this route.", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/V1ErrorEnvelope"}}}}, "500": {"description": "Generic server failure.", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/V1ErrorEnvelope"}}}}}, "x-financial-iq-safety": {"requiresApiKey": true, "scope": "business.cashflow.scenario_compare.read", "requiredAnyPermission": ["reports", "transactions"], "businessMutation": false, "directFinancialMutation": false, "forecastOnly": true, "writeLevel": "read", "requiresIdempotencyKey": false, "auditedEndpoint": "v1/business/companies/{company_id}/cashflow/scenarios/compare"}, "x-implementation": {"edgeFunction": "supabase/functions/financial-data-api/index.ts", "handler": "handleV1BusinessCashflowRoute", "module": "supabase/functions/financial-data-api/v1/businessCashflow.ts", "atomicRpc": "public.cashflow_api_v1_atomic", "tests": ["supabase/functions/financial-data-api/cashflow_api.test.ts", "supabase/tests/cashflow_api.sql", "supabase/tests/cashflow_scenarios.sql"]}}}, "/v1/business/companies/{company_id}/cashflow/headroom": {"get": {"tags": ["Business"], "operationId": "getBusinessCashflowHeadroom", "summary": "Ask whether an amount can be taken out", "description": "Answers \"can I take this much out on this date\" from the line the company is already on: the lowest point after the withdrawal, the slow case where a band exists, whether both stay at or above the buffer, the most that could leave and still clear it, the three events that set the low point, and one sentence a person can read aloud. Asking does not move the line.", "security": [{"ApiKeyAuth": []}], "parameters": [{"name": "company_id", "in": "path", "required": true, "description": "Business company id. Company scope comes from this path value only.", "schema": {"type": "string", "format": "uuid"}}, {"$ref": "#/components/parameters/RequestId"}, {"name": "amount", "in": "query", "required": true, "description": "Amount in pounds that would leave, greater than zero.", "schema": {"type": "number", "format": "double", "exclusiveMinimum": 0, "maximum": 999999999.99}}, {"name": "date", "in": "query", "required": false, "description": "The day the money would leave. Defaults to today.", "schema": {"type": "string", "format": "date", "pattern": "^\\d{4}-\\d{2}-\\d{2}$"}}, {"name": "window", "in": "query", "required": false, "description": "Window to judge against. Defaults to 13w.", "schema": {"type": "string", "enum": ["6w", "13w", "12m"]}}], "responses": {"200": {"description": "Headroom answer returned.", "headers": {"X-FIQ-API-Version": {"$ref": "#/components/headers/V1ApiVersion"}, "X-FIQ-Request-Id": {"$ref": "#/components/headers/RequestId"}}, "content": {"application/json": {"schema": {"$ref": "#/components/schemas/V1BusinessCashflowHeadroomResponse"}}}}, "400": {"description": "A path, filter or body value is invalid.", "headers": {"X-FIQ-API-Version": {"$ref": "#/components/headers/V1ApiVersion"}, "X-FIQ-Request-Id": {"$ref": "#/components/headers/RequestId"}}, "content": {"application/json": {"schema": {"$ref": "#/components/schemas/V1ErrorEnvelope"}}}}, "401": {"description": "Missing, invalid, expired or inactive API key.", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/LegacyErrorResponse"}}}}, "403": {"description": "The API key lacks the required permission, or its owner has no access to this company cash flow.", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/V1ErrorEnvelope"}}}}, "404": {"description": "Business company, cash flow record or route not found.", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/V1ErrorEnvelope"}}}}, "405": {"description": "The HTTP method is not allowed for this route.", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/V1ErrorEnvelope"}}}}, "500": {"description": "Generic server failure.", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/V1ErrorEnvelope"}}}}}, "x-financial-iq-safety": {"requiresApiKey": true, "scope": "business.cashflow.headroom.read", "requiredAnyPermission": ["reports", "transactions"], "businessMutation": false, "directFinancialMutation": false, "forecastOnly": true, "writeLevel": "read", "requiresIdempotencyKey": false, "auditedEndpoint": "v1/business/companies/{company_id}/cashflow/headroom"}, "x-implementation": {"edgeFunction": "supabase/functions/financial-data-api/index.ts", "handler": "handleV1BusinessCashflowRoute", "module": "supabase/functions/financial-data-api/v1/businessCashflow.ts", "atomicRpc": "public.cashflow_api_v1_atomic", "tests": ["supabase/functions/financial-data-api/cashflow_api.test.ts", "supabase/tests/cashflow_api.sql", "supabase/tests/cashflow_headroom.sql"]}}, "post": {"tags": ["Business"], "operationId": "askBusinessCashflowHeadroom", "summary": "Ask whether an amount can be taken out, with a body", "description": "Answers \"can I take this much out on this date\" from the line the company is already on: the lowest point after the withdrawal, the slow case where a band exists, whether both stay at or above the buffer, the most that could leave and still clear it, the three events that set the low point, and one sentence a person can read aloud. Asking does not move the line. This is the same read as the GET route, offered with a JSON body for agents that would rather not build a query string. It requires no Idempotency-Key, writes nothing and records no audit event.", "security": [{"ApiKeyAuth": []}], "parameters": [{"name": "company_id", "in": "path", "required": true, "description": "Business company id. Company scope comes from this path value only.", "schema": {"type": "string", "format": "uuid"}}, {"$ref": "#/components/parameters/RequestId"}], "requestBody": {"required": true, "content": {"application/json": {"schema": {"$ref": "#/components/schemas/V1BusinessCashflowHeadroomInput"}}}}, "responses": {"200": {"description": "Headroom answer returned.", "headers": {"X-FIQ-API-Version": {"$ref": "#/components/headers/V1ApiVersion"}, "X-FIQ-Request-Id": {"$ref": "#/components/headers/RequestId"}}, "content": {"application/json": {"schema": {"$ref": "#/components/schemas/V1BusinessCashflowHeadroomResponse"}}}}, "400": {"description": "A path, filter or body value is invalid.", "headers": {"X-FIQ-API-Version": {"$ref": "#/components/headers/V1ApiVersion"}, "X-FIQ-Request-Id": {"$ref": "#/components/headers/RequestId"}}, "content": {"application/json": {"schema": {"$ref": "#/components/schemas/V1ErrorEnvelope"}}}}, "401": {"description": "Missing, invalid, expired or inactive API key.", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/LegacyErrorResponse"}}}}, "403": {"description": "The API key lacks the required permission, or its owner has no access to this company cash flow.", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/V1ErrorEnvelope"}}}}, "404": {"description": "Business company, cash flow record or route not found.", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/V1ErrorEnvelope"}}}}, "405": {"description": "The HTTP method is not allowed for this route.", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/V1ErrorEnvelope"}}}}, "500": {"description": "Generic server failure.", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/V1ErrorEnvelope"}}}}}, "x-financial-iq-safety": {"requiresApiKey": true, "scope": "business.cashflow.headroom.read", "requiredAnyPermission": ["reports", "transactions"], "businessMutation": false, "directFinancialMutation": false, "forecastOnly": true, "writeLevel": "read", "requiresIdempotencyKey": false, "auditedEndpoint": "v1/business/companies/{company_id}/cashflow/headroom"}, "x-implementation": {"edgeFunction": "supabase/functions/financial-data-api/index.ts", "handler": "handleV1BusinessCashflowRoute", "module": "supabase/functions/financial-data-api/v1/businessCashflow.ts", "atomicRpc": "public.cashflow_api_v1_atomic", "tests": ["supabase/functions/financial-data-api/cashflow_api.test.ts", "supabase/tests/cashflow_api.sql", "supabase/tests/cashflow_headroom.sql"]}}}, "/v1/business/companies/{company_id}/cashflow/timing": {"get": {"tags": ["Business"], "operationId": "getBusinessCashflowTiming", "summary": "Get counterparty payment timing", "description": "Returns how the engine expects each customer and supplier to pay, relative to the document due date: the days applied, whether that comes from this counterparty's own memory or from the default prior, the observed quartiles, and the amount currently outstanding. Read-only.", "security": [{"ApiKeyAuth": []}], "parameters": [{"name": "company_id", "in": "path", "required": true, "description": "Business company id. Company scope comes from this path value only.", "schema": {"type": "string", "format": "uuid"}}, {"$ref": "#/components/parameters/RequestId"}], "responses": {"200": {"description": "Counterparty timing returned.", "headers": {"X-FIQ-API-Version": {"$ref": "#/components/headers/V1ApiVersion"}, "X-FIQ-Request-Id": {"$ref": "#/components/headers/RequestId"}}, "content": {"application/json": {"schema": {"$ref": "#/components/schemas/V1BusinessCashflowTimingResponse"}}}}, "400": {"description": "A path, filter or body value is invalid.", "headers": {"X-FIQ-API-Version": {"$ref": "#/components/headers/V1ApiVersion"}, "X-FIQ-Request-Id": {"$ref": "#/components/headers/RequestId"}}, "content": {"application/json": {"schema": {"$ref": "#/components/schemas/V1ErrorEnvelope"}}}}, "401": {"description": "Missing, invalid, expired or inactive API key.", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/LegacyErrorResponse"}}}}, "403": {"description": "The API key lacks the required permission, or its owner has no access to this company cash flow.", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/V1ErrorEnvelope"}}}}, "404": {"description": "Business company, cash flow record or route not found.", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/V1ErrorEnvelope"}}}}, "405": {"description": "The HTTP method is not allowed for this route.", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/V1ErrorEnvelope"}}}}, "500": {"description": "Generic server failure.", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/V1ErrorEnvelope"}}}}}, "x-financial-iq-safety": {"requiresApiKey": true, "scope": "business.cashflow.timing.read", "requiredAnyPermission": ["reports", "transactions"], "businessMutation": false, "directFinancialMutation": false, "forecastOnly": true, "writeLevel": "read", "requiresIdempotencyKey": false, "auditedEndpoint": "v1/business/companies/{company_id}/cashflow/timing"}, "x-implementation": {"edgeFunction": "supabase/functions/financial-data-api/index.ts", "handler": "handleV1BusinessCashflowRoute", "module": "supabase/functions/financial-data-api/v1/businessCashflow.ts", "atomicRpc": "public.cashflow_api_v1_atomic", "tests": ["supabase/functions/financial-data-api/cashflow_api.test.ts", "supabase/tests/cashflow_api.sql", "supabase/tests/cashflow_known_events.sql"]}}}, "/v1/business/companies/{company_id}/cashflow/buckets": {"get": {"tags": ["Business"], "operationId": "listBusinessCashflowBuckets", "summary": "List budget bucket expectations", "description": "Returns the bucket expectations the line still holds for each budget line and period: the budget, what has actually landed, the specific plans inside it, what remains and what the line still expects after fading for elapsed time. Read-only.", "security": [{"ApiKeyAuth": []}], "parameters": [{"name": "company_id", "in": "path", "required": true, "description": "Business company id. Company scope comes from this path value only.", "schema": {"type": "string", "format": "uuid"}}, {"$ref": "#/components/parameters/RequestId"}, {"name": "from", "in": "query", "required": true, "description": "Inclusive period start.", "schema": {"type": "string", "format": "date", "pattern": "^\\d{4}-\\d{2}-\\d{2}$"}}, {"name": "to", "in": "query", "required": true, "description": "Inclusive period end, at most 400 days after from.", "schema": {"type": "string", "format": "date", "pattern": "^\\d{4}-\\d{2}-\\d{2}$"}}], "responses": {"200": {"description": "Bucket expectations returned.", "headers": {"X-FIQ-API-Version": {"$ref": "#/components/headers/V1ApiVersion"}, "X-FIQ-Request-Id": {"$ref": "#/components/headers/RequestId"}}, "content": {"application/json": {"schema": {"$ref": "#/components/schemas/V1BusinessCashflowBucketListResponse"}}}}, "400": {"description": "A path, filter or body value is invalid.", "headers": {"X-FIQ-API-Version": {"$ref": "#/components/headers/V1ApiVersion"}, "X-FIQ-Request-Id": {"$ref": "#/components/headers/RequestId"}}, "content": {"application/json": {"schema": {"$ref": "#/components/schemas/V1ErrorEnvelope"}}}}, "401": {"description": "Missing, invalid, expired or inactive API key.", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/LegacyErrorResponse"}}}}, "403": {"description": "The API key lacks the required permission, or its owner has no access to this company cash flow.", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/V1ErrorEnvelope"}}}}, "404": {"description": "Business company, cash flow record or route not found.", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/V1ErrorEnvelope"}}}}, "405": {"description": "The HTTP method is not allowed for this route.", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/V1ErrorEnvelope"}}}}, "500": {"description": "Generic server failure.", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/V1ErrorEnvelope"}}}}}, "x-financial-iq-safety": {"requiresApiKey": true, "scope": "business.cashflow.buckets.read", "requiredAnyPermission": ["reports", "transactions"], "businessMutation": false, "directFinancialMutation": false, "forecastOnly": true, "writeLevel": "read", "requiresIdempotencyKey": false, "auditedEndpoint": "v1/business/companies/{company_id}/cashflow/buckets"}, "x-implementation": {"edgeFunction": "supabase/functions/financial-data-api/index.ts", "handler": "handleV1BusinessCashflowRoute", "module": "supabase/functions/financial-data-api/v1/businessCashflow.ts", "atomicRpc": "public.cashflow_api_v1_atomic", "tests": ["supabase/functions/financial-data-api/cashflow_api.test.ts", "supabase/tests/cashflow_api.sql", "supabase/tests/cashflow_plans.sql"]}}}, "/v1/business/companies/{company_id}/reports/fund-movement": {"get": {"tags":["Business"],"operationId":"getBusinessFundMovementReport","summary":"Get charity fund movement report","description":"Returns read-only opening balances, income, expenditure, gains or losses, transfers and closing balances per charity fund for one accessible business company and inclusive period. It does not mutate books or submit filings.","security":[{"ApiKeyAuth":[]}],"parameters":[{"$ref":"#/components/parameters/BusinessCompanyId"},{"name":"from_date","in":"query","required":true,"description":"Inclusive period start date.","schema":{"type":"string","format":"date","pattern":"^\\d{4}-\\d{2}-\\d{2}$"}},{"name":"to_date","in":"query","required":true,"description":"Inclusive period end date.","schema":{"type":"string","format":"date","pattern":"^\\d{4}-\\d{2}-\\d{2}$"}},{"name":"include_unassigned","in":"query","required":false,"description":"Include transactions not assigned to a fund.","schema":{"type":"boolean","default":false}},{"$ref":"#/components/parameters/RequestId"}],"responses":{"200":{"description":"Business fund movement report returned.","headers":{"X-FIQ-API-Version":{"$ref":"#/components/headers/V1ApiVersion"},"X-FIQ-Request-Id":{"$ref":"#/components/headers/RequestId"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/V1BusinessFundMovementReportResponse"}}}},"400":{"description":"The company, date range or boolean filter is invalid.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/V1ErrorEnvelope"}}}},"401":{"description":"Missing, invalid, expired or inactive API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/LegacyErrorResponse"}}}},"403":{"description":"The API key does not have reports permission, or the master key is not allowed to access the company.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/V1ErrorEnvelope"}}}},"404":{"description":"Business company not found.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/V1ErrorEnvelope"}}}},"405":{"description":"Only GET is allowed for this route.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/V1ErrorEnvelope"}}}},"500":{"description":"Generic server failure.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/V1ErrorEnvelope"}}}}},"x-financial-iq-safety":{"requiresApiKey":true,"scope":"business.reports.fund_movement.read","requiredApiKeyPermission":"reports","businessMutation":false,"directFinancialMutation":false,"writeLevel":"read","requiresIdempotencyKey":false,"auditedEndpoint":"v1/business/companies/{company_id}/reports/fund-movement","serverSideAggregation":true},"x-implementation":{"edgeFunction":"supabase/functions/financial-data-api/index.ts","handler":"handleV1BusinessFundMovementReport","tests":["supabase/functions/financial-data-api/invoice_idempotency.test.ts"]}}}, "/v1/business/companies/{company_id}/reports/summary": { "get": { "tags": [ "Business" ], "operationId": "getBusinessReportSummary", "summary": "Get business report summary", "description": "Returns compact invoice and cash summary totals for one accessible business company and period. This route is read-only and does not return raw transaction rows.", "security": [ { "ApiKeyAuth": [] } ], "parameters": [ { "$ref": "#/components/parameters/BusinessCompanyId" }, { "$ref": "#/components/parameters/RequestId" }, { "name": "from_date", "in": "query", "required": false, "description": "Inclusive period start date in YYYY-MM-DD format. Defaults to 2020-01-01.", "schema": { "type": "string", "format": "date", "pattern": "^\\d{4}-\\d{2}-\\d{2}$" } }, { "name": "to_date", "in": "query", "required": false, "description": "Inclusive period end date in YYYY-MM-DD format. Defaults to today.", "schema": { "type": "string", "format": "date", "pattern": "^\\d{4}-\\d{2}-\\d{2}$" } } ], "responses": { "200": { "description": "Business report summary returned.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1BusinessReportSummaryResponse" } } } }, "400": { "description": "The company_id or date filter is invalid.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1ErrorEnvelope" } } } }, "401": { "description": "Missing, invalid, expired or inactive API key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LegacyErrorResponse" } } } }, "403": { "description": "The API key does not have reports permission, or the master key is not allowed to access the company.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1ErrorEnvelope" } } } }, "404": { "description": "Business company not found.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1ErrorEnvelope" } } } }, "405": { "description": "Only GET is allowed for this route.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1ErrorEnvelope" } } } }, "500": { "description": "Generic server failure. Internal database details must not be returned.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1ErrorEnvelope" } } } } }, "x-financial-iq-safety": { "scope": "business.reports.summary.read", "businessMutation": false, "directFinancialMutation": false, "writeLevel": "read", "requiresIdempotencyKey": false, "auditedEndpoint": "v1/business/companies/{company_id}/reports/summary", "requiredApiKeyPermission": "reports", "serverSideAggregation": true }, "x-implementation": { "edgeFunction": "supabase/functions/financial-data-api/index.ts", "handler": "handleV1BusinessReportSummary", "tests": [ "supabase/functions/financial-data-api/invoice_idempotency.test.ts" ] } } }, "/v1/business/companies/{company_id}/reports/profit-loss": { "get": { "tags": [ "Business" ], "operationId": "getBusinessProfitLossReport", "summary": "Get business profit-and-loss report", "description": "Returns a read-only accrual profit-and-loss report for one accessible business company and period. This route aggregates posted journals for active profit-and-loss chart accounts, excluding year-end roll-up and close journals, and places each account on the statutory line its heading names, as the statutory accounts do. It does not expose journal entry IDs or mutate the ledger.", "security": [ { "ApiKeyAuth": [] } ], "parameters": [ { "$ref": "#/components/parameters/BusinessCompanyId" }, { "$ref": "#/components/parameters/RequestId" }, { "name": "from_date", "in": "query", "required": true, "description": "Inclusive period start date in YYYY-MM-DD format.", "schema": { "type": "string", "format": "date", "pattern": "^\\d{4}-\\d{2}-\\d{2}$" } }, { "name": "to_date", "in": "query", "required": true, "description": "Inclusive period end date in YYYY-MM-DD format.", "schema": { "type": "string", "format": "date", "pattern": "^\\d{4}-\\d{2}-\\d{2}$" } } ], "responses": { "200": { "description": "Business profit-and-loss report returned.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1BusinessProfitLossReportResponse" } } } }, "400": { "description": "The company_id or date filter is invalid.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1ErrorEnvelope" } } } }, "401": { "description": "Missing, invalid, expired or inactive API key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LegacyErrorResponse" } } } }, "403": { "description": "The API key does not have reports permission, or the master key is not allowed to access the company.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1ErrorEnvelope" } } } }, "404": { "description": "Business company not found.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1ErrorEnvelope" } } } }, "405": { "description": "Only GET is allowed for this route.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1ErrorEnvelope" } } } }, "500": { "description": "Generic server failure. Internal database details must not be returned.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1ErrorEnvelope" } } } } }, "x-financial-iq-safety": { "scope": "business.reports.profit_loss.read", "businessMutation": false, "directFinancialMutation": false, "readOnly": true, "writeLevel": "read", "requiresIdempotencyKey": false, "auditedEndpoint": "v1/business/companies/{company_id}/reports/profit-loss", "requiredApiKeyPermission": "reports", "serverSideAggregation": true, "redacts": [ "journal_entry_ids", "internal_actor_ids", "raw_provider_payloads", "bank_details", "tax_filing_payloads", "document_contents" ], "doesNot": [ "create_journal_entries", "post_ledger_entries", "submit_tax_return", "file_accounts", "close_accounting_period", "move_money" ] }, "x-implementation": { "edgeFunction": "supabase/functions/financial-data-api/index.ts", "handler": "handleV1BusinessProfitLossReport", "tests": [ "supabase/functions/financial-data-api/invoice_idempotency.test.ts" ] } } }, "/v1/business/companies/{company_id}/reports/trial-balance": { "get": { "tags": [ "Business" ], "operationId": "getBusinessTrialBalanceReport", "summary": "Get business trial balance report", "description": "Returns a read-only trial balance report for one accessible business company as at a requested date. This route uses the existing company-scoped trial balance calculation, returns debit, credit and net balances by account, and does not expose journal IDs or mutate the ledger.", "security": [ { "ApiKeyAuth": [] } ], "parameters": [ { "$ref": "#/components/parameters/BusinessCompanyId" }, { "$ref": "#/components/parameters/RequestId" }, { "name": "as_at_date", "in": "query", "required": true, "description": "Report date in YYYY-MM-DD format. Posted ledger entries up to and including this date are included.", "schema": { "type": "string", "format": "date", "pattern": "^\\d{4}-\\d{2}-\\d{2}$" } }, { "name": "current_period_start", "in": "query", "required": false, "description": "Optional current period start date in YYYY-MM-DD format. When supplied, profit-and-loss accounts only include entries from this date onwards.", "schema": { "type": "string", "format": "date", "pattern": "^\\d{4}-\\d{2}-\\d{2}$" } } ], "responses": { "200": { "description": "Business trial balance report returned.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1BusinessTrialBalanceReportResponse" } } } }, "400": { "description": "The company_id or date filter is invalid.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1ErrorEnvelope" } } } }, "401": { "description": "Missing, invalid, expired or inactive API key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LegacyErrorResponse" } } } }, "403": { "description": "The API key does not have reports permission, or the master key is not allowed to access the company.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1ErrorEnvelope" } } } }, "404": { "description": "Business company not found.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1ErrorEnvelope" } } } }, "405": { "description": "Only GET is allowed for this route.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1ErrorEnvelope" } } } }, "500": { "description": "Generic server failure. Internal database details must not be returned.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1ErrorEnvelope" } } } } }, "x-financial-iq-safety": { "scope": "business.reports.trial_balance.read", "businessMutation": false, "directFinancialMutation": false, "readOnly": true, "writeLevel": "read", "requiresIdempotencyKey": false, "auditedEndpoint": "v1/business/companies/{company_id}/reports/trial-balance", "requiredApiKeyPermission": "reports", "serverSideAggregation": true, "redacts": [ "journal_entry_ids", "journal_transaction_ids", "internal_actor_ids", "raw_provider_payloads", "bank_details", "tax_filing_payloads", "document_contents" ], "doesNot": [ "create_journal_entries", "post_ledger_entries", "submit_tax_return", "file_accounts", "close_accounting_period", "move_money" ] }, "x-implementation": { "edgeFunction": "supabase/functions/financial-data-api/index.ts", "handler": "handleV1BusinessTrialBalanceReport", "tests": [ "supabase/functions/financial-data-api/invoice_idempotency.test.ts" ] } } }, "/v1/business/companies/{company_id}/reports/balance-sheet": { "get": { "tags": [ "Business" ], "operationId": "getBusinessBalanceSheetReport", "summary": "Get business balance sheet report", "description": "Returns a read-only accrual balance sheet report for one accessible business company as at a requested date. This route uses existing company-scoped financial statement calculations, includes current-period profit in equity, and does not expose journal IDs or mutate the ledger.", "security": [ { "ApiKeyAuth": [] } ], "parameters": [ { "$ref": "#/components/parameters/BusinessCompanyId" }, { "$ref": "#/components/parameters/RequestId" }, { "name": "as_at_date", "in": "query", "required": true, "description": "Balance sheet date in YYYY-MM-DD format. Posted ledger entries up to and including this date are included.", "schema": { "type": "string", "format": "date", "pattern": "^\\d{4}-\\d{2}-\\d{2}$" } }, { "name": "current_period_start", "in": "query", "required": true, "description": "Current accounting period start date in YYYY-MM-DD format. Used to include current-period profit in equity.", "schema": { "type": "string", "format": "date", "pattern": "^\\d{4}-\\d{2}-\\d{2}$" } } ], "responses": { "200": { "description": "Business balance sheet report returned.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1BusinessBalanceSheetReportResponse" } } } }, "400": { "description": "The company_id or date filter is invalid.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1ErrorEnvelope" } } } }, "401": { "description": "Missing, invalid, expired or inactive API key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LegacyErrorResponse" } } } }, "403": { "description": "The API key does not have reports permission, or the master key is not allowed to access the company.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1ErrorEnvelope" } } } }, "404": { "description": "Business company not found.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1ErrorEnvelope" } } } }, "405": { "description": "Only GET is allowed for this route.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1ErrorEnvelope" } } } }, "500": { "description": "Generic server failure. Internal database details must not be returned.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1ErrorEnvelope" } } } } }, "x-financial-iq-safety": { "scope": "business.reports.balance_sheet.read", "businessMutation": false, "directFinancialMutation": false, "readOnly": true, "writeLevel": "read", "requiresIdempotencyKey": false, "auditedEndpoint": "v1/business/companies/{company_id}/reports/balance-sheet", "requiredApiKeyPermission": "reports", "serverSideAggregation": true, "redacts": [ "journal_entry_ids", "journal_transaction_ids", "internal_actor_ids", "raw_provider_payloads", "bank_details", "tax_filing_payloads", "document_contents" ], "doesNot": [ "create_journal_entries", "post_ledger_entries", "submit_tax_return", "file_accounts", "close_accounting_period", "move_money" ] }, "x-implementation": { "edgeFunction": "supabase/functions/financial-data-api/index.ts", "handler": "handleV1BusinessBalanceSheetReport", "tests": [ "supabase/functions/financial-data-api/invoice_idempotency.test.ts" ] } } }, "/v1/business/companies/{company_id}/reports/cash-flow": { "get": { "tags": [ "Business" ], "operationId": "getBusinessCashFlowReport", "summary": "Get business cash-flow report", "description": "Returns a read-only indirect cash-flow report for one accessible business company and period. This route compares opening and closing company-scoped trial balances, classifies non-cash movements into operating, investing and financing activities, and does not expose journal IDs or mutate the ledger.", "security": [ { "ApiKeyAuth": [] } ], "parameters": [ { "$ref": "#/components/parameters/BusinessCompanyId" }, { "$ref": "#/components/parameters/RequestId" }, { "name": "from_date", "in": "query", "required": true, "description": "Inclusive period start date in YYYY-MM-DD format. Opening cash is measured at the day before this date.", "schema": { "type": "string", "format": "date", "pattern": "^\\d{4}-\\d{2}-\\d{2}$" } }, { "name": "to_date", "in": "query", "required": true, "description": "Inclusive period end date in YYYY-MM-DD format.", "schema": { "type": "string", "format": "date", "pattern": "^\\d{4}-\\d{2}-\\d{2}$" } } ], "responses": { "200": { "description": "Business cash-flow report returned.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1BusinessCashFlowReportResponse" } } } }, "400": { "description": "The company_id or date filter is invalid.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1ErrorEnvelope" } } } }, "401": { "description": "Missing, invalid, expired or inactive API key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LegacyErrorResponse" } } } }, "403": { "description": "The API key does not have reports permission, or the master key is not allowed to access the company.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1ErrorEnvelope" } } } }, "404": { "description": "Business company not found.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1ErrorEnvelope" } } } }, "405": { "description": "Only GET is allowed for this route.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1ErrorEnvelope" } } } }, "500": { "description": "Generic server failure. Internal database details must not be returned.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1ErrorEnvelope" } } } } }, "x-financial-iq-safety": { "scope": "business.reports.cash_flow.read", "businessMutation": false, "directFinancialMutation": false, "readOnly": true, "writeLevel": "read", "requiresIdempotencyKey": false, "auditedEndpoint": "v1/business/companies/{company_id}/reports/cash-flow", "requiredApiKeyPermission": "reports", "serverSideAggregation": true, "redacts": [ "journal_entry_ids", "journal_transaction_ids", "internal_actor_ids", "raw_provider_payloads", "bank_details", "tax_filing_payloads", "document_contents" ], "doesNot": [ "create_journal_entries", "post_ledger_entries", "submit_tax_return", "file_accounts", "close_accounting_period", "move_money" ] }, "x-implementation": { "edgeFunction": "supabase/functions/financial-data-api/index.ts", "handler": "handleV1BusinessCashFlowReport", "tests": [ "supabase/functions/financial-data-api/invoice_idempotency.test.ts" ] } } }, "/v1/business/companies/{company_id}/reports/general-ledger": { "get": { "tags": [ "Business" ], "operationId": "getBusinessGeneralLedgerReport", "summary": "Get business general-ledger report", "description": "Returns a read-only account-level general ledger report for one accessible business company and period. The route requires one chart account, uses posted current journal entries for the line detail, ties opening and closing balances back to the trial balance, and does not mutate the ledger.", "security": [ { "ApiKeyAuth": [] } ], "parameters": [ { "$ref": "#/components/parameters/BusinessCompanyId" }, { "$ref": "#/components/parameters/RequestId" }, { "name": "account_id", "in": "query", "required": true, "description": "Chart-of-accounts ID to report on. The account must belong to the requested company.", "schema": { "type": "string", "format": "uuid" } }, { "name": "from_date", "in": "query", "required": true, "description": "Inclusive period start date in YYYY-MM-DD format. Opening balance is measured at the day before this date.", "schema": { "type": "string", "format": "date", "pattern": "^\\d{4}-\\d{2}-\\d{2}$" } }, { "name": "to_date", "in": "query", "required": true, "description": "Inclusive period end date in YYYY-MM-DD format.", "schema": { "type": "string", "format": "date", "pattern": "^\\d{4}-\\d{2}-\\d{2}$" } }, { "name": "limit", "in": "query", "required": false, "description": "Maximum returned ledger lines. Defaults to 100 and is capped at 200.", "schema": { "type": "integer", "minimum": 1, "maximum": 200, "default": 100 } }, { "name": "offset", "in": "query", "required": false, "description": "Zero-based offset into the matching ledger lines.", "schema": { "type": "integer", "minimum": 0, "default": 0 } } ], "responses": { "200": { "description": "Business general-ledger report returned.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1BusinessGeneralLedgerReportResponse" } } } }, "400": { "description": "The company_id, account_id or date filter is invalid.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1ErrorEnvelope" } } }, "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" } } }, "401": { "description": "Missing, invalid, expired or inactive API key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LegacyErrorResponse" } } } }, "403": { "description": "The API key does not have reports permission, or the master key is not allowed to access the company.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1ErrorEnvelope" } } }, "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" } } }, "404": { "description": "Business company or chart account not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1ErrorEnvelope" } } }, "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" } } }, "405": { "description": "Only GET is allowed for this route.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1ErrorEnvelope" } } }, "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" } } }, "500": { "description": "Generic server failure. Internal database details must not be returned.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1ErrorEnvelope" } } }, "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" } } } }, "x-financial-iq-safety": { "scope": "business.reports.general_ledger.read", "businessMutation": false, "directFinancialMutation": false, "readOnly": true, "writeLevel": "read", "requiresIdempotencyKey": false, "auditedEndpoint": "v1/business/companies/{company_id}/reports/general-ledger", "requiredApiKeyPermission": "reports", "serverSideAggregation": true, "redacts": [ "internal_actor_ids", "raw_provider_payloads", "bank_details", "tax_filing_payloads", "document_contents" ], "exposes": [ "journal_entry_ids", "journal_transaction_ids" ], "doesNot": [ "create_journal_entries", "amend_journal_entries", "void_journal_entries", "delete_journal_entries", "post_ledger_entries", "submit_tax_return", "file_accounts", "close_accounting_period", "move_money" ] }, "x-implementation": { "edgeFunction": "supabase/functions/financial-data-api/index.ts", "handler": "handleV1BusinessGeneralLedgerReport", "tests": [ "supabase/functions/financial-data-api/invoice_idempotency.test.ts" ] } } }, "/v1/business/companies/{company_id}/reports/aged-debtors": { "get": { "tags": [ "Business" ], "operationId": "getBusinessAgedDebtorsReport", "summary": "Get business aged debtors report", "description": "Returns a read-only invoice-backed aged debtors report for one accessible business company as at a requested date. The route groups unpaid sales invoices into ageing buckets, summarises balances by customer, and does not mutate invoices, payments or the ledger.", "security": [ { "ApiKeyAuth": [] } ], "parameters": [ { "$ref": "#/components/parameters/BusinessCompanyId" }, { "$ref": "#/components/parameters/RequestId" }, { "name": "as_of_date", "in": "query", "required": true, "description": "Report date in YYYY-MM-DD format. The response includes invoices outstanding as at this date.", "schema": { "type": "string", "format": "date", "pattern": "^\\d{4}-\\d{2}-\\d{2}$" } }, { "name": "customer_id", "in": "query", "required": false, "description": "Optional customer ID to narrow the report to one customer.", "schema": { "type": "string", "format": "uuid" } }, { "name": "limit", "in": "query", "required": false, "description": "Maximum returned invoice rows. Defaults to 100 and is capped at 200.", "schema": { "type": "integer", "minimum": 1, "maximum": 200, "default": 100 } }, { "name": "offset", "in": "query", "required": false, "description": "Zero-based offset into the matching invoice rows.", "schema": { "type": "integer", "minimum": 0, "default": 0 } } ], "responses": { "200": { "description": "Business aged debtors report returned.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1BusinessAgedDebtorsReportResponse" } } } }, "400": { "description": "The company_id, as_of_date or customer_id filter is invalid.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1ErrorEnvelope" } } }, "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" } } }, "401": { "description": "Missing, invalid, expired or inactive API key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LegacyErrorResponse" } } } }, "403": { "description": "The API key does not have reports permission, or the master key is not allowed to access the company.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1ErrorEnvelope" } } }, "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" } } }, "404": { "description": "Business company not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1ErrorEnvelope" } } }, "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" } } }, "405": { "description": "Only GET is allowed for this route.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1ErrorEnvelope" } } }, "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" } } }, "500": { "description": "Generic server failure. Internal database details must not be returned.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1ErrorEnvelope" } } }, "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" } } } }, "x-financial-iq-safety": { "scope": "business.reports.aged_debtors.read", "businessMutation": false, "directFinancialMutation": false, "readOnly": true, "writeLevel": "read", "requiresIdempotencyKey": false, "auditedEndpoint": "v1/business/companies/{company_id}/reports/aged-debtors", "requiredApiKeyPermission": "reports", "serverSideAggregation": true, "redacts": [ "journal_entry_ids", "journal_transaction_ids", "internal_actor_ids", "raw_provider_payloads", "bank_details", "tax_filing_payloads", "document_contents" ], "doesNot": [ "create_invoices", "chase_invoices", "create_journal_entries", "post_ledger_entries", "submit_tax_return", "file_accounts", "close_accounting_period", "move_money" ] }, "x-implementation": { "edgeFunction": "supabase/functions/financial-data-api/index.ts", "handler": "handleV1BusinessAgedDebtorsReport", "tests": [ "supabase/functions/financial-data-api/invoice_idempotency.test.ts" ] } } }, "/v1/business/companies/{company_id}/reports/aged-creditors": { "get": { "tags": [ "Business" ], "operationId": "getBusinessAgedCreditorsReport", "summary": "Get business aged creditors report", "description": "Returns a read-only purchase-invoice-backed aged creditors report for one accessible business company as at a requested date. The route groups unpaid supplier bills into ageing buckets, summarises balances by supplier, and does not mutate purchase invoices, payments or the ledger.", "security": [ { "ApiKeyAuth": [] } ], "parameters": [ { "$ref": "#/components/parameters/BusinessCompanyId" }, { "$ref": "#/components/parameters/RequestId" }, { "name": "as_of_date", "in": "query", "required": true, "description": "Report date in YYYY-MM-DD format. The response includes purchase invoices outstanding as at this date.", "schema": { "type": "string", "format": "date", "pattern": "^\\d{4}-\\d{2}-\\d{2}$" } }, { "name": "supplier_id", "in": "query", "required": false, "description": "Optional supplier ID to narrow the report to one supplier.", "schema": { "type": "string", "format": "uuid" } }, { "name": "limit", "in": "query", "required": false, "description": "Maximum returned purchase invoice rows. Defaults to 100 and is capped at 200.", "schema": { "type": "integer", "minimum": 1, "maximum": 200, "default": 100 } }, { "name": "offset", "in": "query", "required": false, "description": "Zero-based offset into the matching purchase invoice rows.", "schema": { "type": "integer", "minimum": 0, "default": 0 } } ], "responses": { "200": { "description": "Business aged creditors report returned.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1BusinessAgedCreditorsReportResponse" } } } }, "400": { "description": "The company_id, as_of_date or supplier_id filter is invalid.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1ErrorEnvelope" } } }, "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" } } }, "401": { "description": "Missing, invalid, expired or inactive API key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LegacyErrorResponse" } } } }, "403": { "description": "The API key does not have reports permission, or the master key is not allowed to access the company.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1ErrorEnvelope" } } }, "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" } } }, "404": { "description": "Business company not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1ErrorEnvelope" } } }, "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" } } }, "405": { "description": "Only GET is allowed for this route.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1ErrorEnvelope" } } }, "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" } } }, "500": { "description": "Generic server failure. Internal database details must not be returned.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1ErrorEnvelope" } } }, "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" } } } }, "x-financial-iq-safety": { "scope": "business.reports.aged_creditors.read", "businessMutation": false, "directFinancialMutation": false, "readOnly": true, "writeLevel": "read", "requiresIdempotencyKey": false, "auditedEndpoint": "v1/business/companies/{company_id}/reports/aged-creditors", "requiredApiKeyPermission": "reports", "serverSideAggregation": true, "redacts": [ "journal_entry_ids", "journal_transaction_ids", "internal_actor_ids", "raw_provider_payloads", "bank_details", "tax_filing_payloads", "document_contents" ], "doesNot": [ "create_purchase_invoices", "pay_purchase_invoices", "export_supplier_payment_file", "create_journal_entries", "post_ledger_entries", "submit_tax_return", "file_accounts", "close_accounting_period", "move_money" ] }, "x-implementation": { "edgeFunction": "supabase/functions/financial-data-api/index.ts", "handler": "handleV1BusinessAgedCreditorsReport", "tests": [ "supabase/functions/financial-data-api/invoice_idempotency.test.ts" ] } } }, "/v1/business/companies/{company_id}/hmrc-correspondence": { "get": { "tags": [ "Business" ], "operationId": "listBusinessHmrcCorrespondence", "summary": "List business HMRC correspondence", "description": "Lists HMRC correspondence inbox records for one accessible business company. This route is read-only and does not create, update, review, respond to, archive or submit HMRC correspondence.", "security": [ { "ApiKeyAuth": [] } ], "parameters": [ { "$ref": "#/components/parameters/BusinessCompanyId" }, { "$ref": "#/components/parameters/RequestId" }, { "name": "tax_area", "in": "query", "required": false, "description": "Filter by HMRC tax area.", "schema": { "type": "string", "enum": [ "vat", "corporation_tax", "paye", "cis", "companies_house", "unknown" ] } }, { "name": "category", "in": "query", "required": false, "description": "Filter by correspondence category.", "schema": { "type": "string", "enum": [ "assessment", "demand", "enquiry", "refund", "information" ] } }, { "name": "urgency", "in": "query", "required": false, "description": "Filter by correspondence urgency.", "schema": { "type": "string", "enum": [ "low", "medium", "high" ] } }, { "name": "status", "in": "query", "required": false, "description": "Filter by correspondence status.", "schema": { "type": "string", "enum": [ "needs_review", "waiting_on_client", "responded", "resolved", "archived" ] } }, { "name": "response_required", "in": "query", "required": false, "description": "Filter to correspondence items that do or do not require a response.", "schema": { "type": "boolean" } }, { "name": "received_from", "in": "query", "required": false, "description": "Inclusive lower bound for the received date.", "schema": { "type": "string", "format": "date", "pattern": "^\\d{4}-\\d{2}-\\d{2}$" } }, { "name": "received_to", "in": "query", "required": false, "description": "Inclusive upper bound for the received date.", "schema": { "type": "string", "format": "date", "pattern": "^\\d{4}-\\d{2}-\\d{2}$" } }, { "name": "response_due_from", "in": "query", "required": false, "description": "Inclusive lower bound for the response due date.", "schema": { "type": "string", "format": "date", "pattern": "^\\d{4}-\\d{2}-\\d{2}$" } }, { "name": "response_due_to", "in": "query", "required": false, "description": "Inclusive upper bound for the response due date.", "schema": { "type": "string", "format": "date", "pattern": "^\\d{4}-\\d{2}-\\d{2}$" } }, { "name": "source_document_id", "in": "query", "required": false, "description": "Filter by linked source document id.", "schema": { "type": "string", "format": "uuid" } }, { "name": "limit", "in": "query", "required": false, "description": "Maximum number of records to return. Values are clamped between 1 and 100.", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 50 } }, { "name": "offset", "in": "query", "required": false, "description": "Zero-based offset for paginating results.", "schema": { "type": "integer", "minimum": 0, "default": 0 } } ], "responses": { "200": { "description": "Business HMRC correspondence returned.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BusinessHmrcCorrespondenceListResponse" } } } }, "400": { "description": "The company_id or filter is invalid.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1ErrorEnvelope" } } } }, "401": { "description": "Missing, invalid, expired or inactive API key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LegacyErrorResponse" } } } }, "403": { "description": "The API key does not have reports permission, or the master key is not allowed to access the company.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1ErrorEnvelope" } } } }, "404": { "description": "Business company not found.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1ErrorEnvelope" } } } }, "405": { "description": "Only GET is allowed for this route.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1ErrorEnvelope" } } } }, "500": { "description": "Generic server failure. Internal database details must not be returned.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1ErrorEnvelope" } } } } }, "x-financial-iq-safety": { "scope": "business.hmrc_correspondence.read", "businessMutation": false, "directFinancialMutation": false, "writeLevel": "read", "readOnly": true, "requiresIdempotencyKey": false, "auditedEndpoint": "v1/business/companies/{company_id}/hmrc-correspondence", "requiredApiKeyPermission": "reports", "redactions": [ "notes", "created_by", "reviewed_by", "internal_actor_ids" ], "doesNot": [ "create_hmrc_correspondence", "update_hmrc_correspondence", "review_hmrc_correspondence", "respond_to_hmrc", "archive_hmrc_correspondence", "submit_to_hmrc", "move_money" ] }, "x-implementation": { "edgeFunction": "supabase/functions/financial-data-api/index.ts", "handler": "handleV1BusinessHmrcCorrespondence", "tests": [ "supabase/functions/financial-data-api/invoice_idempotency.test.ts" ] } } }, "/v1/business/companies/{company_id}/hmrc-correspondence/{hmrc_correspondence_id}": { "get": { "tags": [ "Business" ], "operationId": "getBusinessHmrcCorrespondence", "summary": "Get business HMRC correspondence", "description": "Returns one HMRC correspondence inbox record for an accessible business company. This route is read-only and does not respond to HMRC, mark correspondence reviewed or move money.", "security": [ { "ApiKeyAuth": [] } ], "parameters": [ { "$ref": "#/components/parameters/BusinessCompanyId" }, { "name": "hmrc_correspondence_id", "in": "path", "required": true, "description": "HMRC correspondence id.", "schema": { "type": "string", "format": "uuid" } }, { "$ref": "#/components/parameters/RequestId" } ], "responses": { "200": { "description": "Business HMRC correspondence returned.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BusinessHmrcCorrespondenceDetailResponse" } } } }, "400": { "description": "The company_id or hmrc_correspondence_id is invalid.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1ErrorEnvelope" } } } }, "401": { "description": "Missing, invalid, expired or inactive API key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LegacyErrorResponse" } } } }, "403": { "description": "The API key does not have reports permission, or the master key is not allowed to access the company.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1ErrorEnvelope" } } } }, "404": { "description": "Business HMRC correspondence not found.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1ErrorEnvelope" } } } }, "405": { "description": "Only GET is allowed for this route.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1ErrorEnvelope" } } } }, "500": { "description": "Generic server failure. Internal database details must not be returned.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1ErrorEnvelope" } } } } }, "x-financial-iq-safety": { "scope": "business.hmrc_correspondence.read", "businessMutation": false, "directFinancialMutation": false, "writeLevel": "read", "readOnly": true, "requiresIdempotencyKey": false, "auditedEndpoint": "v1/business/companies/{company_id}/hmrc-correspondence/{hmrc_correspondence_id}", "requiredApiKeyPermission": "reports", "redactions": [ "notes", "created_by", "reviewed_by", "internal_actor_ids" ], "doesNot": [ "create_hmrc_correspondence", "update_hmrc_correspondence", "review_hmrc_correspondence", "respond_to_hmrc", "archive_hmrc_correspondence", "submit_to_hmrc", "move_money" ] }, "x-implementation": { "edgeFunction": "supabase/functions/financial-data-api/index.ts", "handler": "handleV1BusinessHmrcCorrespondenceDetail", "tests": [ "supabase/functions/financial-data-api/invoice_idempotency.test.ts" ] } } }, "/v1/business/companies/{company_id}/vat-returns": { "get": { "tags": [ "Business" ], "operationId": "listBusinessVatReturns", "summary": "List business VAT returns", "description": "Lists VAT return history and status for one accessible business company. This route is read-only: it does not calculate VAT, create returns, submit to HMRC, post ledger entries, close periods or move money.", "security": [ { "ApiKeyAuth": [] } ], "parameters": [ { "$ref": "#/components/parameters/BusinessCompanyId" }, { "$ref": "#/components/parameters/RequestId" }, { "name": "submission_status", "in": "query", "required": false, "description": "Filter by local VAT return status.", "schema": { "type": "string", "enum": [ "draft", "submitted", "cancelled", "error" ] } }, { "name": "period_start_from", "in": "query", "required": false, "description": "Inclusive lower bound for the VAT period start date.", "schema": { "type": "string", "format": "date", "pattern": "^\\d{4}-\\d{2}-\\d{2}$" } }, { "name": "period_start_to", "in": "query", "required": false, "description": "Inclusive upper bound for the VAT period start date.", "schema": { "type": "string", "format": "date", "pattern": "^\\d{4}-\\d{2}-\\d{2}$" } }, { "name": "period_end_from", "in": "query", "required": false, "description": "Inclusive lower bound for the VAT period end date.", "schema": { "type": "string", "format": "date", "pattern": "^\\d{4}-\\d{2}-\\d{2}$" } }, { "name": "period_end_to", "in": "query", "required": false, "description": "Inclusive upper bound for the VAT period end date.", "schema": { "type": "string", "format": "date", "pattern": "^\\d{4}-\\d{2}-\\d{2}$" } }, { "name": "include_cancelled", "in": "query", "required": false, "description": "Set to true to include cancelled VAT returns in the list for audit review.", "schema": { "type": "boolean", "default": false } }, { "name": "limit", "in": "query", "required": false, "description": "Maximum records to return, capped at 100.", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 50 } }, { "name": "offset", "in": "query", "required": false, "description": "Zero-based pagination offset.", "schema": { "type": "integer", "minimum": 0, "default": 0 } } ], "responses": { "200": { "description": "Business VAT returns returned.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1BusinessVatReturnListResponse" } } } }, "400": { "description": "The company_id, date filter or boolean filter is invalid.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1ErrorEnvelope" } } } }, "401": { "description": "Missing, invalid, expired or inactive API key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LegacyErrorResponse" } } } }, "403": { "description": "The API key does not grant reports permission.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1ErrorEnvelope" } } } }, "404": { "description": "Business company not found.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1ErrorEnvelope" } } } }, "405": { "description": "Only GET is allowed for this route.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1ErrorEnvelope" } } } }, "500": { "description": "Generic server failure. Internal database details must not be returned.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1ErrorEnvelope" } } } } }, "x-financial-iq-safety": { "scope": "business.vat_returns.read", "businessMutation": false, "directFinancialMutation": false, "writeLevel": "read", "requiresIdempotencyKey": false, "auditedEndpoint": "v1/business/companies/{company_id}/vat-returns", "requiredPermission": "reports", "doesNot": [ "calculate_vat", "create_vat_return", "cancel_vat_return", "submit_to_hmrc", "post_to_ledger", "file_tax_return", "close_accounting_period", "move_money" ] }, "x-implementation": { "edgeFunction": "supabase/functions/financial-data-api/index.ts", "handler": "handleV1BusinessVatReturns", "tests": [ "supabase/functions/financial-data-api/invoice_idempotency.test.ts" ] } } }, "/v1/business/companies/{company_id}/vat-returns/{vat_return_id}": { "get": { "tags": [ "Business" ], "operationId": "getBusinessVatReturn", "summary": "Get business VAT return", "description": "Returns one VAT return for an accessible business company. This route is read-only and never submits to HMRC or changes the books.", "security": [ { "ApiKeyAuth": [] } ], "parameters": [ { "$ref": "#/components/parameters/BusinessCompanyId" }, { "name": "vat_return_id", "in": "path", "required": true, "description": "VAT return id to fetch.", "schema": { "type": "string", "format": "uuid" } }, { "$ref": "#/components/parameters/RequestId" } ], "responses": { "200": { "description": "Business VAT return returned.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1BusinessVatReturnDetailResponse" } } } }, "400": { "description": "The company_id or vat_return_id path parameter is invalid.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1ErrorEnvelope" } } } }, "401": { "description": "Missing, invalid, expired or inactive API key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LegacyErrorResponse" } } } }, "403": { "description": "The API key does not grant reports permission.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1ErrorEnvelope" } } } }, "404": { "description": "Business VAT return not found.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1ErrorEnvelope" } } } }, "405": { "description": "Only GET is allowed for this route.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1ErrorEnvelope" } } } }, "500": { "description": "Generic server failure. Internal database details must not be returned.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1ErrorEnvelope" } } } } }, "x-financial-iq-safety": { "scope": "business.vat_returns.read", "businessMutation": false, "directFinancialMutation": false, "writeLevel": "read", "requiresIdempotencyKey": false, "auditedEndpoint": "v1/business/companies/{company_id}/vat-returns/{vat_return_id}", "requiredPermission": "reports", "doesNot": [ "calculate_vat", "create_vat_return", "cancel_vat_return", "submit_to_hmrc", "post_to_ledger", "file_tax_return", "close_accounting_period", "move_money" ] }, "x-implementation": { "edgeFunction": "supabase/functions/financial-data-api/index.ts", "handler": "handleV1BusinessVatReturnDetail", "tests": [ "supabase/functions/financial-data-api/invoice_idempotency.test.ts" ] } } }, "/v1/business/companies/{company_id}/vat-returns/{vat_return_id}/submission-requests": { "post": { "tags": ["Business"], "operationId": "createBusinessVatSubmissionRequest", "summary": "Request business VAT submission approval", "description": "Creates a short-lived, audited handoff for a signed-in Financial IQ user to review and submit a VAT return. The API key cannot submit directly, bypass HMRC controls or bypass MFA.", "security": [{"ApiKeyAuth": []}], "parameters": [ {"$ref": "#/components/parameters/BusinessCompanyId"}, {"name": "vat_return_id", "in": "path", "required": true, "description": "Draft VAT return to submit after user approval.", "schema": {"type": "string", "format": "uuid"}}, {"$ref": "#/components/parameters/RequestId"}, {"$ref": "#/components/parameters/IdempotencyKey"} ], "responses": { "201": {"description": "VAT submission approval handoff created.", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/V1BusinessVatSubmissionRequestResponse"}}}}, "400": {"description": "Invalid path or missing idempotency key.", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/V1ErrorEnvelope"}}}}, "401": {"description": "Missing, invalid, expired or inactive API key."}, "403": {"description": "The API key does not grant tax_filings permission.", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/V1ErrorEnvelope"}}}}, "404": {"description": "Business VAT return not found.", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/V1ErrorEnvelope"}}}}, "409": {"description": "The VAT return is not eligible for submission.", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/V1ErrorEnvelope"}}}} }, "x-financial-iq-safety": {"scope": "business.vat_submission_requests.create", "businessMutation": true, "directFinancialMutation": false, "writeLevel": "human_approval", "requiresIdempotencyKey": true, "auditedEndpoint": "v1/business/companies/{company_id}/vat-returns/{vat_return_id}/submission-requests", "requiredPermission": "tax_filings", "approvalRequired": true, "doesNot": ["submit_directly_to_hmrc", "bypass_mfa", "bypass_filing_authority", "post_to_ledger", "move_money"]}, "x-implementation": {"edgeFunction": "supabase/functions/financial-data-api/index.ts", "handler": "handleV1BusinessVatSubmissionRequestCreate", "tests": ["supabase/functions/financial-data-api/invoice_idempotency.test.ts", "supabase/tests/api_business_vat_submission_request.sql"]} } }, "/v1/business/companies/{company_id}/vat-submission-requests/{request_id}": { "get": { "tags": ["Business"], "operationId": "getBusinessVatSubmissionRequest", "summary": "Get business VAT submission approval status", "description": "Returns the status of a VAT submission approval handoff. It never submits, retries or changes the VAT return.", "security": [{"ApiKeyAuth": []}], "parameters": [ {"$ref": "#/components/parameters/BusinessCompanyId"}, {"name": "request_id", "in": "path", "required": true, "description": "VAT submission approval request id.", "schema": {"type": "string", "format": "uuid"}}, {"$ref": "#/components/parameters/RequestId"} ], "responses": { "200": {"description": "VAT submission approval status returned.", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/V1BusinessVatSubmissionRequestResponse"}}}}, "400": {"description": "Invalid path parameter.", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/V1ErrorEnvelope"}}}}, "401": {"description": "Missing, invalid, expired or inactive API key."}, "403": {"description": "The API key does not grant tax_filings permission.", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/V1ErrorEnvelope"}}}}, "404": {"description": "VAT submission request not found.", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/V1ErrorEnvelope"}}}} }, "x-financial-iq-safety": {"scope": "business.vat_submission_requests.read", "businessMutation": false, "directFinancialMutation": false, "writeLevel": "read", "requiresIdempotencyKey": false, "auditedEndpoint": "v1/business/companies/{company_id}/vat-submission-requests/{request_id}", "requiredPermission": "tax_filings", "doesNot": ["submit_to_hmrc", "post_to_ledger", "move_money"]}, "x-implementation": {"edgeFunction": "supabase/functions/financial-data-api/index.ts", "handler": "handleV1BusinessVatSubmissionRequestDetail", "tests": ["supabase/functions/financial-data-api/invoice_idempotency.test.ts", "supabase/tests/api_business_vat_submission_request.sql"]} } }, "/v1/business/companies/{company_id}/ct600-submission-requests": { "post": { "tags": ["Business"], "operationId": "createBusinessCt600SubmissionRequest", "summary": "Request business CT600 submission approval", "description": "Creates a short-lived, audited handoff for a signed-in Financial IQ user to review and submit a CT600 return. The API key cannot submit directly or bypass GovTalk, iXBRL, MFA or filing-authority controls.", "security": [{"ApiKeyAuth": []}], "parameters": [ {"$ref": "#/components/parameters/BusinessCompanyId"}, {"$ref": "#/components/parameters/RequestId"}, {"$ref": "#/components/parameters/IdempotencyKey"} ], "requestBody": {"required": true, "content": {"application/json": {"schema": {"$ref": "#/components/schemas/V1BusinessCt600SubmissionRequestCreate"}}}}, "responses": { "201": {"description": "CT600 submission approval handoff created.", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/V1BusinessCt600SubmissionRequestResponse"}}}}, "400": {"description": "Invalid filing details or missing idempotency key.", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/V1ErrorEnvelope"}}}}, "401": {"description": "Missing, invalid, expired or inactive API key."}, "403": {"description": "The API key does not grant tax_filings permission.", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/V1ErrorEnvelope"}}}}, "404": {"description": "Business CT600 filing request not found.", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/V1ErrorEnvelope"}}}}, "409": {"description": "A filing already exists for the accounting period and environment.", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/V1ErrorEnvelope"}}}} }, "x-financial-iq-safety": {"scope": "business.ct600_submission_requests.create", "businessMutation": true, "directFinancialMutation": false, "writeLevel": "human_approval", "requiresIdempotencyKey": true, "auditedEndpoint": "v1/business/companies/{company_id}/ct600-submission-requests", "requiredPermission": "tax_filings", "approvalRequired": true, "doesNot": ["submit_directly_to_hmrc", "bypass_govtalk", "bypass_ixbrl", "bypass_mfa", "post_to_ledger", "move_money"]}, "x-implementation": {"edgeFunction": "supabase/functions/financial-data-api/index.ts", "handler": "handleV1BusinessCt600SubmissionRequestCreate", "tests": ["supabase/functions/financial-data-api/invoice_idempotency.test.ts", "supabase/tests/api_business_ct600_submission_request.sql"]} } }, "/v1/business/companies/{company_id}/ct600-submission-requests/{request_id}": { "get": { "tags": ["Business"], "operationId": "getBusinessCt600SubmissionRequest", "summary": "Get business CT600 submission approval status", "description": "Returns the status of a CT600 submission approval handoff. It never submits, retries or changes the CT600 filing.", "security": [{"ApiKeyAuth": []}], "parameters": [ {"$ref": "#/components/parameters/BusinessCompanyId"}, {"name": "request_id", "in": "path", "required": true, "description": "CT600 submission approval request id.", "schema": {"type": "string", "format": "uuid"}}, {"$ref": "#/components/parameters/RequestId"} ], "responses": { "200": {"description": "CT600 submission approval status returned.", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/V1BusinessCt600SubmissionRequestResponse"}}}}, "400": {"description": "Invalid path parameter.", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/V1ErrorEnvelope"}}}}, "401": {"description": "Missing, invalid, expired or inactive API key."}, "403": {"description": "The API key does not grant tax_filings permission.", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/V1ErrorEnvelope"}}}}, "404": {"description": "CT600 submission request not found.", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/V1ErrorEnvelope"}}}} }, "x-financial-iq-safety": {"scope": "business.ct600_submission_requests.read", "businessMutation": false, "directFinancialMutation": false, "writeLevel": "read", "requiresIdempotencyKey": false, "auditedEndpoint": "v1/business/companies/{company_id}/ct600-submission-requests/{request_id}", "requiredPermission": "tax_filings", "doesNot": ["submit_to_hmrc", "post_to_ledger", "move_money"]}, "x-implementation": {"edgeFunction": "supabase/functions/financial-data-api/index.ts", "handler": "handleV1BusinessCt600SubmissionRequestDetail", "tests": ["supabase/functions/financial-data-api/invoice_idempotency.test.ts", "supabase/tests/api_business_ct600_submission_request.sql"]} } }, "/v1/business/companies/{company_id}/companies-house-submission-requests": { "post": { "tags": ["Business"], "operationId": "createBusinessCompaniesHouseSubmissionRequest", "summary": "Request business Companies House submission approval", "description": "Creates a short-lived, audited handoff for a signed-in Financial IQ user to review and submit statutory accounts to Companies House. The API key cannot submit directly or bypass accounts readiness, filing authority, credentials or duplicate-submission controls.", "security": [{"ApiKeyAuth": []}], "parameters": [ {"$ref": "#/components/parameters/BusinessCompanyId"}, {"$ref": "#/components/parameters/RequestId"}, {"$ref": "#/components/parameters/IdempotencyKey"} ], "requestBody": {"required": true, "content": {"application/json": {"schema": {"$ref": "#/components/schemas/V1BusinessCompaniesHouseSubmissionRequestCreate"}}}}, "responses": { "201": {"description": "Companies House submission approval handoff created.", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/V1BusinessCompaniesHouseSubmissionRequestResponse"}}}}, "400": {"description": "Invalid accounting period or missing idempotency key.", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/V1ErrorEnvelope"}}}}, "401": {"description": "Missing, invalid, expired or inactive API key."}, "403": {"description": "The API key does not grant tax_filings permission.", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/V1ErrorEnvelope"}}}}, "404": {"description": "Business accounting period not found.", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/V1ErrorEnvelope"}}}}, "409": {"description": "A filing already exists for the accounting period and environment.", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/V1ErrorEnvelope"}}}} }, "x-financial-iq-safety": {"scope": "business.companies_house_submission_requests.create", "businessMutation": true, "directFinancialMutation": false, "writeLevel": "human_approval", "requiresIdempotencyKey": true, "auditedEndpoint": "v1/business/companies/{company_id}/companies-house-submission-requests", "requiredPermission": "tax_filings", "approvalRequired": true, "doesNot": ["submit_directly_to_companies_house", "bypass_accounts_readiness", "bypass_filing_authority", "bypass_credentials", "post_to_ledger", "move_money"]}, "x-implementation": {"edgeFunction": "supabase/functions/financial-data-api/index.ts", "handler": "handleV1BusinessCompaniesHouseSubmissionRequestCreate", "tests": ["supabase/functions/financial-data-api/invoice_idempotency.test.ts", "supabase/tests/api_business_companies_house_submission_request.sql"]} } }, "/v1/business/companies/{company_id}/companies-house-submission-requests/{request_id}": { "get": { "tags": ["Business"], "operationId": "getBusinessCompaniesHouseSubmissionRequest", "summary": "Get business Companies House submission approval status", "description": "Returns the status of a Companies House submission approval handoff. It never submits, retries or changes statutory accounts.", "security": [{"ApiKeyAuth": []}], "parameters": [ {"$ref": "#/components/parameters/BusinessCompanyId"}, {"name": "request_id", "in": "path", "required": true, "description": "Companies House submission approval request id.", "schema": {"type": "string", "format": "uuid"}}, {"$ref": "#/components/parameters/RequestId"} ], "responses": { "200": {"description": "Companies House submission approval status returned.", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/V1BusinessCompaniesHouseSubmissionRequestResponse"}}}}, "400": {"description": "Invalid path parameter.", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/V1ErrorEnvelope"}}}}, "401": {"description": "Missing, invalid, expired or inactive API key."}, "403": {"description": "The API key does not grant tax_filings permission.", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/V1ErrorEnvelope"}}}}, "404": {"description": "Companies House submission request not found.", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/V1ErrorEnvelope"}}}} }, "x-financial-iq-safety": {"scope": "business.companies_house_submission_requests.read", "businessMutation": false, "directFinancialMutation": false, "writeLevel": "read", "requiresIdempotencyKey": false, "auditedEndpoint": "v1/business/companies/{company_id}/companies-house-submission-requests/{request_id}", "requiredPermission": "tax_filings", "doesNot": ["submit_to_companies_house", "post_to_ledger", "move_money"]}, "x-implementation": {"edgeFunction": "supabase/functions/financial-data-api/index.ts", "handler": "handleV1BusinessCompaniesHouseSubmissionRequestDetail", "tests": ["supabase/functions/financial-data-api/invoice_idempotency.test.ts", "supabase/tests/api_business_companies_house_submission_request.sql"]} } }, "/v1/business/companies/{company_id}/ct600-filings": { "get": { "tags": [ "Business" ], "operationId": "listBusinessCt600Filings", "summary": "List business CT600 filings", "description": "Lists CT600 filing history and status for one accessible business company. This route is read-only: it does not calculate corporation tax, generate iXBRL, create filings, submit to HMRC, poll HMRC, post ledger entries, close periods or move money.", "security": [ { "ApiKeyAuth": [] } ], "parameters": [ { "$ref": "#/components/parameters/BusinessCompanyId" }, { "$ref": "#/components/parameters/RequestId" }, { "name": "status", "in": "query", "required": false, "description": "Filter by local CT600 filing status.", "schema": { "type": "string", "enum": [ "draft", "pending", "submitted", "accepted", "rejected", "failed" ] } }, { "name": "environment", "in": "query", "required": false, "description": "Filter by HMRC endpoint environment.", "schema": { "type": "string", "enum": [ "sandbox", "production" ] } }, { "name": "accounting_period_id", "in": "query", "required": false, "description": "Filter by accounting period id.", "schema": { "type": "string", "format": "uuid" } }, { "name": "submitted_from", "in": "query", "required": false, "description": "Inclusive lower bound for submitted timestamp.", "schema": { "type": "string", "format": "date-time" } }, { "name": "submitted_to", "in": "query", "required": false, "description": "Inclusive upper bound for submitted timestamp.", "schema": { "type": "string", "format": "date-time" } }, { "name": "accepted_from", "in": "query", "required": false, "description": "Inclusive lower bound for accepted timestamp.", "schema": { "type": "string", "format": "date-time" } }, { "name": "accepted_to", "in": "query", "required": false, "description": "Inclusive upper bound for accepted timestamp.", "schema": { "type": "string", "format": "date-time" } }, { "name": "limit", "in": "query", "required": false, "description": "Maximum records to return, capped at 100.", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 50 } }, { "name": "offset", "in": "query", "required": false, "description": "Zero-based pagination offset.", "schema": { "type": "integer", "minimum": 0, "default": 0 } } ], "responses": { "200": { "description": "Business CT600 filings returned.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1BusinessCt600FilingListResponse" } } } }, "400": { "description": "The company_id, id filter, status, environment or timestamp filter is invalid.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1ErrorEnvelope" } } } }, "401": { "description": "Missing, invalid, expired or inactive API key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LegacyErrorResponse" } } } }, "403": { "description": "The API key does not grant reports permission.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1ErrorEnvelope" } } } }, "404": { "description": "Business company not found.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1ErrorEnvelope" } } } }, "405": { "description": "Only GET is allowed for this route.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1ErrorEnvelope" } } } }, "500": { "description": "Generic server failure. Internal database details must not be returned.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1ErrorEnvelope" } } } } }, "x-financial-iq-safety": { "scope": "business.ct600_filings.read", "businessMutation": false, "directFinancialMutation": false, "writeLevel": "read", "requiresIdempotencyKey": false, "auditedEndpoint": "v1/business/companies/{company_id}/ct600-filings", "requiredPermission": "reports", "doesNot": [ "calculate_corporation_tax", "generate_ixbrl", "create_ct600_filing", "submit_to_hmrc", "poll_hmrc", "post_to_ledger", "file_tax_return", "close_accounting_period", "move_money" ] }, "x-implementation": { "edgeFunction": "supabase/functions/financial-data-api/index.ts", "handler": "handleV1BusinessCt600Filings", "tests": [ "supabase/functions/financial-data-api/invoice_idempotency.test.ts" ] } } }, "/v1/business/companies/{company_id}/ct600-filings/{ct600_filing_id}": { "get": { "tags": [ "Business" ], "operationId": "getBusinessCt600Filing", "summary": "Get business CT600 filing", "description": "Returns one CT600 filing status for an accessible business company. This route is read-only and never submits to HMRC or changes the books.", "security": [ { "ApiKeyAuth": [] } ], "parameters": [ { "$ref": "#/components/parameters/BusinessCompanyId" }, { "name": "ct600_filing_id", "in": "path", "required": true, "description": "CT600 filing id to fetch.", "schema": { "type": "string", "format": "uuid" } }, { "$ref": "#/components/parameters/RequestId" } ], "responses": { "200": { "description": "Business CT600 filing returned.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1BusinessCt600FilingDetailResponse" } } } }, "400": { "description": "The company_id or ct600_filing_id path parameter is invalid.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1ErrorEnvelope" } } } }, "401": { "description": "Missing, invalid, expired or inactive API key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LegacyErrorResponse" } } } }, "403": { "description": "The API key does not grant reports permission.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1ErrorEnvelope" } } } }, "404": { "description": "Business CT600 filing not found.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1ErrorEnvelope" } } } }, "405": { "description": "Only GET is allowed for this route.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1ErrorEnvelope" } } } }, "500": { "description": "Generic server failure. Internal database details must not be returned.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1ErrorEnvelope" } } } } }, "x-financial-iq-safety": { "scope": "business.ct600_filings.read", "businessMutation": false, "directFinancialMutation": false, "writeLevel": "read", "requiresIdempotencyKey": false, "auditedEndpoint": "v1/business/companies/{company_id}/ct600-filings/{ct600_filing_id}", "requiredPermission": "reports", "doesNot": [ "calculate_corporation_tax", "generate_ixbrl", "create_ct600_filing", "submit_to_hmrc", "poll_hmrc", "post_to_ledger", "file_tax_return", "close_accounting_period", "move_money" ] }, "x-implementation": { "edgeFunction": "supabase/functions/financial-data-api/index.ts", "handler": "handleV1BusinessCt600FilingDetail", "tests": [ "supabase/functions/financial-data-api/invoice_idempotency.test.ts" ] } } }, "/v1/business/companies/{company_id}/statutory-accounts/versions": { "get": { "tags": [ "Business" ], "operationId": "listBusinessStatutoryAccountsVersions", "summary": "List business statutory accounts versions", "description": "Lists statutory accounts version metadata for one accessible business company. This route is read-only: it does not generate statutory accounts, generate iXBRL, save versions, file accounts, submit to Companies House, close periods or move money.", "security": [ { "ApiKeyAuth": [] } ], "parameters": [ { "$ref": "#/components/parameters/BusinessCompanyId" }, { "$ref": "#/components/parameters/RequestId" }, { "name": "accounting_period_id", "in": "query", "required": false, "description": "Filter by accounting period id.", "schema": { "type": "string", "format": "uuid" } }, { "name": "current_only", "in": "query", "required": false, "description": "Set to true to return only current statutory accounts versions.", "schema": { "type": "boolean", "default": false } }, { "name": "include_inactive", "in": "query", "required": false, "description": "Set to true to include inactive/replaced statutory accounts versions.", "schema": { "type": "boolean", "default": false } }, { "name": "is_audited", "in": "query", "required": false, "description": "Filter by audit flag.", "schema": { "type": "boolean" } }, { "name": "saved_from", "in": "query", "required": false, "description": "Inclusive lower bound for saved timestamp.", "schema": { "type": "string", "format": "date-time" } }, { "name": "saved_to", "in": "query", "required": false, "description": "Inclusive upper bound for saved timestamp.", "schema": { "type": "string", "format": "date-time" } }, { "name": "limit", "in": "query", "required": false, "description": "Maximum records to return, capped at 100.", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 50 } }, { "name": "offset", "in": "query", "required": false, "description": "Zero-based pagination offset.", "schema": { "type": "integer", "minimum": 0, "default": 0 } } ], "responses": { "200": { "description": "Business statutory accounts versions returned.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1BusinessStatutoryAccountsVersionListResponse" } } } }, "400": { "description": "The company_id, id filter, boolean filter or timestamp filter is invalid.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1ErrorEnvelope" } } } }, "401": { "description": "Missing, invalid, expired or inactive API key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LegacyErrorResponse" } } } }, "403": { "description": "The API key does not grant reports permission.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1ErrorEnvelope" } } } }, "404": { "description": "Business company not found.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1ErrorEnvelope" } } } }, "405": { "description": "Only GET is allowed for this route.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1ErrorEnvelope" } } } }, "500": { "description": "Generic server failure. Internal database details must not be returned.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1ErrorEnvelope" } } } } }, "x-financial-iq-safety": { "scope": "business.statutory_accounts_versions.read", "businessMutation": false, "directFinancialMutation": false, "writeLevel": "read", "requiresIdempotencyKey": false, "auditedEndpoint": "v1/business/companies/{company_id}/statutory-accounts/versions", "requiredPermission": "reports", "doesNot": [ "generate_statutory_accounts", "generate_ixbrl", "save_statutory_accounts_version", "set_current_version", "file_accounts", "submit_to_companies_house", "close_accounting_period", "move_money" ] }, "x-implementation": { "edgeFunction": "supabase/functions/financial-data-api/index.ts", "handler": "handleV1BusinessStatutoryAccountsVersions", "tests": [ "supabase/functions/financial-data-api/invoice_idempotency.test.ts" ] } } }, "/v1/business/companies/{company_id}/statutory-accounts/versions/{statutory_accounts_version_id}": { "get": { "tags": [ "Business" ], "operationId": "getBusinessStatutoryAccountsVersion", "summary": "Get business statutory accounts version", "description": "Returns one statutory accounts version metadata record for an accessible business company. This route is read-only and never regenerates accounts, files accounts, or changes the books.", "security": [ { "ApiKeyAuth": [] } ], "parameters": [ { "$ref": "#/components/parameters/BusinessCompanyId" }, { "name": "statutory_accounts_version_id", "in": "path", "required": true, "description": "Statutory accounts version id to fetch.", "schema": { "type": "string", "format": "uuid" } }, { "$ref": "#/components/parameters/RequestId" } ], "responses": { "200": { "description": "Business statutory accounts version returned.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1BusinessStatutoryAccountsVersionDetailResponse" } } } }, "400": { "description": "The company_id or statutory_accounts_version_id path parameter is invalid.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1ErrorEnvelope" } } } }, "401": { "description": "Missing, invalid, expired or inactive API key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LegacyErrorResponse" } } } }, "403": { "description": "The API key does not grant reports permission.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1ErrorEnvelope" } } } }, "404": { "description": "Business statutory accounts version not found.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1ErrorEnvelope" } } } }, "405": { "description": "Only GET is allowed for this route.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1ErrorEnvelope" } } } }, "500": { "description": "Generic server failure. Internal database details must not be returned.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1ErrorEnvelope" } } } } }, "x-financial-iq-safety": { "scope": "business.statutory_accounts_versions.read", "businessMutation": false, "directFinancialMutation": false, "writeLevel": "read", "requiresIdempotencyKey": false, "auditedEndpoint": "v1/business/companies/{company_id}/statutory-accounts/versions/{statutory_accounts_version_id}", "requiredPermission": "reports", "doesNot": [ "generate_statutory_accounts", "generate_ixbrl", "save_statutory_accounts_version", "set_current_version", "file_accounts", "submit_to_companies_house", "close_accounting_period", "move_money" ] }, "x-implementation": { "edgeFunction": "supabase/functions/financial-data-api/index.ts", "handler": "handleV1BusinessStatutoryAccountsVersionDetail", "tests": [ "supabase/functions/financial-data-api/invoice_idempotency.test.ts" ] } } }, "/v1/business/companies/{company_id}/directors": { "get": { "tags": [ "Business" ], "operationId": "listBusinessDirectors", "summary": "List business directors", "description": "Lists current director register records for one accessible business company. Set include_resigned=true to include resigned directors. This route is read-only: it does not appoint directors, resign directors, update company registers, post journals, close periods or move money.", "security": [ { "ApiKeyAuth": [] } ], "parameters": [ { "$ref": "#/components/parameters/BusinessCompanyId" }, { "$ref": "#/components/parameters/RequestId" }, { "name": "include_resigned", "in": "query", "required": false, "description": "Set to true to include resigned directors.", "schema": { "type": "boolean", "default": false } }, { "name": "search", "in": "query", "required": false, "description": "Case-insensitive director name search. Alias: q.", "schema": { "type": "string", "maxLength": 120 } }, { "name": "q", "in": "query", "required": false, "description": "Alias for search.", "schema": { "type": "string", "maxLength": 120 } }, { "name": "appointed_from", "in": "query", "required": false, "description": "Inclusive lower bound for appointment date.", "schema": { "type": "string", "format": "date" } }, { "name": "appointed_to", "in": "query", "required": false, "description": "Inclusive upper bound for appointment date.", "schema": { "type": "string", "format": "date" } }, { "name": "resigned_from", "in": "query", "required": false, "description": "Inclusive lower bound for resignation date.", "schema": { "type": "string", "format": "date" } }, { "name": "resigned_to", "in": "query", "required": false, "description": "Inclusive upper bound for resignation date.", "schema": { "type": "string", "format": "date" } }, { "name": "limit", "in": "query", "required": false, "description": "Maximum records to return, capped at 100.", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 50 } }, { "name": "offset", "in": "query", "required": false, "description": "Zero-based pagination offset.", "schema": { "type": "integer", "minimum": 0, "default": 0 } } ], "responses": { "200": { "description": "Business directors returned.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1BusinessDirectorListResponse" } } } }, "400": { "description": "The company_id, filter value, boolean filter, search string or date filter is invalid.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1ErrorEnvelope" } } } }, "401": { "description": "Missing, invalid, expired or inactive API key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LegacyErrorResponse" } } } }, "403": { "description": "The API key does not grant reports permission.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1ErrorEnvelope" } } } }, "404": { "description": "Business company not found.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1ErrorEnvelope" } } } }, "405": { "description": "Only GET is allowed for this route.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1ErrorEnvelope" } } } }, "500": { "description": "Generic server failure. Internal database details must not be returned.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1ErrorEnvelope" } } } } }, "x-financial-iq-safety": { "scope": "business.directors.read", "businessMutation": false, "directFinancialMutation": false, "writeLevel": "read", "requiresIdempotencyKey": false, "auditedEndpoint": "v1/business/companies/{company_id}/directors", "requiredPermission": "reports", "doesNot": [ "create_director", "update_director", "resign_director", "update_company_register", "post_to_ledger", "close_accounting_period", "move_money" ] }, "x-implementation": { "edgeFunction": "supabase/functions/financial-data-api/index.ts", "handler": "handleV1BusinessDirectors", "tests": [ "supabase/functions/financial-data-api/invoice_idempotency.test.ts" ] } } }, "/v1/business/companies/{company_id}/directors/{director_id}": { "get": { "tags": [ "Business" ], "operationId": "getBusinessDirector", "summary": "Get business director", "description": "Returns one director register record for an accessible business company. This route is read-only and never changes the register, posts to the ledger or files anything with Companies House.", "security": [ { "ApiKeyAuth": [] } ], "parameters": [ { "$ref": "#/components/parameters/BusinessCompanyId" }, { "name": "director_id", "in": "path", "required": true, "description": "Director id to fetch.", "schema": { "type": "string", "format": "uuid" } }, { "$ref": "#/components/parameters/RequestId" } ], "responses": { "200": { "description": "Business director returned.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1BusinessDirectorDetailResponse" } } } }, "400": { "description": "The company_id or director_id path parameter is invalid.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1ErrorEnvelope" } } } }, "401": { "description": "Missing, invalid, expired or inactive API key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LegacyErrorResponse" } } } }, "403": { "description": "The API key does not grant reports permission.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1ErrorEnvelope" } } } }, "404": { "description": "Business director not found.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1ErrorEnvelope" } } } }, "405": { "description": "Only GET is allowed for this route.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1ErrorEnvelope" } } } }, "500": { "description": "Generic server failure. Internal database details must not be returned.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1ErrorEnvelope" } } } } }, "x-financial-iq-safety": { "scope": "business.directors.read", "businessMutation": false, "directFinancialMutation": false, "writeLevel": "read", "requiresIdempotencyKey": false, "auditedEndpoint": "v1/business/companies/{company_id}/directors/{director_id}", "requiredPermission": "reports", "doesNot": [ "create_director", "update_director", "resign_director", "update_company_register", "post_to_ledger", "close_accounting_period", "move_money" ] }, "x-implementation": { "edgeFunction": "supabase/functions/financial-data-api/index.ts", "handler": "handleV1BusinessDirectorDetail", "tests": [ "supabase/functions/financial-data-api/invoice_idempotency.test.ts" ] } } }, "/v1/business/companies/{company_id}/shareholders": { "get": { "tags": [ "Business" ], "operationId": "listBusinessShareholders", "summary": "List business shareholders", "description": "Lists active shareholder register records for one accessible business company. Set include_inactive=true to include inactive historical shareholders. This route is read-only: it does not create shareholders, update shareholdings, update company registers, post journals, close periods or move money.", "security": [ { "ApiKeyAuth": [] } ], "parameters": [ { "$ref": "#/components/parameters/BusinessCompanyId" }, { "$ref": "#/components/parameters/RequestId" }, { "name": "include_inactive", "in": "query", "required": false, "description": "Set to true to include inactive shareholder records.", "schema": { "type": "boolean", "default": false } }, { "name": "member_type", "in": "query", "required": false, "description": "Filter by shareholder member type.", "schema": { "type": "string", "enum": [ "individual", "entity" ] } }, { "name": "search", "in": "query", "required": false, "description": "Case-insensitive shareholder name search. Alias: q.", "schema": { "type": "string", "maxLength": 120 } }, { "name": "q", "in": "query", "required": false, "description": "Alias for search.", "schema": { "type": "string", "maxLength": 120 } }, { "name": "limit", "in": "query", "required": false, "description": "Maximum records to return, capped at 100.", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 50 } }, { "name": "offset", "in": "query", "required": false, "description": "Zero-based pagination offset.", "schema": { "type": "integer", "minimum": 0, "default": 0 } } ], "responses": { "200": { "description": "Business shareholders returned.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1BusinessShareholderListResponse" } } } }, "400": { "description": "The company_id, filter value, boolean filter or search string is invalid.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1ErrorEnvelope" } } } }, "401": { "description": "Missing, invalid, expired or inactive API key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LegacyErrorResponse" } } } }, "403": { "description": "The API key does not grant reports permission.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1ErrorEnvelope" } } } }, "404": { "description": "Business company not found.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1ErrorEnvelope" } } } }, "405": { "description": "Only GET is allowed for this route.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1ErrorEnvelope" } } } }, "500": { "description": "Generic server failure. Internal database details must not be returned.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1ErrorEnvelope" } } } } }, "x-financial-iq-safety": { "scope": "business.shareholders.read", "businessMutation": false, "directFinancialMutation": false, "writeLevel": "read", "requiresIdempotencyKey": false, "auditedEndpoint": "v1/business/companies/{company_id}/shareholders", "requiredPermission": "reports", "doesNot": [ "create_shareholder", "update_shareholder", "deactivate_shareholder", "update_company_register", "post_to_ledger", "close_accounting_period", "move_money" ] }, "x-implementation": { "edgeFunction": "supabase/functions/financial-data-api/index.ts", "handler": "handleV1BusinessShareholders", "tests": [ "supabase/functions/financial-data-api/invoice_idempotency.test.ts" ] } } }, "/v1/business/companies/{company_id}/shareholders/{shareholder_id}": { "get": { "tags": [ "Business" ], "operationId": "getBusinessShareholder", "summary": "Get business shareholder", "description": "Returns one shareholder register record for an accessible business company. This route is read-only and never changes the member register, shareholdings, ledger or filings.", "security": [ { "ApiKeyAuth": [] } ], "parameters": [ { "$ref": "#/components/parameters/BusinessCompanyId" }, { "name": "shareholder_id", "in": "path", "required": true, "description": "Shareholder id to fetch.", "schema": { "type": "string", "format": "uuid" } }, { "$ref": "#/components/parameters/RequestId" } ], "responses": { "200": { "description": "Business shareholder returned.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1BusinessShareholderDetailResponse" } } } }, "400": { "description": "The company_id or shareholder_id path parameter is invalid.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1ErrorEnvelope" } } } }, "401": { "description": "Missing, invalid, expired or inactive API key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LegacyErrorResponse" } } } }, "403": { "description": "The API key does not grant reports permission.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1ErrorEnvelope" } } } }, "404": { "description": "Business shareholder not found.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1ErrorEnvelope" } } } }, "405": { "description": "Only GET is allowed for this route.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1ErrorEnvelope" } } } }, "500": { "description": "Generic server failure. Internal database details must not be returned.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1ErrorEnvelope" } } } } }, "x-financial-iq-safety": { "scope": "business.shareholders.read", "businessMutation": false, "directFinancialMutation": false, "writeLevel": "read", "requiresIdempotencyKey": false, "auditedEndpoint": "v1/business/companies/{company_id}/shareholders/{shareholder_id}", "requiredPermission": "reports", "doesNot": [ "create_shareholder", "update_shareholder", "deactivate_shareholder", "update_company_register", "post_to_ledger", "close_accounting_period", "move_money" ] }, "x-implementation": { "edgeFunction": "supabase/functions/financial-data-api/index.ts", "handler": "handleV1BusinessShareholderDetail", "tests": [ "supabase/functions/financial-data-api/invoice_idempotency.test.ts" ] } } }, "/v1/business/companies/{company_id}/share-classes": { "get": { "tags": [ "Business" ], "operationId": "listBusinessShareClasses", "summary": "List business share classes", "description": "Lists share classes for one accessible business company. This route is read-only: it does not create share classes, allot shares, update registers, post journals, close periods or move money.", "security": [ { "ApiKeyAuth": [] } ], "parameters": [ { "$ref": "#/components/parameters/BusinessCompanyId" }, { "$ref": "#/components/parameters/RequestId" }, { "name": "is_numbered", "in": "query", "required": false, "description": "Filter numbered or unnumbered share classes.", "schema": { "type": "boolean" } }, { "name": "search", "in": "query", "required": false, "description": "Case-insensitive share-class name search. Alias: q.", "schema": { "type": "string", "maxLength": 120 } }, { "name": "q", "in": "query", "required": false, "description": "Alias for search.", "schema": { "type": "string", "maxLength": 120 } }, { "name": "limit", "in": "query", "required": false, "description": "Maximum records to return, capped at 100.", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 50 } }, { "name": "offset", "in": "query", "required": false, "description": "Zero-based pagination offset.", "schema": { "type": "integer", "minimum": 0, "default": 0 } } ], "responses": { "200": { "description": "business share classes returned.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1BusinessShareClassListResponse" } } } }, "400": { "description": "The path or query parameters are invalid.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1ErrorEnvelope" } } } }, "401": { "description": "Missing, invalid, expired or inactive API key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LegacyErrorResponse" } } } }, "403": { "description": "The API key does not grant reports permission.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1ErrorEnvelope" } } } }, "404": { "description": "Business company not found.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1ErrorEnvelope" } } } }, "405": { "description": "Only GET is allowed for this route.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1ErrorEnvelope" } } } }, "500": { "description": "Generic server failure. Internal database details must not be returned.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1ErrorEnvelope" } } } } }, "x-financial-iq-safety": { "writeLevel": "read", "requiresIdempotencyKey": false, "scope": "business.share_classes.read", "requiredPermission": "reports", "auditedEndpoint": "v1/business/companies/{company_id}/share-classes", "doesNot": [ "create_share_class", "allot_shares", "update_company_register", "post_journal", "close_accounting_period", "move_money" ] }, "x-implementation": { "handler": "handleV1BusinessShareClasses" } } }, "/v1/business/companies/{company_id}/share-classes/{share_class_id}": { "get": { "tags": [ "Business" ], "operationId": "getBusinessShareClass", "summary": "Get business share class", "description": "Returns one share class for an accessible business company. This route is read-only and never changes share capital, registers, ledgers or filings.", "security": [ { "ApiKeyAuth": [] } ], "parameters": [ { "$ref": "#/components/parameters/BusinessCompanyId" }, { "name": "share_class_id", "in": "path", "required": true, "description": "Share class id to fetch.", "schema": { "type": "string", "format": "uuid" } }, { "$ref": "#/components/parameters/RequestId" } ], "responses": { "200": { "description": "business share class returned.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1BusinessShareClassDetailResponse" } } } }, "400": { "description": "The company_id or share_class_id path parameter is invalid.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1ErrorEnvelope" } } } }, "401": { "description": "Missing, invalid, expired or inactive API key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LegacyErrorResponse" } } } }, "403": { "description": "The API key does not grant reports permission.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1ErrorEnvelope" } } } }, "404": { "description": "Business shareholder not found.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1ErrorEnvelope" } } } }, "405": { "description": "Only GET is allowed for this route.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1ErrorEnvelope" } } } }, "500": { "description": "Generic server failure. Internal database details must not be returned.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1ErrorEnvelope" } } } } }, "x-financial-iq-safety": { "writeLevel": "read", "requiresIdempotencyKey": false, "scope": "business.share_classes.read", "requiredPermission": "reports", "auditedEndpoint": "v1/business/companies/{company_id}/share-classes/{share_class_id}", "doesNot": [ "create_share_class", "allot_shares", "update_company_register", "post_journal", "close_accounting_period", "move_money" ] }, "x-implementation": { "handler": "handleV1BusinessShareClassDetail" } } }, "/v1/business/companies/{company_id}/share-issues": { "get": { "tags": [ "Business" ], "operationId": "listBusinessShareIssues", "summary": "List business share issues", "description": "Lists share issues for one accessible business company. This route is read-only: it does not issue shares, update registers, post journals, close periods or move money.", "security": [ { "ApiKeyAuth": [] } ], "parameters": [ { "$ref": "#/components/parameters/BusinessCompanyId" }, { "$ref": "#/components/parameters/RequestId" }, { "name": "share_class_id", "in": "query", "required": false, "description": "Filter by share class.", "schema": { "type": "string", "format": "uuid" } }, { "name": "shareholder_id", "in": "query", "required": false, "description": "Filter by shareholder.", "schema": { "type": "string", "format": "uuid" } }, { "name": "issued_from", "in": "query", "required": false, "description": "Inclusive lower bound for issue date.", "schema": { "type": "string", "format": "date" } }, { "name": "issued_to", "in": "query", "required": false, "description": "Inclusive upper bound for issue date.", "schema": { "type": "string", "format": "date" } }, { "name": "posted_to_ledger", "in": "query", "required": false, "description": "Filter by ledger posting state.", "schema": { "type": "boolean" } }, { "name": "search", "in": "query", "required": false, "description": "Case-insensitive reference search. Alias: q.", "schema": { "type": "string", "maxLength": 120 } }, { "name": "q", "in": "query", "required": false, "description": "Alias for search.", "schema": { "type": "string", "maxLength": 120 } }, { "name": "limit", "in": "query", "required": false, "description": "Maximum records to return, capped at 100.", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 50 } }, { "name": "offset", "in": "query", "required": false, "description": "Zero-based pagination offset.", "schema": { "type": "integer", "minimum": 0, "default": 0 } } ], "responses": { "200": { "description": "business share issues returned.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1BusinessShareIssueListResponse" } } } }, "400": { "description": "The path or query parameters are invalid.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1ErrorEnvelope" } } } }, "401": { "description": "Missing, invalid, expired or inactive API key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LegacyErrorResponse" } } } }, "403": { "description": "The API key does not grant reports permission.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1ErrorEnvelope" } } } }, "404": { "description": "Business company not found.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1ErrorEnvelope" } } } }, "405": { "description": "Only GET is allowed for this route.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1ErrorEnvelope" } } } }, "500": { "description": "Generic server failure. Internal database details must not be returned.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1ErrorEnvelope" } } } } }, "x-financial-iq-safety": { "writeLevel": "read", "requiresIdempotencyKey": false, "scope": "business.share_issues.read", "requiredPermission": "reports", "auditedEndpoint": "v1/business/companies/{company_id}/share-issues", "doesNot": [ "create_share_class", "allot_shares", "update_company_register", "post_journal", "close_accounting_period", "move_money" ] }, "x-implementation": { "handler": "handleV1BusinessShareIssues" } } }, "/v1/business/companies/{company_id}/share-issues/{share_issue_id}": { "get": { "tags": [ "Business" ], "operationId": "getBusinessShareIssue", "summary": "Get business share issue", "description": "Returns one share issue for an accessible business company. This route is read-only and never changes share capital, registers, ledgers or filings.", "security": [ { "ApiKeyAuth": [] } ], "parameters": [ { "$ref": "#/components/parameters/BusinessCompanyId" }, { "name": "share_issue_id", "in": "path", "required": true, "description": "Share issue id to fetch.", "schema": { "type": "string", "format": "uuid" } }, { "$ref": "#/components/parameters/RequestId" } ], "responses": { "200": { "description": "business share issue returned.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1BusinessShareIssueDetailResponse" } } } }, "400": { "description": "The company_id or share_issue_id path parameter is invalid.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1ErrorEnvelope" } } } }, "401": { "description": "Missing, invalid, expired or inactive API key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LegacyErrorResponse" } } } }, "403": { "description": "The API key does not grant reports permission.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1ErrorEnvelope" } } } }, "404": { "description": "Business shareholder not found.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1ErrorEnvelope" } } } }, "405": { "description": "Only GET is allowed for this route.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1ErrorEnvelope" } } } }, "500": { "description": "Generic server failure. Internal database details must not be returned.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1ErrorEnvelope" } } } } }, "x-financial-iq-safety": { "writeLevel": "read", "requiresIdempotencyKey": false, "scope": "business.share_issues.read", "requiredPermission": "reports", "auditedEndpoint": "v1/business/companies/{company_id}/share-issues/{share_issue_id}", "doesNot": [ "create_share_class", "allot_shares", "update_company_register", "post_journal", "close_accounting_period", "move_money" ] }, "x-implementation": { "handler": "handleV1BusinessShareIssueDetail" } } }, "/v1/business/companies/{company_id}/dividend-declarations": { "post": { "tags": [ "Business" ], "operationId": "createBusinessDividendDeclaration", "summary": "Create a draft dividend proposal", "description": "Creates a draft dividend proposal for a company. A human must approve it before any paperwork, ledger posting, settlement or payment occurs.", "security": [ { "ApiKeyAuth": [] } ], "parameters": [ { "$ref": "#/components/parameters/BusinessCompanyId" }, { "$ref": "#/components/parameters/RequestId" }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BusinessDividendDeclarationCreateRequest" } } } }, "responses": { "201": { "description": "Draft dividend proposal created.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1BusinessDividendDeclarationDetailResponse" } } } }, "400": { "description": "The request body, date or idempotency key is invalid.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1ErrorEnvelope" } } } }, "401": { "description": "Missing, invalid, expired or inactive API key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LegacyErrorResponse" } } } }, "403": { "description": "The API key lacks dividend permission or the owner lacks company dividend authority.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1ErrorEnvelope" } } } }, "404": { "description": "Business company not found or inaccessible.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1ErrorEnvelope" } } } }, "409": { "description": "The declaration reference or idempotency key conflicts with an existing request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1ErrorEnvelope" } } } }, "500": { "description": "Generic server failure.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1ErrorEnvelope" } } } } }, "x-financial-iq-safety": { "requiresApiKey": true, "apiKeysAllowed": true, "requiresUserBearerToken": false, "auditedEndpoint": "v1/business/companies/{company_id}/dividend-declarations", "scope": "business.dividend_declarations.create", "requiredPermission": "dividends", "businessMutation": true, "directFinancialMutation": false, "writeLevel": "approval_proposal", "requiresIdempotencyKey": true, "approvalRequired": true, "directExecution": false, "doesNot": [ "approve_dividend", "post_journal", "settle_dividend", "make_payment" ] }, "x-implementation": { "source": "supabase/functions/financial-data-api/v1.ts", "handler": "handleV1BusinessDividendDeclarations", "database": "create_business_dividend_declaration_api_v1_atomic" } }, "get": { "tags": [ "Business" ], "operationId": "listBusinessDividendDeclarations", "summary": "List business dividend declarations", "description": "Lists dividend declarations for one accessible business company. The collection also supports creating a draft proposal; this GET operation is read-only and does not approve, cancel, post or pay dividends.", "security": [ { "ApiKeyAuth": [] } ], "parameters": [ { "$ref": "#/components/parameters/BusinessCompanyId" }, { "$ref": "#/components/parameters/RequestId" }, { "name": "status", "in": "query", "required": false, "description": "Filter by declaration status.", "schema": { "type": "string", "enum": [ "draft", "approved", "posted", "cancelled" ] } }, { "name": "declaration_type", "in": "query", "required": false, "description": "Filter by declaration type.", "schema": { "type": "string", "enum": [ "interim", "final", "other" ] } }, { "name": "declared_from", "in": "query", "required": false, "description": "Inclusive lower bound for declaration date.", "schema": { "type": "string", "format": "date" } }, { "name": "declared_to", "in": "query", "required": false, "description": "Inclusive upper bound for declaration date.", "schema": { "type": "string", "format": "date" } }, { "name": "record_from", "in": "query", "required": false, "description": "Inclusive lower bound for record date.", "schema": { "type": "string", "format": "date" } }, { "name": "record_to", "in": "query", "required": false, "description": "Inclusive upper bound for record date.", "schema": { "type": "string", "format": "date" } }, { "name": "payment_from", "in": "query", "required": false, "description": "Inclusive lower bound for payment date.", "schema": { "type": "string", "format": "date" } }, { "name": "payment_to", "in": "query", "required": false, "description": "Inclusive upper bound for payment date.", "schema": { "type": "string", "format": "date" } }, { "name": "search", "in": "query", "required": false, "description": "Case-insensitive declaration reference search. Alias: q.", "schema": { "type": "string", "maxLength": 120 } }, { "name": "q", "in": "query", "required": false, "description": "Alias for search.", "schema": { "type": "string", "maxLength": 120 } }, { "name": "limit", "in": "query", "required": false, "description": "Maximum records to return, capped at 100.", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 50 } }, { "name": "offset", "in": "query", "required": false, "description": "Zero-based pagination offset.", "schema": { "type": "integer", "minimum": 0, "default": 0 } } ], "responses": { "200": { "description": "business dividend declarations returned.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1BusinessDividendDeclarationListResponse" } } } }, "400": { "description": "The path or query parameters are invalid.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1ErrorEnvelope" } } } }, "401": { "description": "Missing, invalid, expired or inactive API key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LegacyErrorResponse" } } } }, "403": { "description": "The API key does not grant reports permission.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1ErrorEnvelope" } } } }, "404": { "description": "Business company not found.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1ErrorEnvelope" } } } }, "405": { "description": "Only GET and POST are allowed for this route.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1ErrorEnvelope" } } } }, "500": { "description": "Generic server failure. Internal database details must not be returned.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1ErrorEnvelope" } } } } }, "x-financial-iq-safety": { "writeLevel": "read", "requiresIdempotencyKey": false, "scope": "business.dividend_declarations.read", "requiredPermission": "reports", "auditedEndpoint": "v1/business/companies/{company_id}/dividend-declarations", "doesNot": [ "declare_dividend", "approve_dividend", "cancel_dividend", "regenerate_allocations", "generate_paperwork", "post_journal", "make_payment", "close_accounting_period", "move_money" ] }, "x-implementation": { "handler": "handleV1BusinessDividendDeclarations" } } }, "/v1/business/companies/{company_id}/dividend-declarations/{dividend_declaration_id}": { "get": { "tags": [ "Business" ], "operationId": "getBusinessDividendDeclaration", "summary": "Get business dividend declaration", "description": "Returns one dividend declaration for an accessible business company. This route is read-only and never approves, cancels, posts or pays dividends.", "security": [ { "ApiKeyAuth": [] } ], "parameters": [ { "$ref": "#/components/parameters/BusinessCompanyId" }, { "name": "dividend_declaration_id", "in": "path", "required": true, "description": "Dividend declaration id to fetch.", "schema": { "type": "string", "format": "uuid" } }, { "$ref": "#/components/parameters/RequestId" } ], "responses": { "200": { "description": "business dividend declaration returned.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1BusinessDividendDeclarationDetailResponse" } } } }, "400": { "description": "The company_id or dividend_declaration_id path parameter is invalid.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1ErrorEnvelope" } } } }, "401": { "description": "Missing, invalid, expired or inactive API key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LegacyErrorResponse" } } } }, "403": { "description": "The API key does not grant reports permission.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1ErrorEnvelope" } } } }, "404": { "description": "Business shareholder not found.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1ErrorEnvelope" } } } }, "405": { "description": "Only GET is allowed for this route.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1ErrorEnvelope" } } } }, "500": { "description": "Generic server failure. Internal database details must not be returned.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1ErrorEnvelope" } } } } }, "x-financial-iq-safety": { "writeLevel": "read", "requiresIdempotencyKey": false, "scope": "business.dividend_declarations.read", "requiredPermission": "reports", "auditedEndpoint": "v1/business/companies/{company_id}/dividend-declarations/{dividend_declaration_id}", "doesNot": [ "declare_dividend", "approve_dividend", "cancel_dividend", "regenerate_allocations", "generate_paperwork", "post_journal", "make_payment", "close_accounting_period", "move_money" ] }, "x-implementation": { "handler": "handleV1BusinessDividendDeclarationDetail" } }, "patch": { "tags": [ "Business" ], "operationId": "updateBusinessDividendDeclaration", "summary": "Update a draft dividend declaration", "description": "Updates draft dividend metadata such as dates, reference, notes or currency. A reason is required and the change is audited. Approved and posted declarations are immutable.", "security": [ { "ApiKeyAuth": [] } ], "parameters": [ { "$ref": "#/components/parameters/BusinessCompanyId" }, { "name": "dividend_declaration_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "$ref": "#/components/parameters/RequestId" }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "required": [ "reason" ], "properties": { "declaration_type": { "type": "string", "enum": [ "interim", "final", "other" ] }, "declared_at": { "type": "string", "format": "date" }, "record_date": { "type": "string", "format": "date" }, "payment_date": { "type": [ "string", "null" ], "format": "date" }, "currency": { "type": "string", "pattern": "^[A-Za-z]{3}$" }, "declaration_reference": { "type": [ "string", "null" ], "maxLength": 120 }, "notes": { "type": [ "string", "null" ], "maxLength": 2000 }, "reason": { "type": "string", "minLength": 5, "maxLength": 1000 } } } } } }, "responses": { "200": { "description": "Draft dividend declaration updated.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1BusinessDividendDeclarationDetailResponse" } } } }, "400": { "description": "Invalid path, body or idempotency key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1ErrorEnvelope" } } } }, "401": { "description": "Missing, invalid, expired or inactive API key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LegacyErrorResponse" } } } }, "403": { "description": "The API key does not grant dividend permission.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1ErrorEnvelope" } } } }, "404": { "description": "Business dividend declaration not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1ErrorEnvelope" } } } }, "409": { "description": "The declaration is not a draft or its dates are invalid.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1ErrorEnvelope" } } } }, "500": { "description": "Dividend declaration update failed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1ErrorEnvelope" } } } } }, "x-financial-iq-safety": { "auditedEndpoint": "v1/business/companies/{company_id}/dividend-declarations/{dividend_declaration_id}", "requiresApiKey": true, "apiKeysAllowed": true, "requiresUserBearerToken": false, "scope": "business.dividend_declarations.update", "requiredPermissions": [ "dividends" ], "businessMutation": true, "directFinancialMutation": true, "writeLevel": "draft_correction", "requiresIdempotencyKey": true, "approvalRequired": false, "directExecution": true, "doesNot": [ "approve_dividend", "post_journal", "make_payment", "delete_records" ] }, "x-implementation": { "source": "supabase/functions/financial-data-api/v1.ts", "handler": "updateV1BusinessDividendDeclaration" } } }, "/v1/business/companies/{company_id}/dividend-declarations/{dividend_declaration_id}/submit": { "post": { "tags": [ "Business" ], "operationId": "submitBusinessDividendDeclarationForApproval", "summary": "Submit a draft dividend declaration for human approval", "description": "Creates or replays a human approval request for a draft dividend declaration. Approval regenerates shareholder allocations, marks the declaration approved, emits the dividend integration event and records audit evidence atomically. The API never pays the dividend or posts a journal entry.", "security": [ { "ApiKeyAuth": [] } ], "parameters": [ { "$ref": "#/components/parameters/BusinessCompanyId" }, { "description": "Dividend declaration id.", "in": "path", "name": "dividend_declaration_id", "required": true, "schema": { "format": "uuid", "type": "string" } }, { "$ref": "#/components/parameters/RequestId" }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "properties": { "reason": { "type": [ "string", "null" ], "maxLength": 1000 }, "requested_by_name": { "type": [ "string", "null" ], "maxLength": 160 }, "requested_by_email": { "type": [ "string", "null" ], "format": "email" } } } } } }, "responses": { "202": { "description": "Human approval request created or replayed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1BusinessApprovalRequestResponse" } } } }, "400": { "description": "Invalid path, request or idempotency key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1ErrorEnvelope" } } } }, "401": { "description": "Missing, invalid, expired or inactive API key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LegacyErrorResponse" } } } }, "403": { "description": "The API key does not grant dividend and approval-workflow permissions.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1ErrorEnvelope" } } } }, "404": { "description": "Business dividend declaration not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1ErrorEnvelope" } } } }, "409": { "description": "The declaration is not an eligible draft or approval is already being processed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1ErrorEnvelope" } } } }, "500": { "description": "Approval request creation failed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1ErrorEnvelope" } } } } }, "x-financial-iq-safety": { "auditedEndpoint": "v1/business/companies/{company_id}/dividend-declarations/{dividend_declaration_id}/submit", "requiresApiKey": true, "apiKeysAllowed": true, "requiresUserBearerToken": false, "scope": "business.dividend_declarations.approval", "requiredPermissions": [ "dividends", "approval_workflow" ], "businessMutation": true, "directFinancialMutation": true, "writeLevel": "human_approval", "requiresIdempotencyKey": true, "approvalRequired": true, "createsApprovalRequest": true, "directExecution": false, "doesNot": [ "make_payment", "settle_dividend", "post_journal" ] }, "x-implementation": { "source": "supabase/functions/financial-data-api/v1.ts", "handler": "handleV1BusinessDividendDeclarationSubmitApproval" } } }, "/v1/business/companies/{company_id}/dividend-declarations/{dividend_declaration_id}/cancel": { "post": { "tags": [ "Business" ], "operationId": "cancelBusinessDividendDeclaration", "summary": "Cancel a draft or approved dividend declaration", "description": "Cancels a draft or approved dividend declaration, archives active allocations and rejects any pending approval request. Posted declarations are protected and require a separate accounting reversal workflow. The API never pays a dividend, posts a journal entry or deletes records.", "security": [ { "ApiKeyAuth": [] } ], "parameters": [ { "$ref": "#/components/parameters/BusinessCompanyId" }, { "description": "Dividend declaration id.", "in": "path", "name": "dividend_declaration_id", "required": true, "schema": { "format": "uuid", "type": "string" } }, { "$ref": "#/components/parameters/RequestId" }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "required": [ "reason" ], "properties": { "reason": { "type": "string", "minLength": 5, "maxLength": 1000 } } } } } }, "responses": { "200": { "description": "Dividend declaration cancelled or cancellation replayed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1BusinessDividendDeclarationDetailResponse" } } } }, "400": { "description": "Invalid path, body or idempotency key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1ErrorEnvelope" } } } }, "401": { "description": "Missing, invalid, expired or inactive API key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LegacyErrorResponse" } } } }, "403": { "description": "The API key does not grant dividend permission.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1ErrorEnvelope" } } } }, "404": { "description": "Business dividend declaration not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1ErrorEnvelope" } } } }, "409": { "description": "The declaration is posted or otherwise not eligible for cancellation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1ErrorEnvelope" } } } }, "500": { "description": "Dividend cancellation failed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1ErrorEnvelope" } } } } }, "x-financial-iq-safety": { "auditedEndpoint": "v1/business/companies/{company_id}/dividend-declarations/{dividend_declaration_id}/cancel", "requiresApiKey": true, "apiKeysAllowed": true, "requiresUserBearerToken": false, "scope": "business.dividend_declarations.cancel", "requiredPermissions": [ "dividends" ], "businessMutation": true, "directFinancialMutation": true, "writeLevel": "accounting_reversal", "requiresIdempotencyKey": true, "approvalRequired": false, "directExecution": true, "doesNot": [ "make_payment", "settle_dividend", "post_journal", "delete_records" ] }, "x-implementation": { "source": "supabase/functions/financial-data-api/v1.ts", "handler": "handleV1BusinessDividendDeclarationCancel" } } }, "/v1/business/companies/{company_id}/dividend-declarations/{dividend_declaration_id}/paperwork": { "get": { "tags": [ "Business" ], "operationId": "previewBusinessDividendPaperwork", "summary": "Preview draft dividend paperwork", "description": "Returns a safe board-minute preview for a dividend declaration. Draft previews are clearly marked as unapproved; shareholder vouchers are unavailable until approval and allocation.", "security": [ { "ApiKeyAuth": [] } ], "parameters": [ { "$ref": "#/components/parameters/BusinessCompanyId" }, { "description": "Dividend declaration id.", "in": "path", "name": "dividend_declaration_id", "required": true, "schema": { "format": "uuid", "type": "string" } }, { "$ref": "#/components/parameters/RequestId" } ], "responses": { "200": { "description": "Dividend paperwork preview returned.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1BusinessDividendPaperworkPreviewResponse" } } } }, "400": { "description": "The path parameters are invalid.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1ErrorEnvelope" } } } }, "401": { "description": "Missing, invalid, expired or inactive API key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LegacyErrorResponse" } } } }, "403": { "description": "The API key does not grant reports permission.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1ErrorEnvelope" } } } }, "404": { "description": "Business dividend declaration not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1ErrorEnvelope" } } } }, "500": { "description": "Generic server failure.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1ErrorEnvelope" } } } } }, "x-financial-iq-safety": { "auditedEndpoint": "v1/business/companies/{company_id}/dividend-declarations/{dividend_declaration_id}/paperwork", "requiresApiKey": true, "apiKeysAllowed": true, "requiresUserBearerToken": false, "scope": "business.dividend_declarations.paperwork.read", "requiredPermission": "reports", "businessMutation": false, "directFinancialMutation": false, "writeLevel": "read", "requiresIdempotencyKey": false, "approvalRequired": false, "directExecution": false, "doesNot": [ "approve_dividend", "post_journal", "make_payment", "expose_shareholder_vouchers" ] }, "x-implementation": { "source": "supabase/functions/financial-data-api/v1.ts", "handler": "handleV1BusinessDividendPaperwork" } } }, "/v1/business/companies/{company_id}/dividend-declarations/{dividend_declaration_id}/lines": { "post": { "tags": [ "Business" ], "operationId": "createBusinessDividendDeclarationLines", "summary": "Add lines to a draft dividend proposal", "description": "Adds server-validated share-class lines to a draft dividend proposal and recalculates its proposed total. It does not allocate, approve, post or pay the dividend.", "security": [ { "ApiKeyAuth": [] } ], "parameters": [ { "$ref": "#/components/parameters/BusinessCompanyId" }, { "description": "Dividend declaration id.", "in": "path", "name": "dividend_declaration_id", "required": true, "schema": { "format": "uuid", "type": "string" } }, { "$ref": "#/components/parameters/RequestId" }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BusinessDividendDeclarationLinesCreateRequest" } } } }, "responses": { "201": { "description": "Draft dividend lines created.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1BusinessDividendDeclarationLineListResponse" } } } }, "400": { "description": "The line payload, path or idempotency key is invalid.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1ErrorEnvelope" } } } }, "401": { "description": "Missing, invalid, expired or inactive API key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LegacyErrorResponse" } } } }, "403": { "description": "The API key lacks dividend permission or the owner lacks dividend authority.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1ErrorEnvelope" } } } }, "404": { "description": "The dividend declaration was not found or is inaccessible.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1ErrorEnvelope" } } } }, "409": { "description": "A line or idempotency key conflicts with an existing request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1ErrorEnvelope" } } } }, "500": { "description": "Generic server failure.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1ErrorEnvelope" } } } } }, "x-financial-iq-safety": { "auditedEndpoint": "v1/business/companies/{company_id}/dividend-declarations/{dividend_declaration_id}/lines", "requiresApiKey": true, "apiKeysAllowed": true, "requiresUserBearerToken": false, "scope": "business.dividend_declarations.lines.create", "requiredPermission": "dividends", "businessMutation": true, "directFinancialMutation": false, "writeLevel": "approval_proposal", "requiresIdempotencyKey": true, "approvalRequired": true, "directExecution": false, "doesNot": [ "allocate_dividend", "approve_dividend", "post_journal", "make_payment" ] }, "x-implementation": { "source": "supabase/functions/financial-data-api/v1.ts", "handler": "handleV1BusinessDividendDeclarationLines", "database": "add_business_dividend_declaration_lines_api_v1_atomic" } }, "get": { "tags": [ "Business" ], "operationId": "listBusinessDividendDeclarationLines", "summary": "List business dividend declaration lines", "description": "Lists share-class lines for one accessible dividend declaration. Archived lines are hidden by default. This route is read-only and never recalculates or regenerates dividends.", "security": [ { "ApiKeyAuth": [] } ], "parameters": [ { "$ref": "#/components/parameters/BusinessCompanyId" }, { "name": "dividend_declaration_id", "in": "path", "required": true, "description": "Dividend declaration id.", "schema": { "type": "string", "format": "uuid" } }, { "$ref": "#/components/parameters/RequestId" }, { "name": "include_archived", "in": "query", "required": false, "description": "Set to true to include archived/replaced lines.", "schema": { "type": "boolean", "default": false } }, { "name": "limit", "in": "query", "required": false, "description": "Maximum records to return, capped at 100.", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 50 } }, { "name": "offset", "in": "query", "required": false, "description": "Zero-based pagination offset.", "schema": { "type": "integer", "minimum": 0, "default": 0 } } ], "responses": { "200": { "description": "business dividend declaration lines returned.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1BusinessDividendDeclarationLineListResponse" } } } }, "400": { "description": "The path or query parameters are invalid.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1ErrorEnvelope" } } } }, "401": { "description": "Missing, invalid, expired or inactive API key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LegacyErrorResponse" } } } }, "403": { "description": "The API key does not grant reports permission.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1ErrorEnvelope" } } } }, "404": { "description": "Business company not found.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1ErrorEnvelope" } } } }, "405": { "description": "Only GET is allowed for this route.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1ErrorEnvelope" } } } }, "500": { "description": "Generic server failure. Internal database details must not be returned.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1ErrorEnvelope" } } } } }, "x-financial-iq-safety": { "writeLevel": "read", "requiresIdempotencyKey": false, "scope": "business.dividend_declarations.read", "requiredPermission": "reports", "auditedEndpoint": "v1/business/companies/{company_id}/dividend-declarations/{dividend_declaration_id}/lines", "doesNot": [ "declare_dividend", "approve_dividend", "cancel_dividend", "regenerate_allocations", "generate_paperwork", "post_journal", "make_payment", "close_accounting_period", "move_money" ] }, "x-implementation": { "handler": "handleV1BusinessDividendDeclarationLines" } } }, "/v1/business/companies/{company_id}/dividend-declarations/{dividend_declaration_id}/lines/{dividend_line_id}": { "get": { "tags": [ "Business" ], "operationId": "getBusinessDividendDeclarationLine", "summary": "Get business dividend declaration line", "description": "Returns one share-class dividend line for one accessible dividend declaration. This route is read-only and never recalculates, posts or pays dividends.", "security": [ { "ApiKeyAuth": [] } ], "parameters": [ { "$ref": "#/components/parameters/BusinessCompanyId" }, { "name": "dividend_declaration_id", "in": "path", "required": true, "description": "Dividend declaration id.", "schema": { "type": "string", "format": "uuid" } }, { "name": "dividend_line_id", "in": "path", "required": true, "description": "Dividend declaration line id to fetch.", "schema": { "type": "string", "format": "uuid" } }, { "$ref": "#/components/parameters/RequestId" } ], "responses": { "200": { "description": "business dividend declaration line returned.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1BusinessDividendDeclarationLineDetailResponse" } } } }, "400": { "description": "The company_id, dividend_declaration_id or dividend_line_id path parameter is invalid.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1ErrorEnvelope" } } } }, "401": { "description": "Missing, invalid, expired or inactive API key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LegacyErrorResponse" } } } }, "403": { "description": "The API key does not grant reports permission.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1ErrorEnvelope" } } } }, "404": { "description": "Business dividend declaration line not found.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1ErrorEnvelope" } } } }, "405": { "description": "Only GET is allowed for this route.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1ErrorEnvelope" } } } }, "500": { "description": "Generic server failure. Internal database details must not be returned.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1ErrorEnvelope" } } } } }, "x-financial-iq-safety": { "writeLevel": "read", "requiresIdempotencyKey": false, "scope": "business.dividend_declarations.read", "requiredPermission": "reports", "auditedEndpoint": "v1/business/companies/{company_id}/dividend-declarations/{dividend_declaration_id}/lines/{dividend_line_id}", "doesNot": [ "declare_dividend", "approve_dividend", "cancel_dividend", "regenerate_allocations", "generate_paperwork", "post_journal", "make_payment", "close_accounting_period", "move_money" ] }, "x-implementation": { "handler": "handleV1BusinessDividendLineDetail" } }, "patch": { "tags": [ "Business" ], "operationId": "updateBusinessDividendDeclarationLine", "summary": "Update a draft dividend declaration line", "description": "Replaces one active line on a draft dividend declaration, retaining the previous line as history and recalculating the draft total. Approved and posted declarations are immutable.", "security": [ { "ApiKeyAuth": [] } ], "parameters": [ { "$ref": "#/components/parameters/BusinessCompanyId" }, { "name": "dividend_declaration_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "dividend_line_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "$ref": "#/components/parameters/RequestId" }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "required": [ "reason" ], "properties": { "share_class_id": { "type": "string", "format": "uuid" }, "dividend_per_share": { "type": "number", "exclusiveMinimum": 0 }, "shares_on_record_date": { "type": "integer", "minimum": 1 }, "reason": { "type": "string", "minLength": 5, "maxLength": 1000 } } } } } }, "responses": { "200": { "description": "Draft dividend line updated and prior version retained.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1BusinessDividendDeclarationLineDetailResponse" } } } }, "400": { "description": "Invalid path, body or idempotency key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1ErrorEnvelope" } } } }, "401": { "description": "Missing, invalid, expired or inactive API key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LegacyErrorResponse" } } } }, "403": { "description": "The API key does not grant dividend permission.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1ErrorEnvelope" } } } }, "404": { "description": "Business dividend declaration line not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1ErrorEnvelope" } } } }, "409": { "description": "The declaration is not a draft or the line cannot be edited.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1ErrorEnvelope" } } } }, "500": { "description": "Dividend line update failed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1ErrorEnvelope" } } } } }, "x-financial-iq-safety": { "auditedEndpoint": "v1/business/companies/{company_id}/dividend-declarations/{dividend_declaration_id}/lines/{dividend_line_id}", "requiresApiKey": true, "apiKeysAllowed": true, "requiresUserBearerToken": false, "scope": "business.dividend_declarations.lines.update", "requiredPermissions": [ "dividends" ], "businessMutation": true, "directFinancialMutation": true, "writeLevel": "draft_correction", "requiresIdempotencyKey": true, "approvalRequired": false, "directExecution": true, "doesNot": [ "approve_dividend", "post_journal", "make_payment", "delete_records" ] }, "x-implementation": { "source": "supabase/functions/financial-data-api/v1.ts", "handler": "updateV1BusinessDividendDeclarationLine" } }, "delete": { "tags": [ "Business" ], "operationId": "archiveBusinessDividendDeclarationLine", "summary": "Archive a draft dividend declaration line", "description": "Archives one active line from a draft dividend declaration, retains the prior row in history and recalculates the draft total. This route never deletes records.", "security": [ { "ApiKeyAuth": [] } ], "parameters": [ { "$ref": "#/components/parameters/BusinessCompanyId" }, { "name": "dividend_declaration_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "dividend_line_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "$ref": "#/components/parameters/RequestId" }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "required": [ "reason" ], "properties": { "reason": { "type": "string", "minLength": 5, "maxLength": 1000 } } } } } }, "responses": { "200": { "description": "Draft dividend line archived.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1BusinessDividendDeclarationLineDetailResponse" } } } }, "400": { "description": "Invalid path, body or idempotency key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1ErrorEnvelope" } } } }, "401": { "description": "Missing, invalid, expired or inactive API key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LegacyErrorResponse" } } } }, "403": { "description": "The API key does not grant dividend permission.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1ErrorEnvelope" } } } }, "404": { "description": "Business dividend declaration line not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1ErrorEnvelope" } } } }, "409": { "description": "The declaration is not a draft or the line cannot be archived.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1ErrorEnvelope" } } } }, "500": { "description": "Dividend line archival failed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1ErrorEnvelope" } } } } }, "x-financial-iq-safety": { "auditedEndpoint": "v1/business/companies/{company_id}/dividend-declarations/{dividend_declaration_id}/lines/{dividend_line_id}", "requiresApiKey": true, "apiKeysAllowed": true, "requiresUserBearerToken": false, "scope": "business.dividend_declarations.lines.archive", "requiredPermissions": [ "dividends" ], "businessMutation": true, "directFinancialMutation": true, "writeLevel": "draft_correction", "requiresIdempotencyKey": true, "approvalRequired": false, "directExecution": true, "doesNot": [ "approve_dividend", "post_journal", "make_payment", "delete_records" ] }, "x-implementation": { "source": "supabase/functions/financial-data-api/v1.ts", "handler": "archiveV1BusinessDividendDeclarationLine" } } }, "/v1/business/companies/{company_id}/dividend-declarations/{dividend_declaration_id}/allocations": { "get": { "tags": [ "Business" ], "operationId": "listBusinessDividendDeclarationAllocations", "summary": "List business dividend allocations", "description": "Lists shareholder allocations for one accessible dividend declaration. Archived allocations are hidden by default. This route is read-only and never recalculates, posts or pays dividends.", "security": [ { "ApiKeyAuth": [] } ], "parameters": [ { "$ref": "#/components/parameters/BusinessCompanyId" }, { "name": "dividend_declaration_id", "in": "path", "required": true, "description": "Dividend declaration id.", "schema": { "type": "string", "format": "uuid" } }, { "$ref": "#/components/parameters/RequestId" }, { "name": "include_archived", "in": "query", "required": false, "description": "Set to true to include archived/replaced allocations.", "schema": { "type": "boolean", "default": false } }, { "name": "shareholder_id", "in": "query", "required": false, "description": "Filter allocations by shareholder.", "schema": { "type": "string", "format": "uuid" } }, { "name": "limit", "in": "query", "required": false, "description": "Maximum records to return, capped at 100.", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 50 } }, { "name": "offset", "in": "query", "required": false, "description": "Zero-based pagination offset.", "schema": { "type": "integer", "minimum": 0, "default": 0 } } ], "responses": { "200": { "description": "business dividend allocations returned.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1BusinessDividendAllocationListResponse" } } } }, "400": { "description": "The path or query parameters are invalid.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1ErrorEnvelope" } } } }, "401": { "description": "Missing, invalid, expired or inactive API key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LegacyErrorResponse" } } } }, "403": { "description": "The API key does not grant reports permission.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1ErrorEnvelope" } } } }, "404": { "description": "Business company not found.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1ErrorEnvelope" } } } }, "405": { "description": "Only GET is allowed for this route.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1ErrorEnvelope" } } } }, "500": { "description": "Generic server failure. Internal database details must not be returned.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1ErrorEnvelope" } } } } }, "x-financial-iq-safety": { "writeLevel": "read", "requiresIdempotencyKey": false, "scope": "business.dividend_declarations.read", "requiredPermission": "reports", "auditedEndpoint": "v1/business/companies/{company_id}/dividend-declarations/{dividend_declaration_id}/allocations", "doesNot": [ "declare_dividend", "approve_dividend", "cancel_dividend", "regenerate_allocations", "generate_paperwork", "post_journal", "make_payment", "close_accounting_period", "move_money" ] }, "x-implementation": { "handler": "handleV1BusinessDividendDeclarationAllocations" } } }, "/v1/business/companies/{company_id}/dividend-declarations/{dividend_declaration_id}/allocations/{dividend_allocation_id}": { "get": { "tags": [ "Business" ], "operationId": "getBusinessDividendDeclarationAllocation", "summary": "Get business dividend allocation", "description": "Returns one shareholder allocation for one accessible dividend declaration. This route is read-only and never recalculates, posts or pays dividends.", "security": [ { "ApiKeyAuth": [] } ], "parameters": [ { "$ref": "#/components/parameters/BusinessCompanyId" }, { "name": "dividend_declaration_id", "in": "path", "required": true, "description": "Dividend declaration id.", "schema": { "type": "string", "format": "uuid" } }, { "name": "dividend_allocation_id", "in": "path", "required": true, "description": "Dividend allocation id to fetch.", "schema": { "type": "string", "format": "uuid" } }, { "$ref": "#/components/parameters/RequestId" } ], "responses": { "200": { "description": "business dividend allocation returned.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1BusinessDividendAllocationDetailResponse" } } } }, "400": { "description": "The company_id, dividend_declaration_id or dividend_allocation_id path parameter is invalid.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1ErrorEnvelope" } } } }, "401": { "description": "Missing, invalid, expired or inactive API key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LegacyErrorResponse" } } } }, "403": { "description": "The API key does not grant reports permission.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1ErrorEnvelope" } } } }, "404": { "description": "Business dividend allocation not found.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1ErrorEnvelope" } } } }, "405": { "description": "Only GET is allowed for this route.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1ErrorEnvelope" } } } }, "500": { "description": "Generic server failure. Internal database details must not be returned.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1ErrorEnvelope" } } } } }, "x-financial-iq-safety": { "writeLevel": "read", "requiresIdempotencyKey": false, "scope": "business.dividend_declarations.read", "requiredPermission": "reports", "auditedEndpoint": "v1/business/companies/{company_id}/dividend-declarations/{dividend_declaration_id}/allocations/{dividend_allocation_id}", "doesNot": [ "declare_dividend", "approve_dividend", "cancel_dividend", "regenerate_allocations", "generate_paperwork", "post_journal", "make_payment", "close_accounting_period", "move_money" ] }, "x-implementation": { "handler": "handleV1BusinessDividendAllocationDetail" } } }, "/v1/business/companies/{company_id}/companies-house/change-events": { "get": { "tags": [ "Business" ], "operationId": "listBusinessCompaniesHouseChangeEvents", "summary": "List business Companies House change events", "description": "Lists saved Companies House change-event filing packs for one accessible business company. This route is read-only: it does not create change events, update filing packs, submit to Companies House, update statutory registers, close periods, post to the ledger or move money.", "security": [ { "ApiKeyAuth": [] } ], "parameters": [ { "$ref": "#/components/parameters/BusinessCompanyId" }, { "$ref": "#/components/parameters/RequestId" }, { "name": "change_type", "in": "query", "required": false, "description": "Filter by Companies House change-event type.", "schema": { "type": "string", "enum": [ "registered_office", "director_appointment", "director_resignation", "share_allotment", "psc_add", "psc_change", "psc_cease" ] } }, { "name": "status", "in": "query", "required": false, "description": "Filter by local change-event status.", "schema": { "type": "string", "enum": [ "draft", "reviewed", "manually_filed", "superseded" ] } }, { "name": "form_code", "in": "query", "required": false, "description": "Filter by Companies House form code.", "schema": { "type": "string", "enum": [ "AD01", "AP01", "TM01", "SH01", "PSC01", "PSC04", "PSC07" ] } }, { "name": "effective_from", "in": "query", "required": false, "description": "Inclusive lower bound for effective date.", "schema": { "type": "string", "format": "date" } }, { "name": "effective_to", "in": "query", "required": false, "description": "Inclusive upper bound for effective date.", "schema": { "type": "string", "format": "date" } }, { "name": "filed_from", "in": "query", "required": false, "description": "Inclusive lower bound for manual filing timestamp.", "schema": { "type": "string", "format": "date-time" } }, { "name": "filed_to", "in": "query", "required": false, "description": "Inclusive upper bound for manual filing timestamp.", "schema": { "type": "string", "format": "date-time" } }, { "name": "limit", "in": "query", "required": false, "description": "Maximum records to return, capped at 100.", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 50 } }, { "name": "offset", "in": "query", "required": false, "description": "Zero-based pagination offset.", "schema": { "type": "integer", "minimum": 0, "default": 0 } } ], "responses": { "200": { "description": "Business Companies House change events returned.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1BusinessCompaniesHouseChangeEventListResponse" } } } }, "400": { "description": "The company_id, filter value, date filter or timestamp filter is invalid.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1ErrorEnvelope" } } } }, "401": { "description": "Missing, invalid, expired or inactive API key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LegacyErrorResponse" } } } }, "403": { "description": "The API key does not grant reports permission.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1ErrorEnvelope" } } } }, "404": { "description": "Business company not found.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1ErrorEnvelope" } } } }, "405": { "description": "Only GET is allowed for this route.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1ErrorEnvelope" } } } }, "500": { "description": "Generic server failure. Internal database details must not be returned.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1ErrorEnvelope" } } } } }, "x-financial-iq-safety": { "scope": "business.companies_house_change_events.read", "businessMutation": false, "directFinancialMutation": false, "writeLevel": "read", "requiresIdempotencyKey": false, "auditedEndpoint": "v1/business/companies/{company_id}/companies-house/change-events", "requiredPermission": "reports", "doesNot": [ "create_change_event", "update_filing_pack", "submit_to_companies_house", "update_company_register", "post_to_ledger", "close_accounting_period", "move_money" ] }, "x-implementation": { "edgeFunction": "supabase/functions/financial-data-api/index.ts", "handler": "handleV1BusinessCompaniesHouseChangeEvents", "tests": [ "supabase/functions/financial-data-api/invoice_idempotency.test.ts" ] } } }, "/v1/business/companies/{company_id}/companies-house/change-events/{change_event_id}": { "get": { "tags": [ "Business" ], "operationId": "getBusinessCompaniesHouseChangeEvent", "summary": "Get business Companies House change event", "description": "Returns one saved Companies House change-event filing pack for an accessible business company. This route is read-only and never changes the statutory register or files anything with Companies House.", "security": [ { "ApiKeyAuth": [] } ], "parameters": [ { "$ref": "#/components/parameters/BusinessCompanyId" }, { "name": "change_event_id", "in": "path", "required": true, "description": "Companies House change-event id to fetch.", "schema": { "type": "string", "format": "uuid" } }, { "$ref": "#/components/parameters/RequestId" } ], "responses": { "200": { "description": "Business Companies House change event returned.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1BusinessCompaniesHouseChangeEventDetailResponse" } } } }, "400": { "description": "The company_id or change_event_id path parameter is invalid.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1ErrorEnvelope" } } } }, "401": { "description": "Missing, invalid, expired or inactive API key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LegacyErrorResponse" } } } }, "403": { "description": "The API key does not grant reports permission.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1ErrorEnvelope" } } } }, "404": { "description": "Business Companies House change event not found.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1ErrorEnvelope" } } } }, "405": { "description": "Only GET is allowed for this route.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1ErrorEnvelope" } } } }, "500": { "description": "Generic server failure. Internal database details must not be returned.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1ErrorEnvelope" } } } } }, "x-financial-iq-safety": { "scope": "business.companies_house_change_events.read", "businessMutation": false, "directFinancialMutation": false, "writeLevel": "read", "requiresIdempotencyKey": false, "auditedEndpoint": "v1/business/companies/{company_id}/companies-house/change-events/{change_event_id}", "requiredPermission": "reports", "doesNot": [ "create_change_event", "update_filing_pack", "submit_to_companies_house", "update_company_register", "post_to_ledger", "close_accounting_period", "move_money" ] }, "x-implementation": { "edgeFunction": "supabase/functions/financial-data-api/index.ts", "handler": "handleV1BusinessCompaniesHouseChangeEventDetail", "tests": [ "supabase/functions/financial-data-api/invoice_idempotency.test.ts" ] } } }, "/v1/business/companies/{company_id}/companies-house/psc-register": { "get": { "tags": [ "Business" ], "operationId": "listBusinessCompaniesHousePscRegister", "summary": "List business Companies House PSC register records", "description": "Lists active PSC register records for one accessible business company. This route is read-only: it does not create PSC records, update PSC records, generate filing packs, submit to Companies House, close periods or move money.", "security": [ { "ApiKeyAuth": [] } ], "parameters": [ { "$ref": "#/components/parameters/BusinessCompanyId" }, { "$ref": "#/components/parameters/RequestId" }, { "name": "psc_type", "in": "query", "required": false, "description": "Filter by PSC type.", "schema": { "type": "string", "enum": [ "individual", "corporate", "other" ] } }, { "name": "source", "in": "query", "required": false, "description": "Filter by PSC record source.", "schema": { "type": "string", "enum": [ "manual", "shareholding_review", "companies_house" ] } }, { "name": "personal_code_status", "in": "query", "required": false, "description": "Filter by Companies House personal code status.", "schema": { "type": "string", "enum": [ "not_recorded", "checked", "not_required" ] } }, { "name": "identity_verified", "in": "query", "required": false, "description": "Filter by identity verification status.", "schema": { "type": "boolean" } }, { "name": "include_ceased", "in": "query", "required": false, "description": "Set to true to include ceased PSC records.", "schema": { "type": "boolean", "default": false } }, { "name": "search", "in": "query", "required": false, "description": "Case-insensitive PSC name search. Alias: q.", "schema": { "type": "string", "maxLength": 120 } }, { "name": "q", "in": "query", "required": false, "description": "Alias for search.", "schema": { "type": "string", "maxLength": 120 } }, { "name": "notified_from", "in": "query", "required": false, "description": "Inclusive lower bound for notified date.", "schema": { "type": "string", "format": "date" } }, { "name": "notified_to", "in": "query", "required": false, "description": "Inclusive upper bound for notified date.", "schema": { "type": "string", "format": "date" } }, { "name": "ceased_from", "in": "query", "required": false, "description": "Inclusive lower bound for ceased date.", "schema": { "type": "string", "format": "date" } }, { "name": "ceased_to", "in": "query", "required": false, "description": "Inclusive upper bound for ceased date.", "schema": { "type": "string", "format": "date" } }, { "name": "limit", "in": "query", "required": false, "description": "Maximum records to return, capped at 100.", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 50 } }, { "name": "offset", "in": "query", "required": false, "description": "Zero-based pagination offset.", "schema": { "type": "integer", "minimum": 0, "default": 0 } } ], "responses": { "200": { "description": "Business Companies House PSC register records returned.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1BusinessPscRegisterListResponse" } } } }, "400": { "description": "The company_id, filter value, boolean filter, search string or date filter is invalid.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1ErrorEnvelope" } } } }, "401": { "description": "Missing, invalid, expired or inactive API key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LegacyErrorResponse" } } } }, "403": { "description": "The API key does not grant reports permission.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1ErrorEnvelope" } } } }, "404": { "description": "Business company not found.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1ErrorEnvelope" } } } }, "405": { "description": "Only GET is allowed for this route.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1ErrorEnvelope" } } } }, "500": { "description": "Generic server failure. Internal database details must not be returned.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1ErrorEnvelope" } } } } }, "x-financial-iq-safety": { "scope": "business.companies_house_psc_register.read", "businessMutation": false, "directFinancialMutation": false, "writeLevel": "read", "requiresIdempotencyKey": false, "auditedEndpoint": "v1/business/companies/{company_id}/companies-house/psc-register", "requiredPermission": "reports", "doesNot": [ "create_psc_record", "update_psc_record", "generate_filing_pack", "submit_to_companies_house", "post_to_ledger", "close_accounting_period", "move_money" ] }, "x-implementation": { "edgeFunction": "supabase/functions/financial-data-api/index.ts", "handler": "handleV1BusinessPscRegister", "tests": [ "supabase/functions/financial-data-api/invoice_idempotency.test.ts" ] } } }, "/v1/business/companies/{company_id}/companies-house/psc-register/{psc_record_id}": { "get": { "tags": [ "Business" ], "operationId": "getBusinessCompaniesHousePscRegisterRecord", "summary": "Get business Companies House PSC register record", "description": "Returns one PSC register record for an accessible business company. This route is read-only and never changes the register or files anything with Companies House.", "security": [ { "ApiKeyAuth": [] } ], "parameters": [ { "$ref": "#/components/parameters/BusinessCompanyId" }, { "name": "psc_record_id", "in": "path", "required": true, "description": "PSC register record id to fetch.", "schema": { "type": "string", "format": "uuid" } }, { "$ref": "#/components/parameters/RequestId" } ], "responses": { "200": { "description": "Business Companies House PSC register record returned.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1BusinessPscRegisterDetailResponse" } } } }, "400": { "description": "The company_id or psc_record_id path parameter is invalid.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1ErrorEnvelope" } } } }, "401": { "description": "Missing, invalid, expired or inactive API key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LegacyErrorResponse" } } } }, "403": { "description": "The API key does not grant reports permission.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1ErrorEnvelope" } } } }, "404": { "description": "Business Companies House PSC register record not found.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1ErrorEnvelope" } } } }, "405": { "description": "Only GET is allowed for this route.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1ErrorEnvelope" } } } }, "500": { "description": "Generic server failure. Internal database details must not be returned.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1ErrorEnvelope" } } } } }, "x-financial-iq-safety": { "scope": "business.companies_house_psc_register.read", "businessMutation": false, "directFinancialMutation": false, "writeLevel": "read", "requiresIdempotencyKey": false, "auditedEndpoint": "v1/business/companies/{company_id}/companies-house/psc-register/{psc_record_id}", "requiredPermission": "reports", "doesNot": [ "create_psc_record", "update_psc_record", "generate_filing_pack", "submit_to_companies_house", "post_to_ledger", "close_accounting_period", "move_money" ] }, "x-implementation": { "edgeFunction": "supabase/functions/financial-data-api/index.ts", "handler": "handleV1BusinessPscRegisterDetail", "tests": [ "supabase/functions/financial-data-api/invoice_idempotency.test.ts" ] } } }, "/v1/business/companies/{company_id}/companies-house/filings": { "get": { "tags": [ "Business" ], "operationId": "listBusinessCompaniesHouseFilings", "summary": "List business Companies House filings", "description": "Lists Companies House accounts filing history and status for one accessible business company. This route is read-only: it does not generate statutory accounts, generate iXBRL, create filings, submit to Companies House, poll Companies House, post ledger entries, close periods or move money.", "security": [ { "ApiKeyAuth": [] } ], "parameters": [ { "$ref": "#/components/parameters/BusinessCompanyId" }, { "$ref": "#/components/parameters/RequestId" }, { "name": "status", "in": "query", "required": false, "description": "Filter by local Companies House filing status.", "schema": { "type": "string", "enum": [ "pending", "submitted", "acknowledged", "accepted", "rejected" ] } }, { "name": "environment", "in": "query", "required": false, "description": "Filter by Companies House submission environment.", "schema": { "type": "string", "enum": [ "test", "production" ] } }, { "name": "accounting_period_id", "in": "query", "required": false, "description": "Filter by accounting period id.", "schema": { "type": "string", "format": "uuid" } }, { "name": "submitted_from", "in": "query", "required": false, "description": "Inclusive lower bound for submitted timestamp.", "schema": { "type": "string", "format": "date-time" } }, { "name": "submitted_to", "in": "query", "required": false, "description": "Inclusive upper bound for submitted timestamp.", "schema": { "type": "string", "format": "date-time" } }, { "name": "acknowledged_from", "in": "query", "required": false, "description": "Inclusive lower bound for acknowledged timestamp.", "schema": { "type": "string", "format": "date-time" } }, { "name": "acknowledged_to", "in": "query", "required": false, "description": "Inclusive upper bound for acknowledged timestamp.", "schema": { "type": "string", "format": "date-time" } }, { "name": "limit", "in": "query", "required": false, "description": "Maximum records to return, capped at 100.", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 50 } }, { "name": "offset", "in": "query", "required": false, "description": "Zero-based pagination offset.", "schema": { "type": "integer", "minimum": 0, "default": 0 } } ], "responses": { "200": { "description": "Business Companies House filings returned.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1BusinessCompaniesHouseFilingListResponse" } } } }, "400": { "description": "The company_id, id filter, status, environment or timestamp filter is invalid.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1ErrorEnvelope" } } } }, "401": { "description": "Missing, invalid, expired or inactive API key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LegacyErrorResponse" } } } }, "403": { "description": "The API key does not grant reports permission.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1ErrorEnvelope" } } } }, "404": { "description": "Business company not found.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1ErrorEnvelope" } } } }, "405": { "description": "Only GET is allowed for this route.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1ErrorEnvelope" } } } }, "500": { "description": "Generic server failure. Internal database details must not be returned.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1ErrorEnvelope" } } } } }, "x-financial-iq-safety": { "scope": "business.companies_house_filings.read", "businessMutation": false, "directFinancialMutation": false, "writeLevel": "read", "requiresIdempotencyKey": false, "auditedEndpoint": "v1/business/companies/{company_id}/companies-house/filings", "requiredPermission": "reports", "doesNot": [ "generate_statutory_accounts", "generate_ixbrl", "create_companies_house_filing", "submit_to_companies_house", "poll_companies_house", "post_to_ledger", "file_accounts", "close_accounting_period", "move_money" ] }, "x-implementation": { "edgeFunction": "supabase/functions/financial-data-api/index.ts", "handler": "handleV1BusinessCompaniesHouseFilings", "tests": [ "supabase/functions/financial-data-api/invoice_idempotency.test.ts" ] } } }, "/v1/business/companies/{company_id}/companies-house/filings/{companies_house_filing_id}": { "get": { "tags": [ "Business" ], "operationId": "getBusinessCompaniesHouseFiling", "summary": "Get business Companies House filing", "description": "Returns one Companies House filing status for an accessible business company. This route is read-only and never submits to Companies House or changes the books.", "security": [ { "ApiKeyAuth": [] } ], "parameters": [ { "$ref": "#/components/parameters/BusinessCompanyId" }, { "name": "companies_house_filing_id", "in": "path", "required": true, "description": "Companies House filing id to fetch.", "schema": { "type": "string", "format": "uuid" } }, { "$ref": "#/components/parameters/RequestId" } ], "responses": { "200": { "description": "Business Companies House filing returned.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1BusinessCompaniesHouseFilingDetailResponse" } } } }, "400": { "description": "The company_id or companies_house_filing_id path parameter is invalid.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1ErrorEnvelope" } } } }, "401": { "description": "Missing, invalid, expired or inactive API key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LegacyErrorResponse" } } } }, "403": { "description": "The API key does not grant reports permission.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1ErrorEnvelope" } } } }, "404": { "description": "Business Companies House filing not found.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1ErrorEnvelope" } } } }, "405": { "description": "Only GET is allowed for this route.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1ErrorEnvelope" } } } }, "500": { "description": "Generic server failure. Internal database details must not be returned.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1ErrorEnvelope" } } } } }, "x-financial-iq-safety": { "scope": "business.companies_house_filings.read", "businessMutation": false, "directFinancialMutation": false, "writeLevel": "read", "requiresIdempotencyKey": false, "auditedEndpoint": "v1/business/companies/{company_id}/companies-house/filings/{companies_house_filing_id}", "requiredPermission": "reports", "doesNot": [ "generate_statutory_accounts", "generate_ixbrl", "create_companies_house_filing", "submit_to_companies_house", "poll_companies_house", "post_to_ledger", "file_accounts", "close_accounting_period", "move_money" ] }, "x-implementation": { "edgeFunction": "supabase/functions/financial-data-api/index.ts", "handler": "handleV1BusinessCompaniesHouseFilingDetail", "tests": [ "supabase/functions/financial-data-api/invoice_idempotency.test.ts" ] } } }, "/v1/business/companies/{company_id}/journal-transactions": { "get": { "tags": [ "Business" ], "operationId": "listBusinessJournalTransactions", "summary": "List business journal transactions", "description": "Returns read-only journal transaction batches and their debit/credit lines for an accessible business company. It does not create, amend, void, delete, or post journal entries.", "security": [ { "ApiKeyAuth": [] } ], "parameters": [ { "name": "company_id", "in": "path", "required": true, "description": "Business company id.", "schema": { "type": "string", "format": "uuid" } }, { "$ref": "#/components/parameters/RequestId" }, { "name": "status", "in": "query", "required": false, "description": "Filter by journal status.", "schema": { "type": "string" } }, { "name": "source_type", "in": "query", "required": false, "description": "Filter by journal source type.", "schema": { "type": "string" } }, { "name": "transaction_type", "in": "query", "required": false, "description": "Filter by journal transaction type.", "schema": { "type": "string" } }, { "name": "reference", "in": "query", "required": false, "description": "Filter by exact journal reference.", "schema": { "type": "string" } }, { "name": "from_date", "in": "query", "required": false, "description": "Filter journals on or after this date.", "schema": { "type": "string", "format": "date" } }, { "name": "to_date", "in": "query", "required": false, "description": "Filter journals on or before this date.", "schema": { "type": "string", "format": "date" } }, { "name": "include_superseded", "in": "query", "required": false, "description": "When true, includes old amended journal versions.", "schema": { "type": "boolean" } }, { "$ref": "#/components/parameters/Limit" }, { "$ref": "#/components/parameters/Offset" } ], "responses": { "200": { "description": "Business journal transactions returned.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BusinessJournalTransactionListResponse" } } } }, "400": { "description": "Invalid company id or date filter.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1ErrorEnvelope" } } } }, "401": { "description": "Missing or invalid API key.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1ErrorEnvelope" } } } }, "403": { "description": "API key does not have reports permission.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1ErrorEnvelope" } } } }, "404": { "description": "Company is not accessible to the API key.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1ErrorEnvelope" } } } }, "405": { "description": "Only GET is allowed for this route.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1ErrorEnvelope" } } } } }, "x-financial-iq-safety": { "requiresApiKey": true, "apiKeysAllowed": true, "requiresUserBearerToken": false, "scope": "business.journal_transactions.read", "businessMutation": false, "directFinancialMutation": false, "readOnly": true, "exposesLedgerLines": true, "requiresIdempotencyKey": false, "auditedEndpoint": "v1/business/companies/{company_id}/journal-transactions", "redactions": [ "idempotency_key", "import_batch_id", "created_by", "amended_by" ], "doesNot": [ "create_journal_entries", "amend_journal_entries", "void_journal_entries", "delete_journal_entries", "post_to_ledger" ], "writeLevel": "read" }, "x-implementation": { "edgeFunction": "supabase/functions/financial-data-api/index.ts", "handler": "handleV1BusinessJournalTransactions", "tests": [ "supabase/functions/financial-data-api/invoice_idempotency.test.ts" ] } }, "post": { "tags": [ "Business" ], "operationId": "createBusinessDraftJournalTransaction", "summary": "Create a draft business journal transaction", "description": "Creates a balanced draft manual journal for an accessible business company. This route requires transactions permission and an Idempotency-Key. It validates every account and analysis dimension against the requested company, always creates status=draft with posting_origin=api_draft, and does not post, amend, void, delete, file tax, close periods, set source provenance, or move money.", "security": [ { "ApiKeyAuth": [] } ], "parameters": [ { "name": "company_id", "in": "path", "required": true, "description": "Business company id.", "schema": { "type": "string", "format": "uuid" } }, { "$ref": "#/components/parameters/RequestId" }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BusinessJournalDraftCreateRequest" } } } }, "responses": { "201": { "description": "Draft business journal transaction created.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" }, "X-FIQ-Idempotency-Replayed": { "$ref": "#/components/headers/IdempotencyReplayed" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BusinessJournalTransactionCreateResponse" } } } }, "400": { "description": "Invalid request body, invalid company id, invalid references, unbalanced journal, or missing Idempotency-Key.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1ErrorEnvelope" } } } }, "401": { "description": "Missing, invalid, expired or inactive API key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LegacyErrorResponse" } } } }, "403": { "description": "The API key does not have transactions permission or has no owner user.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1ErrorEnvelope" } } } }, "404": { "description": "Business company not found.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1ErrorEnvelope" } } } }, "405": { "description": "Only GET and POST are allowed for this route.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1ErrorEnvelope" } } } }, "409": { "description": "The Idempotency-Key is currently processing or was used with a different request body.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1ErrorEnvelope" } } } }, "500": { "description": "Generic server failure. Internal database details must not be returned.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1ErrorEnvelope" } } } } }, "x-financial-iq-safety": { "requiresApiKey": true, "apiKeysAllowed": true, "requiresUserBearerToken": false, "scope": "business.journal_transactions.create", "requiredPermission": "transactions", "businessMutation": true, "directFinancialMutation": false, "readOnly": false, "writeLevel": "ledger_draft", "requiresIdempotencyKey": true, "auditedEndpoint": "v1/business/companies/{company_id}/journal-transactions", "forbiddenFields": [ "status", "source_type", "source_id", "posting_origin", "created_by", "posted_at", "approval_status" ], "doesNot": [ "post_to_ledger", "amend_posted_journals", "void_journals", "delete_journals", "set_source_provenance", "file_tax", "close_accounting_periods", "move_money" ] }, "x-implementation": { "edgeFunction": "supabase/functions/financial-data-api/index.ts", "handler": "handleV1BusinessJournalTransactions", "tests": [ "supabase/functions/financial-data-api/invoice_idempotency.test.ts" ] } } }, "/v1/business/companies/{company_id}/journal-transactions/{journal_transaction_id}": { "get": { "tags": [ "Business" ], "operationId": "getBusinessJournalTransaction", "summary": "Get a business journal transaction", "description": "Returns one read-only journal transaction batch and its debit/credit lines for an accessible business company. Inaccessible ids return not found.", "security": [ { "ApiKeyAuth": [] } ], "parameters": [ { "name": "company_id", "in": "path", "required": true, "description": "Business company id.", "schema": { "type": "string", "format": "uuid" } }, { "name": "journal_transaction_id", "in": "path", "required": true, "description": "Journal transaction id.", "schema": { "type": "string", "format": "uuid" } }, { "$ref": "#/components/parameters/RequestId" } ], "responses": { "200": { "description": "Business journal transaction returned.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BusinessJournalTransactionDetailResponse" } } } }, "400": { "description": "Invalid company id or journal transaction id.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1ErrorEnvelope" } } } }, "401": { "description": "Missing or invalid API key.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1ErrorEnvelope" } } } }, "403": { "description": "API key does not have reports permission.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1ErrorEnvelope" } } } }, "404": { "description": "Journal transaction is not accessible to the API key.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1ErrorEnvelope" } } } }, "405": { "description": "Only GET is allowed for this route.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1ErrorEnvelope" } } } } }, "x-financial-iq-safety": { "requiresApiKey": true, "apiKeysAllowed": true, "requiresUserBearerToken": false, "scope": "business.journal_transactions.read", "businessMutation": false, "directFinancialMutation": false, "readOnly": true, "exposesLedgerLines": true, "requiresIdempotencyKey": false, "auditedEndpoint": "v1/business/companies/{company_id}/journal-transactions/{journal_transaction_id}", "redactions": [ "idempotency_key", "import_batch_id", "created_by", "amended_by" ], "doesNot": [ "create_journal_entries", "amend_journal_entries", "void_journal_entries", "delete_journal_entries", "post_to_ledger" ], "writeLevel": "read" }, "x-implementation": { "edgeFunction": "supabase/functions/financial-data-api/index.ts", "handler": "handleV1BusinessJournalTransactionDetail", "tests": [ "supabase/functions/financial-data-api/invoice_idempotency.test.ts" ] } } }, "/v1/business/companies/{company_id}/fixed-asset-classes": { "get": { "tags": [ "Business" ], "operationId": "listBusinessFixedAssetClasses", "summary": "List business fixed asset classes", "description": "Lists fixed asset class setup records for one accessible business company. This route is read-only: it does not create asset classes, create ledger accounts, create assets, post depreciation, post journals, close accounting periods or move money.", "security": [ { "ApiKeyAuth": [] } ], "parameters": [ { "name": "company_id", "in": "path", "required": true, "description": "Business company id.", "schema": { "type": "string", "format": "uuid" } }, { "$ref": "#/components/parameters/RequestId" }, { "name": "asset_type", "in": "query", "required": false, "description": "Optional fixed asset class type filter.", "schema": { "type": "string", "enum": [ "tangible", "intangible", "investment" ] } }, { "name": "include_inactive", "in": "query", "required": false, "description": "When true, include archived/inactive classes.", "schema": { "type": "boolean", "default": false } }, { "name": "limit", "in": "query", "required": false, "description": "Maximum records to return, capped at 100.", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 50 } }, { "name": "offset", "in": "query", "required": false, "description": "Zero-based pagination offset.", "schema": { "type": "integer", "minimum": 0, "default": 0 } } ], "responses": { "200": { "description": "Business fixed asset classes returned.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BusinessFixedAssetClassListResponse" } } } }, "400": { "description": "Invalid query parameter.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1ErrorEnvelope" } } } }, "401": { "description": "Missing, invalid, expired or inactive API key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LegacyErrorResponse" } } } }, "403": { "description": "The API key does not have reports, transactions or chart_of_accounts permission.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1ErrorEnvelope" } } } }, "404": { "description": "Business company not found.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1ErrorEnvelope" } } } }, "500": { "description": "Unexpected server error.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1ErrorEnvelope" } } } } }, "x-financial-iq-safety": { "requiresApiKey": true, "apiKeysAllowed": true, "requiresUserBearerToken": false, "scope": "business.fixed_asset_classes.read", "allowedApiKeyPermissions": [ "reports", "transactions", "chart_of_accounts" ], "readOnly": true, "businessMutation": false, "directFinancialMutation": false, "writeLevel": "read", "requiresIdempotencyKey": false, "auditedEndpoint": "v1/business/companies/{company_id}/fixed-asset-classes", "doesNot": [ "create_fixed_asset_class", "create_chart_accounts", "create_fixed_asset", "post_depreciation", "post_journal", "close_accounting_period", "move_money" ] }, "x-implementation": { "edgeFunction": "supabase/functions/financial-data-api/index.ts", "handler": "handleV1BusinessFixedAssetClasses", "tables": [ "fixed_asset_classes" ], "tests": [ "supabase/functions/financial-data-api/invoice_idempotency.test.ts" ] } }, "post": { "tags": [ "Business" ], "operationId": "createBusinessFixedAssetClass", "summary": "Create business fixed asset class", "description": "Creates one fixed asset class for an accessible business company and generates the linked cost, accumulated-depreciation and depreciation/fair-value chart accounts. This route requires chart_of_accounts permission and an Idempotency-Key. It is a setup/configuration write: it does not create fixed asset register records, post depreciation, post journals, close accounting periods, file tax submissions or move money.", "security": [ { "ApiKeyAuth": [] } ], "parameters": [ { "name": "company_id", "in": "path", "required": true, "description": "Business company id.", "schema": { "type": "string", "format": "uuid" } }, { "$ref": "#/components/parameters/RequestId" }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BusinessFixedAssetClassCreateRequest" } } } }, "responses": { "201": { "description": "Business fixed asset class created.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" }, "X-FIQ-Idempotency-Replayed": { "$ref": "#/components/headers/IdempotencyReplayed" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BusinessFixedAssetClassCreateResponse" } } } }, "400": { "description": "Invalid request body, invalid company id, invalid setup values, or missing Idempotency-Key.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1ErrorEnvelope" } } } }, "401": { "description": "Missing, invalid, expired or inactive API key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LegacyErrorResponse" } } } }, "403": { "description": "The API key does not have chart_of_accounts permission or has no owner user.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1ErrorEnvelope" } } } }, "404": { "description": "Business company not found.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1ErrorEnvelope" } } } }, "409": { "description": "Fixed asset class already exists or no suitable setup codes are available.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1ErrorEnvelope" } } } }, "500": { "description": "Unexpected server error.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1ErrorEnvelope" } } } } }, "x-financial-iq-safety": { "requiresApiKey": true, "apiKeysAllowed": true, "requiresUserBearerToken": false, "scope": "business.fixed_asset_classes.create", "requiredApiKeyPermission": "chart_of_accounts", "businessMutation": true, "directFinancialMutation": false, "readOnly": false, "writeLevel": "configuration", "requiresIdempotencyKey": true, "auditedEndpoint": "v1/business/companies/{company_id}/fixed-asset-classes", "doesCreateChartAccounts": true, "doesNot": [ "create_fixed_asset", "post_depreciation", "post_journal", "close_accounting_period", "move_money", "file_tax_submission" ] }, "x-implementation": { "edgeFunction": "supabase/functions/financial-data-api/index.ts", "handler": "createV1BusinessFixedAssetClass", "rpc": "create_fixed_asset_class_with_codes_atomic", "tables": [ "fixed_asset_classes", "chart_of_accounts", "company_coa_categories", "audit_logs" ], "tests": [ "supabase/functions/financial-data-api/invoice_idempotency.test.ts" ] } } }, "/v1/business/companies/{company_id}/fixed-asset-classes/{fixed_asset_class_id}": { "get": { "tags": [ "Business" ], "operationId": "getBusinessFixedAssetClass", "summary": "Get business fixed asset class", "description": "Returns one fixed asset class setup record for an accessible business company. This route is read-only.", "security": [ { "ApiKeyAuth": [] } ], "parameters": [ { "name": "company_id", "in": "path", "required": true, "description": "Business company id.", "schema": { "type": "string", "format": "uuid" } }, { "name": "fixed_asset_class_id", "in": "path", "required": true, "description": "Fixed asset class id.", "schema": { "type": "string", "format": "uuid" } }, { "$ref": "#/components/parameters/RequestId" } ], "responses": { "200": { "description": "Business fixed asset class returned.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BusinessFixedAssetClassDetailResponse" } } } }, "400": { "description": "Invalid path parameter.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1ErrorEnvelope" } } } }, "401": { "description": "Missing, invalid, expired or inactive API key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LegacyErrorResponse" } } } }, "403": { "description": "The API key does not have reports, transactions or chart_of_accounts permission.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1ErrorEnvelope" } } } }, "404": { "description": "Business fixed asset class not found.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1ErrorEnvelope" } } } }, "500": { "description": "Unexpected server error.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1ErrorEnvelope" } } } } }, "x-financial-iq-safety": { "requiresApiKey": true, "apiKeysAllowed": true, "requiresUserBearerToken": false, "scope": "business.fixed_asset_classes.read", "allowedApiKeyPermissions": [ "reports", "transactions", "chart_of_accounts" ], "readOnly": true, "businessMutation": false, "directFinancialMutation": false, "writeLevel": "read", "requiresIdempotencyKey": false, "auditedEndpoint": "v1/business/companies/{company_id}/fixed-asset-classes/{fixed_asset_class_id}", "doesNot": [ "create_fixed_asset_class", "archive_fixed_asset_class", "create_fixed_asset", "post_depreciation", "post_journal", "move_money" ] }, "x-implementation": { "edgeFunction": "supabase/functions/financial-data-api/index.ts", "handler": "handleV1BusinessFixedAssetClassDetail", "tables": [ "fixed_asset_classes" ], "tests": [ "supabase/functions/financial-data-api/invoice_idempotency.test.ts" ] } } }, "/v1/business/companies/{company_id}/fixed-asset-classes/{fixed_asset_class_id}/archive": { "post": { "tags": [ "Business" ], "operationId": "archiveBusinessFixedAssetClass", "summary": "Archive business fixed asset class", "description": "Archives one fixed asset class and its generated ledger setup records for an accessible business company. This route requires chart_of_accounts permission, a reason and an Idempotency-Key. It refuses classes still used by active fixed assets. It does not hard-delete records, delete fixed assets, post depreciation, post journals, close accounting periods, file tax submissions or move money.", "security": [ { "ApiKeyAuth": [] } ], "parameters": [ { "name": "company_id", "in": "path", "required": true, "description": "Business company id.", "schema": { "type": "string", "format": "uuid" } }, { "name": "fixed_asset_class_id", "in": "path", "required": true, "description": "Fixed asset class id.", "schema": { "type": "string", "format": "uuid" } }, { "$ref": "#/components/parameters/RequestId" }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BusinessFixedAssetClassArchiveRequest" } } } }, "responses": { "200": { "description": "Business fixed asset class archived.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" }, "X-FIQ-Idempotency-Replayed": { "$ref": "#/components/headers/IdempotencyReplayed" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BusinessFixedAssetClassArchiveResponse" } } } }, "400": { "description": "Invalid request body, invalid path parameter, or missing Idempotency-Key.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1ErrorEnvelope" } } } }, "401": { "description": "Missing, invalid, expired or inactive API key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LegacyErrorResponse" } } } }, "403": { "description": "The API key does not have chart_of_accounts permission or has no owner user.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1ErrorEnvelope" } } } }, "404": { "description": "Business fixed asset class not found.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1ErrorEnvelope" } } } }, "409": { "description": "Fixed asset class archive was blocked because active fixed assets still use the class, the Idempotency-Key is in progress, or an accounting safeguard blocked the change.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1ErrorEnvelope" } } } }, "500": { "description": "Unexpected server error.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1ErrorEnvelope" } } } } }, "x-financial-iq-safety": { "requiresApiKey": true, "apiKeysAllowed": true, "requiresUserBearerToken": false, "scope": "business.fixed_asset_classes.archive", "requiredApiKeyPermission": "chart_of_accounts", "businessMutation": true, "directFinancialMutation": false, "readOnly": false, "writeLevel": "archive", "requiresIdempotencyKey": true, "auditedEndpoint": "v1/business/companies/{company_id}/fixed-asset-classes/{fixed_asset_class_id}/archive", "doesNotHardDelete": true, "doesNot": [ "delete_fixed_asset_class", "delete_chart_accounts", "delete_fixed_asset", "post_depreciation", "post_journal", "close_accounting_period", "move_money", "file_tax_submission" ] }, "x-implementation": { "edgeFunction": "supabase/functions/financial-data-api/index.ts", "handler": "archiveV1BusinessFixedAssetClass", "rpc": "archive_fixed_asset_class_atomic", "tables": [ "fixed_asset_classes", "chart_of_accounts", "company_coa_categories", "audit_logs" ], "tests": [ "supabase/functions/financial-data-api/invoice_idempotency.test.ts" ] } } }, "/v1/business/companies/{company_id}/fixed-assets": { "get": { "tags": [ "Business" ], "operationId": "listBusinessFixedAssets", "summary": "List business fixed assets", "description": "Lists fixed asset register records for one accessible business company. This route is read-only: it does not create assets, post depreciation, dispose assets, post journals, close accounting periods or move money.", "security": [ { "ApiKeyAuth": [] } ], "parameters": [ { "name": "company_id", "in": "path", "required": true, "description": "Business company id.", "schema": { "type": "string", "format": "uuid" } }, { "$ref": "#/components/parameters/RequestId" }, { "name": "status", "in": "query", "required": false, "description": "Optional fixed asset status filter.", "schema": { "type": "string", "enum": [ "active", "disposed", "fully_depreciated" ] } }, { "name": "asset_class_id", "in": "query", "required": false, "description": "Optional fixed asset class id filter.", "schema": { "type": "string", "format": "uuid" } }, { "name": "supplier_id", "in": "query", "required": false, "description": "Optional supplier id filter.", "schema": { "type": "string", "format": "uuid" } }, { "name": "cost_center_id", "in": "query", "required": false, "description": "Optional cost-centre option id filter.", "schema": { "type": "string", "format": "uuid" } }, { "name": "fund_id", "in": "query", "required": false, "description": "Optional fund id filter.", "schema": { "type": "string", "format": "uuid" } }, { "name": "project_id", "in": "query", "required": false, "description": "Optional project id filter.", "schema": { "type": "string", "format": "uuid" } }, { "name": "is_disposed", "in": "query", "required": false, "description": "Optional disposal-state filter.", "schema": { "type": "boolean" } }, { "name": "acquired_from", "in": "query", "required": false, "description": "Inclusive acquisition-date lower bound.", "schema": { "type": "string", "format": "date" } }, { "name": "acquired_to", "in": "query", "required": false, "description": "Inclusive acquisition-date upper bound.", "schema": { "type": "string", "format": "date" } }, { "name": "limit", "in": "query", "required": false, "description": "Maximum records to return, capped at 100.", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 50 } }, { "name": "offset", "in": "query", "required": false, "description": "Zero-based pagination offset.", "schema": { "type": "integer", "minimum": 0, "default": 0 } } ], "responses": { "200": { "description": "Business fixed assets returned.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BusinessFixedAssetListResponse" } } } }, "400": { "description": "The path or query parameters are invalid.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1ErrorEnvelope" } } } }, "401": { "description": "Missing, invalid, expired or inactive API key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LegacyErrorResponse" } } } }, "403": { "description": "The API key does not have reports permission, or the master key is not allowed to access the company.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1ErrorEnvelope" } } } }, "404": { "description": "Business company not found.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1ErrorEnvelope" } } } }, "405": { "description": "Only GET is allowed for this route.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1ErrorEnvelope" } } } }, "500": { "description": "Generic server failure. Internal database details must not be returned.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1ErrorEnvelope" } } } } }, "x-financial-iq-safety": { "requiresApiKey": true, "apiKeysAllowed": true, "requiresUserBearerToken": false, "scope": "business.fixed_assets.read", "requiredApiKeyPermission": "reports", "businessMutation": false, "directFinancialMutation": false, "readOnly": true, "writeLevel": "read", "requiresIdempotencyKey": false, "auditedEndpoint": "v1/business/companies/{company_id}/fixed-assets", "doesNot": [ "create_fixed_asset", "correct_fixed_asset", "dispose_fixed_asset", "reverse_disposal", "post_depreciation", "post_journal", "close_accounting_period", "move_money" ] }, "x-implementation": { "edgeFunction": "supabase/functions/financial-data-api/index.ts", "handler": "handleV1BusinessFixedAssets", "tables": [ "fixed_assets", "fixed_asset_classes", "depreciation_schedules" ] } }, "post": { "tags": [ "Business" ], "operationId": "createBusinessFixedAsset", "summary": "Create business fixed asset", "description": "Creates one fixed asset register record for an accessible business company. This route requires transactions permission and an Idempotency-Key. It validates asset class and optional supplier, cost-centre, fund and project references against the requested company. It does not dispose assets, post depreciation, post journals, close accounting periods or move money.", "security": [ { "ApiKeyAuth": [] } ], "parameters": [ { "name": "company_id", "in": "path", "required": true, "description": "Business company id.", "schema": { "type": "string", "format": "uuid" } }, { "$ref": "#/components/parameters/RequestId" }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BusinessFixedAssetCreateRequest" } } } }, "responses": { "201": { "description": "Business fixed asset created.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" }, "X-FIQ-Idempotency-Replayed": { "$ref": "#/components/headers/IdempotencyReplayed" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BusinessFixedAssetCreateResponse" } } } }, "400": { "description": "Invalid request body, invalid company id, invalid references, invalid fixed asset values, or missing Idempotency-Key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1ErrorEnvelope" } } }, "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" } } }, "401": { "description": "Missing, invalid, expired or inactive API key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LegacyErrorResponse" } } } }, "403": { "description": "The API key does not have transactions permission or has no owner user.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1ErrorEnvelope" } } }, "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" } } }, "404": { "description": "Business company not found.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1ErrorEnvelope" } } } }, "405": { "description": "Only GET and POST are allowed for this route.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1ErrorEnvelope" } } }, "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" } } }, "409": { "description": "The Idempotency-Key is currently processing, was used with a different request body, or an accounting safeguard blocked the change.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1ErrorEnvelope" } } }, "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" } } }, "500": { "description": "Generic server failure. Internal database details must not be returned.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1ErrorEnvelope" } } } } }, "x-financial-iq-safety": { "requiresApiKey": true, "apiKeysAllowed": true, "requiresUserBearerToken": false, "scope": "business.fixed_assets.create", "requiredApiKeyPermission": "transactions", "businessMutation": true, "directFinancialMutation": true, "readOnly": false, "writeLevel": "create", "requiresIdempotencyKey": true, "auditedEndpoint": "v1/business/companies/{company_id}/fixed-assets", "doesNot": [ "dispose_fixed_asset", "reverse_disposal", "post_depreciation", "post_journal", "close_accounting_period", "move_money" ] }, "x-implementation": { "edgeFunction": "supabase/functions/financial-data-api/index.ts", "handler": "handleV1BusinessFixedAssets", "rpc": "create_fixed_asset_atomic", "tables": [ "fixed_assets", "fixed_asset_classes", "depreciation_schedules", "audit_logs" ], "tests": [ "supabase/functions/financial-data-api/invoice_idempotency.test.ts" ] } } }, "/v1/business/companies/{company_id}/fixed-assets/{fixed_asset_id}": { "get": { "tags": [ "Business" ], "operationId": "getBusinessFixedAsset", "summary": "Get one business fixed asset", "description": "Returns one fixed asset register record and its latest saved depreciation schedule for an accessible business company. Inaccessible assets are returned as not found. This route is read-only and does not post depreciation or update the asset register.", "security": [ { "ApiKeyAuth": [] } ], "parameters": [ { "name": "company_id", "in": "path", "required": true, "description": "Business company id.", "schema": { "type": "string", "format": "uuid" } }, { "name": "fixed_asset_id", "in": "path", "required": true, "description": "Fixed asset id to fetch.", "schema": { "type": "string", "format": "uuid" } }, { "$ref": "#/components/parameters/RequestId" } ], "responses": { "200": { "description": "Business fixed asset returned.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BusinessFixedAssetDetailResponse" } } } }, "400": { "description": "The company_id or fixed_asset_id path parameter is invalid.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1ErrorEnvelope" } } } }, "401": { "description": "Missing, invalid, expired or inactive API key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LegacyErrorResponse" } } } }, "403": { "description": "The API key does not have reports permission, or the master key is not allowed to access the company.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1ErrorEnvelope" } } } }, "404": { "description": "Business fixed asset not found.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1ErrorEnvelope" } } } }, "405": { "description": "Only GET is allowed for this route.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1ErrorEnvelope" } } } }, "500": { "description": "Generic server failure. Internal database details must not be returned.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1ErrorEnvelope" } } } } }, "x-financial-iq-safety": { "requiresApiKey": true, "apiKeysAllowed": true, "requiresUserBearerToken": false, "scope": "business.fixed_assets.read", "requiredApiKeyPermission": "reports", "businessMutation": false, "directFinancialMutation": false, "readOnly": true, "writeLevel": "read", "requiresIdempotencyKey": false, "auditedEndpoint": "v1/business/companies/{company_id}/fixed-assets/{fixed_asset_id}", "doesNot": [ "create_fixed_asset", "correct_fixed_asset", "dispose_fixed_asset", "reverse_disposal", "post_depreciation", "post_journal", "close_accounting_period", "move_money" ] }, "x-implementation": { "edgeFunction": "supabase/functions/financial-data-api/index.ts", "handler": "handleV1BusinessFixedAssetDetail", "tables": [ "fixed_assets", "fixed_asset_classes", "depreciation_schedules" ] } }, "patch": { "tags": [ "Business" ], "operationId": "correctBusinessFixedAsset", "summary": "Correct business fixed asset", "description": "Corrects safe fixed asset register fields for an accessible business company. This route requires transactions permission, a correction reason and an Idempotency-Key. It uses the fixed-asset correction workflow and does not dispose assets, reverse disposals, post depreciation, post journals, close accounting periods or move money.", "security": [ { "ApiKeyAuth": [] } ], "parameters": [ { "name": "company_id", "in": "path", "required": true, "description": "Business company id.", "schema": { "type": "string", "format": "uuid" } }, { "name": "fixed_asset_id", "in": "path", "required": true, "description": "Fixed asset id to correct.", "schema": { "type": "string", "format": "uuid" } }, { "$ref": "#/components/parameters/RequestId" }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BusinessFixedAssetCorrectionRequest" } } } }, "responses": { "200": { "description": "Business fixed asset corrected.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" }, "X-FIQ-Idempotency-Replayed": { "$ref": "#/components/headers/IdempotencyReplayed" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BusinessFixedAssetCorrectionResponse" } } } }, "400": { "description": "Invalid request body, invalid path parameter, invalid references, invalid fixed asset values, or missing Idempotency-Key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1ErrorEnvelope" } } }, "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" } } }, "401": { "description": "Missing, invalid, expired or inactive API key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LegacyErrorResponse" } } } }, "403": { "description": "The API key does not have transactions permission or has no owner user.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1ErrorEnvelope" } } }, "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" } } }, "404": { "description": "Business fixed asset not found.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1ErrorEnvelope" } } } }, "405": { "description": "Only GET and PATCH are allowed for this route.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1ErrorEnvelope" } } }, "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" } } }, "409": { "description": "The Idempotency-Key is currently processing, was used with a different request body, or an accounting safeguard blocked the correction.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1ErrorEnvelope" } } }, "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" } } }, "500": { "description": "Generic server failure. Internal database details must not be returned.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1ErrorEnvelope" } } } } }, "x-financial-iq-safety": { "requiresApiKey": true, "apiKeysAllowed": true, "requiresUserBearerToken": false, "scope": "business.fixed_assets.correct", "requiredApiKeyPermission": "transactions", "businessMutation": true, "directFinancialMutation": true, "readOnly": false, "writeLevel": "update", "requiresIdempotencyKey": true, "auditedEndpoint": "v1/business/companies/{company_id}/fixed-assets/{fixed_asset_id}", "doesNot": [ "create_fixed_asset", "dispose_fixed_asset", "reverse_disposal", "post_depreciation", "post_journal", "close_accounting_period", "move_money" ] }, "x-implementation": { "edgeFunction": "supabase/functions/financial-data-api/index.ts", "handler": "handleV1BusinessFixedAssetDetail", "rpc": "correct_fixed_asset_atomic", "tables": [ "fixed_assets", "fixed_asset_classes", "depreciation_schedules", "audit_logs" ], "tests": [ "supabase/functions/financial-data-api/invoice_idempotency.test.ts" ] } } }, "/v1/business/companies/{company_id}/fixed-assets/{fixed_asset_id}/dispose": { "post": { "tags": [ "Business" ], "operationId": "disposeBusinessFixedAsset", "summary": "Dispose business fixed asset", "description": "Disposes one fixed asset for an accessible business company and posts the disposal journal. This route requires transactions permission, a disposal reason and an Idempotency-Key. It uses the fixed-asset disposal workflow, respects accounting-period locks, and does not move money, delete assets, post depreciation or file tax submissions.", "security": [ { "ApiKeyAuth": [] } ], "parameters": [ { "name": "company_id", "in": "path", "required": true, "description": "Business company id.", "schema": { "type": "string", "format": "uuid" } }, { "name": "fixed_asset_id", "in": "path", "required": true, "description": "Fixed asset id to dispose.", "schema": { "type": "string", "format": "uuid" } }, { "$ref": "#/components/parameters/RequestId" }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BusinessFixedAssetDisposalRequest" } } } }, "responses": { "200": { "description": "Business fixed asset disposed.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" }, "X-FIQ-Idempotency-Replayed": { "$ref": "#/components/headers/IdempotencyReplayed" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BusinessFixedAssetDisposalResponse" } } } }, "400": { "description": "Invalid request body, invalid path parameter, invalid company reference, invalid fixed asset lifecycle values, or missing Idempotency-Key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1ErrorEnvelope" } } }, "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" } } }, "401": { "description": "Missing, invalid, expired or inactive API key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LegacyErrorResponse" } } } }, "403": { "description": "The API key does not have transactions permission or has no owner user.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1ErrorEnvelope" } } }, "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" } } }, "404": { "description": "Business fixed asset not found.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1ErrorEnvelope" } } } }, "405": { "description": "Only POST is allowed for this route.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1ErrorEnvelope" } } }, "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" } } }, "409": { "description": "The Idempotency-Key is currently processing, was used with a different request body, or an accounting safeguard blocked the disposal.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1ErrorEnvelope" } } }, "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" } } }, "500": { "description": "Generic server failure. Internal database details must not be returned.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1ErrorEnvelope" } } } } }, "x-financial-iq-safety": { "requiresApiKey": true, "apiKeysAllowed": true, "requiresUserBearerToken": false, "scope": "business.fixed_assets.dispose", "requiredApiKeyPermission": "transactions", "businessMutation": true, "directFinancialMutation": true, "readOnly": false, "writeLevel": "post", "requiresIdempotencyKey": true, "auditedEndpoint": "v1/business/companies/{company_id}/fixed-assets/{fixed_asset_id}/dispose", "doesPostJournal": true, "doesNot": [ "create_fixed_asset", "correct_fixed_asset", "reverse_disposal", "post_depreciation", "delete_fixed_asset", "close_accounting_period", "move_money", "file_tax_submission" ] }, "x-implementation": { "edgeFunction": "supabase/functions/financial-data-api/index.ts", "handler": "disposeV1BusinessFixedAsset", "rpc": "dispose_fixed_asset_atomic", "tables": [ "fixed_assets", "fixed_asset_classes", "depreciation_schedules", "chart_of_accounts", "journal_transactions", "journal_entries", "audit_logs" ], "tests": [ "supabase/functions/financial-data-api/invoice_idempotency.test.ts" ] } } }, "/v1/business/companies/{company_id}/fixed-assets/{fixed_asset_id}/reverse-disposal": { "post": { "tags": [ "Business" ], "operationId": "reverseBusinessFixedAssetDisposal", "summary": "Reverse business fixed asset disposal", "description": "Reverses one fixed asset disposal for an accessible business company and posts the reversal journal. This route requires transactions permission, a reversal reason and an Idempotency-Key. It uses the fixed-asset disposal reversal workflow, respects accounting-period locks, and does not move money, delete assets, post depreciation or file tax submissions.", "security": [ { "ApiKeyAuth": [] } ], "parameters": [ { "name": "company_id", "in": "path", "required": true, "description": "Business company id.", "schema": { "type": "string", "format": "uuid" } }, { "name": "fixed_asset_id", "in": "path", "required": true, "description": "Fixed asset id whose disposal should be reversed.", "schema": { "type": "string", "format": "uuid" } }, { "$ref": "#/components/parameters/RequestId" }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BusinessFixedAssetDisposalReversalRequest" } } } }, "responses": { "200": { "description": "Business fixed asset disposal reversed.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" }, "X-FIQ-Idempotency-Replayed": { "$ref": "#/components/headers/IdempotencyReplayed" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BusinessFixedAssetDisposalReversalResponse" } } } }, "400": { "description": "Invalid request body, invalid path parameter, invalid company reference, invalid fixed asset lifecycle values, or missing Idempotency-Key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1ErrorEnvelope" } } }, "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" } } }, "401": { "description": "Missing, invalid, expired or inactive API key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LegacyErrorResponse" } } } }, "403": { "description": "The API key does not have transactions permission or has no owner user.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1ErrorEnvelope" } } }, "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" } } }, "404": { "description": "Business fixed asset not found.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1ErrorEnvelope" } } } }, "405": { "description": "Only POST is allowed for this route.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1ErrorEnvelope" } } }, "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" } } }, "409": { "description": "The Idempotency-Key is currently processing, was used with a different request body, or an accounting safeguard blocked the reversal.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1ErrorEnvelope" } } }, "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" } } }, "500": { "description": "Generic server failure. Internal database details must not be returned.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1ErrorEnvelope" } } } } }, "x-financial-iq-safety": { "requiresApiKey": true, "apiKeysAllowed": true, "requiresUserBearerToken": false, "scope": "business.fixed_assets.reverse_disposal", "requiredApiKeyPermission": "transactions", "businessMutation": true, "directFinancialMutation": true, "readOnly": false, "writeLevel": "post", "requiresIdempotencyKey": true, "auditedEndpoint": "v1/business/companies/{company_id}/fixed-assets/{fixed_asset_id}/reverse-disposal", "doesPostJournal": true, "doesNot": [ "create_fixed_asset", "correct_fixed_asset", "dispose_fixed_asset", "post_depreciation", "delete_fixed_asset", "close_accounting_period", "move_money", "file_tax_submission" ] }, "x-implementation": { "edgeFunction": "supabase/functions/financial-data-api/index.ts", "handler": "reverseV1BusinessFixedAssetDisposal", "rpc": "reverse_fixed_asset_disposal_atomic", "tables": [ "fixed_assets", "depreciation_schedules", "journal_transactions", "journal_entries", "audit_logs" ], "tests": [ "supabase/functions/financial-data-api/invoice_idempotency.test.ts" ] } } }, "/v1/business/companies/{company_id}/payment-links": { "get": { "tags": [ "Business" ], "operationId": "listBusinessPaymentLinks", "summary": "List business payment links", "description": "Lists invoice payment links for one accessible business company. This route is read-only: it does not create checkout sessions, charge customers, update invoices, post journals, reconcile payouts or move money.", "security": [ { "ApiKeyAuth": [] } ], "parameters": [ { "name": "company_id", "in": "path", "required": true, "description": "Business company id.", "schema": { "type": "string", "format": "uuid" } }, { "$ref": "#/components/parameters/RequestId" }, { "name": "invoice_id", "in": "query", "required": false, "description": "Optional invoice id filter.", "schema": { "type": "string", "format": "uuid" } }, { "name": "is_active", "in": "query", "required": false, "description": "Optional active-state filter.", "schema": { "type": "boolean" } }, { "name": "limit", "in": "query", "required": false, "description": "Maximum records to return, capped at 100.", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 50 } }, { "name": "offset", "in": "query", "required": false, "description": "Zero-based pagination offset.", "schema": { "type": "integer", "minimum": 0, "default": 0 } } ], "responses": { "200": { "description": "Business payment links returned.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BusinessPaymentLinkListResponse" } } } }, "400": { "description": "The company_id path parameter or query filters are invalid.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1ErrorEnvelope" } } } }, "401": { "description": "Missing, invalid, expired or inactive API key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LegacyErrorResponse" } } } }, "403": { "description": "The API key does not have invoices permission, or the master key is not allowed to access the company.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1ErrorEnvelope" } } } }, "404": { "description": "Business company not found.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1ErrorEnvelope" } } } }, "405": { "description": "Only GET and POST are allowed for this route.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1ErrorEnvelope" } } } }, "500": { "description": "Generic server failure. Internal database details must not be returned.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1ErrorEnvelope" } } } } }, "x-financial-iq-safety": { "requiresApiKey": true, "apiKeysAllowed": true, "requiresUserBearerToken": false, "scope": "business.payment_links.read", "requiredApiKeyPermission": "invoices", "businessMutation": false, "directFinancialMutation": false, "readOnly": true, "writeLevel": "read", "requiresIdempotencyKey": false, "doesNot": [ "create_payment_link", "create_checkout_session", "charge_customer", "activate_payment_link", "deactivate_payment_link", "update_invoice_payment_state", "post_journal", "reconcile_payout", "move_money" ], "auditedEndpoint": "v1/business/companies/{company_id}/payment-links" }, "x-implementation": { "edgeFunction": "supabase/functions/financial-data-api/index.ts", "tables": [ "payment_links", "invoices" ], "handler": "handleV1BusinessPaymentLinks" } }, "post": { "tags": [ "Business" ], "operationId": "createBusinessPaymentLink", "summary": "Create or reuse a business invoice payment link", "description": "Creates or reuses a safe public /pay/... link for one accessible business invoice. The API validates the invoice, reuses an active unexpired link where possible, creates a new payment link when needed, and marks the invoice as publicly payable by that link. This route requires invoices permission and an Idempotency-Key. It does not create a checkout session, charge a customer, accept card details, record a payment, update invoice payment state, post journals, reconcile payouts or move money.", "security": [ { "ApiKeyAuth": [] } ], "parameters": [ { "name": "company_id", "in": "path", "required": true, "description": "Business company id.", "schema": { "type": "string", "format": "uuid" } }, { "$ref": "#/components/parameters/RequestId" }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BusinessPaymentLinkCreateRequest" } } } }, "responses": { "200": { "description": "An active unexpired payment link already existed and was reused.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" }, "X-FIQ-Idempotency-Replayed": { "$ref": "#/components/headers/IdempotencyReplayed" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BusinessPaymentLinkCreateResponse" } } } }, "201": { "description": "Business payment link created.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" }, "X-FIQ-Idempotency-Replayed": { "$ref": "#/components/headers/IdempotencyReplayed" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BusinessPaymentLinkCreateResponse" } } } }, "400": { "description": "Invalid request body, invalid company id, invalid invoice id, invalid expiry_days, invalid require_email_verification, unsupported fields, or missing Idempotency-Key.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1ErrorEnvelope" } } } }, "401": { "description": "Missing, invalid, expired or inactive API key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LegacyErrorResponse" } } } }, "403": { "description": "The API key does not have invoices permission, has no owner, or the master key is not allowed to access the company.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1ErrorEnvelope" } } } }, "404": { "description": "Business company or invoice not found.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1ErrorEnvelope" } } } }, "405": { "description": "Only GET and POST are allowed for this route.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1ErrorEnvelope" } } } }, "422": { "description": "The invoice cannot receive a payment link because it is cancelled, voided, or already fully paid.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1ErrorEnvelope" } } } }, "500": { "description": "Generic server failure. Internal database details must not be returned.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1ErrorEnvelope" } } } } }, "x-financial-iq-safety": { "requiresApiKey": true, "apiKeysAllowed": true, "requiresUserBearerToken": false, "scope": "business.payment_links.create", "requiredApiKeyPermission": "invoices", "businessMutation": true, "directFinancialMutation": false, "readOnly": false, "writeLevel": "payment_link", "requiresIdempotencyKey": true, "createsPublicPaymentPath": true, "reusesActiveUnexpiredLink": true, "doesNot": [ "create_checkout_session", "charge_customer", "accept_card_details", "record_customer_payment", "update_invoice_payment_state", "post_journal", "reconcile_payout", "move_money" ], "redactions": [ "provider_account_id", "checkout_session_id", "card_details", "webhook_payloads", "payment_transaction_internals" ], "auditedEndpoint": "v1/business/companies/{company_id}/payment-links" }, "x-implementation": { "edgeFunction": "supabase/functions/financial-data-api/index.ts", "tables": [ "payment_links", "invoices", "invoice_payment_settings", "api_idempotency_records", "api_usage_logs", "audit_logs" ], "handler": "handleV1BusinessPaymentLinks", "tests": [ "supabase/functions/financial-data-api/invoice_idempotency.test.ts" ] } } }, "/v1/business/companies/{company_id}/payment-links/{payment_link_id}": { "get": { "tags": [ "Business" ], "operationId": "getBusinessPaymentLink", "summary": "Get one business payment link", "description": "Returns one invoice payment link for an accessible business company. Inaccessible payment links are returned as not found. This route is read-only and does not create checkout sessions or charge customers.", "security": [ { "ApiKeyAuth": [] } ], "parameters": [ { "name": "company_id", "in": "path", "required": true, "description": "Business company id.", "schema": { "type": "string", "format": "uuid" } }, { "name": "payment_link_id", "in": "path", "required": true, "description": "Payment link id to fetch.", "schema": { "type": "string", "format": "uuid" } }, { "$ref": "#/components/parameters/RequestId" } ], "responses": { "200": { "description": "Business payment link returned.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BusinessPaymentLinkDetailResponse" } } } }, "400": { "description": "The company_id or payment_link_id path parameter is invalid.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1ErrorEnvelope" } } } }, "401": { "description": "Missing, invalid, expired or inactive API key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LegacyErrorResponse" } } } }, "403": { "description": "The API key does not have invoices permission, or the master key is not allowed to access the company.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1ErrorEnvelope" } } } }, "404": { "description": "Business payment link not found.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1ErrorEnvelope" } } } }, "405": { "description": "Only GET is allowed for this route.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1ErrorEnvelope" } } } }, "500": { "description": "Generic server failure. Internal database details must not be returned.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1ErrorEnvelope" } } } } }, "x-financial-iq-safety": { "requiresApiKey": true, "apiKeysAllowed": true, "requiresUserBearerToken": false, "scope": "business.payment_links.read", "requiredApiKeyPermission": "invoices", "businessMutation": false, "directFinancialMutation": false, "readOnly": true, "writeLevel": "read", "requiresIdempotencyKey": false, "doesNot": [ "create_payment_link", "create_checkout_session", "charge_customer", "activate_payment_link", "deactivate_payment_link", "update_invoice_payment_state", "post_journal", "reconcile_payout", "move_money" ], "auditedEndpoint": "v1/business/companies/{company_id}/payment-links/{payment_link_id}" }, "x-implementation": { "edgeFunction": "supabase/functions/financial-data-api/index.ts", "tables": [ "payment_links", "invoices" ], "handler": "handleV1BusinessPaymentLinkDetail" } } }, "/v1/business/companies/{company_id}/customer-payments": { "get": { "tags": [ "Business" ], "operationId": "listBusinessCustomerPayments", "summary": "List business customer payments", "description": "Lists customer payment records linked to sales invoices for one accessible business company. This route is read-only: it does not record customer payments, charge customers, create checkout sessions, update invoices, post journals, reconcile bank feeds, reconcile payouts or move money.", "security": [ { "ApiKeyAuth": [] } ], "parameters": [ { "name": "company_id", "in": "path", "required": true, "description": "Business company id.", "schema": { "type": "string", "format": "uuid" } }, { "$ref": "#/components/parameters/RequestId" }, { "name": "invoice_id", "in": "query", "required": false, "description": "Optional sales invoice id filter.", "schema": { "type": "string", "format": "uuid" } }, { "name": "customer_id", "in": "query", "required": false, "description": "Optional customer id filter through the linked invoice.", "schema": { "type": "string", "format": "uuid" } }, { "name": "bank_account_id", "in": "query", "required": false, "description": "Optional bank account id filter.", "schema": { "type": "string", "format": "uuid" } }, { "name": "bank_transaction_id", "in": "query", "required": false, "description": "Optional linked bank transaction id filter.", "schema": { "type": "string", "format": "uuid" } }, { "name": "journal_transaction_id", "in": "query", "required": false, "description": "Optional linked journal transaction id filter.", "schema": { "type": "string", "format": "uuid" } }, { "name": "payment_date_from", "in": "query", "required": false, "description": "Optional inclusive lower bound for payment date.", "schema": { "type": "string", "format": "date" } }, { "name": "payment_date_to", "in": "query", "required": false, "description": "Optional inclusive upper bound for payment date.", "schema": { "type": "string", "format": "date" } }, { "name": "include_archived", "in": "query", "required": false, "description": "Include archived customer payment records. Defaults to false.", "schema": { "type": "boolean", "default": false } }, { "name": "limit", "in": "query", "required": false, "description": "Maximum records to return, capped at 100.", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 50 } }, { "name": "offset", "in": "query", "required": false, "description": "Zero-based pagination offset.", "schema": { "type": "integer", "minimum": 0, "default": 0 } } ], "responses": { "200": { "description": "Business customer payments returned.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BusinessCustomerPaymentListResponse" } } } }, "400": { "description": "The company_id path parameter or query filters are invalid.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1ErrorEnvelope" } } } }, "401": { "description": "Missing, invalid, expired or inactive API key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LegacyErrorResponse" } } } }, "403": { "description": "The API key does not have invoices permission, or the master key is not allowed to access the company.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1ErrorEnvelope" } } } }, "404": { "description": "Business company not found.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1ErrorEnvelope" } } } }, "405": { "description": "Only GET and POST are allowed for this route.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1ErrorEnvelope" } } } }, "500": { "description": "Generic server failure. Internal database details must not be returned.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1ErrorEnvelope" } } } } }, "x-financial-iq-safety": { "requiresApiKey": true, "apiKeysAllowed": true, "requiresUserBearerToken": false, "scope": "business.customer_payments.read", "requiredApiKeyPermission": "invoices", "businessMutation": false, "directFinancialMutation": false, "readOnly": true, "writeLevel": "read", "requiresIdempotencyKey": false, "doesNot": [ "record_customer_payment", "charge_customer", "create_checkout_session", "create_payment_link", "update_invoice_payment_state", "post_journal", "reconcile_bank_transaction", "reconcile_payout", "move_money" ], "redactions": [ "notes", "created_by", "archived_by", "provider_payload", "provider_payment_id", "stripe_account_id", "card_details" ], "auditedEndpoint": "v1/business/companies/{company_id}/customer-payments" }, "x-implementation": { "edgeFunction": "supabase/functions/financial-data-api/index.ts", "tables": [ "invoice_payments", "invoices", "customers", "bank_accounts", "bank_transactions", "journal_transactions" ], "handler": "handleV1BusinessCustomerPayments" } }, "post": { "tags": [ "Business" ], "operationId": "recordBusinessCustomerPayment", "summary": "Record a Stripe-backed business customer payment", "description": "Records an already-completed Stripe payment against a ledger-posted sales invoice for one accessible business company. The API verifies the gross amount and processing fee from Stripe, updates invoice payment state, writes the customer payment evidence row, and posts the standard payment and fee journals. This route requires invoices permission and an Idempotency-Key. It does not charge a customer, create a checkout session, create a payment link, accept caller-supplied amounts or fees, reconcile bank transactions, reconcile Stripe payouts, submit tax returns or move money.", "security": [ { "ApiKeyAuth": [] } ], "parameters": [ { "name": "company_id", "in": "path", "required": true, "description": "Business company id.", "schema": { "type": "string", "format": "uuid" } }, { "$ref": "#/components/parameters/RequestId" }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BusinessCustomerPaymentRecordRequest" } } } }, "responses": { "201": { "description": "Business customer payment recorded.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" }, "X-FIQ-Idempotency-Replayed": { "$ref": "#/components/headers/IdempotencyReplayed" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BusinessCustomerPaymentCreateResponse" } } } }, "400": { "description": "Invalid request body, invalid company id, invalid invoice id, invalid payment date, unsupported fields, or missing Idempotency-Key.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1ErrorEnvelope" } } } }, "401": { "description": "Missing, invalid, expired or inactive API key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LegacyErrorResponse" } } } }, "403": { "description": "The API key does not have invoices permission, or has no owner user.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1ErrorEnvelope" } } } }, "404": { "description": "Business company or invoice not found.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1ErrorEnvelope" } } } }, "405": { "description": "Only GET and POST are allowed for this route.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1ErrorEnvelope" } } } }, "409": { "description": "The Idempotency-Key is currently processing or was used with a different request body.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1ErrorEnvelope" } } } }, "422": { "description": "The payment could not be recorded after validation, for example because the invoice is not ledger-posted or Stripe could not resolve a positive gross amount.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1ErrorEnvelope" } } } }, "500": { "description": "Generic server failure. Internal database, Stripe and journal details must not be returned.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1ErrorEnvelope" } } } } }, "x-financial-iq-safety": { "requiresApiKey": true, "apiKeysAllowed": true, "requiresUserBearerToken": false, "scope": "business.customer_payments.record", "requiredApiKeyPermission": "invoices", "businessMutation": true, "directFinancialMutation": true, "readOnly": false, "writeLevel": "ledger_write", "requiresIdempotencyKey": true, "providerVerification": "stripe_payment_intent", "amountSource": "stripe_verified_only", "does": [ "record_customer_payment", "update_invoice_payment_state", "post_payment_journal", "post_payment_fee_journal" ], "doesNot": [ "accept_manual_amount", "accept_manual_fee", "charge_customer", "create_checkout_session", "create_payment_link", "reconcile_bank_transaction", "reconcile_payout", "submit_tax", "move_money" ], "redactions": [ "notes", "created_by", "provider_payload", "provider_payment_id", "stripe_account_id", "card_details" ], "auditedEndpoint": "v1/business/companies/{company_id}/customer-payments" }, "x-implementation": { "edgeFunction": "supabase/functions/financial-data-api/index.ts", "tables": [ "invoices", "invoice_payments", "chart_of_accounts", "journal_transactions", "journal_entries", "api_idempotency_records", "api_usage_logs", "audit_logs" ], "handler": "handleV1BusinessCustomerPayments", "sharedEngine": "supabase/functions/_shared/paymentJournals.ts#recordInvoicePayment", "tests": [ "supabase/functions/financial-data-api/invoice_idempotency.test.ts" ] } } }, "/v1/business/companies/{company_id}/customer-payments/{customer_payment_id}": { "get": { "tags": [ "Business" ], "operationId": "getBusinessCustomerPayment", "summary": "Get one business customer payment", "description": "Returns one customer payment record linked to a sales invoice for an accessible business company. Inaccessible payment records are returned as not found. This route is read-only and does not record payments, charge customers, post journals or move money.", "security": [ { "ApiKeyAuth": [] } ], "parameters": [ { "name": "company_id", "in": "path", "required": true, "description": "Business company id.", "schema": { "type": "string", "format": "uuid" } }, { "name": "customer_payment_id", "in": "path", "required": true, "description": "Customer payment id to fetch.", "schema": { "type": "string", "format": "uuid" } }, { "$ref": "#/components/parameters/RequestId" } ], "responses": { "200": { "description": "Business customer payment returned.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BusinessCustomerPaymentDetailResponse" } } } }, "400": { "description": "The company_id or customer_payment_id path parameter is invalid.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1ErrorEnvelope" } } } }, "401": { "description": "Missing, invalid, expired or inactive API key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LegacyErrorResponse" } } } }, "403": { "description": "The API key does not have invoices permission, or the master key is not allowed to access the company.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1ErrorEnvelope" } } } }, "404": { "description": "Business customer payment not found.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1ErrorEnvelope" } } } }, "405": { "description": "Only GET is allowed for this route.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1ErrorEnvelope" } } } }, "500": { "description": "Generic server failure. Internal database details must not be returned.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1ErrorEnvelope" } } } } }, "x-financial-iq-safety": { "requiresApiKey": true, "apiKeysAllowed": true, "requiresUserBearerToken": false, "scope": "business.customer_payments.read", "requiredApiKeyPermission": "invoices", "businessMutation": false, "directFinancialMutation": false, "readOnly": true, "writeLevel": "read", "requiresIdempotencyKey": false, "doesNot": [ "record_customer_payment", "charge_customer", "create_checkout_session", "create_payment_link", "update_invoice_payment_state", "post_journal", "reconcile_bank_transaction", "reconcile_payout", "move_money" ], "redactions": [ "notes", "created_by", "archived_by", "provider_payload", "provider_payment_id", "stripe_account_id", "card_details" ], "auditedEndpoint": "v1/business/companies/{company_id}/customer-payments/{customer_payment_id}" }, "x-implementation": { "edgeFunction": "supabase/functions/financial-data-api/index.ts", "tables": [ "invoice_payments", "invoices", "customers", "bank_accounts", "bank_transactions", "journal_transactions" ], "handler": "handleV1BusinessCustomerPaymentDetail" } } }, "/v1/business/companies/{company_id}/supplier-payments": { "get": { "tags": [ "Business" ], "operationId": "listBusinessSupplierPayments", "summary": "List business supplier payments", "description": "Lists supplier payment records linked to purchase invoices for one accessible business company. This route is read-only: it does not initiate supplier payments, export bank payment files, approve payment runs, mark bills as paid, post journals, reconcile bank transactions or move money.", "security": [ { "ApiKeyAuth": [] } ], "parameters": [ { "name": "company_id", "in": "path", "required": true, "description": "Business company id.", "schema": { "type": "string", "format": "uuid" } }, { "$ref": "#/components/parameters/RequestId" }, { "name": "purchase_invoice_id", "in": "query", "required": false, "description": "Optional purchase invoice id filter.", "schema": { "type": "string", "format": "uuid" } }, { "name": "supplier_id", "in": "query", "required": false, "description": "Optional supplier id filter through the linked purchase invoice.", "schema": { "type": "string", "format": "uuid" } }, { "name": "bank_account_id", "in": "query", "required": false, "description": "Optional bank account id filter.", "schema": { "type": "string", "format": "uuid" } }, { "name": "bank_transaction_id", "in": "query", "required": false, "description": "Optional linked bank transaction id filter.", "schema": { "type": "string", "format": "uuid" } }, { "name": "journal_transaction_id", "in": "query", "required": false, "description": "Optional linked journal transaction id filter.", "schema": { "type": "string", "format": "uuid" } }, { "name": "payment_batch_id", "in": "query", "required": false, "description": "Optional supplier payment batch or run id filter.", "schema": { "type": "string", "format": "uuid" } }, { "name": "status", "in": "query", "required": false, "description": "Optional supplier payment status filter.", "schema": { "type": "string" } }, { "name": "payment_method", "in": "query", "required": false, "description": "Optional supplier payment method filter.", "schema": { "type": "string" } }, { "name": "payment_date_from", "in": "query", "required": false, "description": "Optional inclusive lower bound for payment date.", "schema": { "type": "string", "format": "date" } }, { "name": "payment_date_to", "in": "query", "required": false, "description": "Optional inclusive upper bound for payment date.", "schema": { "type": "string", "format": "date" } }, { "name": "include_archived", "in": "query", "required": false, "description": "Include archived supplier payment records. Defaults to false.", "schema": { "type": "boolean", "default": false } }, { "name": "limit", "in": "query", "required": false, "description": "Maximum records to return, capped at 100.", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 50 } }, { "name": "offset", "in": "query", "required": false, "description": "Zero-based pagination offset.", "schema": { "type": "integer", "minimum": 0, "default": 0 } } ], "responses": { "200": { "description": "Business supplier payments returned.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BusinessSupplierPaymentListResponse" } } } }, "400": { "description": "The company_id path parameter or query filters are invalid.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1ErrorEnvelope" } } } }, "401": { "description": "Missing, invalid, expired or inactive API key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LegacyErrorResponse" } } } }, "403": { "description": "The API key does not have invoices permission, or the master key is not allowed to access the company.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1ErrorEnvelope" } } } }, "404": { "description": "Business company not found.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1ErrorEnvelope" } } } }, "405": { "description": "Only GET is allowed for this route.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1ErrorEnvelope" } } } }, "500": { "description": "Generic server failure. Internal database details must not be returned.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1ErrorEnvelope" } } } } }, "x-financial-iq-safety": { "requiresApiKey": true, "apiKeysAllowed": true, "requiresUserBearerToken": false, "scope": "business.supplier_payments.read", "requiredApiKeyPermission": "invoices", "businessMutation": false, "directFinancialMutation": false, "readOnly": true, "writeLevel": "read", "requiresIdempotencyKey": false, "doesNot": [ "initiate_supplier_payment", "export_bank_payment_file", "approve_supplier_payment_run", "mark_bill_paid", "post_journal", "reconcile_bank_transaction", "move_money" ], "redactions": [ "notes", "created_by", "authorised_by", "archived_by", "provider_payload", "provider_payment_id", "yapily_payment_id", "supplier_bank_details" ], "auditedEndpoint": "v1/business/companies/{company_id}/supplier-payments" }, "x-implementation": { "edgeFunction": "supabase/functions/financial-data-api/index.ts", "tables": [ "purchase_payments", "purchase_invoices", "suppliers", "bank_accounts", "bank_transactions", "journal_transactions" ], "handler": "handleV1BusinessSupplierPayments" } } }, "/v1/business/companies/{company_id}/supplier-payments/{supplier_payment_id}": { "get": { "tags": [ "Business" ], "operationId": "getBusinessSupplierPayment", "summary": "Get one business supplier payment", "description": "Returns one supplier payment record linked to a purchase invoice for an accessible business company. Inaccessible payment records are returned as not found. This route is read-only and does not initiate supplier payments, export bank payment files, post journals or move money.", "security": [ { "ApiKeyAuth": [] } ], "parameters": [ { "name": "company_id", "in": "path", "required": true, "description": "Business company id.", "schema": { "type": "string", "format": "uuid" } }, { "name": "supplier_payment_id", "in": "path", "required": true, "description": "Supplier payment id to fetch.", "schema": { "type": "string", "format": "uuid" } }, { "$ref": "#/components/parameters/RequestId" } ], "responses": { "200": { "description": "Business supplier payment returned.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BusinessSupplierPaymentDetailResponse" } } } }, "400": { "description": "The company_id or supplier_payment_id path parameter is invalid.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1ErrorEnvelope" } } } }, "401": { "description": "Missing, invalid, expired or inactive API key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LegacyErrorResponse" } } } }, "403": { "description": "The API key does not have invoices permission, or the master key is not allowed to access the company.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1ErrorEnvelope" } } } }, "404": { "description": "Business supplier payment not found.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1ErrorEnvelope" } } } }, "405": { "description": "Only GET is allowed for this route.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1ErrorEnvelope" } } } }, "500": { "description": "Generic server failure. Internal database details must not be returned.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1ErrorEnvelope" } } } } }, "x-financial-iq-safety": { "requiresApiKey": true, "apiKeysAllowed": true, "requiresUserBearerToken": false, "scope": "business.supplier_payments.read", "requiredApiKeyPermission": "invoices", "businessMutation": false, "directFinancialMutation": false, "readOnly": true, "writeLevel": "read", "requiresIdempotencyKey": false, "doesNot": [ "initiate_supplier_payment", "export_bank_payment_file", "approve_supplier_payment_run", "mark_bill_paid", "post_journal", "reconcile_bank_transaction", "move_money" ], "redactions": [ "notes", "created_by", "authorised_by", "archived_by", "provider_payload", "provider_payment_id", "yapily_payment_id", "supplier_bank_details" ], "auditedEndpoint": "v1/business/companies/{company_id}/supplier-payments/{supplier_payment_id}" }, "x-implementation": { "edgeFunction": "supabase/functions/financial-data-api/index.ts", "tables": [ "purchase_payments", "purchase_invoices", "suppliers", "bank_accounts", "bank_transactions", "journal_transactions" ], "handler": "handleV1BusinessSupplierPaymentDetail" } } }, "/v1/business/companies/{company_id}/payroll-pay-items": { "get": { "tags": [ "Business" ], "operationId": "listBusinessPayrollPayItems", "summary": "List business payroll pay items", "description": "Lists payroll pay item catalogue records for one accessible business company. This route is read-only: it does not create, update or delete pay items, calculate payroll, submit payroll, export bank files or move money.", "security": [ { "ApiKeyAuth": [] } ], "parameters": [ { "name": "company_id", "in": "path", "required": true, "description": "Business company id.", "schema": { "type": "string", "format": "uuid" } }, { "$ref": "#/components/parameters/RequestId" }, { "name": "code", "in": "query", "required": false, "description": "Optional payroll pay item code filter.", "schema": { "type": "string" } }, { "name": "calculation_method", "in": "query", "required": false, "description": "Optional calculation method filter.", "schema": { "type": "string", "enum": [ "manual", "fixed_amount", "percentage_of_gross" ] } }, { "name": "is_active", "in": "query", "required": false, "description": "Optional active-state filter.", "schema": { "type": "boolean" } }, { "name": "taxable", "in": "query", "required": false, "description": "Optional taxable flag filter.", "schema": { "type": "boolean" } }, { "name": "niable", "in": "query", "required": false, "description": "Optional National Insurance flag filter.", "schema": { "type": "boolean" } }, { "name": "pensionable", "in": "query", "required": false, "description": "Optional pensionable flag filter.", "schema": { "type": "boolean" } }, { "name": "limit", "in": "query", "required": false, "description": "Maximum records to return, capped at 100.", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 50 } }, { "name": "offset", "in": "query", "required": false, "description": "Zero-based pagination offset.", "schema": { "type": "integer", "minimum": 0, "default": 0 } } ], "responses": { "200": { "description": "Business payroll pay items returned.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BusinessPayrollPayItemListResponse" } } } }, "400": { "description": "The company_id path parameter or query filters are invalid.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1ErrorEnvelope" } } } }, "401": { "description": "Missing, invalid, expired or inactive API key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LegacyErrorResponse" } } } }, "403": { "description": "The API key does not have reports permission, or the master key is not allowed to access the company.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1ErrorEnvelope" } } } }, "404": { "description": "Business company not found.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1ErrorEnvelope" } } } }, "405": { "description": "Only GET is allowed for this route.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1ErrorEnvelope" } } } }, "500": { "description": "Generic server failure. Internal database details must not be returned.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1ErrorEnvelope" } } } } }, "x-financial-iq-safety": { "requiresApiKey": true, "apiKeysAllowed": true, "requiresUserBearerToken": false, "scope": "business.payroll_pay_items.read", "requiredApiKeyPermission": "reports", "businessMutation": false, "directFinancialMutation": false, "readOnly": true, "writeLevel": "read", "requiresIdempotencyKey": false, "doesNot": [ "create_pay_item", "update_pay_item", "delete_pay_item", "calculate_payroll", "submit_payroll", "export_bank_file", "move_money" ], "redactions": [ "created_by", "internal_actor_ids" ], "auditedEndpoint": "v1/business/companies/{company_id}/payroll-pay-items" }, "x-implementation": { "edgeFunction": "supabase/functions/financial-data-api/index.ts", "tables": [ "payroll_pay_items" ], "handler": "handleV1BusinessPayrollPayItems" } } }, "/v1/business/companies/{company_id}/payroll-pay-items/{payroll_pay_item_id}": { "get": { "tags": [ "Business" ], "operationId": "getBusinessPayrollPayItem", "summary": "Get business payroll pay item", "description": "Returns one payroll pay item catalogue record for an accessible business company. This route is read-only and does not edit payroll setup.", "security": [ { "ApiKeyAuth": [] } ], "parameters": [ { "name": "company_id", "in": "path", "required": true, "description": "Business company id.", "schema": { "type": "string", "format": "uuid" } }, { "name": "payroll_pay_item_id", "in": "path", "required": true, "description": "Payroll pay item id.", "schema": { "type": "string", "format": "uuid" } }, { "$ref": "#/components/parameters/RequestId" } ], "responses": { "200": { "description": "Business payroll pay item returned.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BusinessPayrollPayItemDetailResponse" } } } }, "400": { "description": "The company_id or payroll_pay_item_id path parameter is invalid.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1ErrorEnvelope" } } } }, "401": { "description": "Missing, invalid, expired or inactive API key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LegacyErrorResponse" } } } }, "403": { "description": "The API key does not have reports permission, or the master key is not allowed to access the company.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1ErrorEnvelope" } } } }, "404": { "description": "Business payroll pay item not found.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1ErrorEnvelope" } } } }, "405": { "description": "Only GET is allowed for this route.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1ErrorEnvelope" } } } }, "500": { "description": "Generic server failure. Internal database details must not be returned.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1ErrorEnvelope" } } } } }, "x-financial-iq-safety": { "requiresApiKey": true, "apiKeysAllowed": true, "requiresUserBearerToken": false, "scope": "business.payroll_pay_items.read", "requiredApiKeyPermission": "reports", "businessMutation": false, "directFinancialMutation": false, "readOnly": true, "writeLevel": "read", "requiresIdempotencyKey": false, "doesNot": [ "create_pay_item", "update_pay_item", "delete_pay_item", "calculate_payroll", "submit_payroll", "export_bank_file", "move_money" ], "redactions": [ "created_by", "internal_actor_ids" ], "auditedEndpoint": "v1/business/companies/{company_id}/payroll-pay-items/{payroll_pay_item_id}" }, "x-implementation": { "edgeFunction": "supabase/functions/financial-data-api/index.ts", "tables": [ "payroll_pay_items" ], "handler": "handleV1BusinessPayrollPayItemDetail" } } }, "/v1/business/companies/{company_id}/payroll-deduction-items": { "get": { "tags": [ "Business" ], "operationId": "listBusinessPayrollDeductionItems", "summary": "List business payroll deduction items", "description": "Lists payroll deduction item catalogue records for one accessible business company. This route is read-only: it does not create, update or delete deduction items, calculate payroll, submit payroll, export bank files or move money.", "security": [ { "ApiKeyAuth": [] } ], "parameters": [ { "name": "company_id", "in": "path", "required": true, "description": "Business company id.", "schema": { "type": "string", "format": "uuid" } }, { "$ref": "#/components/parameters/RequestId" }, { "name": "code", "in": "query", "required": false, "description": "Optional payroll deduction item code filter.", "schema": { "type": "string" } }, { "name": "deduction_type", "in": "query", "required": false, "description": "Optional deduction type filter.", "schema": { "type": "string", "enum": [ "paye", "employee_ni", "student_loan", "postgraduate_loan", "employee_pension", "attachment_of_earnings", "other" ] } }, { "name": "calculation_method", "in": "query", "required": false, "description": "Optional calculation method filter.", "schema": { "type": "string", "enum": [ "manual", "fixed_amount", "percentage_of_gross" ] } }, { "name": "is_active", "in": "query", "required": false, "description": "Optional active-state filter.", "schema": { "type": "boolean" } }, { "name": "limit", "in": "query", "required": false, "description": "Maximum records to return, capped at 100.", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 50 } }, { "name": "offset", "in": "query", "required": false, "description": "Zero-based pagination offset.", "schema": { "type": "integer", "minimum": 0, "default": 0 } } ], "responses": { "200": { "description": "Business payroll deduction items returned.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BusinessPayrollDeductionItemListResponse" } } } }, "400": { "description": "The company_id path parameter or query filters are invalid.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1ErrorEnvelope" } } } }, "401": { "description": "Missing, invalid, expired or inactive API key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LegacyErrorResponse" } } } }, "403": { "description": "The API key does not have reports permission, or the master key is not allowed to access the company.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1ErrorEnvelope" } } } }, "404": { "description": "Business company not found.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1ErrorEnvelope" } } } }, "405": { "description": "Only GET is allowed for this route.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1ErrorEnvelope" } } } }, "500": { "description": "Generic server failure. Internal database details must not be returned.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1ErrorEnvelope" } } } } }, "x-financial-iq-safety": { "requiresApiKey": true, "apiKeysAllowed": true, "requiresUserBearerToken": false, "scope": "business.payroll_deduction_items.read", "requiredApiKeyPermission": "reports", "businessMutation": false, "directFinancialMutation": false, "readOnly": true, "writeLevel": "read", "requiresIdempotencyKey": false, "doesNot": [ "create_deduction_item", "update_deduction_item", "delete_deduction_item", "calculate_payroll", "submit_payroll", "export_bank_file", "move_money" ], "redactions": [ "created_by", "internal_actor_ids" ], "auditedEndpoint": "v1/business/companies/{company_id}/payroll-deduction-items" }, "x-implementation": { "edgeFunction": "supabase/functions/financial-data-api/index.ts", "tables": [ "payroll_deduction_items" ], "handler": "handleV1BusinessPayrollDeductionItems" } } }, "/v1/business/companies/{company_id}/payroll-deduction-items/{payroll_deduction_item_id}": { "get": { "tags": [ "Business" ], "operationId": "getBusinessPayrollDeductionItem", "summary": "Get business payroll deduction item", "description": "Returns one payroll deduction item catalogue record for an accessible business company. This route is read-only and does not edit payroll setup.", "security": [ { "ApiKeyAuth": [] } ], "parameters": [ { "name": "company_id", "in": "path", "required": true, "description": "Business company id.", "schema": { "type": "string", "format": "uuid" } }, { "name": "payroll_deduction_item_id", "in": "path", "required": true, "description": "Payroll deduction item id.", "schema": { "type": "string", "format": "uuid" } }, { "$ref": "#/components/parameters/RequestId" } ], "responses": { "200": { "description": "Business payroll deduction item returned.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BusinessPayrollDeductionItemDetailResponse" } } } }, "400": { "description": "The company_id or payroll_deduction_item_id path parameter is invalid.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1ErrorEnvelope" } } } }, "401": { "description": "Missing, invalid, expired or inactive API key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LegacyErrorResponse" } } } }, "403": { "description": "The API key does not have reports permission, or the master key is not allowed to access the company.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1ErrorEnvelope" } } } }, "404": { "description": "Business payroll deduction item not found.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1ErrorEnvelope" } } } }, "405": { "description": "Only GET is allowed for this route.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1ErrorEnvelope" } } } }, "500": { "description": "Generic server failure. Internal database details must not be returned.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1ErrorEnvelope" } } } } }, "x-financial-iq-safety": { "requiresApiKey": true, "apiKeysAllowed": true, "requiresUserBearerToken": false, "scope": "business.payroll_deduction_items.read", "requiredApiKeyPermission": "reports", "businessMutation": false, "directFinancialMutation": false, "readOnly": true, "writeLevel": "read", "requiresIdempotencyKey": false, "doesNot": [ "create_deduction_item", "update_deduction_item", "delete_deduction_item", "calculate_payroll", "submit_payroll", "export_bank_file", "move_money" ], "redactions": [ "created_by", "internal_actor_ids" ], "auditedEndpoint": "v1/business/companies/{company_id}/payroll-deduction-items/{payroll_deduction_item_id}" }, "x-implementation": { "edgeFunction": "supabase/functions/financial-data-api/index.ts", "tables": [ "payroll_deduction_items" ], "handler": "handleV1BusinessPayrollDeductionItemDetail" } } }, "/v1/business/companies/{company_id}/payroll-pension-schemes": { "get": { "tags": [ "Business" ], "operationId": "listBusinessPayrollPensionSchemes", "summary": "List business payroll pension schemes", "description": "Lists payroll pension scheme setup records for one accessible business company. This route is read-only: it does not create, update or delete pension schemes, calculate payroll, submit payroll, submit pension files, export bank files or move money.", "security": [ { "ApiKeyAuth": [] } ], "parameters": [ { "name": "company_id", "in": "path", "required": true, "description": "Business company id.", "schema": { "type": "string", "format": "uuid" } }, { "$ref": "#/components/parameters/RequestId" }, { "name": "provider", "in": "query", "required": false, "description": "Optional pension provider filter. Currently only NEST is supported.", "schema": { "type": "string", "enum": [ "nest" ] } }, { "name": "submission_method", "in": "query", "required": false, "description": "Optional pension submission method filter.", "schema": { "type": "string", "enum": [ "api", "sftp", "file_upload" ] } }, { "name": "status", "in": "query", "required": false, "description": "Optional pension scheme status filter.", "schema": { "type": "string", "enum": [ "active", "inactive" ] } }, { "name": "relief_method", "in": "query", "required": false, "description": "Optional pension tax relief method filter.", "schema": { "type": "string", "enum": [ "relief_at_source", "net_pay", "salary_sacrifice" ] } }, { "name": "contribution_basis", "in": "query", "required": false, "description": "Optional pension contribution basis filter.", "schema": { "type": "string", "enum": [ "qualifying_earnings", "basic_pay", "total_pay", "tier1", "tier2", "tier3" ] } }, { "name": "enforce_ae_minimum", "in": "query", "required": false, "description": "Optional auto-enrolment minimum enforcement filter.", "schema": { "type": "boolean" } }, { "name": "limit", "in": "query", "required": false, "description": "Maximum records to return, capped at 100.", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 50 } }, { "name": "offset", "in": "query", "required": false, "description": "Zero-based pagination offset.", "schema": { "type": "integer", "minimum": 0, "default": 0 } } ], "responses": { "200": { "description": "Business payroll pension schemes returned.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BusinessPayrollPensionSchemeListResponse" } } } }, "400": { "description": "The company_id path parameter or query filters are invalid.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1ErrorEnvelope" } } } }, "401": { "description": "Missing, invalid, expired or inactive API key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LegacyErrorResponse" } } } }, "403": { "description": "The API key does not have reports permission, or the master key is not allowed to access the company.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1ErrorEnvelope" } } } }, "404": { "description": "Business company not found.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1ErrorEnvelope" } } } }, "405": { "description": "Only GET is allowed for this route.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1ErrorEnvelope" } } } }, "500": { "description": "Generic server failure. Internal database details must not be returned.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1ErrorEnvelope" } } } } }, "x-financial-iq-safety": { "requiresApiKey": true, "apiKeysAllowed": true, "requiresUserBearerToken": false, "scope": "business.payroll_pension_schemes.read", "requiredApiKeyPermission": "reports", "businessMutation": false, "directFinancialMutation": false, "readOnly": true, "writeLevel": "read", "requiresIdempotencyKey": false, "doesNot": [ "create_pension_scheme", "update_pension_scheme", "delete_pension_scheme", "calculate_payroll", "submit_payroll", "submit_pension_file", "export_bank_file", "move_money" ], "redactions": [ "credentials_secret_ref", "created_by", "internal_actor_ids" ], "auditedEndpoint": "v1/business/companies/{company_id}/payroll-pension-schemes" }, "x-implementation": { "edgeFunction": "supabase/functions/financial-data-api/index.ts", "tables": [ "payroll_pension_schemes" ], "handler": "handleV1BusinessPayrollPensionSchemes" } } }, "/v1/business/companies/{company_id}/payroll-pension-schemes/{payroll_pension_scheme_id}": { "get": { "tags": [ "Business" ], "operationId": "getBusinessPayrollPensionScheme", "summary": "Get business payroll pension scheme", "description": "Returns one payroll pension scheme setup record for an accessible business company. This route is read-only and does not edit pension setup.", "security": [ { "ApiKeyAuth": [] } ], "parameters": [ { "name": "company_id", "in": "path", "required": true, "description": "Business company id.", "schema": { "type": "string", "format": "uuid" } }, { "name": "payroll_pension_scheme_id", "in": "path", "required": true, "description": "Payroll pension scheme id.", "schema": { "type": "string", "format": "uuid" } }, { "$ref": "#/components/parameters/RequestId" } ], "responses": { "200": { "description": "Business payroll pension scheme returned.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BusinessPayrollPensionSchemeDetailResponse" } } } }, "400": { "description": "The company_id or payroll_pension_scheme_id path parameter is invalid.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1ErrorEnvelope" } } } }, "401": { "description": "Missing, invalid, expired or inactive API key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LegacyErrorResponse" } } } }, "403": { "description": "The API key does not have reports permission, or the master key is not allowed to access the company.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1ErrorEnvelope" } } } }, "404": { "description": "Business payroll pension scheme not found.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1ErrorEnvelope" } } } }, "405": { "description": "Only GET is allowed for this route.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1ErrorEnvelope" } } } }, "500": { "description": "Generic server failure. Internal database details must not be returned.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1ErrorEnvelope" } } } } }, "x-financial-iq-safety": { "requiresApiKey": true, "apiKeysAllowed": true, "requiresUserBearerToken": false, "scope": "business.payroll_pension_schemes.read", "requiredApiKeyPermission": "reports", "businessMutation": false, "directFinancialMutation": false, "readOnly": true, "writeLevel": "read", "requiresIdempotencyKey": false, "doesNot": [ "create_pension_scheme", "update_pension_scheme", "delete_pension_scheme", "calculate_payroll", "submit_payroll", "submit_pension_file", "export_bank_file", "move_money" ], "redactions": [ "credentials_secret_ref", "created_by", "internal_actor_ids" ], "auditedEndpoint": "v1/business/companies/{company_id}/payroll-pension-schemes/{payroll_pension_scheme_id}" }, "x-implementation": { "edgeFunction": "supabase/functions/financial-data-api/index.ts", "tables": [ "payroll_pension_schemes" ], "handler": "handleV1BusinessPayrollPensionSchemeDetail" } } }, "/v1/business/companies/{company_id}/payroll-runs/{payroll_run_id}/submission-requests": { "post": { "tags": ["Business"], "operationId": "createBusinessPayrollSubmissionRequest", "summary": "Request business payroll submission approval", "description": "Creates a short-lived, audited handoff for a signed-in Financial IQ user to review and submit an eligible HMRC FPS or NEST contribution schedule. The API key cannot submit directly or bypass payroll finalisation, credentials or provider controls.", "security": [{"ApiKeyAuth": []}], "parameters": [ {"$ref": "#/components/parameters/BusinessCompanyId"}, {"name": "payroll_run_id", "in": "path", "required": true, "description": "Eligible payroll run to submit after user approval. HMRC FPS may start from calculated, approved or finalised; NEST contribution schedules require a finalised and posted run.", "schema": {"type": "string", "format": "uuid"}}, {"$ref": "#/components/parameters/RequestId"}, {"$ref": "#/components/parameters/IdempotencyKey"} ], "requestBody": {"required": true, "content": {"application/json": {"schema": {"$ref": "#/components/schemas/V1BusinessPayrollSubmissionRequestCreate"}}}}, "responses": { "201": {"description": "Payroll submission approval handoff created.", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/V1BusinessPayrollSubmissionRequestResponse"}}}}, "400": {"description": "Invalid payroll run, environment or missing idempotency key.", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/V1ErrorEnvelope"}}}}, "401": {"description": "Missing, invalid, expired or inactive API key."}, "403": {"description": "The API key does not grant tax_filings permission.", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/V1ErrorEnvelope"}}}}, "404": {"description": "Business payroll run not found.", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/V1ErrorEnvelope"}}}}, "409": {"description": "The payroll run is not eligible or a matching submission already exists for the environment.", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/V1ErrorEnvelope"}}}} }, "x-financial-iq-safety": {"scope": "business.payroll_submission_requests.create", "businessMutation": true, "directFinancialMutation": false, "writeLevel": "human_approval", "requiresIdempotencyKey": true, "auditedEndpoint": "v1/business/companies/{company_id}/payroll-runs/{payroll_run_id}/submission-requests", "requiredPermission": "tax_filings", "approvalRequired": true, "doesNot": ["submit_directly_to_hmrc", "submit_directly_to_nest", "bypass_payroll_finalisation", "bypass_hmrc_credentials", "bypass_nest_credentials", "bypass_mfa", "post_to_ledger", "move_money"]}, "x-implementation": {"edgeFunction": "supabase/functions/financial-data-api/index.ts", "handler": "handleV1BusinessPayrollSubmissionRequestCreate", "tests": ["supabase/functions/financial-data-api/invoice_idempotency.test.ts", "supabase/tests/api_business_payroll_submission_request.sql"]} } }, "/v1/business/companies/{company_id}/payroll-submissions/{payroll_submission_id}/submission-requests": { "post": { "tags": ["Business"], "operationId": "createBusinessPayrollEpsSubmissionRequest", "summary": "Request business EPS submission approval", "description": "Creates a short-lived, audited handoff for a signed-in Financial IQ user to review and submit an existing queued Employer Payment Summary (EPS).", "security": [{"ApiKeyAuth": []}], "parameters": [ {"$ref": "#/components/parameters/BusinessCompanyId"}, {"name": "payroll_submission_id", "in": "path", "required": true, "description": "Queued, retrying or rejected EPS submission to submit after user approval.", "schema": {"type": "string", "format": "uuid"}}, {"$ref": "#/components/parameters/RequestId"}, {"$ref": "#/components/parameters/IdempotencyKey"} ], "requestBody": {"required": true, "content": {"application/json": {"schema": {"$ref": "#/components/schemas/V1BusinessPayrollEpsSubmissionRequestCreate"}}}}, "responses": { "201": {"description": "EPS submission approval handoff created.", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/V1BusinessPayrollSubmissionRequestResponse"}}}}, "400": {"description": "Invalid submission, environment or missing idempotency key.", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/V1ErrorEnvelope"}}}}, "401": {"description": "Missing, invalid, expired or inactive API key."}, "403": {"description": "The API key does not grant tax_filings permission.", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/V1ErrorEnvelope"}}}}, "404": {"description": "EPS submission not found for this company.", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/V1ErrorEnvelope"}}}}, "409": {"description": "The EPS submission is not ready or already has an active approval request.", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/V1ErrorEnvelope"}}}} }, "x-financial-iq-safety": {"scope": "business.payroll_submission_requests.create", "businessMutation": true, "directFinancialMutation": false, "writeLevel": "human_approval", "requiresIdempotencyKey": true, "auditedEndpoint": "v1/business/companies/{company_id}/payroll-submissions/{payroll_submission_id}/submission-requests", "requiredPermission": "tax_filings", "approvalRequired": true, "doesNot": ["submit_directly_to_hmrc", "bypass_payroll_authority", "bypass_hmrc_credentials", "bypass_mfa", "post_to_ledger", "move_money"]}, "x-implementation": {"edgeFunction": "supabase/functions/financial-data-api/index.ts", "handler": "handleV1BusinessPayrollEpsSubmissionRequestCreate", "tests": ["supabase/functions/financial-data-api/invoice_idempotency.test.ts", "supabase/tests/api_business_payroll_submission_request.sql"]} } }, "/v1/business/companies/{company_id}/payroll-submission-requests/{request_id}": { "get": { "tags": ["Business"], "operationId": "getBusinessPayrollSubmissionRequest", "summary": "Get business payroll submission approval status", "description": "Returns the status of a payroll submission approval handoff. It never submits, retries or changes the payroll run.", "security": [{"ApiKeyAuth": []}], "parameters": [ {"$ref": "#/components/parameters/BusinessCompanyId"}, {"name": "request_id", "in": "path", "required": true, "description": "Payroll submission approval request id.", "schema": {"type": "string", "format": "uuid"}}, {"$ref": "#/components/parameters/RequestId"} ], "responses": { "200": {"description": "Payroll submission approval status returned.", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/V1BusinessPayrollSubmissionRequestResponse"}}}}, "400": {"description": "Invalid path parameter.", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/V1ErrorEnvelope"}}}}, "401": {"description": "Missing, invalid, expired or inactive API key."}, "403": {"description": "The API key does not grant tax_filings permission.", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/V1ErrorEnvelope"}}}}, "404": {"description": "Payroll submission request not found.", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/V1ErrorEnvelope"}}}} }, "x-financial-iq-safety": {"scope": "business.payroll_submission_requests.read", "businessMutation": false, "directFinancialMutation": false, "writeLevel": "read", "requiresIdempotencyKey": false, "auditedEndpoint": "v1/business/companies/{company_id}/payroll-submission-requests/{request_id}", "requiredPermission": "tax_filings", "doesNot": ["submit_to_hmrc", "post_to_ledger", "move_money"]}, "x-implementation": {"edgeFunction": "supabase/functions/financial-data-api/index.ts", "handler": "handleV1BusinessPayrollSubmissionRequestDetail", "tests": ["supabase/functions/financial-data-api/invoice_idempotency.test.ts", "supabase/tests/api_business_payroll_submission_request.sql"]} } }, "/v1/business/companies/{company_id}/payroll-submissions": { "get": { "tags": [ "Business" ], "operationId": "listBusinessPayrollSubmissions", "summary": "List business payroll submissions", "description": "Lists payroll RTI/NEST submission status records for one accessible business company. This route is read-only and does not expose raw request or response payloads.", "security": [ { "ApiKeyAuth": [] } ], "parameters": [ { "name": "company_id", "in": "path", "required": true, "description": "Business company id.", "schema": { "type": "string", "format": "uuid" } }, { "$ref": "#/components/parameters/RequestId" }, { "name": "payroll_run_id", "in": "query", "required": false, "description": "Optional payroll run id filter.", "schema": { "type": "string", "format": "uuid" } }, { "name": "submission_channel", "in": "query", "required": false, "description": "Optional submission channel filter.", "schema": { "type": "string", "enum": [ "hmrc_rti", "nest" ] } }, { "name": "submission_type", "in": "query", "required": false, "description": "Optional submission type filter, such as fps or contribution_schedule.", "schema": { "type": "string" } }, { "name": "submission_environment", "in": "query", "required": false, "description": "Optional submission environment filter.", "schema": { "type": "string", "enum": [ "sandbox", "production" ] } }, { "name": "status", "in": "query", "required": false, "description": "Optional submission status filter.", "schema": { "type": "string", "enum": [ "queued", "submitted", "accepted", "rejected", "retrying", "cancelled" ] } }, { "name": "submitted_from", "in": "query", "required": false, "description": "Inclusive submitted-at lower bound as an ISO date/time.", "schema": { "type": "string", "format": "date-time" } }, { "name": "submitted_to", "in": "query", "required": false, "description": "Inclusive submitted-at upper bound as an ISO date/time.", "schema": { "type": "string", "format": "date-time" } }, { "name": "limit", "in": "query", "required": false, "description": "Maximum records to return, capped at 100.", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 50 } }, { "name": "offset", "in": "query", "required": false, "description": "Zero-based pagination offset.", "schema": { "type": "integer", "minimum": 0, "default": 0 } } ], "responses": { "200": { "description": "Business payroll submissions returned.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BusinessPayrollSubmissionListResponse" } } } }, "400": { "description": "The company_id path parameter or query filters are invalid.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1ErrorEnvelope" } } } }, "401": { "description": "Missing, invalid, expired or inactive API key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LegacyErrorResponse" } } } }, "403": { "description": "The API key does not have reports permission, or the master key is not allowed to access the company.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1ErrorEnvelope" } } } }, "404": { "description": "Business company not found.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1ErrorEnvelope" } } } }, "405": { "description": "Only GET is allowed for this route.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1ErrorEnvelope" } } } }, "500": { "description": "Generic server failure. Internal database details must not be returned.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1ErrorEnvelope" } } } } }, "x-financial-iq-safety": { "requiresApiKey": true, "apiKeysAllowed": true, "requiresUserBearerToken": false, "scope": "business.payroll_submissions.read", "requiredApiKeyPermission": "reports", "businessMutation": false, "directFinancialMutation": false, "readOnly": true, "writeLevel": "read", "requiresIdempotencyKey": false, "doesNot": [ "create_submission", "queue_submission", "retry_submission", "cancel_submission", "submit_payroll", "calculate_payroll", "export_bank_file", "move_money" ], "redactions": [ "request_payload", "response_payload", "created_by", "internal_actor_ids" ], "auditedEndpoint": "v1/business/companies/{company_id}/payroll-submissions" }, "x-implementation": { "edgeFunction": "supabase/functions/financial-data-api/index.ts", "tables": [ "payroll_submissions" ], "handler": "handleV1BusinessPayrollSubmissions" } } }, "/v1/business/companies/{company_id}/payroll-submissions/{payroll_submission_id}": { "get": { "tags": [ "Business" ], "operationId": "getBusinessPayrollSubmission", "summary": "Get business payroll submission", "description": "Returns one payroll RTI/NEST submission status record for an accessible business company. This route is read-only and does not expose raw request or response payloads.", "security": [ { "ApiKeyAuth": [] } ], "parameters": [ { "name": "company_id", "in": "path", "required": true, "description": "Business company id.", "schema": { "type": "string", "format": "uuid" } }, { "name": "payroll_submission_id", "in": "path", "required": true, "description": "Payroll submission id.", "schema": { "type": "string", "format": "uuid" } }, { "$ref": "#/components/parameters/RequestId" } ], "responses": { "200": { "description": "Business payroll submission returned.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BusinessPayrollSubmissionDetailResponse" } } } }, "400": { "description": "The company_id or payroll_submission_id path parameter is invalid.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1ErrorEnvelope" } } } }, "401": { "description": "Missing, invalid, expired or inactive API key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LegacyErrorResponse" } } } }, "403": { "description": "The API key does not have reports permission, or the master key is not allowed to access the company.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1ErrorEnvelope" } } } }, "404": { "description": "Business payroll submission not found.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1ErrorEnvelope" } } } }, "405": { "description": "Only GET is allowed for this route.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1ErrorEnvelope" } } } }, "500": { "description": "Generic server failure. Internal database details must not be returned.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1ErrorEnvelope" } } } } }, "x-financial-iq-safety": { "requiresApiKey": true, "apiKeysAllowed": true, "requiresUserBearerToken": false, "scope": "business.payroll_submissions.read", "requiredApiKeyPermission": "reports", "businessMutation": false, "directFinancialMutation": false, "readOnly": true, "writeLevel": "read", "requiresIdempotencyKey": false, "doesNot": [ "create_submission", "queue_submission", "retry_submission", "cancel_submission", "submit_payroll", "calculate_payroll", "export_bank_file", "move_money" ], "redactions": [ "request_payload", "response_payload", "created_by", "internal_actor_ids" ], "auditedEndpoint": "v1/business/companies/{company_id}/payroll-submissions/{payroll_submission_id}" }, "x-implementation": { "edgeFunction": "supabase/functions/financial-data-api/index.ts", "tables": [ "payroll_submissions" ], "handler": "handleV1BusinessPayrollSubmissionDetail" } } }, "/v1/business/companies/{company_id}/p11d-benefits": { "get": { "tags": [ "Business" ], "operationId": "listBusinessP11DBenefits", "summary": "List business P11D benefits", "description": "Lists P11D benefit records for one accessible business company. This route is read-only and does not create benefits, change review status or submit P11D/EXB filings.", "security": [ { "ApiKeyAuth": [] } ], "parameters": [ { "name": "company_id", "in": "path", "required": true, "description": "Business company id.", "schema": { "type": "string", "format": "uuid" } }, { "$ref": "#/components/parameters/RequestId" }, { "name": "tax_year", "in": "query", "required": false, "description": "Optional P11D tax year filter in YYYY/YY format, such as 2025/26.", "schema": { "type": "string", "pattern": "^\\d{4}/\\d{2}$" } }, { "name": "employee_id", "in": "query", "required": false, "description": "Optional payroll employee id filter.", "schema": { "type": "string", "format": "uuid" } }, { "name": "benefit_type", "in": "query", "required": false, "description": "Optional benefit type filter, such as company_car or medical_insurance.", "schema": { "type": "string" } }, { "name": "status", "in": "query", "required": false, "description": "Optional P11D benefit status filter.", "schema": { "type": "string", "enum": [ "draft", "reviewed", "excluded" ] } }, { "name": "limit", "in": "query", "required": false, "description": "Maximum records to return, capped at 100.", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 50 } }, { "name": "offset", "in": "query", "required": false, "description": "Zero-based pagination offset.", "schema": { "type": "integer", "minimum": 0, "default": 0 } } ], "responses": { "200": { "description": "Business P11D benefits returned.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BusinessP11DBenefitListResponse" } } } }, "400": { "description": "The company_id path parameter or query filters are invalid.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1ErrorEnvelope" } } } }, "401": { "description": "Missing, invalid, expired or inactive API key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LegacyErrorResponse" } } } }, "403": { "description": "The API key does not have reports permission, or the master key is not allowed to access the company.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1ErrorEnvelope" } } } }, "404": { "description": "Business company not found.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1ErrorEnvelope" } } } }, "405": { "description": "Only GET is allowed for this route.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1ErrorEnvelope" } } } }, "500": { "description": "Generic server failure. Internal database details must not be returned.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1ErrorEnvelope" } } } } }, "x-financial-iq-safety": { "requiresApiKey": true, "apiKeysAllowed": true, "requiresUserBearerToken": false, "scope": "business.p11d_benefits.read", "requiredApiKeyPermission": "reports", "businessMutation": false, "directFinancialMutation": false, "readOnly": true, "writeLevel": "read", "requiresIdempotencyKey": false, "doesNot": [ "create_p11d_benefit", "update_p11d_benefit", "delete_p11d_benefit", "review_p11d_benefit", "submit_p11d", "submit_exb", "calculate_payroll", "export_bank_file", "move_money" ], "redactions": [ "notes", "created_by", "internal_actor_ids" ], "auditedEndpoint": "v1/business/companies/{company_id}/p11d-benefits" }, "x-implementation": { "edgeFunction": "supabase/functions/financial-data-api/index.ts", "tables": [ "p11d_benefits" ], "handler": "handleV1BusinessP11DBenefits" } } }, "/v1/business/companies/{company_id}/p11d-benefits/{p11d_benefit_id}": { "get": { "tags": [ "Business" ], "operationId": "getBusinessP11DBenefit", "summary": "Get business P11D benefit", "description": "Returns one P11D benefit record for an accessible business company. This route is read-only and does not create benefits, change review status or submit P11D/EXB filings.", "security": [ { "ApiKeyAuth": [] } ], "parameters": [ { "name": "company_id", "in": "path", "required": true, "description": "Business company id.", "schema": { "type": "string", "format": "uuid" } }, { "name": "p11d_benefit_id", "in": "path", "required": true, "description": "P11D benefit id.", "schema": { "type": "string", "format": "uuid" } }, { "$ref": "#/components/parameters/RequestId" } ], "responses": { "200": { "description": "Business P11D benefit returned.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BusinessP11DBenefitDetailResponse" } } } }, "400": { "description": "The company_id or p11d_benefit_id path parameter is invalid.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1ErrorEnvelope" } } } }, "401": { "description": "Missing, invalid, expired or inactive API key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LegacyErrorResponse" } } } }, "403": { "description": "The API key does not have reports permission, or the master key is not allowed to access the company.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1ErrorEnvelope" } } } }, "404": { "description": "Business P11D benefit not found.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1ErrorEnvelope" } } } }, "405": { "description": "Only GET is allowed for this route.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1ErrorEnvelope" } } } }, "500": { "description": "Generic server failure. Internal database details must not be returned.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1ErrorEnvelope" } } } } }, "x-financial-iq-safety": { "requiresApiKey": true, "apiKeysAllowed": true, "requiresUserBearerToken": false, "scope": "business.p11d_benefits.read", "requiredApiKeyPermission": "reports", "businessMutation": false, "directFinancialMutation": false, "readOnly": true, "writeLevel": "read", "requiresIdempotencyKey": false, "doesNot": [ "create_p11d_benefit", "update_p11d_benefit", "delete_p11d_benefit", "review_p11d_benefit", "submit_p11d", "submit_exb", "calculate_payroll", "export_bank_file", "move_money" ], "redactions": [ "notes", "created_by", "internal_actor_ids" ], "auditedEndpoint": "v1/business/companies/{company_id}/p11d-benefits/{p11d_benefit_id}" }, "x-implementation": { "edgeFunction": "supabase/functions/financial-data-api/index.ts", "tables": [ "p11d_benefits" ], "handler": "handleV1BusinessP11DBenefitDetail" } } }, "/v1/business/companies/{company_id}/cis-subcontractors": { "get": { "tags": [ "Business" ], "operationId": "listBusinessCISSubcontractors", "summary": "List business CIS subcontractors", "description": "Lists CIS subcontractor verification records for one accessible business company. This route is read-only and does not expose UTRs, HMRC verification numbers or internal notes.", "security": [ { "ApiKeyAuth": [] } ], "parameters": [ { "name": "company_id", "in": "path", "required": true, "description": "Business company id.", "schema": { "type": "string", "format": "uuid" } }, { "$ref": "#/components/parameters/RequestId" }, { "name": "supplier_id", "in": "query", "required": false, "description": "Optional supplier id filter.", "schema": { "type": "string", "format": "uuid" } }, { "name": "verification_status", "in": "query", "required": false, "description": "Optional CIS verification status filter.", "schema": { "type": "string", "enum": [ "gross", "registered", "unregistered" ] } }, { "name": "limit", "in": "query", "required": false, "description": "Maximum records to return, capped at 100.", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 50 } }, { "name": "offset", "in": "query", "required": false, "description": "Zero-based pagination offset.", "schema": { "type": "integer", "minimum": 0, "default": 0 } } ], "responses": { "200": { "description": "Business CIS subcontractors returned.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BusinessCISSubcontractorListResponse" } } } }, "400": { "description": "The company_id path parameter or query filters are invalid.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1ErrorEnvelope" } } } }, "401": { "description": "Missing, invalid, expired or inactive API key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LegacyErrorResponse" } } } }, "403": { "description": "The API key does not have reports permission, or the master key is not allowed to access the company.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1ErrorEnvelope" } } } }, "404": { "description": "Business company not found.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1ErrorEnvelope" } } } }, "405": { "description": "Only GET is allowed for this route.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1ErrorEnvelope" } } } }, "500": { "description": "Generic server failure. Internal database details must not be returned.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1ErrorEnvelope" } } } } }, "x-financial-iq-safety": { "requiresApiKey": true, "apiKeysAllowed": true, "requiresUserBearerToken": false, "scope": "business.cis_subcontractors.read", "requiredApiKeyPermission": "reports", "businessMutation": false, "directFinancialMutation": false, "readOnly": true, "writeLevel": "read", "requiresIdempotencyKey": false, "doesNot": [ "create_cis_subcontractor", "update_cis_subcontractor", "delete_cis_subcontractor", "verify_subcontractor", "submit_cis_return", "calculate_cis_deduction", "export_bank_file", "move_money" ], "redactions": [ "utr", "verification_number", "notes", "created_by", "internal_actor_ids" ], "auditedEndpoint": "v1/business/companies/{company_id}/cis-subcontractors" }, "x-implementation": { "edgeFunction": "supabase/functions/financial-data-api/index.ts", "tables": [ "cis_subcontractors" ], "handler": "handleV1BusinessCISSubcontractors" } } }, "/v1/business/companies/{company_id}/cis-subcontractors/{cis_subcontractor_id}": { "get": { "tags": [ "Business" ], "operationId": "getBusinessCISSubcontractor", "summary": "Get business CIS subcontractor", "description": "Returns one CIS subcontractor verification record for an accessible business company. This route is read-only and does not expose UTRs, HMRC verification numbers or internal notes.", "security": [ { "ApiKeyAuth": [] } ], "parameters": [ { "name": "company_id", "in": "path", "required": true, "description": "Business company id.", "schema": { "type": "string", "format": "uuid" } }, { "name": "cis_subcontractor_id", "in": "path", "required": true, "description": "CIS subcontractor id.", "schema": { "type": "string", "format": "uuid" } }, { "$ref": "#/components/parameters/RequestId" } ], "responses": { "200": { "description": "Business CIS subcontractor returned.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BusinessCISSubcontractorDetailResponse" } } } }, "400": { "description": "The company_id or cis_subcontractor_id path parameter is invalid.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1ErrorEnvelope" } } } }, "401": { "description": "Missing, invalid, expired or inactive API key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LegacyErrorResponse" } } } }, "403": { "description": "The API key does not have reports permission, or the master key is not allowed to access the company.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1ErrorEnvelope" } } } }, "404": { "description": "Business CIS subcontractor not found.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1ErrorEnvelope" } } } }, "405": { "description": "Only GET is allowed for this route.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1ErrorEnvelope" } } } }, "500": { "description": "Generic server failure. Internal database details must not be returned.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1ErrorEnvelope" } } } } }, "x-financial-iq-safety": { "requiresApiKey": true, "apiKeysAllowed": true, "requiresUserBearerToken": false, "scope": "business.cis_subcontractors.read", "requiredApiKeyPermission": "reports", "businessMutation": false, "directFinancialMutation": false, "readOnly": true, "writeLevel": "read", "requiresIdempotencyKey": false, "doesNot": [ "create_cis_subcontractor", "update_cis_subcontractor", "delete_cis_subcontractor", "verify_subcontractor", "submit_cis_return", "calculate_cis_deduction", "export_bank_file", "move_money" ], "redactions": [ "utr", "verification_number", "notes", "created_by", "internal_actor_ids" ], "auditedEndpoint": "v1/business/companies/{company_id}/cis-subcontractors/{cis_subcontractor_id}" }, "x-implementation": { "edgeFunction": "supabase/functions/financial-data-api/index.ts", "tables": [ "cis_subcontractors" ], "handler": "handleV1BusinessCISSubcontractorDetail" } } }, "/v1/business/companies/{company_id}/cis-deductions": { "get": { "tags": [ "Business" ], "operationId": "listBusinessCISDeductions", "summary": "List business CIS deductions", "description": "Lists CIS deduction records for one accessible business company. This route is read-only and does not calculate deductions, edit payment records or submit CIS returns.", "security": [ { "ApiKeyAuth": [] } ], "parameters": [ { "name": "company_id", "in": "path", "required": true, "description": "Business company id.", "schema": { "type": "string", "format": "uuid" } }, { "$ref": "#/components/parameters/RequestId" }, { "name": "subcontractor_id", "in": "query", "required": false, "description": "Optional CIS subcontractor id filter.", "schema": { "type": "string", "format": "uuid" } }, { "name": "supplier_id", "in": "query", "required": false, "description": "Optional supplier id filter.", "schema": { "type": "string", "format": "uuid" } }, { "name": "tax_month", "in": "query", "required": false, "description": "Optional CIS tax month filter in YYYY-MM format.", "schema": { "type": "string", "pattern": "^\\d{4}-(0[1-9]|1[0-2])$" } }, { "name": "status", "in": "query", "required": false, "description": "Optional CIS deduction status filter.", "schema": { "type": "string", "enum": [ "draft", "reviewed", "submitted" ] } }, { "name": "payment_date_from", "in": "query", "required": false, "description": "Optional lower bound for payment_date.", "schema": { "type": "string", "format": "date" } }, { "name": "payment_date_to", "in": "query", "required": false, "description": "Optional upper bound for payment_date.", "schema": { "type": "string", "format": "date" } }, { "name": "limit", "in": "query", "required": false, "description": "Maximum records to return, capped at 100.", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 50 } }, { "name": "offset", "in": "query", "required": false, "description": "Zero-based pagination offset.", "schema": { "type": "integer", "minimum": 0, "default": 0 } } ], "responses": { "200": { "description": "Business CIS deductions returned.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BusinessCISDeductionListResponse" } } } }, "400": { "description": "The company_id path parameter or query filters are invalid.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1ErrorEnvelope" } } } }, "401": { "description": "Missing, invalid, expired or inactive API key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LegacyErrorResponse" } } } }, "403": { "description": "The API key does not have reports permission, or the master key is not allowed to access the company.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1ErrorEnvelope" } } } }, "404": { "description": "Business company not found.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1ErrorEnvelope" } } } }, "405": { "description": "Only GET is allowed for this route.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1ErrorEnvelope" } } } }, "500": { "description": "Generic server failure. Internal database details must not be returned.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1ErrorEnvelope" } } } } }, "x-financial-iq-safety": { "requiresApiKey": true, "apiKeysAllowed": true, "requiresUserBearerToken": false, "scope": "business.cis_deductions.read", "requiredApiKeyPermission": "reports", "businessMutation": false, "directFinancialMutation": false, "readOnly": true, "writeLevel": "read", "requiresIdempotencyKey": false, "doesNot": [ "create_cis_deduction", "update_cis_deduction", "delete_cis_deduction", "review_cis_deduction", "submit_cis_return", "recalculate_cis_deduction", "export_bank_file", "move_money" ], "redactions": [ "notes", "created_by", "internal_actor_ids" ], "auditedEndpoint": "v1/business/companies/{company_id}/cis-deductions" }, "x-implementation": { "edgeFunction": "supabase/functions/financial-data-api/index.ts", "tables": [ "cis_deductions" ], "handler": "handleV1BusinessCISDeductions" } } }, "/v1/business/companies/{company_id}/cis-deductions/{cis_deduction_id}": { "get": { "tags": [ "Business" ], "operationId": "getBusinessCISDeduction", "summary": "Get business CIS deduction", "description": "Returns one CIS deduction record for an accessible business company. This route is read-only and does not calculate deductions, edit payment records or submit CIS returns.", "security": [ { "ApiKeyAuth": [] } ], "parameters": [ { "name": "company_id", "in": "path", "required": true, "description": "Business company id.", "schema": { "type": "string", "format": "uuid" } }, { "name": "cis_deduction_id", "in": "path", "required": true, "description": "CIS deduction id.", "schema": { "type": "string", "format": "uuid" } }, { "$ref": "#/components/parameters/RequestId" } ], "responses": { "200": { "description": "Business CIS deduction returned.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BusinessCISDeductionDetailResponse" } } } }, "400": { "description": "The company_id or cis_deduction_id path parameter is invalid.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1ErrorEnvelope" } } } }, "401": { "description": "Missing, invalid, expired or inactive API key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LegacyErrorResponse" } } } }, "403": { "description": "The API key does not have reports permission, or the master key is not allowed to access the company.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1ErrorEnvelope" } } } }, "404": { "description": "Business CIS deduction not found.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1ErrorEnvelope" } } } }, "405": { "description": "Only GET is allowed for this route.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1ErrorEnvelope" } } } }, "500": { "description": "Generic server failure. Internal database details must not be returned.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1ErrorEnvelope" } } } } }, "x-financial-iq-safety": { "requiresApiKey": true, "apiKeysAllowed": true, "requiresUserBearerToken": false, "scope": "business.cis_deductions.read", "requiredApiKeyPermission": "reports", "businessMutation": false, "directFinancialMutation": false, "readOnly": true, "writeLevel": "read", "requiresIdempotencyKey": false, "doesNot": [ "create_cis_deduction", "update_cis_deduction", "delete_cis_deduction", "review_cis_deduction", "submit_cis_return", "recalculate_cis_deduction", "export_bank_file", "move_money" ], "redactions": [ "notes", "created_by", "internal_actor_ids" ], "auditedEndpoint": "v1/business/companies/{company_id}/cis-deductions/{cis_deduction_id}" }, "x-implementation": { "edgeFunction": "supabase/functions/financial-data-api/index.ts", "tables": [ "cis_deductions" ], "handler": "handleV1BusinessCISDeductionDetail" } } }, "/v1/business/companies/{company_id}/payroll-employees": { "get": { "tags": [ "Business" ], "operationId": "listBusinessPayrollEmployees", "summary": "List business payroll employees", "description": "Lists safe payroll employee directory records for one accessible business company. This route is read-only: it does not create, update or delete employees, calculate payroll, submit RTI, submit pension files, export bank files or move money.", "security": [ { "ApiKeyAuth": [] } ], "parameters": [ { "name": "company_id", "in": "path", "required": true, "description": "Business company id.", "schema": { "type": "string", "format": "uuid" } }, { "$ref": "#/components/parameters/RequestId" }, { "name": "employee_code", "in": "query", "required": false, "description": "Optional employee code filter.", "schema": { "type": "string" } }, { "name": "employment_status", "in": "query", "required": false, "description": "Optional employment status filter.", "schema": { "type": "string", "enum": [ "draft", "active", "leaver", "paused" ] } }, { "name": "pay_frequency", "in": "query", "required": false, "description": "Optional pay frequency filter.", "schema": { "type": "string", "enum": [ "weekly", "fortnightly", "four_weekly", "monthly" ] } }, { "name": "start_date_from", "in": "query", "required": false, "description": "Optional inclusive lower bound for employment start date.", "schema": { "type": "string", "format": "date" } }, { "name": "start_date_to", "in": "query", "required": false, "description": "Optional inclusive upper bound for employment start date.", "schema": { "type": "string", "format": "date" } }, { "name": "leave_date_from", "in": "query", "required": false, "description": "Optional inclusive lower bound for employment leave date.", "schema": { "type": "string", "format": "date" } }, { "name": "leave_date_to", "in": "query", "required": false, "description": "Optional inclusive upper bound for employment leave date.", "schema": { "type": "string", "format": "date" } }, { "name": "limit", "in": "query", "required": false, "description": "Maximum records to return, capped at 100.", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 50 } }, { "name": "offset", "in": "query", "required": false, "description": "Zero-based pagination offset.", "schema": { "type": "integer", "minimum": 0, "default": 0 } } ], "responses": { "200": { "description": "Business payroll employees returned.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BusinessPayrollEmployeeListResponse" } } } }, "400": { "description": "The company_id path parameter or query filters are invalid.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1ErrorEnvelope" } } } }, "401": { "description": "Missing, invalid, expired or inactive API key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LegacyErrorResponse" } } } }, "403": { "description": "The API key does not have reports permission, or the master key is not allowed to access the company.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1ErrorEnvelope" } } } }, "404": { "description": "Business company not found.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1ErrorEnvelope" } } } }, "405": { "description": "Only GET is allowed for this route.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1ErrorEnvelope" } } } }, "500": { "description": "Generic server failure. Internal database details must not be returned.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1ErrorEnvelope" } } } } }, "x-financial-iq-safety": { "requiresApiKey": true, "apiKeysAllowed": true, "requiresUserBearerToken": false, "scope": "business.payroll_employees.read", "requiredApiKeyPermission": "reports", "businessMutation": false, "directFinancialMutation": false, "readOnly": true, "writeLevel": "read", "requiresIdempotencyKey": false, "doesNot": [ "create_employee", "update_employee", "delete_employee", "calculate_payroll", "submit_rti", "submit_pension_file", "export_bank_file", "move_money" ], "redactions": [ "date_of_birth", "national_insurance_number_encrypted", "bank_account_encrypted", "tax_code", "ni_category", "work_email", "payroll_email", "notes", "created_by", "pay_amounts", "pension_settings", "starter_declaration" ], "auditedEndpoint": "v1/business/companies/{company_id}/payroll-employees" }, "x-implementation": { "edgeFunction": "supabase/functions/financial-data-api/index.ts", "tables": [ "payroll_employees" ], "handler": "handleV1BusinessPayrollEmployees" } } }, "/v1/business/companies/{company_id}/payroll-employees/{payroll_employee_id}": { "get": { "tags": [ "Business" ], "operationId": "getBusinessPayrollEmployee", "summary": "Get business payroll employee", "description": "Returns one safe payroll employee directory record for an accessible business company. This route is read-only and does not expose payroll-sensitive personal data.", "security": [ { "ApiKeyAuth": [] } ], "parameters": [ { "name": "company_id", "in": "path", "required": true, "description": "Business company id.", "schema": { "type": "string", "format": "uuid" } }, { "name": "payroll_employee_id", "in": "path", "required": true, "description": "Payroll employee id.", "schema": { "type": "string", "format": "uuid" } }, { "$ref": "#/components/parameters/RequestId" } ], "responses": { "200": { "description": "Business payroll employee returned.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BusinessPayrollEmployeeDetailResponse" } } } }, "400": { "description": "The company_id or payroll_employee_id path parameter is invalid.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1ErrorEnvelope" } } } }, "401": { "description": "Missing, invalid, expired or inactive API key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LegacyErrorResponse" } } } }, "403": { "description": "The API key does not have reports permission, or the master key is not allowed to access the company.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1ErrorEnvelope" } } } }, "404": { "description": "Business payroll employee not found.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1ErrorEnvelope" } } } }, "405": { "description": "Only GET is allowed for this route.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1ErrorEnvelope" } } } }, "500": { "description": "Generic server failure. Internal database details must not be returned.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1ErrorEnvelope" } } } } }, "x-financial-iq-safety": { "requiresApiKey": true, "apiKeysAllowed": true, "requiresUserBearerToken": false, "scope": "business.payroll_employees.read", "requiredApiKeyPermission": "reports", "businessMutation": false, "directFinancialMutation": false, "readOnly": true, "writeLevel": "read", "requiresIdempotencyKey": false, "doesNot": [ "create_employee", "update_employee", "delete_employee", "calculate_payroll", "submit_rti", "submit_pension_file", "export_bank_file", "move_money" ], "redactions": [ "date_of_birth", "national_insurance_number_encrypted", "bank_account_encrypted", "tax_code", "ni_category", "work_email", "payroll_email", "notes", "created_by", "pay_amounts", "pension_settings", "starter_declaration" ], "auditedEndpoint": "v1/business/companies/{company_id}/payroll-employees/{payroll_employee_id}" }, "x-implementation": { "edgeFunction": "supabase/functions/financial-data-api/index.ts", "tables": [ "payroll_employees" ], "handler": "handleV1BusinessPayrollEmployeeDetail" } } }, "/v1/business/companies/{company_id}/payroll-runs": { "get": { "tags": [ "Business" ], "operationId": "listBusinessPayrollRuns", "summary": "List business payroll runs", "description": "Lists payroll run summaries for one accessible business company. This route is read-only: it does not calculate payroll, approve payroll, finalise payroll, submit RTI, submit pension files, post journals, export bank files or move money.", "security": [ { "ApiKeyAuth": [] } ], "parameters": [ { "name": "company_id", "in": "path", "required": true, "description": "Business company id.", "schema": { "type": "string", "format": "uuid" } }, { "$ref": "#/components/parameters/RequestId" }, { "name": "status", "in": "query", "required": false, "description": "Optional payroll run status filter.", "schema": { "type": "string", "enum": [ "draft", "calculated", "approved", "finalised", "submitted", "accepted", "rejected", "corrected", "cancelled" ] } }, { "name": "correction_of_run_id", "in": "query", "required": false, "description": "Optional original payroll run id when listing correction runs.", "schema": { "type": "string", "format": "uuid" } }, { "name": "period_start_from", "in": "query", "required": false, "description": "Optional inclusive lower bound for period start date.", "schema": { "type": "string", "format": "date" } }, { "name": "period_start_to", "in": "query", "required": false, "description": "Optional inclusive upper bound for period start date.", "schema": { "type": "string", "format": "date" } }, { "name": "pay_date_from", "in": "query", "required": false, "description": "Optional inclusive lower bound for pay date.", "schema": { "type": "string", "format": "date" } }, { "name": "pay_date_to", "in": "query", "required": false, "description": "Optional inclusive upper bound for pay date.", "schema": { "type": "string", "format": "date" } }, { "name": "limit", "in": "query", "required": false, "description": "Maximum records to return, capped at 100.", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 50 } }, { "name": "offset", "in": "query", "required": false, "description": "Zero-based pagination offset.", "schema": { "type": "integer", "minimum": 0, "default": 0 } } ], "responses": { "200": { "description": "Business payroll runs returned.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BusinessPayrollRunListResponse" } } } }, "400": { "description": "The company_id path parameter or query filters are invalid.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1ErrorEnvelope" } } } }, "401": { "description": "Missing, invalid, expired or inactive API key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LegacyErrorResponse" } } } }, "403": { "description": "The API key does not have reports permission, or the master key is not allowed to access the company.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1ErrorEnvelope" } } } }, "404": { "description": "Business company not found.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1ErrorEnvelope" } } } }, "405": { "description": "Only GET is allowed for this route.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1ErrorEnvelope" } } } }, "500": { "description": "Generic server failure. Internal database details must not be returned.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1ErrorEnvelope" } } } } }, "x-financial-iq-safety": { "requiresApiKey": true, "apiKeysAllowed": true, "requiresUserBearerToken": false, "scope": "business.payroll_runs.read", "requiredApiKeyPermission": "reports", "businessMutation": false, "directFinancialMutation": false, "readOnly": true, "writeLevel": "read", "requiresIdempotencyKey": false, "doesNot": [ "calculate_payroll", "approve_payroll", "finalise_payroll", "submit_rti", "submit_pension_file", "post_journal", "export_bank_file", "move_money" ], "redactions": [ "notes", "approved_by", "created_by", "calculation_snapshot", "payroll_run_employees", "employee_bank_details", "national_insurance_number_encrypted", "tax_code", "raw_payroll_payloads" ], "auditedEndpoint": "v1/business/companies/{company_id}/payroll-runs" }, "x-implementation": { "edgeFunction": "supabase/functions/financial-data-api/index.ts", "tables": [ "payroll_runs" ], "handler": "handleV1BusinessPayrollRuns" } } }, "/v1/business/companies/{company_id}/payroll-runs/{payroll_run_id}": { "get": { "tags": [ "Business" ], "operationId": "getBusinessPayrollRun", "summary": "Get one business payroll run", "description": "Returns one payroll run summary for an accessible business company. Inaccessible payroll runs are returned as not found. This route is read-only and does not calculate, approve, finalise, submit or post payroll.", "security": [ { "ApiKeyAuth": [] } ], "parameters": [ { "name": "company_id", "in": "path", "required": true, "description": "Business company id.", "schema": { "type": "string", "format": "uuid" } }, { "name": "payroll_run_id", "in": "path", "required": true, "description": "Payroll run id to fetch.", "schema": { "type": "string", "format": "uuid" } }, { "$ref": "#/components/parameters/RequestId" } ], "responses": { "200": { "description": "Business payroll run returned.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BusinessPayrollRunDetailResponse" } } } }, "400": { "description": "The company_id or payroll_run_id path parameter is invalid.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1ErrorEnvelope" } } } }, "401": { "description": "Missing, invalid, expired or inactive API key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LegacyErrorResponse" } } } }, "403": { "description": "The API key does not have reports permission, or the master key is not allowed to access the company.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1ErrorEnvelope" } } } }, "404": { "description": "Business payroll run not found.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1ErrorEnvelope" } } } }, "405": { "description": "Only GET is allowed for this route.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1ErrorEnvelope" } } } }, "500": { "description": "Generic server failure. Internal database details must not be returned.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1ErrorEnvelope" } } } } }, "x-financial-iq-safety": { "requiresApiKey": true, "apiKeysAllowed": true, "requiresUserBearerToken": false, "scope": "business.payroll_runs.read", "requiredApiKeyPermission": "reports", "businessMutation": false, "directFinancialMutation": false, "readOnly": true, "writeLevel": "read", "requiresIdempotencyKey": false, "doesNot": [ "calculate_payroll", "approve_payroll", "finalise_payroll", "submit_rti", "submit_pension_file", "post_journal", "export_bank_file", "move_money" ], "redactions": [ "notes", "approved_by", "created_by", "calculation_snapshot", "payroll_run_employees", "employee_bank_details", "national_insurance_number_encrypted", "tax_code", "raw_payroll_payloads" ], "auditedEndpoint": "v1/business/companies/{company_id}/payroll-runs/{payroll_run_id}" }, "x-implementation": { "edgeFunction": "supabase/functions/financial-data-api/index.ts", "tables": [ "payroll_runs" ], "handler": "handleV1BusinessPayrollRunDetail" } } }, "/v1/business/companies/{company_id}/payroll-payables": { "get": { "tags": [ "Business" ], "operationId": "listBusinessPayrollPayables", "summary": "List business payroll payables", "description": "Lists payroll payment obligations from finalised pay runs for one accessible business company. This route is read-only: it does not record payroll payments, initiate bank payments, export bank files, post journals, reverse payments, submit RTI, submit pension files or move money.", "security": [ { "ApiKeyAuth": [] } ], "parameters": [ { "name": "company_id", "in": "path", "required": true, "description": "Business company id.", "schema": { "type": "string", "format": "uuid" } }, { "$ref": "#/components/parameters/RequestId" }, { "name": "payroll_run_id", "in": "query", "required": false, "description": "Optional payroll run id filter.", "schema": { "type": "string", "format": "uuid" } }, { "name": "employee_id", "in": "query", "required": false, "description": "Optional payroll employee id filter.", "schema": { "type": "string", "format": "uuid" } }, { "name": "payable_type", "in": "query", "required": false, "description": "Optional payroll payable type filter.", "schema": { "type": "string", "enum": [ "net_wages", "paye_nic", "pension" ] } }, { "name": "status", "in": "query", "required": false, "description": "Optional payroll payable status filter.", "schema": { "type": "string", "enum": [ "unpaid", "paid", "cancelled" ] } }, { "name": "due_from", "in": "query", "required": false, "description": "Optional inclusive lower bound for due date.", "schema": { "type": "string", "format": "date" } }, { "name": "due_to", "in": "query", "required": false, "description": "Optional inclusive upper bound for due date.", "schema": { "type": "string", "format": "date" } }, { "name": "include_archived", "in": "query", "required": false, "description": "Include archived payroll payment obligations. Defaults to false.", "schema": { "type": "boolean", "default": false } }, { "name": "limit", "in": "query", "required": false, "description": "Maximum records to return, capped at 100.", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 50 } }, { "name": "offset", "in": "query", "required": false, "description": "Zero-based pagination offset.", "schema": { "type": "integer", "minimum": 0, "default": 0 } } ], "responses": { "200": { "description": "Business payroll payables returned.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BusinessPayrollPayableListResponse" } } } }, "400": { "description": "The company_id path parameter or query filters are invalid.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1ErrorEnvelope" } } } }, "401": { "description": "Missing, invalid, expired or inactive API key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LegacyErrorResponse" } } } }, "403": { "description": "The API key does not have reports permission, or the master key is not allowed to access the company.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1ErrorEnvelope" } } } }, "404": { "description": "Business company not found.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1ErrorEnvelope" } } } }, "405": { "description": "Only GET is allowed for this route.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1ErrorEnvelope" } } } }, "500": { "description": "Generic server failure. Internal database details must not be returned.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1ErrorEnvelope" } } } } }, "x-financial-iq-safety": { "requiresApiKey": true, "apiKeysAllowed": true, "requiresUserBearerToken": false, "scope": "business.payroll_payables.read", "requiredApiKeyPermission": "reports", "businessMutation": false, "directFinancialMutation": false, "readOnly": true, "writeLevel": "read", "requiresIdempotencyKey": false, "doesNot": [ "record_payroll_payment", "initiate_bank_payment", "export_bank_file", "post_journal", "reverse_payment", "submit_rti", "submit_pension_file", "move_money" ], "redactions": [ "bank_account_encrypted", "national_insurance_number_encrypted", "tax_code", "work_email", "payroll_email", "date_of_birth", "notes", "created_by", "archived_by", "payment_reversed_by", "calculation_snapshot", "raw_payroll_payloads" ], "auditedEndpoint": "v1/business/companies/{company_id}/payroll-payables" }, "x-implementation": { "edgeFunction": "supabase/functions/financial-data-api/index.ts", "tables": [ "payroll_payables", "payroll_runs", "payroll_employees" ], "handler": "handleV1BusinessPayrollPayables" } } }, "/v1/business/companies/{company_id}/payroll-payables/{payroll_payable_id}": { "get": { "tags": [ "Business" ], "operationId": "getBusinessPayrollPayable", "summary": "Get one business payroll payable", "description": "Returns one payroll payment obligation from an accessible business company. Inaccessible payroll payables are returned as not found. This route is read-only and does not record payroll payments, initiate bank payments, post journals or move money.", "security": [ { "ApiKeyAuth": [] } ], "parameters": [ { "name": "company_id", "in": "path", "required": true, "description": "Business company id.", "schema": { "type": "string", "format": "uuid" } }, { "name": "payroll_payable_id", "in": "path", "required": true, "description": "Payroll payable id to fetch.", "schema": { "type": "string", "format": "uuid" } }, { "$ref": "#/components/parameters/RequestId" } ], "responses": { "200": { "description": "Business payroll payable returned.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BusinessPayrollPayableDetailResponse" } } } }, "400": { "description": "The company_id or payroll_payable_id path parameter is invalid.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1ErrorEnvelope" } } } }, "401": { "description": "Missing, invalid, expired or inactive API key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LegacyErrorResponse" } } } }, "403": { "description": "The API key does not have reports permission, or the master key is not allowed to access the company.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1ErrorEnvelope" } } } }, "404": { "description": "Business payroll payable not found.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1ErrorEnvelope" } } } }, "405": { "description": "Only GET is allowed for this route.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1ErrorEnvelope" } } } }, "500": { "description": "Generic server failure. Internal database details must not be returned.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1ErrorEnvelope" } } } } }, "x-financial-iq-safety": { "requiresApiKey": true, "apiKeysAllowed": true, "requiresUserBearerToken": false, "scope": "business.payroll_payables.read", "requiredApiKeyPermission": "reports", "businessMutation": false, "directFinancialMutation": false, "readOnly": true, "writeLevel": "read", "requiresIdempotencyKey": false, "doesNot": [ "record_payroll_payment", "initiate_bank_payment", "export_bank_file", "post_journal", "reverse_payment", "submit_rti", "submit_pension_file", "move_money" ], "redactions": [ "bank_account_encrypted", "national_insurance_number_encrypted", "tax_code", "work_email", "payroll_email", "date_of_birth", "notes", "created_by", "archived_by", "payment_reversed_by", "calculation_snapshot", "raw_payroll_payloads" ], "auditedEndpoint": "v1/business/companies/{company_id}/payroll-payables/{payroll_payable_id}" }, "x-implementation": { "edgeFunction": "supabase/functions/financial-data-api/index.ts", "tables": [ "payroll_payables", "payroll_runs", "payroll_employees" ], "handler": "handleV1BusinessPayrollPayableDetail" } } }, "/v1/business/companies/{company_id}/purchase-invoices": { "get": { "tags": [ "Business" ], "operationId": "listBusinessPurchaseInvoices", "summary": "List business purchase invoices", "description": "Lists purchase invoices for an accessible business company. This route is read-only and supports bill review workflows without creating or posting bills.", "security": [ { "ApiKeyAuth": [] } ], "parameters": [ { "name": "company_id", "in": "path", "required": true, "description": "Business company id.", "schema": { "type": "string", "format": "uuid" } }, { "$ref": "#/components/parameters/RequestId" }, { "name": "status", "in": "query", "required": false, "description": "Optional purchase invoice status filter.", "schema": { "type": "string" } }, { "name": "supplier_id", "in": "query", "required": false, "description": "Optional supplier id filter.", "schema": { "type": "string", "format": "uuid" } }, { "name": "from_date", "in": "query", "required": false, "description": "Inclusive invoice-date lower bound in YYYY-MM-DD format.", "schema": { "type": "string", "format": "date" } }, { "name": "to_date", "in": "query", "required": false, "description": "Inclusive invoice-date upper bound in YYYY-MM-DD format.", "schema": { "type": "string", "format": "date" } }, { "name": "limit", "in": "query", "required": false, "description": "Maximum number of purchase invoices to return. Values are clamped between 1 and 200.", "schema": { "type": "integer", "minimum": 1, "maximum": 200, "default": 100 } }, { "name": "offset", "in": "query", "required": false, "description": "Zero-based offset for paginating purchase invoice results.", "schema": { "type": "integer", "minimum": 0, "default": 0 } } ], "responses": { "200": { "description": "Accessible business purchase invoices returned.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1BusinessPurchaseInvoiceListResponse" } } } }, "400": { "description": "The company_id, supplier_id or date filter is invalid.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1ErrorEnvelope" } } } }, "401": { "description": "Missing, invalid, expired or inactive API key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LegacyErrorResponse" } } } }, "403": { "description": "The API key does not have invoice read permission, or the master key is not allowed to access the company.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1ErrorEnvelope" } } } }, "404": { "description": "Business company not found.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1ErrorEnvelope" } } } }, "405": { "description": "Only GET is allowed for this route.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1ErrorEnvelope" } } } }, "500": { "description": "Generic server failure. Internal database details must not be returned.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1ErrorEnvelope" } } } } }, "x-financial-iq-safety": { "requiresApiKey": true, "apiKeysAllowed": true, "requiresUserBearerToken": false, "scope": "business.purchase_invoices.read", "requiredApiKeyPermission": "invoices", "businessMutation": false, "directFinancialMutation": false, "writeLevel": "read", "requiresIdempotencyKey": false, "auditedEndpoint": "v1/business/companies/{company_id}/purchase-invoices" }, "x-implementation": { "edgeFunction": "supabase/functions/financial-data-api/index.ts", "handler": "handleV1BusinessPurchaseInvoices", "tests": [ "supabase/functions/financial-data-api/invoice_idempotency.test.ts" ] } }, "post": { "tags": [ "Business" ], "operationId": "createBusinessPurchaseInvoice", "summary": "Create draft business purchase invoice", "description": "Creates a draft supplier bill for an accessible business company. The route requires invoice permission and an Idempotency-Key header. It validates linked supplier, account, project, fund, document and cost-centre references against the requested company. It does not approve, post to ledger, pay, submit tax, send documents or make bank payments.", "security": [ { "ApiKeyAuth": [] } ], "parameters": [ { "name": "company_id", "in": "path", "required": true, "description": "Business company id.", "schema": { "type": "string", "format": "uuid" } }, { "$ref": "#/components/parameters/RequestId" }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BusinessPurchaseInvoiceCreateRequest" }, "examples": { "supplierBill": { "summary": "Draft supplier bill", "value": { "supplier_id": "9f2db3dc-55bd-4f50-b6e7-19e8f5f0c6d6", "supplier_invoice_number": "SUP-2026-001", "invoice_date": "2026-07-07", "due_date": "2026-08-06", "currency": "GBP", "document_required": true, "line_items": [ { "description": "Accounting software subscription", "quantity": 1, "unit_price": 120, "vat_rate": 20 } ] } } } } } }, "responses": { "201": { "description": "Draft business purchase invoice created, or an identical idempotent request replayed.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" }, "X-FIQ-Idempotency-Replayed": { "$ref": "#/components/headers/IdempotencyReplayed" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1BusinessPurchaseInvoiceCreateResponse" } } } }, "400": { "description": "Invalid JSON, missing or invalid idempotency key, invalid company_id, or invalid request body.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1ErrorEnvelope" } } } }, "401": { "description": "Missing, invalid, expired or inactive API key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LegacyErrorResponse" } } } }, "403": { "description": "The API key does not have invoice permission or has no owner for creation.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1ErrorEnvelope" } } } }, "404": { "description": "Business company not found.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1ErrorEnvelope" } } } }, "405": { "description": "Only GET and POST are allowed for this route.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1ErrorEnvelope" } } } }, "409": { "description": "The same idempotency key was reused with a different request body.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1ErrorEnvelope" } } } }, "500": { "description": "Generic server failure. Internal database details must not be returned.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1ErrorEnvelope" } } } } }, "x-financial-iq-safety": { "requiresApiKey": true, "scope": "business.purchase_invoices.create", "requiredPermission": "invoices", "businessMutation": true, "directFinancialMutation": false, "writeLevel": "draft", "requiresIdempotencyKey": true, "auditedEndpoint": "v1/business/companies/{company_id}/purchase-invoices", "forbiddenInThisRoute": [ "approve purchase invoice", "post to ledger", "pay supplier", "file VAT", "file CT600", "file Companies House accounts", "make bank payment", "send document", "close accounting period" ] }, "x-implementation": { "edgeFunction": "supabase/functions/financial-data-api/index.ts", "handler": "createV1BusinessPurchaseInvoice", "tests": [ "supabase/functions/financial-data-api/invoice_idempotency.test.ts" ], "databaseMigration": "supabase/migrations/20260707205803_api_purchase_invoice_atomic_wrapper.sql" } } }, "/v1/business/companies/{company_id}/purchase-invoices/{purchase_invoice_id}": { "get": { "tags": [ "Business" ], "operationId": "getBusinessPurchaseInvoice", "summary": "Get one business purchase invoice", "description": "Returns one purchase invoice for an accessible business company. Inaccessible purchase invoices are returned as not found.", "security": [ { "ApiKeyAuth": [] } ], "parameters": [ { "name": "company_id", "in": "path", "required": true, "description": "Business company id.", "schema": { "type": "string", "format": "uuid" } }, { "name": "purchase_invoice_id", "in": "path", "required": true, "description": "Business purchase invoice id to fetch.", "schema": { "type": "string", "format": "uuid" } }, { "$ref": "#/components/parameters/RequestId" } ], "responses": { "200": { "description": "Accessible business purchase invoice returned.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1BusinessPurchaseInvoiceResponse" } } } }, "400": { "description": "The company_id or purchase_invoice_id path parameter is not a valid UUID.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1ErrorEnvelope" } } } }, "401": { "description": "Missing, invalid, expired or inactive API key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LegacyErrorResponse" } } } }, "403": { "description": "The API key does not have invoice read permission, or the master key is not allowed to access the company.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1ErrorEnvelope" } } } }, "404": { "description": "Business purchase invoice not found.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1ErrorEnvelope" } } } }, "405": { "description": "Only GET is allowed for this route.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1ErrorEnvelope" } } } }, "500": { "description": "Generic server failure. Internal database details must not be returned.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1ErrorEnvelope" } } } } }, "x-financial-iq-safety": { "requiresApiKey": true, "apiKeysAllowed": true, "requiresUserBearerToken": false, "scope": "business.purchase_invoices.read", "requiredApiKeyPermission": "invoices", "businessMutation": false, "directFinancialMutation": false, "writeLevel": "read", "requiresIdempotencyKey": false, "auditedEndpoint": "v1/business/companies/{company_id}/purchase-invoices/{purchase_invoice_id}" }, "x-implementation": { "edgeFunction": "supabase/functions/financial-data-api/index.ts", "handler": "handleV1BusinessPurchaseInvoiceDetail", "tests": [ "supabase/functions/financial-data-api/invoice_idempotency.test.ts" ] } } }, "/v1/business/companies/{company_id}/purchase-invoices/{purchase_invoice_id}/submit": { "post": { "tags": [ "Business" ], "operationId": "submitBusinessPurchaseInvoiceForApproval", "summary": "Submit business purchase invoice for approval", "description": "Creates a pending approval request for a draft supplier bill in a business company. The route requires invoice and approval-workflow permissions plus an Idempotency-Key header. It does not approve, post to ledger, pay, file tax, send documents, create direct journals or make bank payments.", "security": [ { "ApiKeyAuth": [] } ], "parameters": [ { "name": "company_id", "in": "path", "required": true, "description": "Business company id.", "schema": { "type": "string", "format": "uuid" } }, { "name": "purchase_invoice_id", "in": "path", "required": true, "description": "Draft business purchase invoice id to submit for approval.", "schema": { "type": "string", "format": "uuid" } }, { "$ref": "#/components/parameters/RequestId" }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PurchaseInvoiceApprovalRequest" }, "examples": { "readyForApproval": { "summary": "Supplier bill approval request", "value": { "reason": "Supplier bill is ready for approval" } } } } } }, "responses": { "202": { "description": "Approval request created, an existing pending approval returned, or an identical idempotent request replayed.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" }, "X-FIQ-Idempotency-Replayed": { "$ref": "#/components/headers/IdempotencyReplayed" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1PurchaseInvoiceApprovalRequestResponse" } } } }, "400": { "description": "Invalid JSON, invalid company_id or purchase_invoice_id path parameter, or missing/invalid idempotency key.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LegacyErrorResponse" } } } }, "401": { "description": "Missing, invalid, expired or inactive API key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LegacyErrorResponse" } } } }, "403": { "description": "The API key does not have invoice or approval-workflow permission.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LegacyErrorResponse" } } } }, "404": { "description": "Business purchase invoice not found.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LegacyErrorResponse" } } } }, "405": { "description": "Only POST is allowed for this route.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LegacyErrorResponse" } } } }, "409": { "description": "The purchase invoice is not draft, idempotency key was reused with a changed body, or no purchase invoice approval workflow is configured.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LegacyErrorResponse" } } } }, "500": { "description": "Generic server failure. Internal database or provider details must not be returned.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1ErrorEnvelope" } } } } }, "x-financial-iq-safety": { "requiresApiKey": true, "scope": "business.purchase_invoices.approval", "requiredPermissions": [ "invoices", "approval_workflow" ], "businessMutation": true, "directFinancialMutation": false, "writeLevel": "human_approval", "requiresIdempotencyKey": true, "auditedEndpoint": "v1/business/companies/{company_id}/purchase-invoices/{purchase_invoice_id}/submit", "createsApprovalRequest": true, "directExecution": false, "forbiddenInThisRoute": [ "approve purchase invoice immediately", "post to ledger", "pay supplier", "file VAT", "file CT600", "file Companies House accounts", "make bank payment", "send document", "close accounting period" ] }, "x-implementation": { "edgeFunction": "supabase/functions/financial-data-api/index.ts", "handler": "handleV1BusinessPurchaseInvoiceSubmitApproval", "databaseFunction": "public.create_purchase_invoice_approval_api_v1_atomic", "activationGate": "FINANCIAL_API_V1_GUARDED_PURCHASE_INVOICE_SUBMIT_ENABLED", "atomicAuditAfterActivation": true, "masterKeyAllowlistSupported": true, "missingGuardedBridgeBehavior": "fail_closed_503", "tests": [ "supabase/functions/financial-data-api/invoice_idempotency.test.ts", "supabase/functions/financial-data-api/v1_openapi_contract.test.ts", "supabase/tests/api_business_purchase_invoice_submit_hardening.sql", "scripts/run-api-purchase-invoice-submit-concurrency.mjs" ] } } }, "/v1/business/companies/{company_id}/purchase-invoices/{purchase_invoice_id}/void": { "post": { "tags": [ "Business" ], "operationId": "voidBusinessPurchaseInvoice", "summary": "Void an unpaid business purchase invoice", "description": "Voids an unpaid non-draft supplier bill in a business company through the existing guarded purchase invoice void workflow. The route requires invoice permission plus an Idempotency-Key header and a reason. It posts reversal effects where applicable and does not delete the bill, pay suppliers, refund money, file tax, send documents or make bank payments.", "security": [ { "ApiKeyAuth": [] } ], "parameters": [ { "name": "company_id", "in": "path", "required": true, "description": "Business company id.", "schema": { "type": "string", "format": "uuid" } }, { "name": "purchase_invoice_id", "in": "path", "required": true, "description": "Unpaid non-draft business purchase invoice id to void.", "schema": { "type": "string", "format": "uuid" } }, { "$ref": "#/components/parameters/RequestId" }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BusinessPurchaseInvoiceVoidRequest" }, "examples": { "raisedInError": { "summary": "Supplier bill void reason", "value": { "reason": "Supplier bill raised in error" } } } } } }, "responses": { "200": { "description": "Purchase invoice voided, an existing void returned, or an identical idempotent request replayed.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" }, "X-FIQ-Idempotency-Replayed": { "$ref": "#/components/headers/IdempotencyReplayed" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1BusinessPurchaseInvoiceVoidResponse" } } } }, "400": { "description": "The request body, Idempotency-Key or path parameter is invalid.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "The API key lacks invoice permission or owner context.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "The company or purchase invoice was not found for this API key.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "405": { "description": "Only POST is allowed for this route.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "409": { "description": "The purchase invoice cannot be voided from its current state, has payment activity, or failed a guarded reversal check.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Generic server failure. Internal database details must not be returned.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "x-financial-iq-safety": { "writeLevel": "accounting_reversal", "requiresIdempotencyKey": true, "requiredApiKeyPermission": "invoices", "scope": "business.purchase_invoices.void", "auditedEndpoint": "v1/business/companies/{company_id}/purchase-invoices/{purchase_invoice_id}/void", "directExecution": true, "moneyMovementPerformed": false, "paymentRefundPerformed": false, "taxFilingPerformed": false }, "x-implementation": { "handler": "handleV1BusinessPurchaseInvoiceVoid", "databaseFunction": "public.void_purchase_invoice_api_v1_atomic", "activationGate": "FINANCIAL_API_V1_GUARDED_PURCHASE_INVOICE_VOID_ENABLED", "atomicAuditAfterActivation": true, "masterKeyAllowlistSupported": true, "missingGuardedBridgeBehavior": "fail_closed_503", "tests": [ "supabase/functions/financial-data-api/invoice_idempotency.test.ts", "supabase/functions/financial-data-api/v1_openapi_contract.test.ts", "supabase/tests/api_business_purchase_invoice_void_hardening.sql", "scripts/run-api-purchase-invoice-void-concurrency.mjs" ] } } }, "/v1/business/companies/{company_id}/supplier-payment-runs": { "get": { "tags": [ "Business" ], "operationId": "listBusinessSupplierPaymentRuns", "summary": "List business supplier payment runs", "description": "Lists supplier payment runs for one accessible business company. This route is read-only: it does not create payment runs, submit approvals, export files, initiate bank payments, mark bills as paid, post journals, reconcile bank transactions or move money.", "security": [ { "ApiKeyAuth": [] } ], "parameters": [ { "name": "company_id", "in": "path", "required": true, "description": "Business company id.", "schema": { "type": "string", "format": "uuid" } }, { "$ref": "#/components/parameters/RequestId" }, { "name": "status", "in": "query", "required": false, "description": "Optional supplier payment run status filter.", "schema": { "type": "string", "enum": [ "draft", "submitted", "approved", "cancelled", "exported", "executing", "completed", "partially_failed" ] } }, { "name": "provider", "in": "query", "required": false, "description": "Optional payment provider label filter.", "schema": { "type": "string", "maxLength": 80 } }, { "name": "scheduled_from", "in": "query", "required": false, "description": "Inclusive scheduled-payment-date lower bound.", "schema": { "type": "string", "format": "date" } }, { "name": "scheduled_to", "in": "query", "required": false, "description": "Inclusive scheduled-payment-date upper bound.", "schema": { "type": "string", "format": "date" } }, { "name": "limit", "in": "query", "required": false, "description": "Maximum records to return, capped at 100.", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 50 } }, { "name": "offset", "in": "query", "required": false, "description": "Zero-based pagination offset.", "schema": { "type": "integer", "minimum": 0, "default": 0 } } ], "responses": { "200": { "description": "Business supplier payment runs returned.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1BusinessSupplierPaymentRunListResponse" } } } }, "400": { "description": "The path or query parameters are invalid.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1ErrorEnvelope" } } } }, "401": { "description": "Missing, invalid, expired or inactive API key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LegacyErrorResponse" } } } }, "403": { "description": "The API key does not have suppliers or invoices permission, or the master key is not allowed to access the company.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1ErrorEnvelope" } } } }, "404": { "description": "Business company not found.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1ErrorEnvelope" } } } }, "405": { "description": "Only GET is allowed for this route.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1ErrorEnvelope" } } } }, "500": { "description": "Generic server failure. Internal database details must not be returned.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1ErrorEnvelope" } } } } }, "x-financial-iq-safety": { "requiresApiKey": true, "apiKeysAllowed": true, "requiresUserBearerToken": false, "scope": "business.supplier_payment_runs.read", "requiredAnyPermission": [ "suppliers", "invoices" ], "businessMutation": false, "directFinancialMutation": false, "writeLevel": "read", "requiresIdempotencyKey": false, "auditedEndpoint": "v1/business/companies/{company_id}/supplier-payment-runs", "doesNot": [ "create_payment_run", "add_payment_run_item", "remove_payment_run_item", "submit_payment_run", "approve_payment_run", "cancel_payment_run", "export_payment_run", "initiate_bank_payment", "mark_bill_paid", "post_journal", "reconcile_bank_transaction", "move_money" ] }, "x-implementation": { "edgeFunction": "supabase/functions/financial-data-api/index.ts", "handler": "handleV1BusinessSupplierPaymentRuns", "tables": [ "supplier_payment_runs" ] } }, "post": { "tags": [ "Business" ], "operationId": "createBusinessSupplierPaymentRun", "summary": "Create draft business supplier payment run", "description": "Creates a draft supplier payment run from approved, unpaid or partly paid supplier bills for an accessible business company. The route requires supplier or invoice permission and an Idempotency-Key header. It derives payable amounts from the selected bills and existing payments. It does not submit the run, approve it, export it, initiate bank payments, mark bills paid, post journals, reconcile bank transactions or move money.", "security": [ { "ApiKeyAuth": [] } ], "parameters": [ { "name": "company_id", "in": "path", "required": true, "description": "Business company id.", "schema": { "type": "string", "format": "uuid" } }, { "$ref": "#/components/parameters/RequestId" }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BusinessSupplierPaymentRunCreateRequest" }, "examples": { "draftRun": { "summary": "Draft supplier payment run", "value": { "purchase_invoice_ids": [ "48484848-4848-4848-8848-484848484850" ], "scheduled_payment_date": "2026-08-10", "notes": "Prepared by finance agent" } } } } } }, "responses": { "201": { "description": "Draft supplier payment run created, or an identical idempotent request replayed.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" }, "X-FIQ-Idempotency-Replayed": { "$ref": "#/components/headers/IdempotencyReplayed" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1BusinessSupplierPaymentRunCreateResponse" } } } }, "400": { "description": "Invalid JSON, invalid company_id, invalid request body, missing or invalid idempotency key, selected bills outside the company, selected bills are not payable, or mixed currencies.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1ErrorEnvelope" } } } }, "401": { "description": "Missing, invalid, expired or inactive API key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LegacyErrorResponse" } } } }, "403": { "description": "The API key does not have supplier or invoice permission, or has no owner for creation.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1ErrorEnvelope" } } } }, "404": { "description": "Business company not found.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1ErrorEnvelope" } } } }, "405": { "description": "Only GET and POST are allowed for this route.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1ErrorEnvelope" } } } }, "409": { "description": "One or more selected supplier bills are already in an active supplier payment run, or the idempotency key was reused with a different request body.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1ErrorEnvelope" } } } }, "500": { "description": "Unexpected error while creating the draft supplier payment run. Internal database details are not returned.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1ErrorEnvelope" } } } } }, "x-financial-iq-safety": { "requiresApiKey": true, "apiKeysAllowed": true, "requiresUserBearerToken": false, "scope": "business.supplier_payment_runs.create", "requiredAnyPermission": [ "suppliers", "invoices" ], "businessMutation": true, "directFinancialMutation": false, "writeLevel": "draft", "requiresIdempotencyKey": true, "auditedEndpoint": "v1/business/companies/{company_id}/supplier-payment-runs", "forbiddenInThisRoute": [ "submit_payment_run", "approve_payment_run", "cancel_payment_run", "export_payment_run", "initiate_bank_payment", "mark_bill_paid", "post_journal", "reconcile_bank_transaction", "move_money", "write_bank_provider_reference", "write_open_banking_payment_id", "return_supplier_bank_details" ] }, "x-implementation": { "edgeFunction": "supabase/functions/financial-data-api/index.ts", "handler": "createV1BusinessSupplierPaymentRun", "tests": [ "supabase/functions/financial-data-api/invoice_idempotency.test.ts", "supabase/functions/financial-data-api/v1_openapi_contract.test.ts" ], "tables": [ "supplier_payment_runs", "supplier_payment_run_items", "purchase_invoices", "purchase_payments" ] } } }, "/v1/business/companies/{company_id}/supplier-payment-runs/{supplier_payment_run_id}": { "get": { "tags": [ "Business" ], "operationId": "getBusinessSupplierPaymentRun", "summary": "Get one business supplier payment run", "description": "Returns one supplier payment run and its included bill items for an accessible business company. Inaccessible runs are returned as not found. This route is read-only and does not execute payments or update bill payment state.", "security": [ { "ApiKeyAuth": [] } ], "parameters": [ { "name": "company_id", "in": "path", "required": true, "description": "Business company id.", "schema": { "type": "string", "format": "uuid" } }, { "name": "supplier_payment_run_id", "in": "path", "required": true, "description": "Supplier payment run id to fetch.", "schema": { "type": "string", "format": "uuid" } }, { "$ref": "#/components/parameters/RequestId" } ], "responses": { "200": { "description": "Business supplier payment run returned.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1BusinessSupplierPaymentRunResponse" } } } }, "400": { "description": "The company_id or supplier_payment_run_id path parameter is invalid.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1ErrorEnvelope" } } } }, "401": { "description": "Missing, invalid, expired or inactive API key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LegacyErrorResponse" } } } }, "403": { "description": "The API key does not have suppliers or invoices permission, or the master key is not allowed to access the company.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1ErrorEnvelope" } } } }, "404": { "description": "Business supplier payment run not found.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1ErrorEnvelope" } } } }, "405": { "description": "Only GET is allowed for this route.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1ErrorEnvelope" } } } }, "500": { "description": "Generic server failure. Internal database details must not be returned.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1ErrorEnvelope" } } } } }, "x-financial-iq-safety": { "requiresApiKey": true, "apiKeysAllowed": true, "requiresUserBearerToken": false, "scope": "business.supplier_payment_runs.read", "requiredAnyPermission": [ "suppliers", "invoices" ], "businessMutation": false, "directFinancialMutation": false, "writeLevel": "read", "requiresIdempotencyKey": false, "auditedEndpoint": "v1/business/companies/{company_id}/supplier-payment-runs/{supplier_payment_run_id}", "doesNot": [ "create_payment_run", "add_payment_run_item", "remove_payment_run_item", "submit_payment_run", "approve_payment_run", "cancel_payment_run", "export_payment_run", "initiate_bank_payment", "mark_bill_paid", "post_journal", "reconcile_bank_transaction", "move_money" ] }, "x-implementation": { "edgeFunction": "supabase/functions/financial-data-api/index.ts", "handler": "handleV1BusinessSupplierPaymentRunDetail", "tables": [ "supplier_payment_runs", "supplier_payment_run_items" ] } } }, "/v1/business/companies/{company_id}/supplier-payment-runs/{supplier_payment_run_id}/execution-requests": { "post": { "tags": ["Business"], "operationId": "createBusinessSupplierPaymentExecutionRequest", "summary": "Request approval to start an approved supplier payment run", "description": "Creates a short-lived, one-use handoff for a signed-in Financial IQ user to start the existing Yapily payment flow for an already-approved supplier payment run. The API does not receive bank credentials or initiate the provider payment directly.", "security": [{"ApiKeyAuth": []}], "parameters": [ {"name": "company_id", "in": "path", "required": true, "schema": {"type": "string", "format": "uuid"}}, {"name": "supplier_payment_run_id", "in": "path", "required": true, "schema": {"type": "string", "format": "uuid"}}, {"$ref": "#/components/parameters/RequestId"}, {"name": "Idempotency-Key", "in": "header", "required": true, "schema": {"type": "string", "minLength": 1}} ], "requestBody": {"required": true, "content": {"application/json": {"schema": {"type": "object", "required": ["bank_account_id"], "properties": {"bank_account_id": {"type": "string", "format": "uuid"}}}}}}, "responses": {"201": {"description": "Execution approval handoff created."}, "400": {"description": "Invalid request or missing idempotency key."}, "403": {"description": "Missing supplier payment, approval or bank account permission."}, "404": {"description": "Payment run not found."}, "409": {"description": "Run is not approved or bank account is not payment-enabled."}}, "x-financial-iq-safety": { "requiresApiKey": true, "requiresUserBearerToken": false, "scope": "business.supplier_payment_execution_requests.create", "requiredAnyPermission": ["suppliers", "invoices"], "requiredAllPermissions": ["approval_workflow", "bank_accounts"], "businessMutation": true, "directFinancialMutation": false, "writeLevel": "auth_request", "requiresIdempotencyKey": true, "auditedEndpoint": "v1/business/companies/{company_id}/supplier-payment-runs/{supplier_payment_run_id}/execution-requests", "doesNot": ["bypass_user_authorisation", "receive_bank_credentials", "initiate_provider_payment", "mark_bill_paid", "post_journal", "move_money"] }, "x-implementation": {"edgeFunction": "supabase/functions/financial-data-api/index.ts", "handler": "handleV1BusinessSupplierPaymentExecutionRequestCreate", "databaseMigration": "supabase/migrations/20260712030000_api_business_supplier_payment_execution_request.sql", "tests": ["supabase/functions/financial-data-api/invoice_idempotency.test.ts"]} } }, "/v1/business/companies/{company_id}/supplier-payment-execution-requests/{request_id}": { "get": { "tags": ["Business"], "operationId": "getBusinessSupplierPaymentExecutionRequest", "summary": "Get supplier payment execution approval status", "description": "Returns the safe status of a supplier payment execution handoff without exposing bank credentials or provider secrets.", "security": [{"ApiKeyAuth": []}], "parameters": [ {"name": "company_id", "in": "path", "required": true, "schema": {"type": "string", "format": "uuid"}}, {"name": "request_id", "in": "path", "required": true, "schema": {"type": "string", "format": "uuid"}}, {"$ref": "#/components/parameters/RequestId"} ], "responses": {"200": {"description": "Execution approval status."}, "404": {"description": "Execution approval request not found."}}, "x-financial-iq-safety": { "requiresApiKey": true, "requiresUserBearerToken": false, "scope": "business.supplier_payment_execution_requests.read", "requiredAllPermissions": ["approval_workflow", "bank_accounts"], "businessMutation": false, "directFinancialMutation": false, "writeLevel": "read", "requiresIdempotencyKey": false, "auditedEndpoint": "v1/business/companies/{company_id}/supplier-payment-execution-requests/{request_id}", "redactedFields": ["api_key_id", "created_by", "bank_credentials", "provider_credentials"] }, "x-implementation": {"edgeFunction": "supabase/functions/financial-data-api/index.ts", "handler": "handleV1BusinessSupplierPaymentExecutionRequestDetail", "tests": ["supabase/functions/financial-data-api/invoice_idempotency.test.ts"]} } }, "/v1/business/companies/{company_id}/supplier-payment-runs/{supplier_payment_run_id}/submit": { "post": { "tags": [ "Business" ], "operationId": "submitBusinessSupplierPaymentRunForApproval", "summary": "Submit business supplier payment run for approval", "description": "Creates a pending approval request for a draft supplier payment run in a business company. The route requires supplier or invoice permission, approval-workflow permission, and an Idempotency-Key header. It marks the run submitted for human approval only. It does not approve the run, export a payment file, initiate bank payments, mark bills paid, post journals, reconcile bank transactions, write provider payment references or move money.", "security": [ { "ApiKeyAuth": [] } ], "parameters": [ { "name": "company_id", "in": "path", "required": true, "description": "Business company id.", "schema": { "type": "string", "format": "uuid" } }, { "name": "supplier_payment_run_id", "in": "path", "required": true, "description": "Draft supplier payment run id to submit for approval.", "schema": { "type": "string", "format": "uuid" } }, { "$ref": "#/components/parameters/RequestId" }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SupplierPaymentRunApprovalRequest" }, "examples": { "readyForApproval": { "summary": "Supplier payment run approval request", "value": { "reason": "Supplier payment run is ready for approval" } } } } } }, "responses": { "202": { "description": "Approval request created, an existing pending approval returned, or an identical idempotent request replayed.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" }, "X-FIQ-Idempotency-Replayed": { "$ref": "#/components/headers/IdempotencyReplayed" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1SupplierPaymentRunApprovalRequestResponse" } } } }, "400": { "description": "Invalid JSON, invalid company_id or supplier_payment_run_id path parameter, or missing/invalid idempotency key.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LegacyErrorResponse" } } } }, "401": { "description": "Missing, invalid, expired or inactive API key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LegacyErrorResponse" } } } }, "403": { "description": "The API key does not have supplier, invoice or approval-workflow permission.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LegacyErrorResponse" } } } }, "404": { "description": "Business supplier payment run not found.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LegacyErrorResponse" } } } }, "405": { "description": "Only POST is allowed for this route.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LegacyErrorResponse" } } } }, "409": { "description": "The supplier payment run is not draft, has no bill items, idempotency key was reused with a changed body, or no supplier payment run approval workflow is configured.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LegacyErrorResponse" } } } }, "500": { "description": "Generic server failure. Internal database or provider details must not be returned.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1ErrorEnvelope" } } } } }, "x-financial-iq-safety": { "requiresApiKey": true, "apiKeysAllowed": true, "requiresUserBearerToken": false, "scope": "business.supplier_payment_runs.approval", "requiredAnyPermission": [ "suppliers", "invoices" ], "requiredPermissions": [ "approval_workflow" ], "businessMutation": true, "directFinancialMutation": false, "writeLevel": "human_approval", "requiresIdempotencyKey": true, "auditedEndpoint": "v1/business/companies/{company_id}/supplier-payment-runs/{supplier_payment_run_id}/submit", "createsApprovalRequest": true, "directExecution": false, "forbiddenInThisRoute": [ "approve_supplier_payment_run_immediately", "export_payment_run", "initiate_bank_payment", "mark_bill_paid", "post_journal", "reconcile_bank_transaction", "move_money", "write_bank_provider_reference", "write_open_banking_payment_id", "return_supplier_bank_details", "close_accounting_period" ] }, "x-implementation": { "edgeFunction": "supabase/functions/financial-data-api/index.ts", "handler": "handleV1BusinessSupplierPaymentRunSubmitApproval", "databaseFunction": "public.create_supplier_payment_run_approval_api_v1_atomic", "activationGate": "FINANCIAL_API_V1_GUARDED_SUPPLIER_PAYMENT_RUN_SUBMIT_ENABLED", "atomicAuditAfterActivation": true, "masterKeyAllowlistSupported": true, "missingGuardedBridgeBehavior": "fail_closed_503", "tests": [ "supabase/functions/financial-data-api/invoice_idempotency.test.ts", "supabase/functions/financial-data-api/v1_openapi_contract.test.ts", "supabase/tests/api_business_supplier_payment_run_submit_hardening.sql", "scripts/run-api-supplier-payment-run-submit-concurrency.mjs" ], "tables": [ "supplier_payment_runs", "approval_requests", "approval_request_actions" ] } } }, "/v1/business/companies/{company_id}/purchase-orders": { "get": { "tags": [ "Business" ], "operationId": "listBusinessPurchaseOrders", "summary": "List business purchase orders", "description": "Lists purchase orders for an accessible business company. This route is read-only and supports procurement review workflows without creating, approving, completing or cancelling purchase orders.", "security": [ { "ApiKeyAuth": [] } ], "parameters": [ { "name": "company_id", "in": "path", "required": true, "description": "Business company id.", "schema": { "type": "string", "format": "uuid" } }, { "$ref": "#/components/parameters/RequestId" }, { "name": "status", "in": "query", "required": false, "description": "Optional purchase order status filter.", "schema": { "type": "string" } }, { "name": "supplier_id", "in": "query", "required": false, "description": "Optional supplier id filter.", "schema": { "type": "string", "format": "uuid" } }, { "name": "project_id", "in": "query", "required": false, "description": "Optional project id filter.", "schema": { "type": "string", "format": "uuid" } }, { "name": "from_date", "in": "query", "required": false, "description": "Inclusive order-date lower bound in YYYY-MM-DD format.", "schema": { "type": "string", "format": "date" } }, { "name": "to_date", "in": "query", "required": false, "description": "Inclusive order-date upper bound in YYYY-MM-DD format.", "schema": { "type": "string", "format": "date" } }, { "name": "expected_delivery_from", "in": "query", "required": false, "description": "Inclusive expected-delivery lower bound in YYYY-MM-DD format.", "schema": { "type": "string", "format": "date" } }, { "name": "expected_delivery_to", "in": "query", "required": false, "description": "Inclusive expected-delivery upper bound in YYYY-MM-DD format.", "schema": { "type": "string", "format": "date" } }, { "name": "limit", "in": "query", "required": false, "description": "Maximum number of purchase orders to return. Values are clamped between 1 and 200.", "schema": { "type": "integer", "minimum": 1, "maximum": 200, "default": 100 } }, { "name": "offset", "in": "query", "required": false, "description": "Zero-based offset for paginating purchase orders results.", "schema": { "type": "integer", "minimum": 0, "default": 0 } } ], "responses": { "200": { "description": "Accessible business purchase orders returned.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1BusinessPurchaseOrderListResponse" } } } }, "400": { "description": "The company_id, supplier_id, project_id or date filter is invalid.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1ErrorEnvelope" } } } }, "401": { "description": "Missing, invalid, expired or inactive API key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LegacyErrorResponse" } } } }, "403": { "description": "The API key does not have project or transaction read permission, or the master key is not allowed to access the company.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1ErrorEnvelope" } } } }, "404": { "description": "Business company not found.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1ErrorEnvelope" } } } }, "405": { "description": "Only GET and POST are allowed for this route.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1ErrorEnvelope" } } } }, "500": { "description": "The API could not fetch purchase orders.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1ErrorEnvelope" } } } } }, "x-financial-iq-safety": { "requiresApiKey": true, "apiKeysAllowed": true, "requiresUserBearerToken": false, "scope": "business.purchase_orders.read", "requiredAnyPermission": [ "projects", "transactions" ], "businessMutation": false, "directFinancialMutation": false, "writeLevel": "read", "requiresIdempotencyKey": false, "auditedEndpoint": "v1/business/companies/{company_id}/purchase-orders" }, "x-implementation": { "edgeFunction": "supabase/functions/financial-data-api/index.ts", "handler": "handleV1BusinessPurchaseOrders", "tests": [ "supabase/functions/financial-data-api/invoice_idempotency.test.ts" ] } }, "post": { "tags": [ "Business" ], "operationId": "createBusinessPurchaseOrder", "summary": "Create draft business purchase order", "description": "Creates a draft purchase order for an accessible business company. The route requires projects permission, with transactions accepted as the existing fallback, and an Idempotency-Key header. It validates linked supplier, project and chart-of-account references against the requested company. It does not submit for approval, approve, complete, receive goods, create a bill, post to ledger, pay, submit tax, send documents or make bank payments.", "security": [ { "ApiKeyAuth": [] } ], "parameters": [ { "name": "company_id", "in": "path", "required": true, "description": "Business company id.", "schema": { "type": "string", "format": "uuid" } }, { "$ref": "#/components/parameters/RequestId" }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BusinessPurchaseOrderCreateRequest" }, "examples": { "supplierOrder": { "summary": "Draft purchase order", "value": { "supplier_id": "9f2db3dc-55bd-4f50-b6e7-19e8f5f0c6d6", "order_date": "2026-07-07", "expected_delivery_date": "2026-07-20", "currency": "GBP", "project_id": "d7d2ef9a-3fbb-4fbf-8c2b-402145f8729b", "line_items": [ { "description": "Laptop stands", "sku": "STAND-001", "quantity": 2, "unit_price": 50, "vat_rate": 20 } ] } } } } } }, "responses": { "201": { "description": "Draft business purchase order created, or an identical idempotent request replayed.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" }, "X-FIQ-Idempotency-Replayed": { "$ref": "#/components/headers/IdempotencyReplayed" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1BusinessPurchaseOrderCreateResponse" } } } }, "400": { "description": "Invalid JSON, missing or invalid idempotency key, invalid company_id, invalid company reference, or invalid request body.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1ErrorEnvelope" } } } }, "401": { "description": "Missing, invalid, expired or inactive API key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LegacyErrorResponse" } } } }, "403": { "description": "The API key does not have project or transaction permission, or has no owner for creation.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1ErrorEnvelope" } } } }, "404": { "description": "Business company not found.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1ErrorEnvelope" } } } }, "405": { "description": "Only GET and POST are allowed for this route.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1ErrorEnvelope" } } } }, "409": { "description": "The same idempotency key was reused with a different request body, or a purchase order number could not be allocated after retries.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1ErrorEnvelope" } } } }, "500": { "description": "Unexpected error while creating the draft purchase order.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1ErrorEnvelope" } } } } }, "x-financial-iq-safety": { "requiresApiKey": true, "apiKeysAllowed": true, "requiresUserBearerToken": false, "scope": "business.purchase_orders.create", "requiredAnyPermission": [ "projects", "transactions" ], "businessMutation": true, "directFinancialMutation": false, "writeLevel": "draft", "requiresIdempotencyKey": true, "auditedEndpoint": "v1/business/companies/{company_id}/purchase-orders", "forbiddenInThisRoute": [ "submit purchase order for approval", "approve purchase order", "complete purchase order", "receive goods", "create supplier bill", "post to ledger", "pay supplier", "file VAT", "file CT600", "file Companies House accounts", "make bank payment", "send document", "close accounting period" ] }, "x-implementation": { "edgeFunction": "supabase/functions/financial-data-api/index.ts", "handler": "createV1BusinessPurchaseOrder", "tests": [ "supabase/functions/financial-data-api/invoice_idempotency.test.ts" ], "databaseMigration": "supabase/migrations/20260707211916_api_purchase_order_public_api_atomic.sql" } } }, "/v1/business/companies/{company_id}/purchase-orders/{purchase_order_id}": { "get": { "tags": [ "Business" ], "operationId": "getBusinessPurchaseOrder", "summary": "Get one business purchase order", "description": "Returns one purchase order for an accessible business company. Inaccessible purchase orders are returned as not found.", "security": [ { "ApiKeyAuth": [] } ], "parameters": [ { "name": "company_id", "in": "path", "required": true, "description": "Business company id.", "schema": { "type": "string", "format": "uuid" } }, { "name": "purchase_order_id", "in": "path", "required": true, "description": "Business purchase order id to fetch.", "schema": { "type": "string", "format": "uuid" } }, { "$ref": "#/components/parameters/RequestId" } ], "responses": { "200": { "description": "Accessible business purchase order returned.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1BusinessPurchaseOrderResponse" } } } }, "400": { "description": "The company_id or purchase_order_id path parameter is not a valid UUID.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1ErrorEnvelope" } } } }, "401": { "description": "Missing, invalid, expired or inactive API key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LegacyErrorResponse" } } } }, "403": { "description": "The API key does not have project or transaction read permission, or the master key is not allowed to access the company.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1ErrorEnvelope" } } } }, "404": { "description": "Business purchase order not found.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1ErrorEnvelope" } } } }, "405": { "description": "Only GET is allowed for this route.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1ErrorEnvelope" } } } }, "500": { "description": "The API could not fetch the purchase order.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1ErrorEnvelope" } } } } }, "x-financial-iq-safety": { "requiresApiKey": true, "apiKeysAllowed": true, "requiresUserBearerToken": false, "scope": "business.purchase_orders.read", "requiredAnyPermission": [ "projects", "transactions" ], "businessMutation": false, "directFinancialMutation": false, "writeLevel": "read", "requiresIdempotencyKey": false, "auditedEndpoint": "v1/business/companies/{company_id}/purchase-orders/{purchase_order_id}" }, "x-implementation": { "edgeFunction": "supabase/functions/financial-data-api/index.ts", "handler": "handleV1BusinessPurchaseOrderDetail", "tests": [ "supabase/functions/financial-data-api/invoice_idempotency.test.ts" ] } } }, "/v1/business/companies/{company_id}/purchase-orders/{purchase_order_id}/submit": { "post": { "tags": [ "Business" ], "operationId": "submitBusinessPurchaseOrderForApproval", "summary": "Submit business purchase order for approval", "description": "Creates a pending approval request for a draft purchase order in a business company. The route requires project or transaction permission, approval-workflow permission, and an Idempotency-Key header. It does not approve, complete, receive goods, create a supplier bill, post to ledger, pay, file tax, send documents or make bank payments.", "security": [ { "ApiKeyAuth": [] } ], "parameters": [ { "name": "company_id", "in": "path", "required": true, "description": "Business company id.", "schema": { "type": "string", "format": "uuid" } }, { "name": "purchase_order_id", "in": "path", "required": true, "description": "Draft business purchase order id to submit for approval.", "schema": { "type": "string", "format": "uuid" } }, { "$ref": "#/components/parameters/RequestId" }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PurchaseOrderApprovalRequest" }, "examples": { "readyForApproval": { "summary": "Purchase order approval request", "value": { "reason": "Purchase order is ready for approval" } } } } } }, "responses": { "202": { "description": "Approval request created, an existing pending approval returned, or an identical idempotent request replayed.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" }, "X-FIQ-Idempotency-Replayed": { "$ref": "#/components/headers/IdempotencyReplayed" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1PurchaseOrderApprovalRequestResponse" } } } }, "400": { "description": "Invalid JSON, invalid company_id or purchase_order_id path parameter, or missing/invalid idempotency key.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LegacyErrorResponse" } } } }, "401": { "description": "Missing, invalid, expired or inactive API key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LegacyErrorResponse" } } } }, "403": { "description": "The API key does not have project, transaction or approval-workflow permission.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LegacyErrorResponse" } } } }, "404": { "description": "Business purchase order not found.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LegacyErrorResponse" } } } }, "405": { "description": "Only POST is allowed for this route.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LegacyErrorResponse" } } } }, "409": { "description": "The purchase order is not draft, idempotency key was reused with a changed body, or no purchase order approval workflow is configured.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LegacyErrorResponse" } } } }, "500": { "description": "Generic server failure. Internal database or provider details must not be returned.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1ErrorEnvelope" } } } } }, "x-financial-iq-safety": { "requiresApiKey": true, "apiKeysAllowed": true, "requiresUserBearerToken": false, "scope": "business.purchase_orders.approval", "requiredAnyPermission": [ "projects", "transactions" ], "requiredPermissions": [ "approval_workflow" ], "businessMutation": true, "directFinancialMutation": false, "writeLevel": "human_approval", "requiresIdempotencyKey": true, "auditedEndpoint": "v1/business/companies/{company_id}/purchase-orders/{purchase_order_id}/submit", "createsApprovalRequest": true, "directExecution": false, "forbiddenInThisRoute": [ "approve purchase order immediately", "complete purchase order", "receive goods", "create supplier bill", "post to ledger", "pay supplier", "file VAT", "file CT600", "file Companies House accounts", "make bank payment", "send document", "close accounting period" ] }, "x-implementation": { "edgeFunction": "supabase/functions/financial-data-api/index.ts", "handler": "handleV1BusinessPurchaseOrderSubmitApproval", "databaseFunction": "public.create_purchase_order_approval_api_v1_atomic", "activationGate": "FINANCIAL_API_V1_GUARDED_PURCHASE_ORDER_SUBMIT_ENABLED", "atomicAuditAfterActivation": true, "masterKeyAllowlistSupported": true, "missingGuardedBridgeBehavior": "fail_closed_503", "tests": [ "supabase/functions/financial-data-api/invoice_idempotency.test.ts", "supabase/functions/financial-data-api/v1_openapi_contract.test.ts", "supabase/tests/api_business_purchase_order_submit_hardening.sql", "scripts/run-api-purchase-order-submit-concurrency.mjs" ] } } }, "/v1/business/companies/{company_id}/expense-claimants": { "get": { "tags": [ "Business" ], "operationId": "listBusinessExpenseClaimants", "summary": "List business expense claimants", "description": "Lists active expense claimants for an accessible business company by default. This route is read-only and does not expose claimant repayment bank details.", "security": [ { "ApiKeyAuth": [] } ], "parameters": [ { "name": "company_id", "in": "path", "required": true, "description": "Business company id.", "schema": { "type": "string", "format": "uuid" } }, { "$ref": "#/components/parameters/RequestId" }, { "name": "search", "in": "query", "required": false, "description": "Optional claimant name search.", "schema": { "type": "string" } }, { "name": "q", "in": "query", "required": false, "description": "Alias for search.", "schema": { "type": "string" } }, { "name": "is_active", "in": "query", "required": false, "description": "Optional active-status filter.", "schema": { "type": "boolean", "default": true } }, { "name": "active", "in": "query", "required": false, "description": "Alias for is_active.", "schema": { "type": "boolean", "default": true } }, { "name": "include_inactive", "in": "query", "required": false, "description": "Set to true to include inactive claimants when no active-status filter is supplied.", "schema": { "type": "boolean", "default": false } }, { "name": "limit", "in": "query", "required": false, "description": "Maximum number of expense claimants to return. Values are clamped between 1 and 200.", "schema": { "type": "integer", "minimum": 1, "maximum": 200, "default": 100 } }, { "name": "offset", "in": "query", "required": false, "description": "Zero-based offset for paginating expense claimants results.", "schema": { "type": "integer", "minimum": 0, "default": 0 } } ], "responses": { "200": { "description": "Accessible business expense claimants returned.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1BusinessExpenseClaimantListResponse" } } } }, "400": { "description": "The company_id path parameter is invalid.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1ErrorEnvelope" } } } }, "401": { "description": "Missing, invalid, expired or inactive API key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LegacyErrorResponse" } } } }, "403": { "description": "The API key does not have invoice read permission, or the master key is not allowed to access the company.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1ErrorEnvelope" } } } }, "404": { "description": "Business company not found.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1ErrorEnvelope" } } } }, "405": { "description": "Only GET and POST are allowed for this route.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1ErrorEnvelope" } } } }, "500": { "description": "The API could not fetch expense claimants.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1ErrorEnvelope" } } } } }, "x-financial-iq-safety": { "requiresApiKey": true, "apiKeysAllowed": true, "requiresUserBearerToken": false, "scope": "business.expense_claimants.read", "requiredApiKeyPermission": "invoices", "businessMutation": false, "directFinancialMutation": false, "writeLevel": "read", "requiresIdempotencyKey": false, "auditedEndpoint": "v1/business/companies/{company_id}/expense-claimants" }, "x-implementation": { "edgeFunction": "supabase/functions/financial-data-api/index.ts", "handler": "handleV1BusinessExpenseClaimants", "tests": [ "supabase/functions/financial-data-api/invoice_idempotency.test.ts" ] } }, "post": { "tags": [ "Business" ], "operationId": "createBusinessExpenseClaimant", "summary": "Create business expense claimant", "description": "Creates a staff, director or volunteer expense claimant for an accessible business company. The route requires invoice permission and an Idempotency-Key header. It only accepts name, email, optional phone and active status; repayment bank details are not accepted by this endpoint.", "security": [ { "ApiKeyAuth": [] } ], "parameters": [ { "name": "company_id", "in": "path", "required": true, "description": "Business company id.", "schema": { "type": "string", "format": "uuid" } }, { "$ref": "#/components/parameters/RequestId" }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BusinessExpenseClaimantCreateRequest" }, "examples": { "claimant": { "summary": "Expense claimant", "value": { "name": "Alex Claimant", "email": "alex.claimant@example.com", "phone": "020 2222 3333", "is_active": true } } } } } }, "responses": { "201": { "description": "Business expense claimant created, or an identical idempotent request replayed.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" }, "X-FIQ-Idempotency-Replayed": { "$ref": "#/components/headers/IdempotencyReplayed" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1BusinessExpenseClaimantCreateResponse" } } } }, "400": { "description": "Invalid JSON, missing or invalid idempotency key, invalid company_id, or invalid request body.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1ErrorEnvelope" } } } }, "401": { "description": "Missing, invalid, expired or inactive API key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LegacyErrorResponse" } } } }, "403": { "description": "The API key does not have invoice permission or has no owner for creation.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1ErrorEnvelope" } } } }, "404": { "description": "Business company not found.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1ErrorEnvelope" } } } }, "405": { "description": "Only GET and POST are allowed for this route.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1ErrorEnvelope" } } } }, "409": { "description": "The claimant email already exists for the company, or the same idempotency key was reused with a different request body.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1ErrorEnvelope" } } } }, "500": { "description": "Unexpected error while creating the expense claimant.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1ErrorEnvelope" } } } } }, "x-financial-iq-safety": { "requiresApiKey": true, "apiKeysAllowed": true, "requiresUserBearerToken": false, "scope": "business.expense_claimants.create", "requiredApiKeyPermission": "invoices", "businessMutation": true, "directFinancialMutation": false, "writeLevel": "configuration", "requiresIdempotencyKey": true, "auditedEndpoint": "v1/business/companies/{company_id}/expense-claimants", "forbiddenInThisRoute": [ "set repayment bank details", "create expense claim", "approve expense claim", "repay claimant", "post to ledger", "make bank payment", "file VAT", "file CT600", "close accounting period" ], "redactedFields": [ "bank_account_name", "bank_account_number", "bank_account_number_ct", "bank_account_number_encrypted", "bank_sort_code", "bank_sort_code_ct", "bank_sort_code_encrypted" ] }, "x-implementation": { "edgeFunction": "supabase/functions/financial-data-api/index.ts", "handler": "createV1BusinessExpenseClaimant", "tests": [ "supabase/functions/financial-data-api/invoice_idempotency.test.ts" ] } } }, "/v1/business/companies/{company_id}/expense-claimants/{expense_claimant_id}": { "get": { "tags": [ "Business" ], "operationId": "getBusinessExpenseClaimant", "summary": "Get one business expense claimant", "description": "Returns one expense claimant for an accessible business company. Inaccessible claimants are returned as not found and bank details are not exposed.", "security": [ { "ApiKeyAuth": [] } ], "parameters": [ { "name": "company_id", "in": "path", "required": true, "description": "Business company id.", "schema": { "type": "string", "format": "uuid" } }, { "name": "expense_claimant_id", "in": "path", "required": true, "description": "Business expense claimant id to fetch.", "schema": { "type": "string", "format": "uuid" } }, { "$ref": "#/components/parameters/RequestId" } ], "responses": { "200": { "description": "Accessible business expense claimant returned.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1BusinessExpenseClaimantResponse" } } } }, "400": { "description": "The company_id or expense_claimant_id path parameter is not a valid UUID.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1ErrorEnvelope" } } } }, "401": { "description": "Missing, invalid, expired or inactive API key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LegacyErrorResponse" } } } }, "403": { "description": "The API key does not have invoice read permission, or the master key is not allowed to access the company.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1ErrorEnvelope" } } } }, "404": { "description": "Business expense claimant not found.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1ErrorEnvelope" } } } }, "405": { "description": "Only GET is allowed for this route.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1ErrorEnvelope" } } } }, "500": { "description": "The API could not fetch the expense claimant.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1ErrorEnvelope" } } } } }, "x-financial-iq-safety": { "requiresApiKey": true, "apiKeysAllowed": true, "requiresUserBearerToken": false, "scope": "business.expense_claimants.read", "requiredApiKeyPermission": "invoices", "businessMutation": false, "directFinancialMutation": false, "writeLevel": "read", "requiresIdempotencyKey": false, "auditedEndpoint": "v1/business/companies/{company_id}/expense-claimants/{expense_claimant_id}" }, "x-implementation": { "edgeFunction": "supabase/functions/financial-data-api/index.ts", "handler": "handleV1BusinessExpenseClaimantDetail", "tests": [ "supabase/functions/financial-data-api/invoice_idempotency.test.ts" ] } }, "patch": { "tags": [ "Business" ], "operationId": "updateBusinessExpenseClaimant", "summary": "Update business expense claimant", "description": "Updates safe claimant profile fields for one accessible business company. This route requires invoice permission and an Idempotency-Key. It does not set repayment bank details, create expense claims, approve claims, repay claimants, post ledger entries, submit tax, close periods or move money.", "security": [ { "ApiKeyAuth": [] } ], "parameters": [ { "name": "company_id", "in": "path", "required": true, "description": "Business company id.", "schema": { "type": "string", "format": "uuid" } }, { "name": "expense_claimant_id", "in": "path", "required": true, "description": "Business expense claimant id to update.", "schema": { "type": "string", "format": "uuid" } }, { "$ref": "#/components/parameters/RequestId" }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BusinessExpenseClaimantUpdateRequest" } } } }, "responses": { "200": { "description": "Business expense claimant updated.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" }, "X-FIQ-Idempotency-Replayed": { "$ref": "#/components/headers/IdempotencyReplayed" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BusinessExpenseClaimantUpdateResponse" } } } }, "400": { "description": "Invalid request body, missing Idempotency-Key, or invalid company_id/expense_claimant_id path parameter.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1ErrorEnvelope" } } } }, "401": { "description": "Missing, invalid, expired or inactive API key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LegacyErrorResponse" } } } }, "403": { "description": "The API key does not have invoices permission.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1ErrorEnvelope" } } } }, "404": { "description": "Business expense claimant not found.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1ErrorEnvelope" } } } }, "405": { "description": "Only GET and PATCH are allowed for this route.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1ErrorEnvelope" } } } }, "409": { "description": "The idempotency key conflicts with a different request body, or the claimant email already exists for this company.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1ErrorEnvelope" } } } }, "500": { "description": "Generic server failure. Internal database details must not be returned.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1ErrorEnvelope" } } } } }, "x-financial-iq-safety": { "requiresApiKey": true, "scope": "business.expense_claimants.update", "requiredApiKeyPermission": "invoices", "directFinancialMutation": false, "businessMutation": true, "writeLevel": "configuration", "requiresIdempotencyKey": true, "auditedEndpoint": "v1/business/companies/{company_id}/expense-claimants/{expense_claimant_id}", "forbiddenFields": [ "id", "company_id", "created_at", "updated_at", "bank_account_name", "bank_account_number", "bank_account_number_ct", "bank_account_number_encrypted", "bank_sort_code", "bank_sort_code_ct", "bank_sort_code_encrypted", "expense_claim_ids", "ledger_entries" ], "forbiddenInThisRoute": [ "set repayment bank details", "create expense claim", "approve expense claim", "repay claimant", "post to ledger", "submit tax", "close accounting period", "make bank payment" ] }, "x-implementation": { "edgeFunction": "supabase/functions/financial-data-api/index.ts", "handler": "updateV1BusinessExpenseClaimant", "tests": [ "supabase/functions/financial-data-api/invoice_idempotency.test.ts" ] } } }, "/v1/business/companies/{company_id}/transactions": { "get": { "tags": [ "Business" ], "operationId": "listBusinessTransactions", "summary": "List business transactions", "description": "Lists bank transactions for an accessible business company. This route is read-only and omits raw bank-feed provider payloads.", "security": [ { "ApiKeyAuth": [] } ], "parameters": [ { "name": "company_id", "in": "path", "required": true, "description": "Business company id.", "schema": { "type": "string", "format": "uuid" } }, { "$ref": "#/components/parameters/RequestId" }, { "name": "bank_account_id", "in": "query", "required": false, "description": "Optional bank account id filter.", "schema": { "type": "string", "format": "uuid" } }, { "name": "category_id", "in": "query", "required": false, "description": "Optional chart of accounts category id filter.", "schema": { "type": "string", "format": "uuid" } }, { "name": "transaction_type", "in": "query", "required": false, "description": "Optional transaction type filter.", "schema": { "type": "string" } }, { "name": "type", "in": "query", "required": false, "description": "Alias for transaction_type.", "schema": { "type": "string" } }, { "name": "posting_status", "in": "query", "required": false, "description": "Optional posting status filter.", "schema": { "type": "string" } }, { "name": "reconciliation_status", "in": "query", "required": false, "description": "Optional reconciliation status filter.", "schema": { "type": "string" } }, { "name": "from_date", "in": "query", "required": false, "description": "Inclusive transaction-date lower bound in YYYY-MM-DD format.", "schema": { "type": "string", "format": "date" } }, { "name": "to_date", "in": "query", "required": false, "description": "Inclusive transaction-date upper bound in YYYY-MM-DD format.", "schema": { "type": "string", "format": "date" } }, { "name": "uncategorised", "in": "query", "required": false, "description": "When true, returns transactions without a chart of accounts category.", "schema": { "type": "boolean" } }, { "name": "limit", "in": "query", "required": false, "description": "Maximum number of transactions to return. Values are clamped between 1 and 200.", "schema": { "type": "integer", "minimum": 1, "maximum": 200, "default": 100 } }, { "name": "offset", "in": "query", "required": false, "description": "Zero-based offset for paginating transaction results.", "schema": { "type": "integer", "minimum": 0, "default": 0 } } ], "responses": { "200": { "description": "Accessible business transactions returned.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1BusinessTransactionListResponse" } } } }, "400": { "description": "The company_id or filter parameter is invalid.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1ErrorEnvelope" } } } }, "401": { "description": "Missing, invalid, expired or inactive API key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LegacyErrorResponse" } } } }, "403": { "description": "The API key does not have transaction read permission, or the master key is not allowed to access the company.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1ErrorEnvelope" } } } }, "404": { "description": "Business company not found.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1ErrorEnvelope" } } } }, "405": { "description": "Only GET is allowed for this route.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1ErrorEnvelope" } } } }, "500": { "description": "Generic server failure. Internal database details must not be returned.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1ErrorEnvelope" } } } } }, "x-financial-iq-safety": { "requiresApiKey": true, "apiKeysAllowed": true, "requiresUserBearerToken": false, "scope": "business.transactions.read", "businessMutation": false, "directFinancialMutation": false, "writeLevel": "read", "requiresIdempotencyKey": false, "auditedEndpoint": "v1/business/companies/{company_id}/transactions", "redactedFields": [ "provider_metadata", "external_transaction_id", "statement_line_id" ] }, "x-implementation": { "edgeFunction": "supabase/functions/financial-data-api/index.ts", "handler": "handleV1BusinessTransactions", "tests": [ "supabase/functions/financial-data-api/invoice_idempotency.test.ts" ] } }, "post": { "tags": [ "Business" ], "operationId": "createBusinessTransaction", "summary": "Create a manual business transaction", "description": "Creates one manual, unposted business bank transaction. This route requires the transactions permission and an Idempotency-Key. It does not import bank-feed data, reconcile statements, post ledger entries, calculate/post VAT, match customers or suppliers, or file tax returns.", "security": [ { "ApiKeyAuth": [] } ], "parameters": [ { "name": "company_id", "in": "path", "required": true, "description": "Business company id.", "schema": { "type": "string", "format": "uuid" } }, { "$ref": "#/components/parameters/RequestId" }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BusinessTransactionCreateRequest" } } } }, "responses": { "201": { "description": "Manual business transaction created, or an identical idempotent request replayed.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" }, "X-FIQ-Idempotency-Replayed": { "$ref": "#/components/headers/IdempotencyReplayed" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BusinessTransactionCreateResponse" } } } }, "400": { "description": "Invalid request body, inaccessible account/category, or missing Idempotency-Key.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1ErrorEnvelope" } } } }, "401": { "description": "Missing or invalid API key.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1ErrorEnvelope" } } } }, "403": { "description": "API key does not have transactions permission.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1ErrorEnvelope" } } } }, "404": { "description": "Company is not accessible to the API key.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1ErrorEnvelope" } } } }, "405": { "description": "Only GET and POST are allowed for this route.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1ErrorEnvelope" } } } } }, "x-financial-iq-safety": { "requiresApiKey": true, "apiKeysAllowed": true, "requiresUserBearerToken": false, "scope": "business.transactions.create", "businessMutation": true, "directFinancialMutation": true, "writeLevel": "manual_transaction_record", "requiresIdempotencyKey": true, "auditedEndpoint": "v1/business/companies/{company_id}/transactions", "forbiddenFields": [ "company_id", "context_type", "external_transaction_id", "provider_metadata", "raw_provider_payload", "statement_line_id", "customer_id", "supplier_id", "project_id", "fund_id", "document_id", "net_amount", "vat_amount", "vat_rate", "posted_journal_id", "posting_status", "reconciliation_status", "is_matched", "matched_transaction_id" ], "doesNot": [ "import_provider_transactions", "connect_bank_feed", "reconcile_statements", "post_ledger_entries", "calculate_or_post_vat", "match_customers_or_suppliers", "file_tax_returns" ] }, "x-implementation": { "edgeFunction": "supabase/functions/financial-data-api/index.ts", "handler": "createV1BusinessTransaction", "tests": [ "supabase/functions/financial-data-api/invoice_idempotency.test.ts" ] } } }, "/v1/business/companies/{company_id}/transactions/{transaction_id}": { "get": { "tags": [ "Business" ], "operationId": "getBusinessTransaction", "summary": "Get one business transaction", "description": "Returns one bank transaction for an accessible business company. Inaccessible transactions are returned as not found.", "security": [ { "ApiKeyAuth": [] } ], "parameters": [ { "name": "company_id", "in": "path", "required": true, "description": "Business company id.", "schema": { "type": "string", "format": "uuid" } }, { "name": "transaction_id", "in": "path", "required": true, "description": "Business bank transaction id to fetch.", "schema": { "type": "string", "format": "uuid" } }, { "$ref": "#/components/parameters/RequestId" } ], "responses": { "200": { "description": "Accessible business transaction returned.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1BusinessTransactionResponse" } } } }, "400": { "description": "The company_id or transaction_id path parameter is not a valid UUID.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1ErrorEnvelope" } } } }, "401": { "description": "Missing, invalid, expired or inactive API key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LegacyErrorResponse" } } } }, "403": { "description": "The API key does not have transaction read permission, or the master key is not allowed to access the company.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1ErrorEnvelope" } } } }, "404": { "description": "Business transaction not found.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1ErrorEnvelope" } } } }, "405": { "description": "Only GET and PATCH are allowed for this route.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1ErrorEnvelope" } } } }, "500": { "description": "Generic server failure. Internal database details must not be returned.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1ErrorEnvelope" } } } } }, "x-financial-iq-safety": { "requiresApiKey": true, "apiKeysAllowed": true, "requiresUserBearerToken": false, "scope": "business.transactions.read", "businessMutation": false, "directFinancialMutation": false, "writeLevel": "read", "requiresIdempotencyKey": false, "auditedEndpoint": "v1/business/companies/{company_id}/transactions/{transaction_id}", "redactedFields": [ "provider_metadata", "external_transaction_id", "statement_line_id" ] }, "x-implementation": { "edgeFunction": "supabase/functions/financial-data-api/index.ts", "handler": "handleV1BusinessTransactionDetail", "tests": [ "supabase/functions/financial-data-api/invoice_idempotency.test.ts" ] } }, "patch": { "tags": [ "Business" ], "operationId": "updateBusinessTransaction", "summary": "Update business transaction metadata", "description": "Updates safe metadata, categorisation, business links and receipt flags on one business bank transaction. This route requires transaction permission and an Idempotency-Key. It cannot change the amount, date, bank account, currency, provider data, reconciliation state, posting state, VAT, ledger entries, tax filing, or move money.", "security": [ { "ApiKeyAuth": [] } ], "parameters": [ { "name": "company_id", "in": "path", "required": true, "description": "Business company id.", "schema": { "type": "string", "format": "uuid" } }, { "name": "transaction_id", "in": "path", "required": true, "description": "Business bank transaction id to fetch.", "schema": { "type": "string", "format": "uuid" } }, { "$ref": "#/components/parameters/RequestId" }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BusinessTransactionUpdateRequest" } } } }, "responses": { "200": { "description": "Business transaction metadata updated.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" }, "X-FIQ-Idempotency-Replayed": { "$ref": "#/components/headers/IdempotencyReplayed" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BusinessTransactionUpdateResponse" } } } }, "400": { "description": "Invalid request body, inaccessible company reference, invalid UUID, or missing Idempotency-Key.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1ErrorEnvelope" } } } }, "401": { "description": "Missing, invalid, expired or inactive API key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LegacyErrorResponse" } } } }, "403": { "description": "The API key does not have transaction update permission, or has no owner for audited writes.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1ErrorEnvelope" } } } }, "404": { "description": "Business transaction not found.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1ErrorEnvelope" } } } }, "405": { "description": "Only GET and PATCH are allowed for this route.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1ErrorEnvelope" } } } }, "500": { "description": "Generic server failure. Internal database details must not be returned.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1ErrorEnvelope" } } } } }, "x-financial-iq-safety": { "requiresApiKey": true, "apiKeysAllowed": true, "requiresUserBearerToken": false, "requiredApiKeyPermission": "transactions", "scope": "business.transactions.update", "businessMutation": true, "directFinancialMutation": false, "writeLevel": "transaction_metadata", "requiresIdempotencyKey": true, "auditedEndpoint": "v1/business/companies/{company_id}/transactions/{transaction_id}", "forbiddenFields": [ "bank_account_id", "transaction_date", "gross_amount", "net_amount", "vat_amount", "vat_rate", "currency", "original_amount", "original_currency", "exchange_rate", "gbp_amount", "balance_after", "transaction_type", "transaction_nature", "direction", "company_id", "context_type", "external_transaction_id", "provider_metadata", "raw_provider_payload", "statement_line_id", "document_id", "categorisation_status", "categorisation_source", "category_uncertain", "reconciliation_status", "reconciliation_method", "is_matched", "matched_transaction_id", "posting_status", "lifecycle_status", "posted_at", "posted_date", "posted_journal_id", "transaction_source", "wallet_name" ], "doesNot": [ "change_transaction_amount", "change_transaction_date", "change_transaction_account", "change_currency", "import_provider_transactions", "connect_bank_feed", "move_money", "reconcile_statements", "post_ledger_entries", "calculate_or_post_vat", "file_tax_returns" ] }, "x-implementation": { "edgeFunction": "supabase/functions/financial-data-api/index.ts", "handler": "updateV1BusinessTransaction", "tests": [ "supabase/functions/financial-data-api/invoice_idempotency.test.ts" ] } } }, "/v1/business/companies/{company_id}/invoices": { "get": { "tags": [ "Business" ], "operationId": "listBusinessInvoices", "summary": "List business invoices", "description": "Lists invoices for an accessible business company. This route is read-only; draft invoice creation remains POST /v1/invoices/drafts.", "security": [ { "ApiKeyAuth": [] } ], "parameters": [ { "name": "company_id", "in": "path", "required": true, "description": "Business company id.", "schema": { "type": "string", "format": "uuid" } }, { "$ref": "#/components/parameters/RequestId" }, { "name": "status", "in": "query", "required": false, "description": "Optional invoice status filter.", "schema": { "type": "string", "maxLength": 80 } }, { "name": "customer_id", "in": "query", "required": false, "description": "Optional customer id filter.", "schema": { "type": "string", "format": "uuid" } }, { "name": "from_date", "in": "query", "required": false, "description": "Optional invoice_date lower bound.", "schema": { "type": "string", "format": "date" } }, { "name": "to_date", "in": "query", "required": false, "description": "Optional invoice_date upper bound.", "schema": { "type": "string", "format": "date" } }, { "name": "limit", "in": "query", "required": false, "description": "Maximum number of invoices to return. Values are clamped between 1 and 200.", "schema": { "type": "integer", "minimum": 1, "maximum": 200, "default": 100 } }, { "name": "offset", "in": "query", "required": false, "description": "Zero-based offset for paginating invoice results.", "schema": { "type": "integer", "minimum": 0, "default": 0 } } ], "responses": { "200": { "description": "Accessible business invoices returned.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1BusinessInvoiceListResponse" } } } }, "400": { "description": "A filter or path parameter is invalid.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1ErrorEnvelope" } } } }, "401": { "description": "Missing, invalid, expired or inactive API key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LegacyErrorResponse" } } } }, "403": { "description": "The API key does not have invoice read permission, or the master key is not allowed to access the company.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1ErrorEnvelope" } } } }, "404": { "description": "Business company not found.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1ErrorEnvelope" } } } }, "405": { "description": "Only GET is allowed for this route.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1ErrorEnvelope" } } } }, "500": { "description": "Generic server failure. Internal database details must not be returned.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1ErrorEnvelope" } } } } }, "x-financial-iq-safety": { "requiresApiKey": true, "scope": "business.invoices.read", "requiredPermission": "invoices", "directFinancialMutation": false, "writeLevel": "read", "requiresIdempotencyKey": false, "auditedEndpoint": "v1/business/companies/{company_id}/invoices" }, "x-implementation": { "edgeFunction": "supabase/functions/financial-data-api/index.ts", "handler": "handleV1BusinessInvoices", "tests": [ "supabase/functions/financial-data-api/invoice_idempotency.test.ts" ] } }, "post": { "tags": [ "Business" ], "operationId": "createBusinessInvoice", "summary": "Create draft business sales invoice", "description": "Creates a draft sales invoice for an accessible business company. The route requires invoice permission and an Idempotency-Key header. It validates customer, revenue account, project and fund references against the requested company. It does not issue, send, delete, file tax, create direct journals or make bank payments.", "security": [ { "ApiKeyAuth": [] } ], "parameters": [ { "name": "company_id", "in": "path", "required": true, "description": "Business company id.", "schema": { "type": "string", "format": "uuid" } }, { "$ref": "#/components/parameters/RequestId" }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DraftInvoiceCreateRequest" }, "examples": { "consultingInvoice": { "summary": "Draft consulting invoice", "value": { "customer_id": "7c3f0d29-5af1-42c1-b8bb-2e4bb3db37e4", "invoice_date": "2026-07-04", "due_date": "2026-07-18", "payment_terms_days": 14, "currency": "GBP", "line_items": [ { "description": "Consulting services", "quantity": 4, "unit_price": 150, "vat_rate": 20, "revenue_account_id": "2db5c0c3-a977-41e9-8e34-a3fd6157de5a" } ] } } } } } }, "responses": { "201": { "description": "Draft business sales invoice created, or an identical idempotent request replayed.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" }, "X-FIQ-Idempotency-Replayed": { "$ref": "#/components/headers/IdempotencyReplayed" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1InvoiceResponse" } } } }, "400": { "description": "Invalid JSON, missing or invalid idempotency key, invalid path parameter, invalid request body, non-draft status or a referenced record that does not belong to the requested company.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LegacyErrorResponse" } } } }, "401": { "description": "Missing, invalid, expired or inactive API key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LegacyErrorResponse" } } } }, "403": { "description": "The API key does not have invoice permission.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1ErrorEnvelope" } } } }, "404": { "description": "Business company not found.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1ErrorEnvelope" } } } }, "405": { "description": "Only GET and POST are allowed for this route.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LegacyErrorResponse" } } } }, "409": { "description": "The same idempotency key was reused with a different request body.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1ErrorEnvelope" } } } }, "500": { "description": "Generic server failure. Internal database or provider details must not be returned.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1ErrorEnvelope" } } } } }, "x-financial-iq-safety": { "requiresApiKey": true, "scope": "business.invoices.create", "requiredPermission": "invoices", "directFinancialMutation": true, "writeLevel": "draft", "requiresIdempotencyKey": true, "auditedEndpoint": "v1/business/companies/{company_id}/invoices", "forbiddenInThisRoute": [ "issue invoice", "send invoice", "delete invoice", "file VAT", "file CT600", "file Companies House accounts", "make bank payment", "create direct journal", "close accounting period" ] }, "x-implementation": { "edgeFunction": "supabase/functions/financial-data-api/index.ts", "handler": "handleV1BusinessInvoices", "tests": [ "supabase/functions/financial-data-api/invoice_idempotency.test.ts" ] } } }, "/v1/business/companies/{company_id}/invoices/{invoice_id}": { "get": { "tags": [ "Business" ], "operationId": "getBusinessInvoice", "summary": "Get one business invoice", "description": "Returns one invoice for an accessible business company. Inaccessible invoice IDs are returned as not found to avoid leaking tenant data.", "security": [ { "ApiKeyAuth": [] } ], "parameters": [ { "name": "company_id", "in": "path", "required": true, "description": "Business company id.", "schema": { "type": "string", "format": "uuid" } }, { "name": "invoice_id", "in": "path", "required": true, "description": "Business invoice id to fetch.", "schema": { "type": "string", "format": "uuid" } }, { "$ref": "#/components/parameters/RequestId" } ], "responses": { "200": { "description": "Business invoice returned.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1BusinessInvoiceResponse" } } } }, "400": { "description": "The company_id or invoice_id path parameter is not a valid UUID.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1ErrorEnvelope" } } } }, "401": { "description": "Missing, invalid, expired or inactive API key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LegacyErrorResponse" } } } }, "403": { "description": "The API key does not have invoice read permission, or the master key is not allowed to access the company.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1ErrorEnvelope" } } } }, "404": { "description": "Business invoice not found.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1ErrorEnvelope" } } } }, "405": { "description": "Only GET and PATCH are allowed for this route.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1ErrorEnvelope" } } } }, "500": { "description": "Generic server failure. Internal database details must not be returned.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1ErrorEnvelope" } } } } }, "x-financial-iq-safety": { "requiresApiKey": true, "scope": "business.invoices.read", "requiredPermission": "invoices", "directFinancialMutation": false, "writeLevel": "read", "requiresIdempotencyKey": false, "auditedEndpoint": "v1/business/companies/{company_id}/invoices/{invoice_id}" }, "x-implementation": { "edgeFunction": "supabase/functions/financial-data-api/index.ts", "handler": "handleV1BusinessInvoiceDetail", "tests": [ "supabase/functions/financial-data-api/invoice_idempotency.test.ts" ] } }, "patch": { "tags": [ "Business" ], "operationId": "updateBusinessDraftInvoice", "summary": "Correct an unpaid draft business invoice", "description": "Updates safe header or line-item fields on an unpaid draft invoice in one audited database transaction. The caller must provide the lock version returned by the latest invoice read. This route does not issue or send the invoice, post accounting entries, file tax or move money.", "security": [ { "ApiKeyAuth": [] } ], "parameters": [ { "name": "company_id", "in": "path", "required": true, "description": "Business company id.", "schema": { "type": "string", "format": "uuid" } }, { "name": "invoice_id", "in": "path", "required": true, "description": "Unpaid draft business invoice id to update.", "schema": { "type": "string", "format": "uuid" } }, { "$ref": "#/components/parameters/RequestId" }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BusinessInvoiceUpdateRequest" } } } }, "responses": { "200": { "description": "Draft invoice updated, or an identical idempotent request replayed.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" }, "X-FIQ-Idempotency-Replayed": { "$ref": "#/components/headers/IdempotencyReplayed" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1BusinessInvoiceUpdateResponse" } } } }, "400": { "description": "The patch body, company references, Idempotency-Key or path parameters are invalid.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1ErrorEnvelope" } } } }, "401": { "description": "Missing, invalid, expired or inactive API key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LegacyErrorResponse" } } } }, "403": { "description": "The API key lacks invoice permission or owner context.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1ErrorEnvelope" } } } }, "404": { "description": "The company or invoice was not found for this API key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1ErrorEnvelope" } } } }, "409": { "description": "The invoice is no longer an unpaid draft or its lock version is stale.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1ErrorEnvelope" } } } }, "500": { "description": "Generic server failure. Internal database details must not be returned.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1ErrorEnvelope" } } } } }, "x-financial-iq-safety": { "requiresApiKey": true, "scope": "business.invoices.update", "requiredPermission": "invoices", "directFinancialMutation": true, "writeLevel": "draft_correction", "requiresIdempotencyKey": true, "requiresExpectedLockVersion": true, "auditedEndpoint": "v1/business/companies/{company_id}/invoices/{invoice_id}", "accountingEntriesPosted": false, "externalSendPerformed": false, "moneyMovementPerformed": false, "taxFilingPerformed": false, "allowedInvoiceStatuses": [ "draft" ], "forbiddenInThisRoute": [ "issue invoice", "send invoice", "delete invoice", "post journal", "file tax", "make bank payment", "close accounting period" ] }, "x-implementation": { "edgeFunction": "supabase/functions/financial-data-api/index.ts", "handler": "updateV1BusinessDraftInvoice", "databaseFunction": "public.replace_draft_invoice_api_atomic", "tests": [ "supabase/functions/financial-data-api/invoice_idempotency.test.ts", "supabase/functions/financial-data-api/v1_openapi_contract.test.ts" ] } } }, "/v1/business/companies/{company_id}/invoices/{invoice_id}/delivery-events": { "get": { "tags": ["Business"], "operationId": "listBusinessInvoiceDeliveryEvents", "summary": "List invoice delivery evidence", "description": "Returns safe, company-scoped delivery history for an issued business invoice. Provider payloads and email content are not returned.", "security": [{"ApiKeyAuth": []}], "parameters": [ {"name": "company_id", "in": "path", "required": true, "schema": {"type": "string", "format": "uuid"}}, {"name": "invoice_id", "in": "path", "required": true, "schema": {"type": "string", "format": "uuid"}}, {"$ref": "#/components/parameters/RequestId"}, {"name": "limit", "in": "query", "required": false, "schema": {"type": "integer", "minimum": 1, "maximum": 200, "default": 100}}, {"name": "offset", "in": "query", "required": false, "schema": {"type": "integer", "minimum": 0, "default": 0}} ], "responses": { "200": {"description": "Delivery evidence returned.", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/V1BusinessInvoiceDeliveryEventListResponse"}}}}, "400": {"description": "Invalid company or invoice id.", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/V1ErrorEnvelope"}}}}, "403": {"description": "The API key lacks invoice permission.", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/V1ErrorEnvelope"}}}}, "404": {"description": "The company or invoice was not found for this API key.", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/V1ErrorEnvelope"}}}}, "500": {"description": "Generic server failure.", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/V1ErrorEnvelope"}}}} }, "x-financial-iq-safety": { "requiresApiKey": true, "scope": "business.invoices.delivery_events.read", "requiredPermission": "invoices", "directFinancialMutation": false, "writeLevel": "read", "requiresIdempotencyKey": false, "auditedEndpoint": "v1/business/companies/{company_id}/invoices/{invoice_id}/delivery-events" }, "x-implementation": { "edgeFunction": "supabase/functions/financial-data-api/index.ts", "handler": "handleV1BusinessInvoiceDeliveryEvents", "tests": ["supabase/functions/financial-data-api/invoice_idempotency.test.ts"] } } }, "/v1/business/companies/{company_id}/invoices/{invoice_id}/issue": { "post": { "tags": [ "Business" ], "operationId": "issueBusinessInvoice", "summary": "Issue a draft business invoice", "description": "Issues a draft invoice in a business company, including signed expense-deduction lines. The route requires an Idempotency-Key header. Its audited mode posts active lines only to the ledger, VAT and inventory through one database transaction with the required audit entry, and rechecks the active API key, invoice permission and company authority, including master-key allowlists. During the migration-first rollout, simple drafts continue through the existing bridge until the activation gate is enabled; corrected drafts with archived line history are rejected before posting. Once enabled, expense-deduction drafts use the audited bridge and an unavailable audited bridge fails closed with 503 and never falls back. The route does not send the invoice externally, file tax, close accounting periods or move money.", "security": [ { "ApiKeyAuth": [] } ], "parameters": [ { "name": "company_id", "in": "path", "required": true, "description": "Business company id.", "schema": { "type": "string", "format": "uuid" } }, { "name": "invoice_id", "in": "path", "required": true, "description": "Draft business invoice id to issue.", "schema": { "type": "string", "format": "uuid" } }, { "$ref": "#/components/parameters/RequestId" }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "responses": { "200": { "description": "Invoice issued, or an identical idempotent request replayed.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" }, "X-FIQ-Idempotency-Replayed": { "$ref": "#/components/headers/IdempotencyReplayed" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1BusinessInvoiceIssueResponse" } } } }, "400": { "description": "The request body, Idempotency-Key or path parameter is invalid.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "The API key lacks invoice permission or owner context.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "The company or invoice was not found for this API key.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "409": { "description": "The invoice cannot be issued from its current state or failed a guarded posting check.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "503": { "description": "Invoice issue is temporarily unavailable because the audited bridge is being activated, or because a corrected draft is blocked during the migration-first rollout.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" }, "Retry-After": { "description": "Suggested delay in seconds before retrying.", "schema": { "type": "integer", "minimum": 0 } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "x-financial-iq-safety": { "writeLevel": "accounting_entry", "requiresIdempotencyKey": true, "requiredApiKeyPermission": "invoices", "scope": "business.invoices.issue", "auditedEndpoint": "v1/business/companies/{company_id}/invoices/{invoice_id}/issue", "directExecution": true, "atomicAudit": false, "atomicAuditAfterActivation": true, "archivedLinesExcluded": true, "allowedLineTypes": [ "sales" ], "masterKeyAllowlistSupported": true, "auditedBridgeReady": true, "activationGate": "FINANCIAL_API_V1_AUDITED_INVOICE_ISSUE_ENABLED", "legacyModeDatabaseFunction": "public.issue_invoice_api_atomic", "legacyModeGuards": [ "reject_archived_line_history", "reject_expense_deduction" ], "missingAuditedBridgeBehavior": "fail_closed_503", "externalSendPerformed": false, "moneyMovementPerformed": false, "taxFilingPerformed": false }, "x-implementation": { "handler": "handleV1BusinessInvoiceIssue", "databaseFunction": "public.issue_invoice_api_v1_atomic" } } }, "/v1/business/companies/{company_id}/invoices/{invoice_id}/void": { "post": { "tags": [ "Business" ], "operationId": "voidBusinessInvoice", "summary": "Void an issued business invoice", "description": "Voids an issued or sent invoice in a business company, including expense-deduction lines. The route requires invoice permission, an Idempotency-Key header and a reason. Its audited mode rechecks the exact active API key and current company authority, including delegated accountants and master-key allowlists, inside the same transaction as the canonical journal, VAT and stock reversal and required API audit. During migration-first rollout, standard company keys continue through the hardened compatibility bridge. Once enabled, expense-deduction voids use the audited bridge and an unavailable audited bridge returns 503 without falling back. The route does not send documents externally, refund payments, file tax, close accounting periods or move money.", "security": [ { "ApiKeyAuth": [] } ], "parameters": [ { "name": "company_id", "in": "path", "required": true, "description": "Business company id.", "schema": { "type": "string", "format": "uuid" } }, { "name": "invoice_id", "in": "path", "required": true, "description": "Issued or sent business invoice id to void.", "schema": { "type": "string", "format": "uuid" } }, { "$ref": "#/components/parameters/RequestId" }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BusinessInvoiceVoidRequest" } } } }, "responses": { "200": { "description": "Invoice voided, an existing void returned, or an identical idempotent request replayed.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" }, "X-FIQ-Idempotency-Replayed": { "$ref": "#/components/headers/IdempotencyReplayed" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1BusinessInvoiceVoidResponse" } } } }, "400": { "description": "The request body, Idempotency-Key or path parameter is invalid.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "The API key lacks invoice permission or owner context.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "The company or invoice was not found for this API key.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "409": { "description": "The invoice cannot be voided from its current state, has payments recorded, or failed a guarded reversal check.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "503": { "description": "Invoice void is temporarily unavailable because the audited bridge is being activated or a master-key request arrived before activation.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" }, "Retry-After": { "description": "Suggested delay in seconds before retrying.", "schema": { "type": "integer", "minimum": 0 } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Generic server failure. Internal database details must not be returned.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "x-financial-iq-safety": { "writeLevel": "accounting_reversal", "requiresIdempotencyKey": true, "requiredApiKeyPermission": "invoices", "scope": "business.invoices.void", "auditedEndpoint": "v1/business/companies/{company_id}/invoices/{invoice_id}/void", "directExecution": true, "atomicAudit": false, "atomicAuditAfterActivation": true, "allowedLineTypes": [ "sales" ], "masterKeyAllowlistSupported": true, "auditedBridgeReady": true, "activationGate": "FINANCIAL_API_V1_AUDITED_INVOICE_VOID_ENABLED", "legacyModeDatabaseFunction": "public.void_invoice_api_atomic", "legacyModeGuards": [ "master_keys_require_activation", "reject_expense_deduction" ], "missingAuditedBridgeBehavior": "fail_closed_503", "externalSendPerformed": false, "moneyMovementPerformed": false, "paymentRefundPerformed": false, "taxFilingPerformed": false }, "x-implementation": { "handler": "handleV1BusinessInvoiceVoid", "databaseFunction": "public.void_invoice_api_v1_atomic" } } }, "/v1/business/companies/{company_id}/invoices/{invoice_id}/send/execute": {"post":{"tags":["Business"],"operationId":"executeBusinessInvoiceSend","summary":"Execute an approved invoice email delivery","description":"Sends an issued invoice through the existing audited email delivery path only when the supplied invoice-specific approval request is approved. This endpoint does not create or approve the request.","security":[{"ApiKeyAuth":[]}],"parameters":[{"$ref":"#/components/parameters/BusinessCompanyId"},{"name":"invoice_id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}},{"$ref":"#/components/parameters/RequestId"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/V1BusinessInvoiceSendExecutionRequest"}}}},"responses":{"200":{"description":"Invoice email delivery executed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/V1BusinessInvoiceSendExecutionResponse"}}}},"400":{"description":"The request or approval_request_id is invalid.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/V1ErrorEnvelope"}}}},"401":{"description":"Missing, invalid, expired or inactive API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/LegacyErrorResponse"}}}},"403":{"description":"The API key lacks invoice, approval or owner authority.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/V1ErrorEnvelope"}}}},"404":{"description":"The company, invoice or approval request is not accessible.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/V1ErrorEnvelope"}}}},"409":{"description":"The invoice approval has not been approved.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/V1ErrorEnvelope"}}}},"500":{"description":"Generic server failure.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/V1ErrorEnvelope"}}}},"502":{"description":"The email provider could not complete delivery.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/V1ErrorEnvelope"}}}},"503":{"description":"Invoice delivery execution is unavailable.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/V1ErrorEnvelope"}}}}},"x-financial-iq-safety":{"requiresApiKey":true,"scope":"business.invoices.send.execute","requiredPermissions":["invoices","approval_workflow"],"businessMutation":true,"directFinancialMutation":false,"providerMutation":true,"writeLevel":"provider_execution","requiresIdempotencyKey":true,"approvalRequired":true,"auditedEndpoint":"v1/business/companies/{company_id}/invoices/{invoice_id}/send/execute","doesNot":["bypass_approval","post_to_ledger","move_money","file_returns"]},"x-implementation":{"edgeFunction":"supabase/functions/financial-data-api/index.ts","handler":"handleV1BusinessInvoiceSendExecution","tests":["supabase/functions/financial-data-api/invoice_idempotency.test.ts"]}}}, "/v1/business/companies/{company_id}/quotes/{quote_id}/delivery-events": {"get":{"tags":["Business"],"operationId":"listBusinessQuoteDeliveryEvents","summary":"List quote delivery evidence","description":"Returns safe, company-scoped delivery history for an issued business quote. Provider payloads and email content are not returned.","security":[{"ApiKeyAuth":[]}],"parameters":[{"name":"company_id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"quote_id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}},{"$ref":"#/components/parameters/RequestId"},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","minimum":1,"maximum":200,"default":100}},{"name":"offset","in":"query","required":false,"schema":{"type":"integer","minimum":0,"default":0}}],"responses":{"200":{"description":"Delivery evidence returned.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/V1BusinessQuoteDeliveryEventListResponse"}}}},"400":{"description":"Invalid company or quote id.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/V1ErrorEnvelope"}}}},"403":{"description":"The API key lacks quote permission.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/V1ErrorEnvelope"}}}},"404":{"description":"The company or quote was not found for this API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/V1ErrorEnvelope"}}}},"500":{"description":"Generic server failure.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/V1ErrorEnvelope"}}}}},"x-financial-iq-safety":{"requiresApiKey":true,"scope":"business.quotes.delivery_events.read","requiredPermission":"quotes","directFinancialMutation":false,"writeLevel":"read","requiresIdempotencyKey":false,"auditedEndpoint":"v1/business/companies/{company_id}/quotes/{quote_id}/delivery-events"},"x-implementation":{"edgeFunction":"supabase/functions/financial-data-api/index.ts","handler":"handleV1BusinessQuoteDeliveryEvents","tests":["supabase/functions/financial-data-api/quote_idempotency.test.ts"]}}}, "/v1/business/companies/{company_id}/quotes/{quote_id}/send/execute": {"post":{"tags":["Business"],"operationId":"executeBusinessQuoteSend","summary":"Execute an approved quote email delivery","description":"Sends an issued quote through the existing audited email delivery path only when the supplied quote-specific approval request is approved. This endpoint does not create or approve the request.","security":[{"ApiKeyAuth":[]}],"parameters":[{"$ref":"#/components/parameters/BusinessCompanyId"},{"name":"quote_id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}},{"$ref":"#/components/parameters/RequestId"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/V1BusinessQuoteSendExecutionRequest"}}}},"responses":{"200":{"description":"Quote email delivery executed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/V1BusinessQuoteSendExecutionResponse"}}}},"400":{"description":"The request or approval_request_id is invalid.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/V1ErrorEnvelope"}}}},"401":{"description":"Missing, invalid, expired or inactive API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/LegacyErrorResponse"}}}},"403":{"description":"The API key lacks quote, approval or owner authority.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/V1ErrorEnvelope"}}}},"404":{"description":"The company, quote or approval request is not accessible.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/V1ErrorEnvelope"}}}},"409":{"description":"The quote approval has not been approved.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/V1ErrorEnvelope"}}}},"500":{"description":"Generic server failure.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/V1ErrorEnvelope"}}}},"502":{"description":"The email provider could not complete delivery.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/V1ErrorEnvelope"}}}},"503":{"description":"Quote delivery execution is unavailable.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/V1ErrorEnvelope"}}}}},"x-financial-iq-safety":{"requiresApiKey":true,"scope":"business.quotes.send.execute","requiredPermissions":["quotes","approval_workflow"],"businessMutation":true,"directFinancialMutation":false,"providerMutation":true,"writeLevel":"provider_execution","requiresIdempotencyKey":true,"approvalRequired":true,"auditedEndpoint":"v1/business/companies/{company_id}/quotes/{quote_id}/send/execute","doesNot":["bypass_approval","post_to_ledger","move_money","file_returns"]},"x-implementation":{"edgeFunction":"supabase/functions/financial-data-api/index.ts","handler":"handleV1BusinessQuoteSendExecution","tests":["supabase/functions/financial-data-api/invoice_idempotency.test.ts"]}}}, "/v1/business/companies/{company_id}/invoices/{invoice_id}/send": { "post": { "tags": [ "Business" ], "operationId": "requestBusinessInvoiceSendApproval", "summary": "Request approval to send a business invoice", "description": "Creates or reuses a pending approval request for sending a draft invoice in a business company. Guarded mode writes the approval request, submission action and required audit evidence atomically. The route requires invoice and approval-workflow permissions plus an Idempotency-Key header. It does not issue or send the invoice directly.", "security": [ { "ApiKeyAuth": [] } ], "parameters": [ { "name": "company_id", "in": "path", "required": true, "description": "Business company id.", "schema": { "type": "string", "format": "uuid" } }, { "name": "invoice_id", "in": "path", "required": true, "description": "Draft business invoice id to submit for send approval.", "schema": { "type": "string", "format": "uuid" } }, { "$ref": "#/components/parameters/RequestId" }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InvoiceSendApprovalRequest" }, "examples": { "customerApproved": { "summary": "Send approval request", "value": { "reason": "Customer has approved the draft" } } } } } }, "responses": { "202": { "description": "Approval request created, or an identical idempotent request replayed.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" }, "X-FIQ-Idempotency-Replayed": { "$ref": "#/components/headers/IdempotencyReplayed" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1ApprovalRequestResponse" } } } }, "400": { "description": "Invalid JSON, invalid company_id or invoice_id path parameter, or missing/invalid idempotency key.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LegacyErrorResponse" } } } }, "401": { "description": "Missing, invalid, expired or inactive API key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LegacyErrorResponse" } } } }, "403": { "description": "The API key does not have invoice or approval-workflow permission.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LegacyErrorResponse" } } } }, "404": { "description": "Business invoice not found.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LegacyErrorResponse" } } } }, "405": { "description": "Only POST is allowed for this route.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LegacyErrorResponse" } } } }, "409": { "description": "The invoice is not draft, idempotency key was reused with a changed body, or no invoice approval workflow is configured.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LegacyErrorResponse" } } } }, "500": { "description": "Generic server failure. Internal database or provider details must not be returned.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1ErrorEnvelope" } } } } }, "x-financial-iq-safety": { "requiresApiKey": true, "scope": "business.invoices.send", "requiredPermissions": [ "invoices", "approval_workflow" ], "writeLevel": "human_approval", "requiresIdempotencyKey": true, "auditedEndpoint": "v1/business/companies/{company_id}/invoices/{invoice_id}/send", "createsApprovalRequest": true, "directExecution": false, "atomicAuditAfterActivation": true, "masterKeyAllowlistSupported": true, "activationGate": "FINANCIAL_API_V1_GUARDED_INVOICE_SEND_APPROVAL_ENABLED", "databaseFunction": "public.create_invoice_send_approval_api_v1_atomic", "missingGuardedBridgeBehavior": "fail_closed_503", "forbiddenInThisRoute": [ "issue invoice immediately", "send invoice immediately", "delete invoice", "file VAT", "file CT600", "file Companies House accounts", "make bank payment", "create direct journal", "close accounting period" ] }, "x-implementation": { "edgeFunction": "supabase/functions/financial-data-api/index.ts", "handler": "handleV1BusinessInvoiceSendApproval", "tests": [ "supabase/functions/financial-data-api/invoice_idempotency.test.ts", "supabase/functions/financial-data-api/v1_openapi_contract.test.ts", "supabase/tests/api_business_invoice_send_approval_hardening.sql", "scripts/run-api-invoice-send-approval-concurrency.mjs" ] } } }, "/v1/business/companies/{company_id}/quotes": { "get": { "tags": [ "Business" ], "operationId": "listBusinessQuotes", "summary": "List business quotes", "description": "Lists quotes for one accessible business company. This route is read-only and does not convert quotes to invoices.", "security": [ { "ApiKeyAuth": [] } ], "parameters": [ { "$ref": "#/components/parameters/BusinessCompanyId" }, { "$ref": "#/components/parameters/RequestId" }, { "name": "status", "in": "query", "required": false, "description": "Optional quote status filter.", "schema": { "type": "string" } }, { "name": "customer_id", "in": "query", "required": false, "description": "Optional customer id filter.", "schema": { "type": "string", "format": "uuid" } }, { "name": "from_date", "in": "query", "required": false, "description": "Inclusive quote-date lower bound.", "schema": { "type": "string", "format": "date", "pattern": "^\\d{4}-\\d{2}-\\d{2}$" } }, { "name": "to_date", "in": "query", "required": false, "description": "Inclusive quote-date upper bound.", "schema": { "type": "string", "format": "date", "pattern": "^\\d{4}-\\d{2}-\\d{2}$" } }, { "name": "limit", "in": "query", "required": false, "description": "Maximum number of quotes to return. Values are clamped between 1 and 200.", "schema": { "type": "integer", "minimum": 1, "maximum": 200, "default": 50 } }, { "name": "offset", "in": "query", "required": false, "description": "Zero-based offset for paginating quote results.", "schema": { "type": "integer", "minimum": 0, "default": 0 } } ], "responses": { "200": { "description": "Business quotes returned.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1BusinessQuoteListResponse" } } } }, "400": { "description": "The company_id, customer_id or date filter is invalid.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1ErrorEnvelope" } } } }, "401": { "description": "Missing, invalid, expired or inactive API key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LegacyErrorResponse" } } } }, "403": { "description": "The API key does not have quote read permission, or the company is not accessible.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1ErrorEnvelope" } } } }, "404": { "description": "Business company not found.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1ErrorEnvelope" } } } }, "405": { "description": "Only GET is allowed for this route.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1ErrorEnvelope" } } } }, "500": { "description": "Generic server failure. Internal database details must not be returned.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1ErrorEnvelope" } } } } }, "x-financial-iq-safety": { "scope": "business.quotes.read", "businessMutation": false, "directFinancialMutation": false, "writeLevel": "read", "requiresIdempotencyKey": false, "auditedEndpoint": "v1/business/companies/{company_id}/quotes", "requiredApiKeyPermission": "quotes" }, "x-implementation": { "edgeFunction": "supabase/functions/financial-data-api/index.ts", "handler": "handleV1BusinessQuotes", "tests": [ "supabase/functions/financial-data-api/invoice_idempotency.test.ts" ] } }, "post": { "tags": [ "Business" ], "operationId": "createBusinessQuote", "summary": "Create draft business quote", "description": "Creates a draft quote for an accessible business company. The route requires quote permission and an Idempotency-Key header. It validates customer, revenue account, project, cost-centre and fund references against the requested company. It does not send, accept, decline, convert to invoice, post to ledger, submit tax or make bank payments.", "security": [ { "ApiKeyAuth": [] } ], "parameters": [ { "$ref": "#/components/parameters/BusinessCompanyId" }, { "$ref": "#/components/parameters/RequestId" }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BusinessQuoteCreateRequest" }, "examples": { "implementationQuote": { "summary": "Draft implementation quote", "value": { "customer_id": "7c3f0d29-5af1-42c1-b8bb-2e4bb3db37e4", "quote_date": "2026-07-07", "valid_until": "2026-08-06", "currency": "GBP", "line_items": [ { "description": "Implementation services", "quantity": 2, "unit_price": 150, "vat_rate": 20, "revenue_account_id": "2db5c0c3-a977-41e9-8e34-a3fd6157de5a" } ] } } } } } }, "responses": { "201": { "description": "Draft business quote created, or an identical idempotent request replayed.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" }, "X-FIQ-Idempotency-Replayed": { "$ref": "#/components/headers/IdempotencyReplayed" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1BusinessQuoteCreateResponse" } } } }, "400": { "description": "Invalid JSON, missing or invalid idempotency key, invalid path parameter, invalid request body, non-draft status or a referenced record that does not belong to the requested company.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1ErrorEnvelope" } } } }, "401": { "description": "Missing, invalid, expired or inactive API key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LegacyErrorResponse" } } } }, "403": { "description": "The API key does not have quote permission or has no owner for creation.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1ErrorEnvelope" } } } }, "404": { "description": "Business company not found.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1ErrorEnvelope" } } } }, "405": { "description": "Only GET and POST are allowed for this route.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1ErrorEnvelope" } } } }, "409": { "description": "The same idempotency key was reused with a different request body.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1ErrorEnvelope" } } } }, "500": { "description": "Generic server failure. Internal database details must not be returned.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1ErrorEnvelope" } } } } }, "x-financial-iq-safety": { "scope": "business.quotes.create", "requiredApiKeyPermission": "quotes", "directFinancialMutation": true, "writeLevel": "draft", "requiresIdempotencyKey": true, "auditedEndpoint": "v1/business/companies/{company_id}/quotes", "forbiddenInThisRoute": [ "send quote", "accept quote", "decline quote", "convert quote to invoice", "issue invoice", "post to ledger", "file VAT", "file CT600", "make bank payment", "close accounting period" ] }, "x-implementation": { "edgeFunction": "supabase/functions/financial-data-api/index.ts", "handler": "handleV1BusinessQuotes", "tests": [ "supabase/functions/financial-data-api/invoice_idempotency.test.ts" ] } } }, "/v1/business/companies/{company_id}/quotes/{quote_id}": { "get": { "tags": [ "Business" ], "operationId": "getBusinessQuote", "summary": "Get one business quote", "description": "Returns one quote for an accessible business company. Inaccessible quote IDs are returned as not found to avoid tenant leakage.", "security": [ { "ApiKeyAuth": [] } ], "parameters": [ { "$ref": "#/components/parameters/BusinessCompanyId" }, { "name": "quote_id", "in": "path", "required": true, "description": "Quote id to fetch.", "schema": { "type": "string", "format": "uuid" } }, { "$ref": "#/components/parameters/RequestId" } ], "responses": { "200": { "description": "Business quote returned.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1BusinessQuoteResponse" } } } }, "400": { "description": "The company_id or quote_id path parameter is invalid.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1ErrorEnvelope" } } } }, "401": { "description": "Missing, invalid, expired or inactive API key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LegacyErrorResponse" } } } }, "403": { "description": "The API key does not have quote read permission, or the company is not accessible.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1ErrorEnvelope" } } } }, "404": { "description": "Business quote not found.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1ErrorEnvelope" } } } }, "405": { "description": "Only GET and PATCH are allowed for this route.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1ErrorEnvelope" } } } }, "500": { "description": "Generic server failure. Internal database details must not be returned.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1ErrorEnvelope" } } } } }, "x-financial-iq-safety": { "scope": "business.quotes.read", "businessMutation": false, "directFinancialMutation": false, "writeLevel": "read", "requiresIdempotencyKey": false, "auditedEndpoint": "v1/business/companies/{company_id}/quotes/{quote_id}", "requiredApiKeyPermission": "quotes" }, "x-implementation": { "edgeFunction": "supabase/functions/financial-data-api/index.ts", "handler": "handleV1BusinessQuoteDetail", "tests": [ "supabase/functions/financial-data-api/invoice_idempotency.test.ts" ] } }, "patch": { "tags": [ "Business" ], "operationId": "updateBusinessDraftQuote", "summary": "Correct a draft business quote", "description": "Updates safe header or line-item fields on a draft quote in one audited database transaction. The caller must provide the lock version returned by the latest quote read. Replacing lines retains the prior rows as hidden history. Quotes awaiting approval, already approved or on hold cannot be changed; a rejected draft can be corrected and submitted again. The route is enabled only after its migration-first activation gate is set and does not send, convert, delete, post accounting entries, file tax or move money.", "security": [ { "ApiKeyAuth": [] } ], "parameters": [ { "$ref": "#/components/parameters/BusinessCompanyId" }, { "name": "quote_id", "in": "path", "required": true, "description": "Draft business quote id to update.", "schema": { "type": "string", "format": "uuid" } }, { "$ref": "#/components/parameters/RequestId" }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BusinessQuoteUpdateRequest" } } } }, "responses": { "200": { "description": "Draft quote updated, or an identical idempotent request replayed.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" }, "X-FIQ-Idempotency-Replayed": { "$ref": "#/components/headers/IdempotencyReplayed" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1BusinessQuoteUpdateResponse" } } } }, "400": { "description": "The patch body, company references, Idempotency-Key or path parameters are invalid.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1ErrorEnvelope" } } } }, "401": { "description": "Missing, invalid, expired or inactive API key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LegacyErrorResponse" } } } }, "403": { "description": "The exact API key lacks quote permission, owner context or current company authority.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1ErrorEnvelope" } } } }, "404": { "description": "The company or quote was not found for this API key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1ErrorEnvelope" } } } }, "409": { "description": "The quote is no longer an editable draft, is awaiting approval, is approved or on hold, the idempotency key changed body, or the lock version is stale.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1ErrorEnvelope" } } } }, "503": { "description": "Quote correction is temporarily unavailable because its guarded database bridge is not yet activated or is missing.", "headers": { "Retry-After": { "description": "Suggested delay in seconds before retrying.", "schema": { "type": "integer", "minimum": 0 } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1ErrorEnvelope" } } } } }, "x-financial-iq-safety": { "scope": "business.quotes.update", "businessMutation": true, "directFinancialMutation": false, "writeLevel": "draft_correction", "requiresIdempotencyKey": true, "requiresExpectedLockVersion": true, "auditedEndpoint": "v1/business/companies/{company_id}/quotes/{quote_id}", "requiredApiKeyPermission": "quotes", "allowedQuoteStatuses": [ "draft" ], "blockedApprovalStatuses": [ "pending", "approved", "on_hold" ], "atomicAudit": true, "retainsReplacedLineHistory": true, "archivedLinesExcludedFromReadsAndConversion": true, "currentAuthorityRechecked": true, "masterKeyAllowlistSupported": true, "activationGate": "FINANCIAL_API_V1_GUARDED_QUOTE_UPDATE_ENABLED", "missingGuardedBridgeBehavior": "fail_closed_503", "accountingEntriesPosted": false, "externalSendPerformed": false, "moneyMovementPerformed": false, "taxFilingPerformed": false, "forbiddenInThisRoute": [ "send quote", "convert quote", "delete quote", "post journal", "file tax", "make bank payment", "close accounting period" ] }, "x-implementation": { "edgeFunction": "supabase/functions/financial-data-api/index.ts", "handler": "updateV1BusinessDraftQuote", "databaseFunction": "public.replace_draft_quote_api_v1_atomic", "tests": [ "supabase/functions/financial-data-api/invoice_idempotency.test.ts", "supabase/functions/financial-data-api/v1_openapi_contract.test.ts", "supabase/tests/api_business_quote_draft_update.sql" ] } } }, "/v1/business/companies/{company_id}/quotes/{quote_id}/send": { "post": { "tags": [ "Business" ], "operationId": "requestBusinessQuoteSendApproval", "summary": "Request approval to send a business quote", "description": "Creates a pending approval request for sending a draft quote in a business company. The route requires quote and approval-workflow permissions plus an Idempotency-Key header. Once its activation gate is enabled, the request, quote status, submission action and required API audit are committed atomically. It does not send, convert, delete, file tax, create direct journals or make bank payments.", "security": [ { "ApiKeyAuth": [] } ], "parameters": [ { "name": "company_id", "in": "path", "required": true, "description": "Business company id.", "schema": { "type": "string", "format": "uuid" } }, { "name": "quote_id", "in": "path", "required": true, "description": "Draft business quote id to submit for send approval.", "schema": { "type": "string", "format": "uuid" } }, { "$ref": "#/components/parameters/RequestId" }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/QuoteSendApprovalRequest" }, "examples": { "customerApproved": { "summary": "Quote send approval request", "value": { "reason": "Customer has approved the draft quote" } } } } } }, "responses": { "202": { "description": "Approval request created, an existing pending approval returned, or an identical idempotent request replayed.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" }, "X-FIQ-Idempotency-Replayed": { "$ref": "#/components/headers/IdempotencyReplayed" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1QuoteApprovalRequestResponse" } } } }, "400": { "description": "Invalid JSON, invalid company_id or quote_id path parameter, or missing/invalid idempotency key.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LegacyErrorResponse" } } } }, "401": { "description": "Missing, invalid, expired or inactive API key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LegacyErrorResponse" } } } }, "403": { "description": "The API key does not have quote or approval-workflow permission.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LegacyErrorResponse" } } } }, "404": { "description": "Business quote not found.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LegacyErrorResponse" } } } }, "405": { "description": "Only POST is allowed for this route.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LegacyErrorResponse" } } } }, "409": { "description": "The quote is not draft, idempotency key was reused with a changed body, or no quote approval workflow is configured.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LegacyErrorResponse" } } } }, "503": { "description": "Guarded quote approval is temporarily unavailable while the migration-first database safety upgrade is activated. Retry after the indicated delay; the route does not fall back to a less safe write path.", "headers": { "Retry-After": { "$ref": "#/components/headers/RetryAfter" }, "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1ErrorEnvelope" } } } }, "500": { "description": "Generic server failure. Internal database or provider details must not be returned.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1ErrorEnvelope" } } } } }, "x-financial-iq-safety": { "requiresApiKey": true, "scope": "business.quotes.send", "requiredPermissions": [ "quotes", "approval_workflow" ], "writeLevel": "human_approval", "requiresIdempotencyKey": true, "auditedEndpoint": "v1/business/companies/{company_id}/quotes/{quote_id}/send", "createsApprovalRequest": true, "directExecution": false, "activationGate": "FINANCIAL_API_V1_GUARDED_QUOTE_SEND_APPROVAL_ENABLED", "forbiddenInThisRoute": [ "send quote immediately", "convert quote immediately", "delete quote", "file VAT", "file CT600", "file Companies House accounts", "make bank payment", "create direct journal", "close accounting period" ] }, "x-implementation": { "edgeFunction": "supabase/functions/financial-data-api/index.ts", "handler": "handleV1BusinessQuoteSendApproval", "databaseFunction": "public.create_quote_send_approval_api_v1_atomic", "tests": [ "supabase/functions/financial-data-api/invoice_idempotency.test.ts", "supabase/functions/financial-data-api/v1_openapi_contract.test.ts", "supabase/tests/api_business_quote_send_approval_hardening.sql", "scripts/run-api-quote-send-approval-concurrency.mjs" ] } } }, "/v1/business/companies/{company_id}/quotes/{quote_id}/convert": { "post": { "tags": [ "Business" ], "operationId": "convertBusinessQuoteToInvoice", "summary": "Convert a business quote to an issued invoice", "description": "Converts an eligible draft, sent or accepted quote into an issued invoice for one accessible business company. The route requires quote and invoice permissions plus an Idempotency-Key header. Guarded mode rechecks the exact active key and current direct, delegated or master-key authority in the same database transaction as quote conversion, invoice posting and required audit evidence. It does not send the invoice externally, file tax, close accounting periods or make bank payments.", "security": [ { "ApiKeyAuth": [] } ], "parameters": [ { "name": "company_id", "in": "path", "required": true, "description": "Business company id.", "schema": { "type": "string", "format": "uuid" } }, { "name": "quote_id", "in": "path", "required": true, "description": "Business quote id to convert.", "schema": { "type": "string", "format": "uuid" } }, { "$ref": "#/components/parameters/RequestId" }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BusinessQuoteConversionRequest" }, "examples": { "customInvoiceDate": { "summary": "Convert with invoice date and payment terms", "value": { "invoice_date": "2026-07-10", "payment_terms_days": 14 } } } } } }, "responses": { "201": { "description": "Quote converted, issued invoice created, accounting entries posted, or an identical idempotent request replayed.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" }, "X-FIQ-Idempotency-Replayed": { "$ref": "#/components/headers/IdempotencyReplayed" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1BusinessQuoteConversionResponse" } } } }, "400": { "description": "Invalid JSON, unsupported conversion field, invalid date, invalid company_id or quote_id path parameter, or missing/invalid idempotency key.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LegacyErrorResponse" } } } }, "401": { "description": "Missing, invalid, expired or inactive API key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LegacyErrorResponse" } } } }, "403": { "description": "The API key does not have quote and invoice permissions, or the API key owner cannot run the product conversion flow.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LegacyErrorResponse" } } } }, "404": { "description": "Business quote not found.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LegacyErrorResponse" } } } }, "405": { "description": "Only POST is allowed for this route.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LegacyErrorResponse" } } } }, "409": { "description": "The quote is already converted, cannot be converted from its current status, requires approval, has no active lines, contains unreconciled amounts or invalid company coding, targets a locked period, cannot post its accounting entries, or the idempotency key was reused with a changed body.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LegacyErrorResponse" } } } }, "500": { "description": "Generic server failure. Internal database or provider details must not be returned.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1ErrorEnvelope" } } } }, "503": { "description": "Master-key conversion is unavailable before guarded activation. After activation, any key receives this response if the guarded database bridge is unavailable. Standard company keys retain the legacy bridge before activation. No quote, invoice or accounting state was changed; retry the same idempotency key after activation is complete.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" }, "Retry-After": { "schema": { "type": "integer", "minimum": 1 } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1ErrorEnvelope" } } } } }, "x-financial-iq-safety": { "requiresApiKey": true, "scope": "business.quotes.convert", "requiredPermissions": [ "quotes", "invoices" ], "writeLevel": "accounting_entry", "requiresIdempotencyKey": true, "activationGate": "FINANCIAL_API_V1_GUARDED_QUOTE_CONVERSION_ENABLED", "auditedEndpoint": "v1/business/companies/{company_id}/quotes/{quote_id}/convert", "createsApprovalRequest": false, "directExecution": true, "effects": [ "mark quote converted", "create issued invoice", "post accounting entries" ], "forbiddenInThisRoute": [ "send invoice externally", "send quote externally", "delete quote", "file VAT", "file CT600", "file Companies House accounts", "make bank payment", "close accounting period" ] }, "x-implementation": { "edgeFunction": "supabase/functions/financial-data-api/index.ts", "handler": "handleV1BusinessQuoteConvert", "databaseFunction": "public.convert_quote_to_invoice_api_v1_atomic", "tests": [ "supabase/functions/financial-data-api/invoice_idempotency.test.ts", "supabase/functions/financial-data-api/v1_openapi_contract.test.ts", "supabase/tests/api_business_quote_conversion_hardening.sql", "scripts/run-api-quote-conversion-concurrency.mjs", "supabase/tests/api_business_quote_conversion_concurrency_setup.sql" ] } } }, "/v1/business/companies/{company_id}/credit-notes": { "get": { "tags": [ "Business" ], "operationId": "listBusinessCreditNotes", "summary": "List business credit notes", "description": "Lists credit notes for one accessible business company. This route is read-only and does not issue or post credit notes.", "security": [ { "ApiKeyAuth": [] } ], "parameters": [ { "$ref": "#/components/parameters/BusinessCompanyId" }, { "$ref": "#/components/parameters/RequestId" }, { "name": "status", "in": "query", "required": false, "description": "Optional credit-note status filter.", "schema": { "type": "string" } }, { "name": "customer_id", "in": "query", "required": false, "description": "Optional customer id filter.", "schema": { "type": "string", "format": "uuid" } }, { "name": "original_invoice_id", "in": "query", "required": false, "description": "Optional original invoice id filter.", "schema": { "type": "string", "format": "uuid" } }, { "name": "from_date", "in": "query", "required": false, "description": "Inclusive credit-note date lower bound.", "schema": { "type": "string", "format": "date", "pattern": "^\\d{4}-\\d{2}-\\d{2}$" } }, { "name": "to_date", "in": "query", "required": false, "description": "Inclusive credit-note date upper bound.", "schema": { "type": "string", "format": "date", "pattern": "^\\d{4}-\\d{2}-\\d{2}$" } }, { "name": "limit", "in": "query", "required": false, "description": "Maximum number of credit notes to return. Values are clamped between 1 and 200.", "schema": { "type": "integer", "minimum": 1, "maximum": 200, "default": 50 } }, { "name": "offset", "in": "query", "required": false, "description": "Zero-based offset for paginating credit-note results.", "schema": { "type": "integer", "minimum": 0, "default": 0 } } ], "responses": { "200": { "description": "Business credit notes returned.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1BusinessCreditNoteListResponse" } } } }, "400": { "description": "The company_id, customer_id, original_invoice_id or date filter is invalid.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1ErrorEnvelope" } } } }, "401": { "description": "Missing, invalid, expired or inactive API key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LegacyErrorResponse" } } } }, "403": { "description": "The API key does not have invoice read permission, or the company is not accessible.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1ErrorEnvelope" } } } }, "404": { "description": "Business company not found.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1ErrorEnvelope" } } } }, "405": { "description": "Only GET is allowed for this route.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1ErrorEnvelope" } } } }, "500": { "description": "Generic server failure. Internal database details must not be returned.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1ErrorEnvelope" } } } } }, "x-financial-iq-safety": { "scope": "business.credit_notes.read", "businessMutation": false, "directFinancialMutation": false, "writeLevel": "read", "requiresIdempotencyKey": false, "auditedEndpoint": "v1/business/companies/{company_id}/credit-notes", "requiredApiKeyPermission": "invoices" }, "x-implementation": { "edgeFunction": "supabase/functions/financial-data-api/index.ts", "handler": "handleV1BusinessCreditNotes", "tests": [ "supabase/functions/financial-data-api/invoice_idempotency.test.ts" ] } }, "post": { "tags": [ "Business" ], "operationId": "createBusinessCreditNote", "summary": "Create draft business credit note", "description": "Creates a draft credit note for an accessible business company. The route requires invoice permission and an Idempotency-Key header. It validates customer, original invoice, revenue account, project, cost-centre and fund references against the requested company. It does not issue the credit note, post to ledger, apply credit to an invoice, refund a customer, submit tax or make bank payments.", "security": [ { "ApiKeyAuth": [] } ], "parameters": [ { "$ref": "#/components/parameters/BusinessCompanyId" }, { "$ref": "#/components/parameters/RequestId" }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BusinessCreditNoteCreateRequest" }, "examples": { "implementationCreditNote": { "summary": "Draft implementation credit note", "value": { "customer_id": "7c3f0d29-5af1-42c1-b8bb-2e4bb3db37e4", "credit_note_date": "2026-07-07", "currency": "GBP", "reason": "Price adjustment", "line_items": [ { "description": "Credit for implementation services", "quantity": 1, "unit_price": 100, "vat_rate": 20, "revenue_account_id": "2db5c0c3-a977-41e9-8e34-a3fd6157de5a" } ] } } } } } }, "responses": { "201": { "description": "Draft business credit note created, or an identical idempotent request replayed.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" }, "X-FIQ-Idempotency-Replayed": { "$ref": "#/components/headers/IdempotencyReplayed" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1BusinessCreditNoteCreateResponse" } } } }, "400": { "description": "Invalid JSON, missing or invalid idempotency key, invalid path parameter, invalid request body, non-draft status or a referenced record that does not belong to the requested company.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1ErrorEnvelope" } } } }, "401": { "description": "Missing, invalid, expired or inactive API key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LegacyErrorResponse" } } } }, "403": { "description": "The API key does not have invoice permission or has no owner for creation.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1ErrorEnvelope" } } } }, "404": { "description": "Business company not found.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1ErrorEnvelope" } } } }, "405": { "description": "Only GET and POST are allowed for this route.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1ErrorEnvelope" } } } }, "409": { "description": "The same idempotency key was reused with a different request body.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1ErrorEnvelope" } } } }, "500": { "description": "Generic server failure. Internal database details must not be returned.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1ErrorEnvelope" } } } } }, "x-financial-iq-safety": { "scope": "business.credit_notes.create", "requiredApiKeyPermission": "invoices", "directFinancialMutation": true, "writeLevel": "draft", "requiresIdempotencyKey": true, "auditedEndpoint": "v1/business/companies/{company_id}/credit-notes", "forbiddenInThisRoute": [ "issue credit note", "post credit note to ledger", "apply credit to invoice", "refund customer", "issue invoice", "post to ledger", "file VAT", "file CT600", "make bank payment", "close accounting period" ] }, "x-implementation": { "edgeFunction": "supabase/functions/financial-data-api/index.ts", "handler": "handleV1BusinessCreditNotes", "tests": [ "supabase/functions/financial-data-api/invoice_idempotency.test.ts" ] } } }, "/v1/business/companies/{company_id}/credit-notes/{credit_note_id}": { "get": { "tags": [ "Business" ], "operationId": "getBusinessCreditNote", "summary": "Get one business credit note", "description": "Returns one credit note for an accessible business company. Inaccessible credit-note IDs are returned as not found to avoid tenant leakage.", "security": [ { "ApiKeyAuth": [] } ], "parameters": [ { "$ref": "#/components/parameters/BusinessCompanyId" }, { "name": "credit_note_id", "in": "path", "required": true, "description": "Credit note id to fetch.", "schema": { "type": "string", "format": "uuid" } }, { "$ref": "#/components/parameters/RequestId" } ], "responses": { "200": { "description": "Business credit note returned.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1BusinessCreditNoteResponse" } } } }, "400": { "description": "The company_id or credit_note_id path parameter is invalid.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1ErrorEnvelope" } } } }, "401": { "description": "Missing, invalid, expired or inactive API key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LegacyErrorResponse" } } } }, "403": { "description": "The API key does not have invoice read permission, or the company is not accessible.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1ErrorEnvelope" } } } }, "404": { "description": "Business credit note not found.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1ErrorEnvelope" } } } }, "405": { "description": "Only GET is allowed for this route.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1ErrorEnvelope" } } } }, "500": { "description": "Generic server failure. Internal database details must not be returned.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1ErrorEnvelope" } } } } }, "x-financial-iq-safety": { "scope": "business.credit_notes.read", "businessMutation": false, "directFinancialMutation": false, "writeLevel": "read", "requiresIdempotencyKey": false, "auditedEndpoint": "v1/business/companies/{company_id}/credit-notes/{credit_note_id}", "requiredApiKeyPermission": "invoices" }, "x-implementation": { "edgeFunction": "supabase/functions/financial-data-api/index.ts", "handler": "handleV1BusinessCreditNoteDetail", "tests": [ "supabase/functions/financial-data-api/invoice_idempotency.test.ts" ] } } }, "/v1/business/companies/{company_id}/credit-notes/{credit_note_id}/issue": { "post": { "tags": [ "Business" ], "operationId": "issueBusinessCreditNote", "summary": "Issue a draft business credit note", "description": "Issues an existing draft credit note for one accessible business company. The route requires invoice permission plus an Idempotency-Key header. It posts the accounting journal, records VAT effects where applicable, applies the credit to the original invoice when one is linked, and only then marks the credit note as issued. It does not send the credit note externally, refund the customer, file tax, close accounting periods or make bank payments.", "security": [ { "ApiKeyAuth": [] } ], "parameters": [ { "$ref": "#/components/parameters/BusinessCompanyId" }, { "name": "credit_note_id", "in": "path", "required": true, "description": "Business credit note id to issue.", "schema": { "type": "string", "format": "uuid" } }, { "$ref": "#/components/parameters/RequestId" }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "responses": { "200": { "description": "Credit note issued, accounting effects posted, or an identical idempotent request replayed.", "headers": { "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" }, "X-FIQ-Idempotency-Replayed": { "$ref": "#/components/headers/IdempotencyReplayed" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1BusinessCreditNoteIssueResponse" } } } }, "400": { "description": "Invalid JSON, unexpected body field, invalid company_id or credit_note_id path parameter, or missing/invalid idempotency key.", "headers": { "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Missing, invalid, expired or inactive API key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "The API key does not have invoice permission, or the API key owner cannot run the product issue flow.", "headers": { "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Business credit note not found.", "headers": { "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "405": { "description": "Only POST is allowed for this route.", "headers": { "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "409": { "description": "The credit note is not a draft, cannot be posted safely, has missing accounts or line items, exceeds the original invoice balance, or the idempotency key was reused with a changed body.", "headers": { "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Generic server failure. Internal database or provider details must not be returned.", "headers": { "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "x-financial-iq-safety": { "requiresApiKey": true, "scope": "business.credit_notes.issue", "requiredApiKeyPermission": "invoices", "writeLevel": "accounting_entry", "requiresIdempotencyKey": true, "auditedEndpoint": "v1/business/companies/{company_id}/credit-notes/{credit_note_id}/issue", "createsApprovalRequest": false, "directExecution": true, "effects": [ "mark credit note issued", "post accounting entries", "record VAT effects where applicable", "apply credit to linked original invoice where applicable" ], "forbiddenInThisRoute": [ "send credit note externally", "refund customer", "file VAT return", "file CT600", "file Companies House accounts", "make bank payment", "close accounting period", "delete credit note" ] }, "x-implementation": { "edgeFunction": "supabase/functions/financial-data-api/index.ts", "handler": "handleV1BusinessCreditNoteIssue", "databaseFunction": "public.issue_credit_note_api_v1_atomic", "activationGate": "FINANCIAL_API_V1_GUARDED_CREDIT_NOTE_ISSUE_ENABLED", "atomicAuditAfterActivation": true, "masterKeyAllowlistSupported": true, "missingGuardedBridgeBehavior": "fail_closed_503", "tests": [ "supabase/functions/financial-data-api/invoice_idempotency.test.ts", "supabase/functions/financial-data-api/v1_openapi_contract.test.ts", "supabase/tests/api_business_credit_note_hardening.sql", "scripts/run-api-credit-note-concurrency.mjs" ] } } }, "/v1/business/companies/{company_id}/credit-notes/{credit_note_id}/cancel": { "post": { "tags": [ "Business" ], "operationId": "cancelBusinessCreditNote", "summary": "Cancel a business credit note", "description": "Cancels a credit note raised in error for one accessible business company without deleting it. The route requires invoice permission plus an Idempotency-Key header and a reason. It marks the credit note cancelled, voids the linked journal where applicable, and archives linked invoice-allocation and VAT state where applicable. It does not refund the customer, move money, file tax, send documents, close accounting periods or delete the credit note.", "security": [ { "ApiKeyAuth": [] } ], "parameters": [ { "$ref": "#/components/parameters/BusinessCompanyId" }, { "name": "credit_note_id", "in": "path", "required": true, "description": "Business credit note id to cancel.", "schema": { "type": "string", "format": "uuid" } }, { "$ref": "#/components/parameters/RequestId" }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "responses": { "200": { "description": "Credit note cancelled, an existing cancellation returned, or an identical idempotent request replayed.", "headers": { "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" }, "X-FIQ-Idempotency-Replayed": { "$ref": "#/components/headers/IdempotencyReplayed" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1BusinessCreditNoteCancelResponse" } } } }, "400": { "description": "The request body, Idempotency-Key or path parameter is invalid.", "headers": { "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Missing, invalid, expired or inactive API key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "The API key lacks invoice permission or owner context.", "headers": { "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Business credit note not found.", "headers": { "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "405": { "description": "Only POST is allowed for this route.", "headers": { "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "409": { "description": "The credit note cannot be cancelled from its current state, idempotency key was reused with a changed body, or a guarded cancellation check failed.", "headers": { "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Generic server failure. Internal database or provider details must not be returned.", "headers": { "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "x-financial-iq-safety": { "requiresApiKey": true, "scope": "business.credit_notes.cancel", "requiredApiKeyPermission": "invoices", "writeLevel": "accounting_reversal", "requiresIdempotencyKey": true, "auditedEndpoint": "v1/business/companies/{company_id}/credit-notes/{credit_note_id}/cancel", "createsApprovalRequest": false, "directExecution": true, "moneyMovementPerformed": false, "paymentRefundPerformed": false, "taxFilingPerformed": false, "effects": [ "mark credit note cancelled", "void linked journal where applicable", "archive linked credit-note allocations where applicable", "archive linked VAT transactions where applicable" ], "forbiddenInThisRoute": [ "delete credit note", "refund customer", "move money", "send credit note externally", "file VAT return", "file CT600", "file Companies House accounts", "make bank payment", "close accounting period" ] }, "x-implementation": { "edgeFunction": "supabase/functions/financial-data-api/index.ts", "handler": "handleV1BusinessCreditNoteCancel", "databaseFunction": "public.cancel_credit_note_api_v1_atomic", "activationGate": "FINANCIAL_API_V1_GUARDED_CREDIT_NOTE_CANCEL_ENABLED", "atomicAuditAfterActivation": true, "masterKeyAllowlistSupported": true, "missingGuardedBridgeBehavior": "fail_closed_503", "tests": [ "supabase/functions/financial-data-api/invoice_idempotency.test.ts", "supabase/functions/financial-data-api/v1_openapi_contract.test.ts", "supabase/tests/api_business_credit_note_hardening.sql", "scripts/run-api-credit-note-concurrency.mjs" ] }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BusinessCreditNoteCancelRequest" }, "examples": { "raisedInError": { "summary": "Credit-note cancellation reason", "value": { "reason": "Credit note raised in error" } } } } } } } }, "/v1/business/companies/{company_id}/documents": { "get": { "tags": [ "Business" ], "operationId": "listBusinessDocuments", "summary": "List business document metadata", "description": "Lists safe document metadata for one accessible business company. This route is read-only and does not return signed URLs, storage paths, raw OCR text or file content.", "security": [ { "ApiKeyAuth": [] } ], "parameters": [ { "$ref": "#/components/parameters/BusinessCompanyId" }, { "$ref": "#/components/parameters/RequestId" }, { "name": "status", "in": "query", "required": false, "description": "Optional document status filter.", "schema": { "type": "string" } }, { "name": "document_type", "in": "query", "required": false, "description": "Optional document type filter.", "schema": { "type": "string" } }, { "name": "document_classification", "in": "query", "required": false, "description": "Optional document classification filter.", "schema": { "type": "string" } }, { "name": "customer_id", "in": "query", "required": false, "description": "Optional customer id filter.", "schema": { "type": "string", "format": "uuid" } }, { "name": "supplier_id", "in": "query", "required": false, "description": "Optional supplier id filter.", "schema": { "type": "string", "format": "uuid" } }, { "name": "linked_invoice_id", "in": "query", "required": false, "description": "Optional linked sales invoice id filter.", "schema": { "type": "string", "format": "uuid" } }, { "name": "linked_purchase_invoice_id", "in": "query", "required": false, "description": "Optional linked purchase invoice id filter.", "schema": { "type": "string", "format": "uuid" } }, { "name": "linked_purchase_order_id", "in": "query", "required": false, "description": "Optional linked purchase order id filter.", "schema": { "type": "string", "format": "uuid" } }, { "name": "linked_bank_transaction_id", "in": "query", "required": false, "description": "Optional linked bank transaction id filter.", "schema": { "type": "string", "format": "uuid" } }, { "name": "limit", "in": "query", "required": false, "description": "Maximum number of documents to return. Values are clamped between 1 and 200.", "schema": { "type": "integer", "minimum": 1, "maximum": 200, "default": 50 } }, { "name": "offset", "in": "query", "required": false, "description": "Zero-based offset for paginating document results.", "schema": { "type": "integer", "minimum": 0, "default": 0 } } ], "responses": { "200": { "description": "Business document metadata returned.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1BusinessDocumentListResponse" } } } }, "400": { "description": "The company_id or document filter is invalid.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1ErrorEnvelope" } } } }, "401": { "description": "Missing, invalid, expired or inactive API key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LegacyErrorResponse" } } } }, "403": { "description": "The API key does not have document read permission, or the company is not accessible.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1ErrorEnvelope" } } } }, "404": { "description": "Business company not found.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1ErrorEnvelope" } } } }, "405": { "description": "Only GET is allowed for this route.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1ErrorEnvelope" } } } }, "500": { "description": "Generic server failure. Internal database details must not be returned.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1ErrorEnvelope" } } } } }, "x-financial-iq-safety": { "scope": "business.documents.read", "businessMutation": false, "directFinancialMutation": false, "writeLevel": "read", "requiresIdempotencyKey": false, "auditedEndpoint": "v1/business/companies/{company_id}/documents", "requiredApiKeyPermission": "documents" }, "x-implementation": { "edgeFunction": "supabase/functions/financial-data-api/index.ts", "handler": "handleV1BusinessDocuments", "tests": [ "supabase/functions/financial-data-api/invoice_idempotency.test.ts" ] } }, "post": { "tags": [ "Business" ], "operationId": "uploadBusinessDocument", "summary": "Upload business document", "description": "Uploads a business document for an accessible company using a JSON base64 payload. The route requires document permission and an Idempotency-Key header. It validates customer, supplier, purchase invoice, purchase order and bank transaction references against the requested company. It stores the file and returns safe metadata only; it does not return signed URLs, storage paths, raw OCR text or content hashes, and it does not create invoices, post ledger entries or submit tax.", "security": [ { "ApiKeyAuth": [] } ], "parameters": [ { "$ref": "#/components/parameters/BusinessCompanyId" }, { "$ref": "#/components/parameters/RequestId" }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BusinessDocumentUploadRequest" }, "examples": { "receiptUpload": { "summary": "Upload a receipt document", "value": { "file_name": "receipt.csv", "file_type": "text/csv", "file_content": "ZGF0ZSxhbW91bnQKMjAyNi0wNy0wNywyNC4wMAo=", "document_type": "receipt", "document_classification": "purchase_receipt", "linked_bank_transaction_id": "21d8f26f-3b57-44d2-a142-32d6b75db9a2", "supplier_id": "8f61ec9f-6b3c-4c93-bd48-6a568e6050fd" } } } } } }, "responses": { "201": { "description": "Business document uploaded, or an identical idempotent request replayed.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" }, "X-FIQ-Idempotency-Replayed": { "$ref": "#/components/headers/IdempotencyReplayed" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1BusinessDocumentUploadResponse" } } } }, "400": { "description": "Invalid JSON, missing or invalid idempotency key, invalid file payload, invalid path parameter, invalid request body or a referenced record that does not belong to the requested company.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1ErrorEnvelope" } } } }, "401": { "description": "Missing, invalid, expired or inactive API key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LegacyErrorResponse" } } } }, "403": { "description": "The API key does not have document permission or has no owner for upload.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1ErrorEnvelope" } } } }, "404": { "description": "Business company not found.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1ErrorEnvelope" } } } }, "405": { "description": "Only GET and POST are allowed for this route.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1ErrorEnvelope" } } } }, "409": { "description": "The same idempotency key was reused with a different request body.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1ErrorEnvelope" } } } }, "500": { "description": "Generic server failure. Internal database and storage details must not be returned.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1ErrorEnvelope" } } } } }, "x-financial-iq-safety": { "scope": "business.documents.create", "requiredApiKeyPermission": "documents", "directFinancialMutation": false, "writeLevel": "evidence", "requiresIdempotencyKey": true, "auditedEndpoint": "v1/business/companies/{company_id}/documents", "forbiddenInThisRoute": [ "create invoice", "create purchase invoice", "approve expense", "post to ledger", "file VAT", "file CT600", "make bank payment", "close accounting period", "return signed URL", "return storage path", "return content hash" ] }, "x-implementation": { "edgeFunction": "supabase/functions/financial-data-api/index.ts", "handler": "handleV1BusinessDocuments", "tests": [ "supabase/functions/financial-data-api/invoice_idempotency.test.ts" ] } } }, "/v1/business/companies/{company_id}/documents/{document_id}": { "get": { "tags": [ "Business" ], "operationId": "getBusinessDocument", "summary": "Get one business document metadata record", "description": "Returns safe metadata for one document belonging to an accessible business company. Inaccessible document IDs are returned as not found to avoid tenant leakage.", "security": [ { "ApiKeyAuth": [] } ], "parameters": [ { "$ref": "#/components/parameters/BusinessCompanyId" }, { "name": "document_id", "in": "path", "required": true, "description": "Document id to fetch.", "schema": { "type": "string", "format": "uuid" } }, { "$ref": "#/components/parameters/RequestId" } ], "responses": { "200": { "description": "Business document metadata returned.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1BusinessDocumentResponse" } } } }, "400": { "description": "The company_id or document_id path parameter is invalid.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1ErrorEnvelope" } } } }, "401": { "description": "Missing, invalid, expired or inactive API key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LegacyErrorResponse" } } } }, "403": { "description": "The API key does not have document read permission, or the company is not accessible.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1ErrorEnvelope" } } } }, "404": { "description": "Business document not found.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1ErrorEnvelope" } } } }, "405": { "description": "Only GET is allowed for this route.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1ErrorEnvelope" } } } }, "500": { "description": "Generic server failure. Internal database details must not be returned.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1ErrorEnvelope" } } } } }, "x-financial-iq-safety": { "scope": "business.documents.read", "businessMutation": false, "directFinancialMutation": false, "writeLevel": "read", "requiresIdempotencyKey": false, "auditedEndpoint": "v1/business/companies/{company_id}/documents/{document_id}", "requiredApiKeyPermission": "documents" }, "x-implementation": { "edgeFunction": "supabase/functions/financial-data-api/index.ts", "handler": "handleV1BusinessDocumentDetail", "tests": [ "supabase/functions/financial-data-api/invoice_idempotency.test.ts" ] } }, "patch": { "tags": [ "Business" ], "operationId": "updateBusinessDocument", "summary": "Update business document metadata", "description": "Updates safe metadata and company-scoped links for one business document. The route requires document permission and an Idempotency-Key header. It does not replace files, expose storage details, mutate OCR raw text, create invoices or bills, approve expenses, post ledger entries or submit tax.", "security": [ { "ApiKeyAuth": [] } ], "parameters": [ { "$ref": "#/components/parameters/BusinessCompanyId" }, { "name": "document_id", "in": "path", "required": true, "description": "Document id to fetch.", "schema": { "type": "string", "format": "uuid" } }, { "$ref": "#/components/parameters/RequestId" }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BusinessDocumentUpdateRequest" }, "examples": { "classifyAndLink": { "summary": "Classify and link a receipt", "value": { "status": "reviewed", "document_type": "receipt", "document_classification": "purchase_receipt", "linked_purchase_invoice_id": "48484848-4848-8848-8848-484848484848", "linked_bank_transaction_id": "21d8f26f-3b57-44d2-a142-32d6b75db9a2", "notes": "Matched by agent" } } } } } }, "responses": { "200": { "description": "Business document metadata updated, or an identical idempotent request replayed.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" }, "X-FIQ-Idempotency-Replayed": { "$ref": "#/components/headers/IdempotencyReplayed" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1BusinessDocumentUpdateResponse" } } } }, "400": { "description": "Invalid JSON, missing or invalid idempotency key, invalid path parameter, invalid request body or a referenced record that does not belong to the requested company.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1ErrorEnvelope" } } } }, "401": { "description": "Missing, invalid, expired or inactive API key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LegacyErrorResponse" } } } }, "403": { "description": "The API key does not have document permission or has no owner for update.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1ErrorEnvelope" } } } }, "404": { "description": "Business document not found.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1ErrorEnvelope" } } } }, "405": { "description": "Only GET and PATCH are allowed for this route.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1ErrorEnvelope" } } } }, "409": { "description": "The same idempotency key was reused with a different request body.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1ErrorEnvelope" } } } }, "500": { "description": "Generic server failure. Internal database and storage details must not be returned.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1ErrorEnvelope" } } } } }, "x-financial-iq-safety": { "scope": "business.documents.update", "requiredApiKeyPermission": "documents", "businessMutation": true, "directFinancialMutation": false, "writeLevel": "evidence", "requiresIdempotencyKey": true, "auditedEndpoint": "v1/business/companies/{company_id}/documents/{document_id}", "forbiddenInThisRoute": [ "replace file", "return storage bucket", "return storage path", "return content hash", "mutate raw OCR text", "create invoice", "create purchase invoice", "approve expense", "post to ledger", "file VAT", "file CT600", "make bank payment", "close accounting period", "delete document" ] }, "x-implementation": { "edgeFunction": "supabase/functions/financial-data-api/index.ts", "handler": "updateV1BusinessDocumentMetadata", "tests": [ "supabase/functions/financial-data-api/invoice_idempotency.test.ts" ] } }, "delete": { "tags": [ "Business" ], "operationId": "archiveBusinessDocument", "summary": "Archive a business document", "description": "Archives a business document without deleting its database record or storage object. The route requires a reason and an Idempotency-Key and writes the archive audit in the same database transaction as the status change.", "security": [ { "ApiKeyAuth": [] } ], "parameters": [ { "$ref": "#/components/parameters/BusinessCompanyId" }, { "name": "document_id", "in": "path", "required": true, "description": "Document id to archive.", "schema": { "type": "string", "format": "uuid" } }, { "$ref": "#/components/parameters/RequestId" }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "required": [ "reason" ], "properties": { "reason": { "type": "string", "minLength": 5, "maxLength": 500 } } } } } }, "responses": { "200": { "description": "Business document archived, or an identical idempotent request replayed.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" }, "X-FIQ-Idempotency-Replayed": { "$ref": "#/components/headers/IdempotencyReplayed" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "required": [ "object", "changed", "document", "storage_object_retained" ], "properties": { "object": { "const": "business_document_archive" }, "changed": { "type": "boolean" }, "document": { "$ref": "#/components/schemas/BusinessDocument" }, "storage_object_retained": { "type": "boolean", "const": true } } }, "meta": { "$ref": "#/components/schemas/V1BusinessDocumentUpdateMeta" } } } } } }, "400": { "$ref": "#/components/responses/V1BadRequest" }, "401": { "$ref": "#/components/responses/V1Unauthorised" }, "403": { "$ref": "#/components/responses/V1Forbidden" }, "404": { "$ref": "#/components/responses/V1NotFound" }, "409": { "$ref": "#/components/responses/V1Conflict" }, "503": { "$ref": "#/components/responses/V1Unavailable" } }, "x-financial-iq-safety": { "scope": "business.documents.archive", "requiredApiKeyPermission": "documents", "businessMutation": true, "directFinancialMutation": false, "writeLevel": "evidence", "requiresIdempotencyKey": true, "auditedEndpoint": "v1/business/companies/{company_id}/documents/{document_id}", "forbiddenInThisRoute": [ "delete database record", "delete storage object", "create invoice", "create purchase invoice", "approve expense", "post to ledger", "file VAT", "file CT600", "make bank payment", "close accounting period" ] }, "x-implementation": { "edgeFunction": "supabase/functions/financial-data-api/index.ts", "handler": "archiveV1BusinessDocument", "tests": [ "supabase/functions/financial-data-api/invoice_idempotency.test.ts" ] } } }, "/v1/business/companies/{company_id}/documents/{document_id}/replace": { "post": { "tags": [ "Business" ], "operationId": "replaceBusinessDocumentFile", "summary": "Replace a business document file", "description": "Uploads a replacement file and atomically switches the active document reference while retaining the previous file reference for evidence. Requires a reason and Idempotency-Key.", "security": [ { "ApiKeyAuth": [] } ], "parameters": [ { "$ref": "#/components/parameters/BusinessCompanyId" }, { "name": "document_id", "in": "path", "required": true, "description": "Document id whose active file should be replaced.", "schema": { "type": "string", "format": "uuid" } }, { "$ref": "#/components/parameters/RequestId" }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "required": [ "file_name", "file_content", "file_type", "reason" ], "properties": { "file_name": { "type": "string", "maxLength": 255 }, "file_content": { "type": "string", "description": "Base64-encoded replacement file." }, "file_type": { "type": "string" }, "reason": { "type": "string", "minLength": 5, "maxLength": 500 } } } } } }, "responses": { "200": { "description": "Business document file replaced, or an identical idempotent request replayed.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" }, "X-FIQ-Idempotency-Replayed": { "$ref": "#/components/headers/IdempotencyReplayed" } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "data", "meta" ], "properties": { "data": { "type": "object", "required": [ "object", "changed", "document", "previous_file_retained", "previous_file_version_id" ], "properties": { "object": { "const": "business_document_file_replacement" }, "changed": { "type": "boolean", "const": true }, "document": { "$ref": "#/components/schemas/BusinessDocument" }, "previous_file_retained": { "type": "boolean", "const": true }, "previous_file_version_id": { "type": "string", "format": "uuid" } } }, "meta": { "$ref": "#/components/schemas/V1BusinessDocumentUpdateMeta" } } } } } }, "400": { "$ref": "#/components/responses/V1BadRequest" }, "401": { "$ref": "#/components/responses/V1Unauthorised" }, "403": { "$ref": "#/components/responses/V1Forbidden" }, "404": { "$ref": "#/components/responses/V1NotFound" }, "409": { "$ref": "#/components/responses/V1Conflict" }, "503": { "$ref": "#/components/responses/V1Unavailable" } }, "x-financial-iq-safety": { "scope": "business.documents.replace_file", "requiredApiKeyPermission": "documents", "businessMutation": true, "directFinancialMutation": false, "writeLevel": "evidence", "requiresIdempotencyKey": true, "auditedEndpoint": "v1/business/companies/{company_id}/documents/{document_id}/replace", "forbiddenInThisRoute": [ "delete previous file", "delete database record", "create invoice", "create purchase invoice", "approve expense", "post to ledger", "file VAT", "file CT600", "make bank payment", "close accounting period" ] }, "x-implementation": { "edgeFunction": "supabase/functions/financial-data-api/index.ts", "handler": "replaceV1BusinessDocumentFile", "tests": [ "supabase/functions/financial-data-api/invoice_idempotency.test.ts" ] } } }, "/v1/business/companies/{company_id}/documents/{document_id}/versions": { "get": { "tags": [ "Business" ], "operationId": "listBusinessDocumentFileVersions", "summary": "List retained business document file versions", "description": "Returns safe metadata for the immutable file references retained when a business document was replaced. Storage paths, bucket names, content hashes and file contents are never returned.", "security": [ { "ApiKeyAuth": [] } ], "parameters": [ { "$ref": "#/components/parameters/BusinessCompanyId" }, { "name": "document_id", "in": "path", "required": true, "description": "Document whose retained file versions should be listed.", "schema": { "type": "string", "format": "uuid" } }, { "$ref": "#/components/parameters/Limit" }, { "$ref": "#/components/parameters/Offset" }, { "$ref": "#/components/parameters/RequestId" } ], "responses": { "200": { "description": "Retained business document file versions returned.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1BusinessDocumentFileVersionsResponse" } } } }, "400": { "$ref": "#/components/responses/V1BadRequest" }, "401": { "$ref": "#/components/responses/V1Unauthorised" }, "403": { "$ref": "#/components/responses/V1Forbidden" }, "404": { "$ref": "#/components/responses/V1NotFound" }, "500": { "$ref": "#/components/responses/V1ServerError" } }, "x-financial-iq-safety": { "scope": "business.documents.read_versions", "requiredApiKeyPermission": "documents", "businessMutation": false, "directFinancialMutation": false, "writeLevel": "read", "requiresIdempotencyKey": false, "auditedEndpoint": "v1/business/companies/{company_id}/documents/{document_id}/versions", "forbiddenInThisRoute": [ "return storage bucket", "return storage path", "return content hash", "return file contents", "delete previous file" ] }, "x-implementation": { "edgeFunction": "supabase/functions/financial-data-api/index.ts", "handler": "handleV1BusinessDocumentVersions", "tests": [ "supabase/functions/financial-data-api/invoice_idempotency.test.ts" ] } } }, "/v1/business/companies/{company_id}/documents/{document_id}/versions/{version_id}/download": { "get": { "tags": [ "Business" ], "operationId": "downloadBusinessDocumentFileVersion", "summary": "Download a retained business document file version", "description": "Generates a short-lived signed download URL for one retained file version belonging to an accessible business document. Storage paths, bucket names, content hashes and file contents are not returned in the API response.", "security": [ { "ApiKeyAuth": [] } ], "parameters": [ { "$ref": "#/components/parameters/BusinessCompanyId" }, { "name": "document_id", "in": "path", "required": true, "description": "Document that owns the retained file version.", "schema": { "type": "string", "format": "uuid" } }, { "name": "version_id", "in": "path", "required": true, "description": "Retained file version to download.", "schema": { "type": "string", "format": "uuid" } }, { "$ref": "#/components/parameters/RequestId" } ], "responses": { "200": { "description": "Short-lived retained file version download link returned.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1BusinessDocumentFileVersionDownloadResponse" } } } }, "400": { "$ref": "#/components/responses/V1BadRequest" }, "401": { "$ref": "#/components/responses/V1Unauthorised" }, "403": { "$ref": "#/components/responses/V1Forbidden" }, "404": { "$ref": "#/components/responses/V1NotFound" }, "500": { "$ref": "#/components/responses/V1ServerError" } }, "x-financial-iq-safety": { "scope": "business.documents.download_version", "requiredApiKeyPermission": "documents", "businessMutation": false, "directFinancialMutation": false, "writeLevel": "read", "requiresIdempotencyKey": false, "auditedEndpoint": "v1/business/companies/{company_id}/documents/{document_id}/versions/{version_id}/download", "linkExpiresInSeconds": 300, "forbiddenInThisRoute": [ "return storage bucket", "return storage path", "return content hash", "return file contents", "delete retained file" ] }, "x-implementation": { "edgeFunction": "supabase/functions/financial-data-api/index.ts", "handler": "handleV1BusinessDocumentVersionDownload", "tests": [ "supabase/functions/financial-data-api/invoice_idempotency.test.ts" ] } } }, "/v1/business/companies/{company_id}/documents/{document_id}/processing-status": { "get": { "tags": [ "Business" ], "operationId": "getBusinessDocumentProcessingStatus", "summary": "Get business document processing status", "description": "Returns safe OCR and document-processing state for one accessible business document. Queue error messages, OCR text, provider data and file contents are never returned.", "security": [ { "ApiKeyAuth": [] } ], "parameters": [ { "$ref": "#/components/parameters/BusinessCompanyId" }, { "name": "document_id", "in": "path", "required": true, "description": "Document whose processing state should be returned.", "schema": { "type": "string", "format": "uuid" } }, { "$ref": "#/components/parameters/RequestId" } ], "responses": { "200": { "description": "Safe business document processing status returned.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1BusinessDocumentProcessingStatusResponse" } } } }, "400": { "$ref": "#/components/responses/V1BadRequest" }, "401": { "$ref": "#/components/responses/V1Unauthorised" }, "403": { "$ref": "#/components/responses/V1Forbidden" }, "404": { "$ref": "#/components/responses/V1NotFound" }, "500": { "$ref": "#/components/responses/V1ServerError" } }, "x-financial-iq-safety": { "scope": "business.documents.processing_status", "requiredApiKeyPermission": "documents", "businessMutation": false, "directFinancialMutation": false, "writeLevel": "read", "requiresIdempotencyKey": false, "auditedEndpoint": "v1/business/companies/{company_id}/documents/{document_id}/processing-status", "forbiddenInThisRoute": [ "return OCR text", "return queue error message", "return provider payload", "create invoice", "post to ledger", "make bank payment" ] }, "x-implementation": { "edgeFunction": "supabase/functions/financial-data-api/index.ts", "handler": "handleV1BusinessDocumentProcessingStatus", "tests": [ "supabase/functions/financial-data-api/invoice_idempotency.test.ts" ] } } }, "/v1/business/companies/{company_id}/documents/{document_id}/extracted-data": { "get": { "tags": [ "Business" ], "operationId": "getBusinessDocumentExtractedData", "summary": "Get structured business document extraction", "description": "Returns safe structured OCR fields after processing completes. The response never includes raw OCR text, file contents, provider payloads or raw processing errors.", "security": [ { "ApiKeyAuth": [] } ], "parameters": [ { "$ref": "#/components/parameters/BusinessCompanyId" }, { "name": "document_id", "in": "path", "required": true, "description": "Document whose structured extraction should be returned.", "schema": { "type": "string", "format": "uuid" } }, { "$ref": "#/components/parameters/RequestId" } ], "responses": { "200": { "description": "Safe structured extraction returned, or marked not ready.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1BusinessDocumentExtractedDataResponse" } } } }, "400": { "$ref": "#/components/responses/V1BadRequest" }, "401": { "$ref": "#/components/responses/V1Unauthorised" }, "403": { "$ref": "#/components/responses/V1Forbidden" }, "404": { "$ref": "#/components/responses/V1NotFound" }, "500": { "$ref": "#/components/responses/V1ServerError" } }, "x-financial-iq-safety": { "scope": "business.documents.extracted_data", "requiredApiKeyPermission": "documents", "businessMutation": false, "directFinancialMutation": false, "writeLevel": "read", "requiresIdempotencyKey": false, "auditedEndpoint": "v1/business/companies/{company_id}/documents/{document_id}/extracted-data", "forbiddenInThisRoute": [ "return raw OCR text", "return file contents", "return provider payload", "create invoice", "post to ledger", "make bank payment" ] }, "x-implementation": { "edgeFunction": "supabase/functions/financial-data-api/index.ts", "handler": "handleV1BusinessDocumentExtractedData", "tests": [ "supabase/functions/financial-data-api/invoice_idempotency.test.ts" ] } } }, "/v1/business/companies/{company_id}/documents/{document_id}/download": { "get": { "tags": [ "Business" ], "operationId": "downloadBusinessDocument", "summary": "Download business document", "description": "Generates a short-lived signed download URL for one document belonging to an accessible business company. The response includes safe document metadata plus a temporary link only; it does not expose storage bucket names, private storage paths, raw OCR text or content hashes.", "security": [ { "ApiKeyAuth": [] } ], "parameters": [ { "$ref": "#/components/parameters/BusinessCompanyId" }, { "name": "document_id", "in": "path", "required": true, "description": "Document id to fetch.", "schema": { "type": "string", "format": "uuid" } }, { "$ref": "#/components/parameters/RequestId" } ], "responses": { "200": { "description": "Short-lived business document download link returned.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1BusinessDocumentDownloadResponse" } } } }, "400": { "description": "The company_id or document_id path parameter is invalid.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1ErrorEnvelope" } } } }, "401": { "description": "Missing, invalid, expired or inactive API key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LegacyErrorResponse" } } } }, "403": { "description": "The API key does not have document read permission, or the company is not accessible.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1ErrorEnvelope" } } } }, "404": { "description": "Business document not found.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1ErrorEnvelope" } } } }, "405": { "description": "Only GET is allowed for this route.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1ErrorEnvelope" } } } }, "500": { "description": "Generic server failure. Internal database and storage details must not be returned.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1ErrorEnvelope" } } } } }, "x-financial-iq-safety": { "scope": "business.documents.download", "businessMutation": false, "directFinancialMutation": false, "writeLevel": "read", "requiresIdempotencyKey": false, "auditedEndpoint": "v1/business/companies/{company_id}/documents/{document_id}/download", "requiredApiKeyPermission": "documents", "linkExpiresInSeconds": 300, "forbiddenInThisRoute": [ "return storage bucket", "return storage path", "return content hash", "return raw OCR text", "create invoice", "create purchase invoice", "approve expense", "post to ledger", "file VAT", "file CT600", "make bank payment", "close accounting period" ] }, "x-implementation": { "edgeFunction": "supabase/functions/financial-data-api/index.ts", "handler": "handleV1BusinessDocumentDownload", "tests": [ "supabase/functions/financial-data-api/invoice_idempotency.test.ts" ] } } }, "/v1/business/companies/{company_id}/approval-requests": { "get": { "tags": [ "Business" ], "operationId": "listBusinessApprovalRequests", "summary": "List business approval requests", "description": "Lists read-only approval request statuses for one accessible business company. This route does not approve, reject, cancel or otherwise mutate approvals.", "security": [ { "ApiKeyAuth": [] } ], "parameters": [ { "$ref": "#/components/parameters/BusinessCompanyId" }, { "$ref": "#/components/parameters/RequestId" }, { "name": "status", "in": "query", "required": false, "description": "Optional approval status filter.", "schema": { "type": "string" } }, { "name": "resource_type", "in": "query", "required": false, "description": "Optional resource type filter, such as invoice or purchase_invoice.", "schema": { "type": "string" } }, { "name": "resource_id", "in": "query", "required": false, "description": "Optional resource id filter. Resource identifiers are strings because some legacy approval records may use non-UUID ids.", "schema": { "type": "string" } }, { "name": "current_step_id", "in": "query", "required": false, "description": "Optional current approval workflow step id filter.", "schema": { "type": "string", "format": "uuid" } }, { "name": "limit", "in": "query", "required": false, "description": "Maximum number of approval requests to return. Values are clamped between 1 and 200.", "schema": { "type": "integer", "minimum": 1, "maximum": 200, "default": 50 } }, { "name": "offset", "in": "query", "required": false, "description": "Zero-based offset for paginating approval request results.", "schema": { "type": "integer", "minimum": 0, "default": 0 } } ], "responses": { "200": { "description": "Business approval requests returned.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1BusinessApprovalRequestListResponse" } } } }, "400": { "description": "The company_id or current_step_id filter is invalid.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1ErrorEnvelope" } } } }, "401": { "description": "Missing, invalid, expired or inactive API key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LegacyErrorResponse" } } } }, "403": { "description": "The API key does not have approval workflow read permission, or the company is not accessible.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1ErrorEnvelope" } } } }, "404": { "description": "Business company not found.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1ErrorEnvelope" } } } }, "405": { "description": "Only GET is allowed for this route.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1ErrorEnvelope" } } } }, "500": { "description": "Generic server failure. Internal database details must not be returned.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1ErrorEnvelope" } } } } }, "x-financial-iq-safety": { "scope": "business.approval_requests.read", "businessMutation": false, "directFinancialMutation": false, "writeLevel": "read", "requiresIdempotencyKey": false, "auditedEndpoint": "v1/business/companies/{company_id}/approval-requests", "requiredApiKeyPermission": "approval_workflow" }, "x-implementation": { "edgeFunction": "supabase/functions/financial-data-api/index.ts", "handler": "handleV1BusinessApprovalRequests", "tests": [ "supabase/functions/financial-data-api/invoice_idempotency.test.ts" ] } } }, "/v1/business/companies/{company_id}/approval-requests/{approval_request_id}": { "get": { "tags": [ "Business" ], "operationId": "getBusinessApprovalRequest", "summary": "Get one business approval request", "description": "Returns one read-only approval request status for an accessible business company. Inaccessible approval request IDs are returned as not found to avoid tenant leakage.", "security": [ { "ApiKeyAuth": [] } ], "parameters": [ { "$ref": "#/components/parameters/BusinessCompanyId" }, { "name": "approval_request_id", "in": "path", "required": true, "description": "Approval request id to fetch.", "schema": { "type": "string", "format": "uuid" } }, { "$ref": "#/components/parameters/RequestId" } ], "responses": { "200": { "description": "Business approval request returned.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1BusinessApprovalRequestResponse" } } } }, "400": { "description": "The company_id or approval_request_id path parameter is invalid.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1ErrorEnvelope" } } } }, "401": { "description": "Missing, invalid, expired or inactive API key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LegacyErrorResponse" } } } }, "403": { "description": "The API key does not have approval workflow read permission, or the company is not accessible.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1ErrorEnvelope" } } } }, "404": { "description": "Business approval request not found.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1ErrorEnvelope" } } } }, "405": { "description": "Only GET is allowed for this route.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1ErrorEnvelope" } } } }, "500": { "description": "Generic server failure. Internal database details must not be returned.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1ErrorEnvelope" } } } } }, "x-financial-iq-safety": { "scope": "business.approval_requests.read", "businessMutation": false, "directFinancialMutation": false, "writeLevel": "read", "requiresIdempotencyKey": false, "auditedEndpoint": "v1/business/companies/{company_id}/approval-requests/{approval_request_id}", "requiredApiKeyPermission": "approval_workflow" }, "x-implementation": { "edgeFunction": "supabase/functions/financial-data-api/index.ts", "handler": "handleV1BusinessApprovalRequestDetail", "tests": [ "supabase/functions/financial-data-api/invoice_idempotency.test.ts" ] } } }, "/v1/business/companies/{company_id}/approval-requests/{approval_request_id}/approve": { "post": { "tags": [ "Business" ], "operationId": "approveBusinessApprovalRequest", "summary": "Approve a business approval request", "description": "Approves the current step of one pending business approval request for an accessible company. This route records approval only; it does not send invoices, post journals, export payment runs, initiate bank payments or move money.", "security": [ { "ApiKeyAuth": [] } ], "parameters": [ { "$ref": "#/components/parameters/BusinessCompanyId" }, { "name": "approval_request_id", "in": "path", "required": true, "description": "Approval request id to approve.", "schema": { "type": "string", "format": "uuid" } }, { "$ref": "#/components/parameters/RequestId" }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BusinessApprovalRequestApproveRequest" } } } }, "responses": { "200": { "description": "Approval step recorded. The approval request is either fully approved or still pending on a later step.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" }, "Idempotency-Replayed": { "$ref": "#/components/headers/IdempotencyReplayed" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1BusinessApprovalRequestApproveResponse" } } } }, "400": { "description": "The path parameters or request body are invalid.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1ErrorEnvelope" } } } }, "401": { "description": "Missing, invalid, expired or inactive API key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LegacyErrorResponse" } } } }, "403": { "description": "The API key does not have approval workflow permission, or the actor is not assigned to the current approval step.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1ErrorEnvelope" } } } }, "404": { "description": "Business approval request or approval resource not found.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1ErrorEnvelope" } } } }, "405": { "description": "Only POST is allowed for this route.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1ErrorEnvelope" } } } }, "409": { "description": "The approval request is not pending, or the current step has already been approved by this actor.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1ErrorEnvelope" } } } }, "500": { "description": "Generic server failure. Internal database details must not be returned.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1ErrorEnvelope" } } } } }, "x-financial-iq-safety": { "scope": "business.approval_requests.approve", "businessMutation": true, "directFinancialMutation": false, "writeLevel": "human_approval", "requiresIdempotencyKey": true, "createsApprovalRequest": false, "approvesExistingApprovalRequest": true, "directExecution": false, "auditedEndpoint": "v1/business/companies/{company_id}/approval-requests/{approval_request_id}/approve", "requiredApiKeyPermission": "approval_workflow", "forbiddenInThisRoute": [ "send_invoice", "post_journal", "export_payment_run", "initiate_bank_payment", "mark_bill_paid", "settle_supplier_payment", "move_money", "file_vat", "file_ct600", "close_accounting_period" ] }, "x-implementation": { "edgeFunction": "supabase/functions/financial-data-api/index.ts", "handler": "handleV1BusinessApprovalRequestApprove", "tables": [ "approval_requests", "approval_request_actions" ], "tests": [ "supabase/functions/financial-data-api/invoice_idempotency.test.ts" ] } } }, "/v1/business/companies/{company_id}/approval-requests/{approval_request_id}/reject": { "post": { "tags": [ "Business" ], "operationId": "rejectBusinessApprovalRequest", "summary": "Reject a business approval request", "description": "Rejects one pending business approval request for an accessible company with a required reason. This route records rejection only; it does not send invoices, post journals, export payment runs, initiate bank payments or move money.", "security": [ { "ApiKeyAuth": [] } ], "parameters": [ { "$ref": "#/components/parameters/BusinessCompanyId" }, { "name": "approval_request_id", "in": "path", "required": true, "description": "Approval request id to reject.", "schema": { "type": "string", "format": "uuid" } }, { "$ref": "#/components/parameters/RequestId" }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BusinessApprovalRequestRejectRequest" } } } }, "responses": { "200": { "description": "Approval request rejected.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" }, "Idempotency-Replayed": { "$ref": "#/components/headers/IdempotencyReplayed" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1BusinessApprovalRequestRejectResponse" } } } }, "400": { "description": "The path parameters or request body are invalid.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1ErrorEnvelope" } } } }, "401": { "description": "Missing, invalid, expired or inactive API key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LegacyErrorResponse" } } } }, "403": { "description": "The API key does not have approval workflow permission, or the actor is not assigned to the current approval step.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1ErrorEnvelope" } } } }, "404": { "description": "Business approval request or approval resource not found.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1ErrorEnvelope" } } } }, "405": { "description": "Only POST is allowed for this route.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1ErrorEnvelope" } } } }, "409": { "description": "The approval request is not pending, or the current step has already been approved by this actor.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1ErrorEnvelope" } } } }, "500": { "description": "Generic server failure. Internal database details must not be returned.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1ErrorEnvelope" } } } } }, "x-financial-iq-safety": { "scope": "business.approval_requests.reject", "businessMutation": true, "directFinancialMutation": false, "writeLevel": "human_approval", "requiresIdempotencyKey": true, "createsApprovalRequest": false, "approvesExistingApprovalRequest": false, "directExecution": false, "auditedEndpoint": "v1/business/companies/{company_id}/approval-requests/{approval_request_id}/reject", "requiredApiKeyPermission": "approval_workflow", "forbiddenInThisRoute": [ "send_invoice", "post_journal", "export_payment_run", "initiate_bank_payment", "mark_bill_paid", "settle_supplier_payment", "move_money", "file_vat", "file_ct600", "close_accounting_period" ], "rejectsExistingApprovalRequest": true }, "x-implementation": { "edgeFunction": "supabase/functions/financial-data-api/index.ts", "handler": "handleV1BusinessApprovalRequestReject", "tables": [ "approval_requests", "approval_request_actions" ], "tests": [ "supabase/functions/financial-data-api/invoice_idempotency.test.ts" ] } } }, "/v1/business/companies/{company_id}/approval-requests/{approval_request_id}/request-info": { "post": { "tags": [ "Business" ], "operationId": "requestBusinessApprovalRequestInfo", "summary": "Request more information on a business approval request", "description": "Puts one pending business approval request on hold for an accessible company with a required message. This route records the information request only; it does not send invoices, post journals, export payment runs, initiate bank payments or move money.", "security": [ { "ApiKeyAuth": [] } ], "parameters": [ { "$ref": "#/components/parameters/BusinessCompanyId" }, { "name": "approval_request_id", "in": "path", "required": true, "description": "Approval request id to put on hold while more information is requested.", "schema": { "type": "string", "format": "uuid" } }, { "$ref": "#/components/parameters/RequestId" }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BusinessApprovalRequestInfoRequest" } } } }, "responses": { "200": { "description": "More information requested and approval request put on hold.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" }, "Idempotency-Replayed": { "$ref": "#/components/headers/IdempotencyReplayed" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1BusinessApprovalRequestInfoResponse" } } } }, "400": { "description": "The path parameters or request body are invalid.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1ErrorEnvelope" } } } }, "401": { "description": "Missing, invalid, expired or inactive API key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LegacyErrorResponse" } } } }, "403": { "description": "The API key does not have approval workflow permission, or the actor is not assigned to the current approval step.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1ErrorEnvelope" } } } }, "404": { "description": "Business approval request or approval resource not found.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1ErrorEnvelope" } } } }, "405": { "description": "Only POST is allowed for this route.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1ErrorEnvelope" } } } }, "409": { "description": "The approval request is not pending, or the current step has already been approved by this actor.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1ErrorEnvelope" } } } }, "500": { "description": "Generic server failure. Internal database details must not be returned.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1ErrorEnvelope" } } } } }, "x-financial-iq-safety": { "scope": "business.approval_requests.request_info", "businessMutation": true, "directFinancialMutation": false, "writeLevel": "human_approval", "requiresIdempotencyKey": true, "createsApprovalRequest": false, "approvesExistingApprovalRequest": false, "directExecution": false, "auditedEndpoint": "v1/business/companies/{company_id}/approval-requests/{approval_request_id}/request-info", "requiredApiKeyPermission": "approval_workflow", "forbiddenInThisRoute": [ "send_invoice", "post_journal", "export_payment_run", "initiate_bank_payment", "mark_bill_paid", "settle_supplier_payment", "move_money", "file_vat", "file_ct600", "close_accounting_period" ], "rejectsExistingApprovalRequest": false, "requestsMoreInformation": true }, "x-implementation": { "edgeFunction": "supabase/functions/financial-data-api/index.ts", "handler": "handleV1BusinessApprovalRequestInfo", "tables": [ "approval_requests", "approval_request_actions" ], "tests": [ "supabase/functions/financial-data-api/invoice_idempotency.test.ts" ] } } }, "/v1/business/companies/{company_id}/audit-logs": { "get": { "tags": [ "Business" ], "operationId": "listBusinessAuditLogs", "summary": "List business audit logs", "description": "Lists safe audit-log timeline entries for one accessible business company. This route is read-only and does not expose raw old/new values, metadata, actor profile data, IP addresses or user agents.", "security": [ { "ApiKeyAuth": [] } ], "parameters": [ { "$ref": "#/components/parameters/BusinessCompanyId" }, { "$ref": "#/components/parameters/RequestId" }, { "name": "action", "in": "query", "required": false, "description": "Filter by exact audit action.", "schema": { "type": "string", "minLength": 1, "maxLength": 160 } }, { "name": "resource_type", "in": "query", "required": false, "description": "Filter by resource type.", "schema": { "type": "string", "minLength": 1, "maxLength": 160 } }, { "name": "resource_id", "in": "query", "required": false, "description": "Filter by resource id.", "schema": { "type": "string", "minLength": 1, "maxLength": 160 } }, { "name": "created_from", "in": "query", "required": false, "description": "Inclusive lower bound for the audit timestamp.", "schema": { "type": "string", "format": "date-time" } }, { "name": "created_to", "in": "query", "required": false, "description": "Inclusive upper bound for the audit timestamp.", "schema": { "type": "string", "format": "date-time" } }, { "name": "limit", "in": "query", "required": false, "description": "Maximum number of records to return. Values are clamped between 1 and 100.", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 50 } }, { "name": "offset", "in": "query", "required": false, "description": "Zero-based offset for paginating results.", "schema": { "type": "integer", "minimum": 0, "default": 0 } } ], "responses": { "200": { "description": "Business audit-log timeline returned.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BusinessAuditLogListResponse" } } } }, "400": { "description": "The company_id or filter is invalid.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1ErrorEnvelope" } } } }, "401": { "description": "Missing, invalid, expired or inactive API key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LegacyErrorResponse" } } } }, "403": { "description": "The API key does not have evidence permission, or the master key is not allowed to access the company.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1ErrorEnvelope" } } } }, "404": { "description": "Business company not found.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1ErrorEnvelope" } } } }, "405": { "description": "Only GET is allowed for this route.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1ErrorEnvelope" } } } }, "500": { "description": "Generic server failure. Internal database details must not be returned.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1ErrorEnvelope" } } } } }, "x-financial-iq-safety": { "scope": "business.audit_logs.read", "businessMutation": false, "directFinancialMutation": false, "writeLevel": "read", "readOnly": true, "requiresIdempotencyKey": false, "auditedEndpoint": "v1/business/companies/{company_id}/audit-logs", "requiredApiKeyPermission": "evidence", "redactions": [ "metadata", "old_values", "new_values", "ip_address", "user_agent", "profile_data", "internal_actor_ids" ], "doesNot": [ "create_audit_log", "update_audit_log", "delete_audit_log", "export_audit_log", "replay_action", "change_books", "submit_externally", "move_money" ] }, "x-implementation": { "edgeFunction": "supabase/functions/financial-data-api/index.ts", "handler": "handleV1BusinessAuditLogs", "tests": [ "supabase/functions/financial-data-api/invoice_idempotency.test.ts" ] } } }, "/v1/business/companies/{company_id}/audit-logs/{audit_log_id}": { "get": { "tags": [ "Business" ], "operationId": "getBusinessAuditLog", "summary": "Get business audit log", "description": "Returns one safe audit-log timeline entry for an accessible business company. This route is read-only and does not expose raw audit payloads or actor profile data.", "security": [ { "ApiKeyAuth": [] } ], "parameters": [ { "$ref": "#/components/parameters/BusinessCompanyId" }, { "name": "audit_log_id", "in": "path", "required": true, "description": "Audit log id.", "schema": { "type": "string", "format": "uuid" } }, { "$ref": "#/components/parameters/RequestId" } ], "responses": { "200": { "description": "Business audit-log timeline entry returned.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BusinessAuditLogDetailResponse" } } } }, "400": { "description": "The company_id or audit_log_id is invalid.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1ErrorEnvelope" } } } }, "401": { "description": "Missing, invalid, expired or inactive API key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LegacyErrorResponse" } } } }, "403": { "description": "The API key does not have evidence permission, or the master key is not allowed to access the company.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1ErrorEnvelope" } } } }, "404": { "description": "Business audit log not found.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1ErrorEnvelope" } } } }, "405": { "description": "Only GET is allowed for this route.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1ErrorEnvelope" } } } }, "500": { "description": "Generic server failure. Internal database details must not be returned.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1ErrorEnvelope" } } } } }, "x-financial-iq-safety": { "scope": "business.audit_logs.read", "businessMutation": false, "directFinancialMutation": false, "writeLevel": "read", "readOnly": true, "requiresIdempotencyKey": false, "auditedEndpoint": "v1/business/companies/{company_id}/audit-logs/{audit_log_id}", "requiredApiKeyPermission": "evidence", "redactions": [ "metadata", "old_values", "new_values", "ip_address", "user_agent", "profile_data", "internal_actor_ids" ], "doesNot": [ "create_audit_log", "update_audit_log", "delete_audit_log", "export_audit_log", "replay_action", "change_books", "submit_externally", "move_money" ] }, "x-implementation": { "edgeFunction": "supabase/functions/financial-data-api/index.ts", "handler": "handleV1BusinessAuditLogDetail", "tests": [ "supabase/functions/financial-data-api/invoice_idempotency.test.ts" ] } } }, "/v1/business/companies/{company_id}/evidence-bundles/{resource_type}/{resource_id}": { "get": { "tags": [ "Business" ], "operationId": "getBusinessCompanyEvidenceBundle", "summary": "Get a company-scoped evidence bundle", "description": "Returns safe evidence metadata for a supported resource inside a business company. It does not return signed document URLs, raw provider payloads, bank account numbers or sort codes.", "security": [ { "ApiKeyAuth": [] } ], "parameters": [ { "name": "company_id", "in": "path", "required": true, "description": "Business company id.", "schema": { "type": "string", "format": "uuid" } }, { "name": "resource_type", "in": "path", "required": true, "description": "Public evidence resource type. Invoice is implemented first; other contract types return not_supported until implemented.", "schema": { "type": "string" } }, { "name": "resource_id", "in": "path", "required": true, "description": "Company-scoped resource id.", "schema": { "type": "string", "format": "uuid" } }, { "$ref": "#/components/parameters/RequestId" } ], "responses": { "200": { "description": "Evidence bundle returned. The bundle_status field distinguishes complete, partial, missing, not_supported and lookup_failed results.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EvidenceBundle" } } } }, "400": { "description": "The company_id or resource_id path parameter is not a valid UUID.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1ErrorEnvelope" } } } }, "403": { "description": "The API key does not have evidence read permission.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1ErrorEnvelope" } } } }, "404": { "description": "The source record was not found inside the caller company.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1ErrorEnvelope" } } } }, "405": { "description": "Only GET is allowed for this route.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1ErrorEnvelope" } } } } }, "x-financial-iq-safety": { "requiresApiKey": true, "scope": "business.evidence.read", "directFinancialMutation": false, "writeLevel": "read", "requiresIdempotencyKey": false, "auditedEndpoint": "v1/business/companies/{company_id}/evidence-bundles/{resource_type}/{resource_id}", "returnsSignedDocumentUrls": false, "supportedResourceTypes": [ "invoice" ], "bundleStatusValues": [ "complete", "partial", "missing", "not_supported", "lookup_failed" ] }, "x-implementation": { "edgeFunction": "supabase/functions/financial-data-api/index.ts", "handler": "handleV1BusinessEvidenceBundle", "tests": [ "supabase/functions/financial-data-api/invoice_idempotency.test.ts", "supabase/functions/financial-data-api/v1_openapi_contract.test.ts" ] } } }, "/v1/invoices/drafts": { "post": { "tags": [ "Invoices" ], "operationId": "createDraftInvoice", "summary": "Create a draft sales invoice", "description": "Creates a draft invoice only. The route requires an API key with invoice permission and an Idempotency-Key header. The request may omit status; if status is supplied it must be draft. It does not issue, send, delete, file tax, create direct journals or make bank payments.", "security": [ { "ApiKeyAuth": [] } ], "parameters": [ { "$ref": "#/components/parameters/RequestId" }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DraftInvoiceCreateRequest" }, "examples": { "consultingInvoice": { "summary": "Draft consulting invoice", "value": { "customer_id": "7c3f0d29-5af1-42c1-b8bb-2e4bb3db37e4", "invoice_date": "2026-07-04", "due_date": "2026-07-18", "payment_terms_days": 14, "currency": "GBP", "line_items": [ { "description": "Consulting services", "quantity": 4, "unit_price": 150, "vat_rate": 20 } ] } } } } } }, "responses": { "201": { "description": "Draft invoice created, or an identical idempotent request replayed.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" }, "X-FIQ-Idempotency-Replayed": { "$ref": "#/components/headers/IdempotencyReplayed" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1InvoiceResponse" } } } }, "400": { "description": "Invalid JSON, missing or invalid idempotency key, invalid request body, or non-draft status.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LegacyErrorResponse" } } } }, "401": { "description": "Missing, invalid, expired or inactive API key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LegacyErrorResponse" } } } }, "403": { "description": "The API key does not have invoice permission.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1ErrorEnvelope" } } } }, "405": { "description": "Only POST is allowed for this route.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LegacyErrorResponse" } } } }, "409": { "description": "The same idempotency key was reused with a different request body.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1ErrorEnvelope" } } } }, "500": { "description": "Generic server failure. Internal database or provider details must not be returned.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1ErrorEnvelope" } } } } }, "x-financial-iq-safety": { "writeLevel": "draft", "requiresIdempotencyKey": true, "auditedEndpoint": "v1/invoices/drafts", "forbiddenInThisRoute": [ "issue invoice", "send invoice", "delete invoice", "file VAT", "file CT600", "file Companies House accounts", "make bank payment", "create direct journal", "close accounting period" ], "requiresApiKey": true, "apiKeysAllowed": true, "requiresUserBearerToken": false, "scope": "business.invoices.draft", "requiredPermission": "invoices", "businessMutation": true, "directFinancialMutation": true }, "x-implementation": { "edgeFunction": "supabase/functions/financial-data-api/index.ts", "handler": "handleV1DraftInvoices", "tests": [ "supabase/functions/financial-data-api/invoice_idempotency.test.ts", "supabase/functions/financial-data-api/legacy_consumers_contract.test.ts" ] } } }, "/v1/invoices/{invoice_id}/send": { "post": { "tags": [ "Invoices" ], "operationId": "requestInvoiceSendApproval", "summary": "Request approval to send a draft invoice", "description": "Creates or reuses a pending approval request for sending a draft invoice. Guarded mode writes the approval request, submission action and required audit evidence atomically. The route requires invoice and approval-workflow permissions plus an Idempotency-Key header. It does not issue or send the invoice directly.", "security": [ { "ApiKeyAuth": [] } ], "parameters": [ { "name": "invoice_id", "in": "path", "required": true, "description": "Draft invoice id to submit for send approval.", "schema": { "type": "string", "format": "uuid" } }, { "$ref": "#/components/parameters/RequestId" }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InvoiceSendApprovalRequest" }, "examples": { "customerApproved": { "summary": "Send approval request", "value": { "reason": "Customer has approved the draft" } } } } } }, "responses": { "202": { "description": "Approval request created, or an identical idempotent request replayed.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" }, "X-FIQ-Idempotency-Replayed": { "$ref": "#/components/headers/IdempotencyReplayed" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1ApprovalRequestResponse" } } } }, "400": { "description": "Invalid JSON or missing/invalid idempotency key.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LegacyErrorResponse" } } } }, "401": { "description": "Missing, invalid, expired or inactive API key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LegacyErrorResponse" } } } }, "403": { "description": "The API key does not have invoice or approval-workflow permission.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LegacyErrorResponse" } } } }, "404": { "description": "Invoice not found.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LegacyErrorResponse" } } } }, "405": { "description": "Only POST is allowed for this route.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LegacyErrorResponse" } } } }, "409": { "description": "The invoice is not draft, idempotency key was reused with a changed body, or no invoice approval workflow is configured.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LegacyErrorResponse" } } } }, "500": { "description": "Generic server failure. Internal database or provider details must not be returned.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1ErrorEnvelope" } } } } }, "x-financial-iq-safety": { "writeLevel": "human_approval", "requiresIdempotencyKey": true, "auditedEndpoint": "v1/invoices/{invoice_id}/send", "createsApprovalRequest": true, "directExecution": false, "atomicAuditAfterActivation": true, "masterKeyAllowlistSupported": true, "activationGate": "FINANCIAL_API_V1_GUARDED_INVOICE_SEND_APPROVAL_ENABLED", "databaseFunction": "public.create_invoice_send_approval_api_v1_atomic", "missingGuardedBridgeBehavior": "fail_closed_503", "forbiddenInThisRoute": [ "issue invoice immediately", "send invoice immediately", "delete invoice", "file VAT", "file CT600", "file Companies House accounts", "make bank payment", "create direct journal", "close accounting period" ], "requiresApiKey": true, "apiKeysAllowed": true, "requiresUserBearerToken": false, "scope": "business.invoices.send", "requiredPermissions": [ "invoices", "approval_workflow" ], "businessMutation": true, "directFinancialMutation": false }, "x-implementation": { "edgeFunction": "supabase/functions/financial-data-api/index.ts", "handler": "handleV1InvoiceSendApproval", "tests": [ "supabase/functions/financial-data-api/invoice_idempotency.test.ts", "supabase/functions/financial-data-api/v1_openapi_contract.test.ts", "supabase/tests/api_business_invoice_send_approval_hardening.sql", "scripts/run-api-invoice-send-approval-concurrency.mjs" ] } } }, "/v1/evidence-bundles/{resource_type}/{resource_id}": { "get": { "tags": [ "Evidence" ], "operationId": "getEvidenceBundle", "summary": "Get an evidence bundle for a supported resource", "description": "Returns safe, company-scoped evidence metadata for a supported business resource. It does not return signed document URLs, raw provider payloads, bank account numbers or sort codes.", "security": [ { "ApiKeyAuth": [] } ], "parameters": [ { "name": "resource_type", "in": "path", "required": true, "description": "Public evidence resource type. Invoice is implemented first; other contract types return not_supported until implemented.", "schema": { "type": "string" } }, { "name": "resource_id", "in": "path", "required": true, "description": "Company-scoped resource id.", "schema": { "type": "string", "format": "uuid" } }, { "$ref": "#/components/parameters/RequestId" } ], "responses": { "200": { "description": "Evidence bundle returned. The bundle_status field distinguishes complete, partial, missing, not_supported and lookup_failed results.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EvidenceBundle" } } } }, "400": { "description": "The resource id is not a UUID.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1ErrorEnvelope" } } } }, "403": { "description": "The API key does not have evidence read permission.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1ErrorEnvelope" } } } }, "404": { "description": "The source record was not found inside the caller company.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1ErrorEnvelope" } } } }, "405": { "description": "Only GET is allowed for this route.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1ErrorEnvelope" } } } } }, "x-financial-iq-safety": { "requiresApiKey": true, "scope": "business.evidence.read", "directFinancialMutation": false, "writeLevel": "read", "requiresIdempotencyKey": false, "auditedEndpoint": "v1/evidence-bundles/{resource_type}/{resource_id}", "returnsSignedDocumentUrls": false, "supportedResourceTypes": [ "invoice" ], "bundleStatusValues": [ "complete", "partial", "missing", "not_supported", "lookup_failed" ] }, "x-implementation": { "edgeFunction": "supabase/functions/financial-data-api/index.ts", "handler": "handleV1EvidenceBundle", "tests": [ "supabase/functions/financial-data-api/invoice_idempotency.test.ts", "supabase/functions/financial-data-api/v1_openapi_contract.test.ts" ] } } }, "/v1/webhooks/deliveries": {"get":{"operationId":"listWebhookDeliveries","summary":"List webhook delivery status","description":"Returns safe delivery status and retry evidence for webhook events belonging to the API key company. Payload snapshots and response bodies are never exposed.","security":[{"ApiKeyAuth":[]}],"parameters":[{"$ref":"#/components/parameters/RequestId"},{"name":"endpoint_id","in":"query","required":false,"schema":{"type":"string","format":"uuid"}},{"name":"status","in":"query","required":false,"schema":{"type":"string","enum":["queued","sending","succeeded","failed","dead_letter"]}},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","minimum":1,"maximum":200,"default":100}},{"name":"offset","in":"query","required":false,"schema":{"type":"integer","minimum":0,"default":0}}],"responses":{"200":{"description":"Webhook deliveries returned.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/V1WebhookDeliveryListResponse"}}}},"400":{"description":"A delivery filter is invalid.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/V1ErrorEnvelope"}}}},"401":{"description":"Missing, invalid, expired or inactive API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/LegacyErrorResponse"}}}},"403":{"description":"The API key does not have webhook management permission.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/V1ErrorEnvelope"}}}},"500":{"description":"Generic server failure.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/V1ErrorEnvelope"}}}}},"x-implementation":{"handler":"handleV1WebhookEndpoints"},"x-financial-iq-safety":{"requiresApiKey":true,"scope":"business.webhooks.deliveries.read","requiredPermission":"webhooks","businessMutation":false,"directFinancialMutation":false,"writeLevel":"read","auditedEndpoint":"v1/webhooks/deliveries","requiresIdempotencyKey":false,"exposesSigningSecret":false,"exposesPayloadSnapshot":false}}}, "/v1/webhooks/endpoints": { "get": { "operationId": "listWebhookEndpoints", "summary": "List public API webhook endpoints", "description": "Returns configured webhook endpoints for the API key company. Signing-secret vault references are never exposed.", "security": [ { "ApiKeyAuth": [] } ], "parameters": [ { "$ref": "#/components/parameters/RequestId" } ], "x-implementation": { "handler": "handleV1WebhookEndpoints" }, "x-financial-iq-safety": { "requiresApiKey": true, "scope": "business.webhooks.manage", "directFinancialMutation": false, "writeLevel": "read", "auditedEndpoint": "v1/webhooks/endpoints", "exposesSigningSecret": false, "requiresIdempotencyKey": false }, "responses": { "200": { "description": "Webhook endpoints returned.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1WebhookEndpointListResponse" } } } }, "403": { "description": "API key does not have webhook management permission.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1ErrorEnvelope" } } } } } }, "post": { "operationId": "createWebhookEndpoint", "summary": "Create public API webhook endpoint", "description": "Creates an HTTPS webhook endpoint and returns the generated signing secret once. The stored endpoint contains only a vault reference and short preview.", "security": [ { "ApiKeyAuth": [] } ], "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" }, { "$ref": "#/components/parameters/RequestId" } ], "x-implementation": { "handler": "handleV1WebhookEndpoints" }, "x-financial-iq-safety": { "requiresApiKey": true, "scope": "business.webhooks.manage", "directFinancialMutation": false, "writeLevel": "configuration", "requiresIdempotencyKey": true, "auditedEndpoint": "v1/webhooks/endpoints", "storesRawSigningSecret": false, "returnsSigningSecretOnce": true }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookEndpointCreateRequest" } } } }, "responses": { "201": { "description": "Webhook endpoint created.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" }, "X-FIQ-Idempotency-Replayed": { "$ref": "#/components/headers/IdempotencyReplayed" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1WebhookEndpointSecretResponse" } } } }, "400": { "description": "Invalid webhook endpoint payload." }, "403": { "description": "API key does not have webhook management permission." } } } }, "/v1/webhooks/endpoints/{endpoint_id}": { "get": { "operationId": "getWebhookEndpoint", "summary": "Get public API webhook endpoint", "security": [ { "ApiKeyAuth": [] } ], "parameters": [ { "name": "endpoint_id", "in": "path", "required": true, "description": "Webhook endpoint id.", "schema": { "type": "string", "format": "uuid" } }, { "$ref": "#/components/parameters/RequestId" } ], "x-implementation": { "handler": "handleV1WebhookEndpoints" }, "x-financial-iq-safety": { "requiresApiKey": true, "scope": "business.webhooks.manage", "directFinancialMutation": false, "writeLevel": "read", "exposesSigningSecret": false, "auditedEndpoint": "v1/webhooks/endpoints/{endpoint_id}", "requiresIdempotencyKey": false }, "responses": { "200": { "description": "Webhook endpoint returned.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1WebhookEndpointResponse" } } } }, "404": { "description": "Webhook endpoint not found." } } }, "delete": { "operationId": "revokeWebhookEndpoint", "summary": "Revoke public API webhook endpoint", "description": "Revokes a webhook endpoint without deleting its audit history.", "security": [ { "ApiKeyAuth": [] } ], "parameters": [ { "name": "endpoint_id", "in": "path", "required": true, "description": "Webhook endpoint id.", "schema": { "type": "string", "format": "uuid" } }, { "$ref": "#/components/parameters/IdempotencyKey" }, { "$ref": "#/components/parameters/RequestId" } ], "x-implementation": { "handler": "handleV1WebhookEndpoints" }, "x-financial-iq-safety": { "requiresApiKey": true, "scope": "business.webhooks.manage", "directFinancialMutation": false, "writeLevel": "configuration", "requiresIdempotencyKey": true, "auditedEndpoint": "v1/webhooks/endpoints/{endpoint_id}", "deletesEndpointRow": false }, "responses": { "200": { "description": "Webhook endpoint revoked.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" }, "X-FIQ-Idempotency-Replayed": { "$ref": "#/components/headers/IdempotencyReplayed" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1WebhookEndpointResponse" } } } }, "404": { "description": "Webhook endpoint not found." } } } }, "/v1/webhooks/endpoints/{endpoint_id}/rotate-secret": { "post": { "operationId": "rotateWebhookEndpointSecret", "summary": "Rotate public API webhook signing secret", "description": "Generates a replacement signing secret, stores it in Vault and returns the new secret once.", "security": [ { "ApiKeyAuth": [] } ], "parameters": [ { "name": "endpoint_id", "in": "path", "required": true, "description": "Webhook endpoint id.", "schema": { "type": "string", "format": "uuid" } }, { "$ref": "#/components/parameters/IdempotencyKey" }, { "$ref": "#/components/parameters/RequestId" } ], "x-implementation": { "handler": "handleV1WebhookEndpoints" }, "x-financial-iq-safety": { "requiresApiKey": true, "scope": "business.webhooks.manage", "directFinancialMutation": false, "writeLevel": "configuration", "requiresIdempotencyKey": true, "auditedEndpoint": "v1/webhooks/endpoints/{endpoint_id}/rotate-secret", "storesRawSigningSecret": false, "returnsSigningSecretOnce": true }, "responses": { "200": { "description": "Webhook signing secret rotated.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" }, "X-FIQ-Idempotency-Replayed": { "$ref": "#/components/headers/IdempotencyReplayed" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1WebhookEndpointSecretResponse" } } } }, "404": { "description": "Webhook endpoint not found." }, "409": { "description": "Webhook endpoint cannot be rotated." } } } }, "/v1/personal/summary": { "get": { "tags": [ "Personal" ], "operationId": "getPersonalFinancialSummary", "summary": "Get personal financial summary", "description": "Returns aggregate personal account, asset, liability, budget and goal totals for the bearer-token user. Requires all component personal read consents. This route is read-only and does not return account numbers, sort codes, provider tokens, hashes or individual transaction rows.", "security": [ { "BearerAuth": [] } ], "parameters": [ { "$ref": "#/components/parameters/RequestId" } ], "responses": { "200": { "description": "User-authorised personal financial summary returned.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PersonalFinancialSummaryResponse" } } } }, "401": { "description": "Missing, invalid or expired bearer user token.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1ErrorEnvelope" } } } }, "403": { "description": "The bearer token does not grant every required personal summary consent scope.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1ErrorEnvelope" } } } }, "405": { "description": "Only GET is allowed for this route.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1ErrorEnvelope" } } } }, "500": { "description": "Generic server failure. Internal database details must not be returned.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1ErrorEnvelope" } } } } }, "x-financial-iq-safety": { "requiresApiKey": false, "apiKeysAllowed": false, "requiresUserBearerToken": true, "scopes": [ "personal.accounts.read", "personal.assets.read", "personal.liabilities.read", "personal.budgets.read", "personal.goals.read" ], "scopeFamily": "personal.summary", "personalData": true, "businessMutation": false, "directFinancialMutation": false, "writeLevel": "read", "requiresIdempotencyKey": false, "serverSideAggregation": true, "redactedFields": [ "account_number", "account_number_ct", "account_number_hash", "sort_code", "sort_code_ct", "sort_code_hash", "access_token_ct", "refresh_token_ct", "provider_metadata" ], "doesNot": [ "return_individual_transactions", "return_bank_statement_lines", "connect_bank_feeds", "move_money", "post_ledger_entries", "raise_invoices", "file_tax" ], "auditedEndpoint": "v1/personal/summary" }, "x-implementation": { "edgeFunction": "financial-data-api", "handler": "handleV1PersonalSummary", "sourceFile": "supabase/functions/financial-data-api/v1.ts" } } }, "/v1/personal/position": { "get": { "tags": [ "Personal" ], "operationId": "getPersonalOwnerPosition", "summary": "Get personal owner-director position", "description": "Returns the bearer-token user personal financial position with redacted summaries for explicitly linked businesses that the user can currently access. Requires dedicated position consent, all personal summary read consents and business-link read consent. This route is read-only and does not return raw business records, provider payloads, bank details or API keys.", "security": [ { "BearerAuth": [] } ], "parameters": [ { "$ref": "#/components/parameters/RequestId" }, { "name": "from_date", "in": "query", "required": false, "description": "Inclusive business-summary period start date in YYYY-MM-DD format. Defaults to 2020-01-01.", "schema": { "type": "string", "format": "date", "pattern": "^\\d{4}-\\d{2}-\\d{2}$" } }, { "name": "to_date", "in": "query", "required": false, "description": "Inclusive business-summary period end date in YYYY-MM-DD format. Defaults to today.", "schema": { "type": "string", "format": "date", "pattern": "^\\d{4}-\\d{2}-\\d{2}$" } } ], "responses": { "200": { "description": "User-authorised personal owner position returned.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PersonalOwnerPositionResponse" } } } }, "401": { "description": "Missing, invalid or expired bearer user token.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1ErrorEnvelope" } } } }, "403": { "description": "The bearer token does not grant every required position, personal summary and business-link consent scope.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1ErrorEnvelope" } } } }, "405": { "description": "Only GET is allowed for this route.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1ErrorEnvelope" } } } }, "500": { "description": "Generic server failure. Internal database details must not be returned.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1ErrorEnvelope" } } } } }, "x-financial-iq-safety": { "requiresApiKey": false, "apiKeysAllowed": false, "requiresUserBearerToken": true, "scopes": [ "personal.position.read", "personal.accounts.read", "personal.assets.read", "personal.liabilities.read", "personal.budgets.read", "personal.goals.read", "personal.business_links.read" ], "scopeFamily": "personal.position", "personalData": true, "businessMutation": false, "directFinancialMutation": false, "writeLevel": "read", "requiresIdempotencyKey": false, "serverSideAggregation": true, "redactedFields": [ "account_number", "account_number_ct", "account_number_hash", "sort_code", "sort_code_ct", "sort_code_hash", "access_token_ct", "refresh_token_ct", "provider_metadata", "raw_business_records" ], "doesNot": [ "return_business_api_keys", "return_bank_details", "return_raw_business_records", "return_provider_payloads", "change_business_books", "move_money", "post_ledger_entries", "raise_invoices", "file_tax" ], "auditedEndpoint": "v1/personal/position" }, "x-implementation": { "edgeFunction": "financial-data-api", "handler": "handleV1PersonalOwnerPosition", "sourceFile": "supabase/functions/financial-data-api/v1.ts" } } }, "/v1/personal/reports/net-worth": { "get": { "tags": [ "Personal" ], "operationId": "getPersonalNetWorthReport", "summary": "Get personal net-worth report", "description": "Returns aggregate personal net-worth totals for the bearer-token user. This route reads personal accounts, assets and liabilities only, returns grouped totals, and does not expose bank details, transactions, budgets, goals or business ledger data.", "security": [ { "BearerAuth": [] } ], "parameters": [ { "$ref": "#/components/parameters/RequestId" } ], "responses": { "200": { "description": "User-authorised personal net-worth report returned.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PersonalNetWorthReportResponse" } } } }, "401": { "description": "Missing, invalid or expired bearer user token.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1ErrorEnvelope" } } } }, "403": { "description": "The bearer token does not grant every required personal net-worth consent scope.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1ErrorEnvelope" } } } }, "405": { "description": "Only GET is allowed for this route.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1ErrorEnvelope" } } } }, "500": { "description": "Generic server failure. Internal database details must not be returned.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1ErrorEnvelope" } } } } }, "x-financial-iq-safety": { "requiresApiKey": false, "apiKeysAllowed": false, "requiresUserBearerToken": true, "scopes": [ "personal.accounts.read", "personal.assets.read", "personal.liabilities.read" ], "scopeFamily": "personal.net_worth", "personalData": true, "businessMutation": false, "directFinancialMutation": false, "writeLevel": "read", "requiresIdempotencyKey": false, "serverSideAggregation": true, "redactedFields": [ "account_number", "sort_code", "account_number_ct", "sort_code_ct", "account_number_hash", "sort_code_hash", "access_token_ct", "refresh_token_ct", "provider_metadata", "transaction_rows", "budget_rows", "goal_rows" ], "doesNot": [ "return_individual_transactions", "return_account_numbers", "return_sort_codes", "return_bank_statement_lines", "return_budgets", "return_goals", "connect_bank_feeds", "move_money", "post_ledger_entries", "raise_invoices", "file_tax", "mutate_business_books" ], "auditedEndpoint": "v1/personal/reports/net-worth" }, "x-implementation": { "edgeFunction": "financial-data-api", "handler": "handleV1PersonalNetWorthReport", "sourceFile": "supabase/functions/financial-data-api/v1.ts" } } }, "/v1/personal/reports/cash-flow": { "get": { "tags": [ "Personal" ], "operationId": "getPersonalCashFlowReport", "summary": "Get personal cash-flow report", "description": "Returns transaction-backed personal income, expense and net cash-flow totals for a required date range. This route is read-only and returns grouped totals only, not individual transaction rows.", "security": [ { "BearerAuth": [] } ], "parameters": [ { "$ref": "#/components/parameters/RequestId" }, { "name": "from_date", "in": "query", "required": true, "description": "Inclusive period start date in YYYY-MM-DD format.", "schema": { "type": "string", "format": "date", "pattern": "^\\d{4}-\\d{2}-\\d{2}$" } }, { "name": "to_date", "in": "query", "required": true, "description": "Inclusive period end date in YYYY-MM-DD format.", "schema": { "type": "string", "format": "date", "pattern": "^\\d{4}-\\d{2}-\\d{2}$" } }, { "name": "account_id", "in": "query", "required": false, "description": "Optional personal account ID filter.", "schema": { "type": "string", "format": "uuid" } }, { "name": "category_id", "in": "query", "required": false, "description": "Optional personal category ID filter. Cannot be combined with uncategorised=true.", "schema": { "type": "string", "format": "uuid" } }, { "name": "uncategorised", "in": "query", "required": false, "description": "When true, include only uncategorised personal transactions.", "schema": { "type": "boolean", "default": false } } ], "responses": { "200": { "description": "User-authorised personal cash-flow report returned.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PersonalCashFlowReportResponse" } } } }, "400": { "description": "The date range or filter is invalid.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1ErrorEnvelope" } } } }, "401": { "description": "Missing, invalid or expired bearer user token.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1ErrorEnvelope" } } } }, "403": { "description": "The bearer token does not grant personal.transactions.read consent.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1ErrorEnvelope" } } } }, "405": { "description": "Only GET is allowed for this route.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1ErrorEnvelope" } } } }, "500": { "description": "Generic server failure. Internal database details must not be returned.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1ErrorEnvelope" } } } } }, "x-financial-iq-safety": { "requiresApiKey": false, "apiKeysAllowed": false, "requiresUserBearerToken": true, "scope": "personal.transactions.read", "personalData": true, "businessMutation": false, "directFinancialMutation": false, "writeLevel": "read", "requiresIdempotencyKey": false, "serverSideAggregation": true, "redactedFields": [ "description", "merchant_name", "reference", "external_transaction_id", "provider_metadata", "account_number", "sort_code", "access_token_ct", "refresh_token_ct" ], "doesNot": [ "return_individual_transactions", "categorise_transactions", "connect_bank_feeds", "move_money", "post_ledger_entries", "raise_invoices", "file_tax" ], "auditedEndpoint": "v1/personal/reports/cash-flow" }, "x-implementation": { "edgeFunction": "financial-data-api", "handler": "handleV1PersonalCashFlowReport", "sourceFile": "supabase/functions/financial-data-api/v1.ts" } } }, "/v1/personal/reports/budget-performance": { "get": { "tags": [ "Personal" ], "operationId": "getPersonalBudgetPerformanceReport", "summary": "Get personal budget performance report", "description": "Returns read-only personal budget performance totals for a required date range. This route summarises budgeted, spent and remaining amounts and does not expose transaction rows or mutate budgets.", "security": [ { "BearerAuth": [] } ], "parameters": [ { "$ref": "#/components/parameters/RequestId" }, { "name": "from_date", "in": "query", "required": true, "description": "Inclusive budget month start date in YYYY-MM-DD format.", "schema": { "type": "string", "format": "date", "pattern": "^\\d{4}-\\d{2}-\\d{2}$" } }, { "name": "to_date", "in": "query", "required": true, "description": "Inclusive budget month end date in YYYY-MM-DD format.", "schema": { "type": "string", "format": "date", "pattern": "^\\d{4}-\\d{2}-\\d{2}$" } }, { "name": "category_id", "in": "query", "required": false, "description": "Optional personal budget category ID filter.", "schema": { "type": "string", "format": "uuid" } }, { "name": "budget_type", "in": "query", "required": false, "description": "Optional budget type filter, such as expense, income or savings.", "schema": { "type": "string", "minLength": 1, "maxLength": 50 } }, { "name": "period_type", "in": "query", "required": false, "description": "Optional budget period filter, such as weekly, monthly or yearly.", "schema": { "type": "string", "minLength": 1, "maxLength": 50 } }, { "name": "is_active", "in": "query", "required": false, "description": "Optional active-state filter.", "schema": { "type": "boolean" } } ], "responses": { "200": { "description": "User-authorised personal budget performance report returned.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PersonalBudgetPerformanceReportResponse" } } } }, "400": { "description": "The date range or filter is invalid.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1ErrorEnvelope" } } } }, "401": { "description": "Missing, invalid or expired bearer user token.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1ErrorEnvelope" } } } }, "403": { "description": "The bearer token does not grant personal.budgets.read consent.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1ErrorEnvelope" } } } }, "405": { "description": "Only GET is allowed for this route.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1ErrorEnvelope" } } } }, "500": { "description": "Generic server failure. Internal database details must not be returned.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1ErrorEnvelope" } } } } }, "x-financial-iq-safety": { "requiresApiKey": false, "apiKeysAllowed": false, "requiresUserBearerToken": true, "scope": "personal.budgets.read", "personalData": true, "businessMutation": false, "directFinancialMutation": false, "writeLevel": "read", "requiresIdempotencyKey": false, "serverSideAggregation": true, "redactedFields": [ "transaction_rows", "transaction_descriptions", "merchant_name", "external_transaction_id", "provider_metadata", "account_number", "sort_code", "access_token_ct", "refresh_token_ct" ], "doesNot": [ "return_individual_transactions", "categorise_transactions", "connect_bank_feeds", "move_money", "post_ledger_entries", "raise_invoices", "file_tax", "mutate_business_books" ], "auditedEndpoint": "v1/personal/reports/budget-performance" }, "x-implementation": { "edgeFunction": "financial-data-api", "handler": "handleV1PersonalBudgetPerformanceReport", "sourceFile": "supabase/functions/financial-data-api/v1.ts" } } }, "/v1/personal/reports/goal-progress": { "get": { "tags": [ "Personal" ], "operationId": "getPersonalGoalProgressReport", "summary": "Get personal goal progress report", "description": "Returns read-only personal goal progress totals for the bearer-token user. This route summarises target, current and remaining amounts by goal type and category and does not expose transactions or mutate goals.", "security": [ { "BearerAuth": [] } ], "parameters": [ { "$ref": "#/components/parameters/RequestId" }, { "name": "search", "in": "query", "required": false, "description": "Search goals by name.", "schema": { "type": "string", "minLength": 1, "maxLength": 200 } }, { "name": "q", "in": "query", "required": false, "description": "Alias for search.", "schema": { "type": "string", "minLength": 1, "maxLength": 200 } }, { "name": "category_id", "in": "query", "required": false, "description": "Optional personal goal category ID filter.", "schema": { "type": "string", "format": "uuid" } }, { "name": "linked_account_id", "in": "query", "required": false, "description": "Optional linked personal account ID filter.", "schema": { "type": "string", "format": "uuid" } }, { "name": "goal_type", "in": "query", "required": false, "description": "Optional goal type filter.", "schema": { "type": "string", "minLength": 1, "maxLength": 50 } }, { "name": "is_achieved", "in": "query", "required": false, "description": "Optional achieved-state filter.", "schema": { "type": "boolean" } }, { "name": "is_shared", "in": "query", "required": false, "description": "Optional shared-goal filter.", "schema": { "type": "boolean" } }, { "name": "from_target_date", "in": "query", "required": false, "description": "Inclusive target-date lower bound in YYYY-MM-DD format.", "schema": { "type": "string", "format": "date" } }, { "name": "to_target_date", "in": "query", "required": false, "description": "Inclusive target-date upper bound in YYYY-MM-DD format.", "schema": { "type": "string", "format": "date" } } ], "responses": { "200": { "description": "User-authorised personal goal progress report returned.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PersonalGoalProgressReportResponse" } } } }, "400": { "description": "A date or filter parameter is invalid.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1ErrorEnvelope" } } } }, "401": { "description": "Missing, invalid or expired bearer user token.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1ErrorEnvelope" } } } }, "403": { "description": "The bearer token does not grant personal.goals.read consent.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1ErrorEnvelope" } } } }, "405": { "description": "Only GET is allowed for this route.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1ErrorEnvelope" } } } }, "500": { "description": "Generic server failure. Internal database details must not be returned.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1ErrorEnvelope" } } } } }, "x-financial-iq-safety": { "requiresApiKey": false, "apiKeysAllowed": false, "requiresUserBearerToken": true, "scope": "personal.goals.read", "personalData": true, "businessMutation": false, "directFinancialMutation": false, "writeLevel": "read", "requiresIdempotencyKey": false, "serverSideAggregation": true, "redactedFields": [ "description", "transaction_rows", "transaction_descriptions", "merchant_name", "external_transaction_id", "provider_metadata", "account_number", "sort_code", "access_token_ct", "refresh_token_ct" ], "doesNot": [ "return_individual_transactions", "categorise_transactions", "connect_bank_feeds", "move_money", "post_ledger_entries", "raise_invoices", "file_tax", "mutate_business_books" ], "auditedEndpoint": "v1/personal/reports/goal-progress" }, "x-implementation": { "edgeFunction": "financial-data-api", "handler": "handleV1PersonalGoalProgressReport", "sourceFile": "supabase/functions/financial-data-api/v1.ts" } } }, "/v1/personal/accounts": { "get": { "tags": [ "Personal" ], "operationId": "listPersonalAccounts", "summary": "List personal accounts", "description": "Lists personal bank, asset and liability accounts for the bearer-token user. This route requires explicit personal.accounts.read consent and never returns account numbers, sort codes, provider tokens or hashes.", "security": [ { "BearerAuth": [] } ], "parameters": [ { "$ref": "#/components/parameters/RequestId" }, { "name": "limit", "in": "query", "required": false, "description": "Maximum number of accounts to return. Values are clamped between 1 and 200.", "schema": { "type": "integer", "minimum": 1, "maximum": 200, "default": 100 } }, { "name": "offset", "in": "query", "required": false, "description": "Zero-based offset for paginating account results.", "schema": { "type": "integer", "minimum": 0, "default": 0 } } ], "responses": { "200": { "description": "User-authorised personal accounts returned.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PersonalAccountListResponse" } } } }, "401": { "description": "Missing, invalid or expired bearer user token.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1ErrorEnvelope" } } } }, "403": { "description": "The bearer token does not grant personal.accounts.read consent.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1ErrorEnvelope" } } } }, "405": { "description": "Only GET is allowed for this route.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1ErrorEnvelope" } } } }, "500": { "description": "Generic server failure. Internal database details must not be returned.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1ErrorEnvelope" } } } } }, "x-financial-iq-safety": { "requiresApiKey": false, "apiKeysAllowed": false, "requiresUserBearerToken": true, "scope": "personal.accounts.read", "businessMutation": false, "directFinancialMutation": false, "writeLevel": "read", "requiresIdempotencyKey": false, "redactedFields": [ "account_number", "account_number_ct", "account_number_hash", "sort_code", "sort_code_ct", "sort_code_hash", "access_token_ct", "refresh_token_ct" ], "auditedEndpoint": "v1/personal/accounts" }, "x-implementation": { "edgeFunction": "supabase/functions/financial-data-api/index.ts", "handler": "handleV1PersonalAccounts", "tests": [ "supabase/functions/financial-data-api/invoice_idempotency.test.ts" ] } }, "post": { "tags": [ "Personal" ], "operationId": "createPersonalAccount", "summary": "Create a manual personal account", "description": "Creates a manual personal account for the bearer-token user. This route requires explicit personal.accounts.write consent and an Idempotency-Key. It does not connect a bank feed, import transactions, store account numbers or sort codes, move money, or post ledger entries.", "security": [ { "BearerAuth": [] } ], "parameters": [ { "$ref": "#/components/parameters/RequestId" }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PersonalAccountCreateRequest" } } } }, "responses": { "201": { "description": "Manual personal account created.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PersonalAccountCreateResponse" } } } }, "400": { "description": "Invalid request body or missing Idempotency-Key.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1ErrorEnvelope" } } } }, "401": { "description": "Missing, invalid or expired bearer user token.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1ErrorEnvelope" } } } }, "403": { "description": "The bearer token does not grant personal.accounts.write consent.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1ErrorEnvelope" } } } }, "405": { "description": "Only GET and POST are allowed for this route.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1ErrorEnvelope" } } } }, "409": { "description": "The Idempotency-Key is currently processing or was used with a different request body.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1ErrorEnvelope" } } } }, "500": { "description": "Generic server failure. Internal database details must not be returned.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1ErrorEnvelope" } } } } }, "x-financial-iq-safety": { "requiresApiKey": false, "apiKeysAllowed": false, "requiresUserBearerToken": true, "scope": "personal.accounts.write", "businessMutation": false, "directFinancialMutation": false, "writeLevel": "configuration", "requiresIdempotencyKey": true, "auditedEndpoint": "v1/personal/accounts", "forbiddenFields": [ "account_number", "account_number_ct", "account_number_hash", "sort_code", "sort_code_ct", "sort_code_hash", "access_token_ct", "refresh_token_ct", "provider_id", "provider_consent_id", "gocardless_account_id", "truelayer_account_id", "yapily_institution_id" ], "doesNot": [ "connect_bank_feed", "import_transactions", "move_money", "post_ledger_entries", "file_tax_returns" ] }, "x-implementation": { "edgeFunction": "supabase/functions/financial-data-api/index.ts", "handler": "handleV1PersonalAccounts", "tests": [ "supabase/functions/financial-data-api/invoice_idempotency.test.ts" ] } } }, "/v1/personal/accounts/{account_id}": { "get": { "tags": [ "Personal" ], "operationId": "getPersonalAccount", "summary": "Get one personal account", "description": "Returns one personal account owned by the bearer-token user. Inaccessible accounts are returned as not found.", "security": [ { "BearerAuth": [] } ], "parameters": [ { "name": "account_id", "in": "path", "required": true, "description": "Personal account id to fetch.", "schema": { "type": "string", "format": "uuid" } }, { "$ref": "#/components/parameters/RequestId" } ], "responses": { "200": { "description": "User-authorised personal account returned.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PersonalAccountResponse" } } } }, "400": { "description": "The account_id path parameter is not a valid UUID.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1ErrorEnvelope" } } } }, "401": { "description": "Missing, invalid or expired bearer user token.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1ErrorEnvelope" } } } }, "403": { "description": "The bearer token does not grant personal.accounts.read consent.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1ErrorEnvelope" } } } }, "404": { "description": "Personal account not found.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1ErrorEnvelope" } } } }, "405": { "description": "Only GET and PATCH are allowed for this route.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1ErrorEnvelope" } } } }, "500": { "description": "Generic server failure. Internal database details must not be returned.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1ErrorEnvelope" } } } } }, "x-financial-iq-safety": { "requiresApiKey": false, "apiKeysAllowed": false, "requiresUserBearerToken": true, "scope": "personal.accounts.read", "businessMutation": false, "directFinancialMutation": false, "writeLevel": "read", "requiresIdempotencyKey": false, "redactedFields": [ "account_number", "account_number_ct", "account_number_hash", "sort_code", "sort_code_ct", "sort_code_hash", "access_token_ct", "refresh_token_ct" ], "auditedEndpoint": "v1/personal/accounts/{account_id}" }, "x-implementation": { "edgeFunction": "supabase/functions/financial-data-api/index.ts", "handler": "handleV1PersonalAccountDetail", "tests": [ "supabase/functions/financial-data-api/invoice_idempotency.test.ts" ] } }, "patch": { "tags": [ "Personal" ], "operationId": "updatePersonalAccount", "summary": "Update personal account metadata", "description": "Updates safe display and classification fields for one personal account owned by the bearer-token user. This route requires explicit personal.accounts.write consent and an Idempotency-Key. It does not change balances, connect bank feeds, import transactions, store account numbers or sort codes, move money, or post ledger entries.", "security": [ { "BearerAuth": [] } ], "parameters": [ { "name": "account_id", "in": "path", "required": true, "description": "Personal account id to fetch.", "schema": { "type": "string", "format": "uuid" } }, { "$ref": "#/components/parameters/RequestId" }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PersonalAccountUpdateRequest" } } } }, "responses": { "200": { "description": "Personal account metadata updated.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PersonalAccountUpdateResponse" } } } }, "400": { "description": "Invalid request body, missing Idempotency-Key, or invalid account_id path parameter.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1ErrorEnvelope" } } } }, "401": { "description": "Missing, invalid or expired bearer user token.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1ErrorEnvelope" } } } }, "403": { "description": "The bearer token does not grant personal.accounts.write consent.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1ErrorEnvelope" } } } }, "404": { "description": "Personal account not found.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1ErrorEnvelope" } } } }, "405": { "description": "Only GET and PATCH are allowed for this route.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1ErrorEnvelope" } } } }, "409": { "description": "The Idempotency-Key is currently processing or was used with a different request body.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1ErrorEnvelope" } } } }, "500": { "description": "Generic server failure. Internal database details must not be returned.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1ErrorEnvelope" } } } } }, "x-financial-iq-safety": { "requiresApiKey": false, "apiKeysAllowed": false, "requiresUserBearerToken": true, "scope": "personal.accounts.write", "businessMutation": false, "directFinancialMutation": false, "writeLevel": "personal_account_metadata", "requiresIdempotencyKey": true, "auditedEndpoint": "v1/personal/accounts/{account_id}", "forbiddenFields": [ "id", "user_id", "company_id", "context_type", "created_at", "updated_at", "current_balance", "available_balance", "actual_balance", "book_balance", "last_sync_at", "connection_status", "feed_status", "account_number", "account_number_ct", "account_number_hash", "sort_code", "sort_code_ct", "sort_code_hash", "iban", "access_token", "access_token_ct", "refresh_token", "refresh_token_ct", "provider_id", "provider_consent_id", "gocardless_account_id", "gocardless_agreement_id", "gocardless_institution_id", "gocardless_requisition_id", "truelayer_account_id", "yapily_institution_id", "transactions" ], "doesNot": [ "change_balances", "connect_bank_feed", "import_transactions", "store_account_numbers", "update_provider_tokens", "move_money", "post_ledger_entries", "file_tax_returns" ], "redactedFields": [ "account_number", "account_number_ct", "account_number_hash", "sort_code", "sort_code_ct", "sort_code_hash", "access_token_ct", "refresh_token_ct" ] }, "x-implementation": { "edgeFunction": "supabase/functions/financial-data-api/index.ts", "handler": "updateV1PersonalAccount", "tests": [ "supabase/functions/financial-data-api/invoice_idempotency.test.ts" ] } } }, "/v1/personal/assets": { "get": { "tags": [ "Personal" ], "operationId": "listPersonalAssets", "summary": "List personal assets", "description": "Lists personal assets for the bearer-token user. This route requires explicit personal.assets.read consent and cannot be called with an API key.", "security": [ { "BearerAuth": [] } ], "parameters": [ { "$ref": "#/components/parameters/RequestId" }, { "name": "search", "in": "query", "required": false, "description": "Search assets by name.", "schema": { "type": "string", "minLength": 1, "maxLength": 200 } }, { "name": "q", "in": "query", "required": false, "description": "Alias for search.", "schema": { "type": "string", "minLength": 1, "maxLength": 200 } }, { "name": "asset_type", "in": "query", "required": false, "description": "Optional asset type filter.", "schema": { "type": "string", "enum": [ "property", "vehicle", "investment", "savings", "other" ] } }, { "name": "is_active", "in": "query", "required": false, "description": "Optional active-state filter.", "schema": { "type": "boolean" } }, { "name": "min_value", "in": "query", "required": false, "description": "Optional lower bound for current_value.", "schema": { "type": "number" } }, { "name": "max_value", "in": "query", "required": false, "description": "Optional upper bound for current_value.", "schema": { "type": "number" } }, { "name": "limit", "in": "query", "required": false, "description": "Maximum number of assets to return. Values are clamped between 1 and 200.", "schema": { "type": "integer", "minimum": 1, "maximum": 200, "default": 100 } }, { "name": "offset", "in": "query", "required": false, "description": "Zero-based offset for paginating assets.", "schema": { "type": "integer", "minimum": 0, "default": 0 } } ], "responses": { "200": { "description": "User-authorised personal assets returned.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PersonalAssetListResponse" } } } }, "400": { "description": "A filter parameter is invalid.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1ErrorEnvelope" } } } }, "401": { "description": "Missing, invalid or expired bearer user token.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1ErrorEnvelope" } } } }, "403": { "description": "The bearer token does not grant personal.assets.read consent.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1ErrorEnvelope" } } } }, "405": { "description": "Only GET and POST are allowed for this route.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1ErrorEnvelope" } } } }, "500": { "description": "Generic server failure. Internal database details must not be returned.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1ErrorEnvelope" } } } } }, "x-financial-iq-safety": { "requiresApiKey": false, "apiKeysAllowed": false, "requiresUserBearerToken": true, "scope": "personal.assets.read", "businessMutation": false, "directFinancialMutation": false, "writeLevel": "read", "requiresIdempotencyKey": false, "auditedEndpoint": "v1/personal/assets" }, "x-implementation": { "edgeFunction": "supabase/functions/financial-data-api/index.ts", "handler": "handleV1PersonalAssets", "tests": [ "supabase/functions/financial-data-api/invoice_idempotency.test.ts" ] } }, "post": { "tags": [ "Personal" ], "operationId": "createPersonalAsset", "summary": "Create personal asset", "description": "Creates a personal asset record for the bearer-token user. This route requires explicit personal.assets.write consent, cannot be called with an API key, and does not create transactions, move money, post ledger entries, or file tax submissions.", "security": [ { "BearerAuth": [] } ], "parameters": [ { "$ref": "#/components/parameters/RequestId" }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PersonalAssetCreateRequest" } } } }, "responses": { "201": { "description": "Personal asset created.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PersonalAssetCreateResponse" } } } }, "400": { "description": "The request body or idempotency key is invalid.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1ErrorEnvelope" } } } }, "401": { "description": "Missing, invalid or expired bearer user token.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1ErrorEnvelope" } } } }, "403": { "description": "The bearer token does not grant personal.assets.write consent.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1ErrorEnvelope" } } } }, "405": { "description": "Only GET and POST are allowed for this route.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1ErrorEnvelope" } } } }, "409": { "description": "The idempotency key conflicts with a different request body or an in-progress request.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1ErrorEnvelope" } } } }, "500": { "description": "Generic server failure. Internal database details must not be returned.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1ErrorEnvelope" } } } } }, "x-financial-iq-safety": { "requiresApiKey": false, "apiKeysAllowed": false, "requiresUserBearerToken": true, "scope": "personal.assets.write", "businessMutation": false, "directFinancialMutation": false, "writeLevel": "configuration", "requiresIdempotencyKey": true, "auditedEndpoint": "v1/personal/assets" }, "x-implementation": { "edgeFunction": "supabase/functions/financial-data-api/index.ts", "handler": "createV1PersonalAsset", "tests": [ "supabase/functions/financial-data-api/invoice_idempotency.test.ts" ] } } }, "/v1/personal/assets/{asset_id}": { "get": { "tags": [ "Personal" ], "operationId": "getPersonalAsset", "summary": "Get one personal asset", "description": "Returns one personal asset for the bearer-token user. Inaccessible asset IDs are returned as not found to avoid leaking another user's data.", "security": [ { "BearerAuth": [] } ], "parameters": [ { "name": "asset_id", "in": "path", "required": true, "description": "Personal asset id to fetch.", "schema": { "type": "string", "format": "uuid" } }, { "$ref": "#/components/parameters/RequestId" } ], "responses": { "200": { "description": "User-authorised personal asset returned.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PersonalAssetResponse" } } } }, "400": { "description": "The asset_id path parameter is not a valid UUID.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1ErrorEnvelope" } } } }, "401": { "description": "Missing, invalid or expired bearer user token.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1ErrorEnvelope" } } } }, "403": { "description": "The bearer token does not grant personal.assets.read consent.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1ErrorEnvelope" } } } }, "404": { "description": "Personal asset not found.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1ErrorEnvelope" } } } }, "405": { "description": "Only GET and PATCH are allowed for this route.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1ErrorEnvelope" } } } }, "500": { "description": "Generic server failure. Internal database details must not be returned.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1ErrorEnvelope" } } } } }, "x-financial-iq-safety": { "requiresApiKey": false, "apiKeysAllowed": false, "requiresUserBearerToken": true, "scope": "personal.assets.read", "businessMutation": false, "directFinancialMutation": false, "writeLevel": "read", "requiresIdempotencyKey": false, "auditedEndpoint": "v1/personal/assets/{asset_id}" }, "x-implementation": { "edgeFunction": "supabase/functions/financial-data-api/index.ts", "handler": "handleV1PersonalAssetDetail", "tests": [ "supabase/functions/financial-data-api/invoice_idempotency.test.ts" ] } }, "patch": { "tags": [ "Personal" ], "operationId": "updatePersonalAsset", "summary": "Update personal asset", "description": "Updates safe fields for one personal asset owned by the bearer-token user. This route requires explicit personal.assets.write consent and an Idempotency-Key. It cannot be called with an API key and does not create transactions, move money, post ledger entries, file tax submissions, or mutate business books.", "security": [ { "BearerAuth": [] } ], "parameters": [ { "name": "asset_id", "in": "path", "required": true, "description": "Personal asset id to update.", "schema": { "type": "string", "format": "uuid" } }, { "$ref": "#/components/parameters/RequestId" }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PersonalAssetUpdateRequest" } } } }, "responses": { "200": { "description": "Personal asset updated.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PersonalAssetUpdateResponse" } } } }, "400": { "description": "Invalid request body, missing Idempotency-Key, or invalid asset_id path parameter.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1ErrorEnvelope" } } } }, "401": { "description": "Missing, invalid or expired bearer user token.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1ErrorEnvelope" } } } }, "403": { "description": "The bearer token does not grant personal.assets.write consent.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1ErrorEnvelope" } } } }, "404": { "description": "Personal asset not found.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1ErrorEnvelope" } } } }, "405": { "description": "Only GET and PATCH are allowed for this route.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1ErrorEnvelope" } } } }, "409": { "description": "The Idempotency-Key is currently processing or was used with a different request body.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1ErrorEnvelope" } } } }, "500": { "description": "Generic server failure. Internal database details must not be returned.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1ErrorEnvelope" } } } } }, "x-financial-iq-safety": { "requiresApiKey": false, "apiKeysAllowed": false, "requiresUserBearerToken": true, "scope": "personal.assets.write", "businessMutation": false, "directFinancialMutation": false, "writeLevel": "personal_asset", "requiresIdempotencyKey": true, "auditedEndpoint": "v1/personal/assets/{asset_id}", "forbiddenFields": [ "id", "user_id", "created_at", "updated_at", "transactions", "business_transaction_ids", "ledger_entries", "bank_account_id", "company_id" ], "doesNot": [ "create_transactions", "move_money", "post_ledger_entries", "file_tax_returns", "mutate_business_books" ] }, "x-implementation": { "edgeFunction": "supabase/functions/financial-data-api/index.ts", "handler": "updateV1PersonalAsset", "tests": [ "supabase/functions/financial-data-api/invoice_idempotency.test.ts" ] } } }, "/v1/personal/liabilities": { "get": { "tags": [ "Personal" ], "operationId": "listPersonalLiabilities", "summary": "List personal liabilities", "description": "Lists personal liabilities for the bearer-token user. This route requires explicit personal.liabilities.read consent and cannot be called with an API key.", "security": [ { "BearerAuth": [] } ], "parameters": [ { "$ref": "#/components/parameters/RequestId" }, { "name": "search", "in": "query", "required": false, "description": "Search liabilities by name.", "schema": { "type": "string", "minLength": 1, "maxLength": 200 } }, { "name": "q", "in": "query", "required": false, "description": "Alias for search.", "schema": { "type": "string", "minLength": 1, "maxLength": 200 } }, { "name": "liability_type", "in": "query", "required": false, "description": "Optional liability type filter.", "schema": { "type": "string", "enum": [ "mortgage", "loan", "credit_card", "other" ] } }, { "name": "is_active", "in": "query", "required": false, "description": "Optional active-state filter.", "schema": { "type": "boolean" } }, { "name": "min_balance", "in": "query", "required": false, "description": "Optional lower bound for current_balance.", "schema": { "type": "number" } }, { "name": "max_balance", "in": "query", "required": false, "description": "Optional upper bound for current_balance.", "schema": { "type": "number" } }, { "name": "limit", "in": "query", "required": false, "description": "Maximum number of liabilities to return. Values are clamped between 1 and 200.", "schema": { "type": "integer", "minimum": 1, "maximum": 200, "default": 100 } }, { "name": "offset", "in": "query", "required": false, "description": "Zero-based offset for paginating liabilities.", "schema": { "type": "integer", "minimum": 0, "default": 0 } } ], "responses": { "200": { "description": "User-authorised personal liabilities returned.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PersonalLiabilityListResponse" } } } }, "400": { "description": "A filter parameter is invalid.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1ErrorEnvelope" } } } }, "401": { "description": "Missing, invalid or expired bearer user token.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1ErrorEnvelope" } } } }, "403": { "description": "The bearer token does not grant personal.liabilities.read consent.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1ErrorEnvelope" } } } }, "405": { "description": "Only GET and POST are allowed for this route.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1ErrorEnvelope" } } } }, "500": { "description": "Generic server failure. Internal database details must not be returned.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1ErrorEnvelope" } } } } }, "x-financial-iq-safety": { "requiresApiKey": false, "apiKeysAllowed": false, "requiresUserBearerToken": true, "scope": "personal.liabilities.read", "businessMutation": false, "directFinancialMutation": false, "writeLevel": "read", "requiresIdempotencyKey": false, "auditedEndpoint": "v1/personal/liabilities" }, "x-implementation": { "edgeFunction": "supabase/functions/financial-data-api/index.ts", "handler": "handleV1PersonalLiabilities", "tests": [ "supabase/functions/financial-data-api/invoice_idempotency.test.ts" ] } }, "post": { "tags": [ "Personal" ], "operationId": "createPersonalLiability", "summary": "Create personal liability", "description": "Creates a personal liability record for the bearer-token user. This route requires explicit personal.liabilities.write consent, cannot be called with an API key, and does not create transactions, move money, post ledger entries, or file tax submissions.", "security": [ { "BearerAuth": [] } ], "parameters": [ { "$ref": "#/components/parameters/RequestId" }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PersonalLiabilityCreateRequest" } } } }, "responses": { "201": { "description": "Personal liability created.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PersonalLiabilityCreateResponse" } } } }, "400": { "description": "The request body or idempotency key is invalid.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1ErrorEnvelope" } } } }, "401": { "description": "Missing, invalid or expired bearer user token.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1ErrorEnvelope" } } } }, "403": { "description": "The bearer token does not grant personal.liabilities.write consent.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1ErrorEnvelope" } } } }, "405": { "description": "Only GET and POST are allowed for this route.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1ErrorEnvelope" } } } }, "409": { "description": "The idempotency key conflicts with a different request body or an in-progress request.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1ErrorEnvelope" } } } }, "500": { "description": "Generic server failure. Internal database details must not be returned.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1ErrorEnvelope" } } } } }, "x-financial-iq-safety": { "requiresApiKey": false, "apiKeysAllowed": false, "requiresUserBearerToken": true, "scope": "personal.liabilities.write", "businessMutation": false, "directFinancialMutation": false, "writeLevel": "configuration", "requiresIdempotencyKey": true, "auditedEndpoint": "v1/personal/liabilities" }, "x-implementation": { "edgeFunction": "supabase/functions/financial-data-api/index.ts", "handler": "createV1PersonalLiability", "tests": [ "supabase/functions/financial-data-api/invoice_idempotency.test.ts" ] } } }, "/v1/personal/liabilities/{liability_id}": { "get": { "tags": [ "Personal" ], "operationId": "getPersonalLiability", "summary": "Get one personal liability", "description": "Returns one personal liability for the bearer-token user. Inaccessible liability IDs are returned as not found to avoid leaking another user's data.", "security": [ { "BearerAuth": [] } ], "parameters": [ { "name": "liability_id", "in": "path", "required": true, "description": "Personal liability id to fetch.", "schema": { "type": "string", "format": "uuid" } }, { "$ref": "#/components/parameters/RequestId" } ], "responses": { "200": { "description": "User-authorised personal liability returned.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PersonalLiabilityResponse" } } } }, "400": { "description": "The liability_id path parameter is not a valid UUID.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1ErrorEnvelope" } } } }, "401": { "description": "Missing, invalid or expired bearer user token.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1ErrorEnvelope" } } } }, "403": { "description": "The bearer token does not grant personal.liabilities.read consent.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1ErrorEnvelope" } } } }, "404": { "description": "Personal liability not found.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1ErrorEnvelope" } } } }, "405": { "description": "Only GET and PATCH are allowed for this route.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1ErrorEnvelope" } } } }, "500": { "description": "Generic server failure. Internal database details must not be returned.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1ErrorEnvelope" } } } } }, "x-financial-iq-safety": { "requiresApiKey": false, "apiKeysAllowed": false, "requiresUserBearerToken": true, "scope": "personal.liabilities.read", "businessMutation": false, "directFinancialMutation": false, "writeLevel": "read", "requiresIdempotencyKey": false, "auditedEndpoint": "v1/personal/liabilities/{liability_id}" }, "x-implementation": { "edgeFunction": "supabase/functions/financial-data-api/index.ts", "handler": "handleV1PersonalLiabilityDetail", "tests": [ "supabase/functions/financial-data-api/invoice_idempotency.test.ts" ] } }, "patch": { "tags": [ "Personal" ], "operationId": "updatePersonalLiability", "summary": "Update personal liability", "description": "Updates safe fields for one personal liability owned by the bearer-token user. This route requires explicit personal.liabilities.write consent and an Idempotency-Key. It cannot be called with an API key and does not create transactions, move money, post ledger entries, file tax submissions, or mutate business books.", "security": [ { "BearerAuth": [] } ], "parameters": [ { "name": "liability_id", "in": "path", "required": true, "description": "Personal liability id to update.", "schema": { "type": "string", "format": "uuid" } }, { "$ref": "#/components/parameters/RequestId" }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PersonalLiabilityUpdateRequest" } } } }, "responses": { "200": { "description": "Personal liability updated.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PersonalLiabilityUpdateResponse" } } } }, "400": { "description": "Invalid request body, missing Idempotency-Key, or invalid liability_id path parameter.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1ErrorEnvelope" } } } }, "401": { "description": "Missing, invalid or expired bearer user token.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1ErrorEnvelope" } } } }, "403": { "description": "The bearer token does not grant personal.liabilities.write consent.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1ErrorEnvelope" } } } }, "404": { "description": "Personal liability not found.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1ErrorEnvelope" } } } }, "405": { "description": "Only GET and PATCH are allowed for this route.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1ErrorEnvelope" } } } }, "409": { "description": "The Idempotency-Key is currently processing or was used with a different request body.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1ErrorEnvelope" } } } }, "500": { "description": "Generic server failure. Internal database details must not be returned.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1ErrorEnvelope" } } } } }, "x-financial-iq-safety": { "requiresApiKey": false, "apiKeysAllowed": false, "requiresUserBearerToken": true, "scope": "personal.liabilities.write", "businessMutation": false, "directFinancialMutation": false, "writeLevel": "personal_liability", "requiresIdempotencyKey": true, "auditedEndpoint": "v1/personal/liabilities/{liability_id}", "forbiddenFields": [ "id", "user_id", "created_at", "updated_at", "transactions", "business_transaction_ids", "ledger_entries", "bank_account_id", "company_id" ], "doesNot": [ "create_transactions", "move_money", "post_ledger_entries", "file_tax_returns", "mutate_business_books" ] }, "x-implementation": { "edgeFunction": "supabase/functions/financial-data-api/index.ts", "handler": "updateV1PersonalLiability", "tests": [ "supabase/functions/financial-data-api/invoice_idempotency.test.ts" ] } } }, "/v1/personal/budgets": { "get": { "tags": [ "Personal" ], "operationId": "listPersonalBudgets", "summary": "List personal budgets", "description": "Lists personal budgets for the bearer-token user. This route requires explicit personal.budgets.read consent and cannot be called with an API key.", "security": [ { "BearerAuth": [] } ], "parameters": [ { "$ref": "#/components/parameters/RequestId" }, { "name": "category_id", "in": "query", "required": false, "description": "Optional personal category id filter.", "schema": { "type": "string", "format": "uuid" } }, { "name": "budget_type", "in": "query", "required": false, "description": "Optional budget type filter.", "schema": { "type": "string" } }, { "name": "period_type", "in": "query", "required": false, "description": "Optional period type filter.", "schema": { "type": "string" } }, { "name": "is_active", "in": "query", "required": false, "description": "Optional active-state filter.", "schema": { "type": "boolean" } }, { "name": "from_date", "in": "query", "required": false, "description": "Inclusive budget-month lower bound in YYYY-MM-DD format.", "schema": { "type": "string", "format": "date" } }, { "name": "to_date", "in": "query", "required": false, "description": "Inclusive budget-month upper bound in YYYY-MM-DD format.", "schema": { "type": "string", "format": "date" } }, { "name": "limit", "in": "query", "required": false, "description": "Maximum number of budgets to return. Values are clamped between 1 and 200.", "schema": { "type": "integer", "minimum": 1, "maximum": 200, "default": 100 } }, { "name": "offset", "in": "query", "required": false, "description": "Zero-based offset for paginating budgets.", "schema": { "type": "integer", "minimum": 0, "default": 0 } } ], "responses": { "200": { "description": "User-authorised personal budgets returned.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PersonalBudgetListResponse" } } } }, "400": { "description": "A filter parameter is invalid.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1ErrorEnvelope" } } } }, "401": { "description": "Missing, invalid or expired bearer user token.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1ErrorEnvelope" } } } }, "403": { "description": "The bearer token does not grant personal.budgets.read consent.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1ErrorEnvelope" } } } }, "405": { "description": "Only GET and POST are allowed for this route.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1ErrorEnvelope" } } } }, "500": { "description": "Generic server failure. Internal database details must not be returned.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1ErrorEnvelope" } } } } }, "x-financial-iq-safety": { "requiresApiKey": false, "apiKeysAllowed": false, "requiresUserBearerToken": true, "scope": "personal.budgets.read", "businessMutation": false, "directFinancialMutation": false, "writeLevel": "read", "requiresIdempotencyKey": false, "auditedEndpoint": "v1/personal/budgets" }, "x-implementation": { "edgeFunction": "supabase/functions/financial-data-api/index.ts", "handler": "handleV1PersonalBudgets", "tests": [ "supabase/functions/financial-data-api/invoice_idempotency.test.ts" ] } }, "post": { "tags": [ "Personal" ], "operationId": "createPersonalBudget", "summary": "Create personal budget", "description": "Creates a personal budget target for the bearer-token user. This route requires explicit personal.budgets.write consent, cannot be called with an API key, and does not create transactions, move money, post ledger entries, or file tax submissions.", "security": [ { "BearerAuth": [] } ], "parameters": [ { "$ref": "#/components/parameters/RequestId" }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PersonalBudgetCreateRequest" } } } }, "responses": { "201": { "description": "Personal budget created.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PersonalBudgetCreateResponse" } } } }, "400": { "description": "The request body, linked reference or idempotency key is invalid.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1ErrorEnvelope" } } } }, "401": { "description": "Missing, invalid or expired bearer user token.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1ErrorEnvelope" } } } }, "403": { "description": "The bearer token does not grant personal.budgets.write consent.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1ErrorEnvelope" } } } }, "405": { "description": "Only GET and POST are allowed for this route.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1ErrorEnvelope" } } } }, "409": { "description": "The idempotency key conflicts with a different request body or an in-progress request.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1ErrorEnvelope" } } } }, "500": { "description": "Generic server failure. Internal database details must not be returned.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1ErrorEnvelope" } } } } }, "x-financial-iq-safety": { "requiresApiKey": false, "apiKeysAllowed": false, "requiresUserBearerToken": true, "scope": "personal.budgets.write", "businessMutation": false, "directFinancialMutation": false, "writeLevel": "configuration", "requiresIdempotencyKey": true, "auditedEndpoint": "v1/personal/budgets" }, "x-implementation": { "edgeFunction": "supabase/functions/financial-data-api/index.ts", "handler": "createV1PersonalBudget", "tests": [ "supabase/functions/financial-data-api/invoice_idempotency.test.ts" ] } } }, "/v1/personal/budgets/{budget_id}": { "get": { "tags": [ "Personal" ], "operationId": "getPersonalBudget", "summary": "Get one personal budget", "description": "Returns one personal budget for the bearer-token user. Inaccessible budget IDs are returned as not found to avoid leaking another user's data.", "security": [ { "BearerAuth": [] } ], "parameters": [ { "name": "budget_id", "in": "path", "required": true, "description": "Personal budget id to fetch.", "schema": { "type": "string", "format": "uuid" } }, { "$ref": "#/components/parameters/RequestId" } ], "responses": { "200": { "description": "User-authorised personal budget returned.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PersonalBudgetResponse" } } } }, "400": { "description": "The budget_id path parameter is not a valid UUID.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1ErrorEnvelope" } } } }, "401": { "description": "Missing, invalid or expired bearer user token.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1ErrorEnvelope" } } } }, "403": { "description": "The bearer token does not grant personal.budgets.read consent.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1ErrorEnvelope" } } } }, "404": { "description": "Personal budget not found.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1ErrorEnvelope" } } } }, "405": { "description": "Only GET and PATCH are allowed for this route.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1ErrorEnvelope" } } } }, "500": { "description": "Generic server failure. Internal database details must not be returned.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1ErrorEnvelope" } } } } }, "x-financial-iq-safety": { "requiresApiKey": false, "apiKeysAllowed": false, "requiresUserBearerToken": true, "scope": "personal.budgets.read", "businessMutation": false, "directFinancialMutation": false, "writeLevel": "read", "requiresIdempotencyKey": false, "auditedEndpoint": "v1/personal/budgets/{budget_id}" }, "x-implementation": { "edgeFunction": "supabase/functions/financial-data-api/index.ts", "handler": "handleV1PersonalBudgetDetail", "tests": [ "supabase/functions/financial-data-api/invoice_idempotency.test.ts" ] } }, "patch": { "tags": [ "Personal" ], "operationId": "updatePersonalBudget", "summary": "Update personal budget", "description": "Updates safe fields for one personal budget owned by the bearer-token user. This route requires explicit personal.budgets.write consent and an Idempotency-Key. It cannot be called with an API key and does not create transactions, move money, post ledger entries, file tax submissions, or mutate business books.", "security": [ { "BearerAuth": [] } ], "parameters": [ { "name": "budget_id", "in": "path", "required": true, "description": "Personal budget id to update.", "schema": { "type": "string", "format": "uuid" } }, { "$ref": "#/components/parameters/RequestId" }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PersonalBudgetUpdateRequest" } } } }, "responses": { "200": { "description": "Personal budget updated.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PersonalBudgetUpdateResponse" } } } }, "400": { "description": "Invalid request body, linked reference, missing Idempotency-Key, or invalid budget_id path parameter.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1ErrorEnvelope" } } } }, "401": { "description": "Missing, invalid or expired bearer user token.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1ErrorEnvelope" } } } }, "403": { "description": "The bearer token does not grant personal.budgets.write consent.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1ErrorEnvelope" } } } }, "404": { "description": "Personal budget not found.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1ErrorEnvelope" } } } }, "405": { "description": "Only GET and PATCH are allowed for this route.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1ErrorEnvelope" } } } }, "409": { "description": "The Idempotency-Key is currently processing or was used with a different request body.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1ErrorEnvelope" } } } }, "500": { "description": "Generic server failure. Internal database details must not be returned.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1ErrorEnvelope" } } } } }, "x-financial-iq-safety": { "requiresApiKey": false, "apiKeysAllowed": false, "requiresUserBearerToken": true, "scope": "personal.budgets.write", "businessMutation": false, "directFinancialMutation": false, "writeLevel": "personal_budget", "requiresIdempotencyKey": true, "auditedEndpoint": "v1/personal/budgets/{budget_id}", "forbiddenFields": [ "id", "user_id", "created_at", "updated_at", "transactions", "business_transaction_ids", "ledger_entries", "bank_account_id", "company_id" ], "doesNot": [ "create_transactions", "move_money", "post_ledger_entries", "file_tax_returns", "mutate_business_books" ] }, "x-implementation": { "edgeFunction": "supabase/functions/financial-data-api/index.ts", "handler": "updateV1PersonalBudget", "tests": [ "supabase/functions/financial-data-api/invoice_idempotency.test.ts" ] } } }, "/v1/personal/categories": { "get": { "tags": [ "Personal" ], "operationId": "listPersonalCategories", "summary": "List personal categories", "description": "Lists personal finance categories for the bearer-token user. This route requires explicit personal.categories.read consent and cannot be called with an API key.", "security": [ { "BearerAuth": [] } ], "parameters": [ { "$ref": "#/components/parameters/RequestId" }, { "name": "search", "in": "query", "required": false, "description": "Search categories by name.", "schema": { "type": "string", "minLength": 1, "maxLength": 200 } }, { "name": "q", "in": "query", "required": false, "description": "Alias for search.", "schema": { "type": "string", "minLength": 1, "maxLength": 200 } }, { "name": "category_type", "in": "query", "required": false, "description": "Optional category type filter.", "schema": { "type": "string", "enum": [ "income", "expense", "transfer" ] } }, { "name": "parent_id", "in": "query", "required": false, "description": "Optional parent category id filter.", "schema": { "type": "string", "format": "uuid" } }, { "name": "is_active", "in": "query", "required": false, "description": "Optional active-state filter.", "schema": { "type": "boolean" } }, { "name": "limit", "in": "query", "required": false, "description": "Maximum number of categories to return. Values are clamped between 1 and 200.", "schema": { "type": "integer", "minimum": 1, "maximum": 200, "default": 100 } }, { "name": "offset", "in": "query", "required": false, "description": "Zero-based offset for paginating categories.", "schema": { "type": "integer", "minimum": 0, "default": 0 } } ], "responses": { "200": { "description": "User-authorised personal categories returned.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PersonalCategoryListResponse" } } } }, "400": { "description": "A filter parameter is invalid.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1ErrorEnvelope" } } } }, "401": { "description": "Missing, invalid or expired bearer user token.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1ErrorEnvelope" } } } }, "403": { "description": "The bearer token does not grant personal.categories.read consent.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1ErrorEnvelope" } } } }, "405": { "description": "Only GET is allowed for this route.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1ErrorEnvelope" } } } }, "500": { "description": "Generic server failure. Internal database details must not be returned.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1ErrorEnvelope" } } } } }, "x-financial-iq-safety": { "requiresApiKey": false, "apiKeysAllowed": false, "requiresUserBearerToken": true, "scope": "personal.categories.read", "businessMutation": false, "directFinancialMutation": false, "writeLevel": "read", "requiresIdempotencyKey": false, "auditedEndpoint": "v1/personal/categories" }, "x-implementation": { "edgeFunction": "supabase/functions/financial-data-api/index.ts", "handler": "handleV1PersonalCategories", "tests": [ "supabase/functions/financial-data-api/invoice_idempotency.test.ts" ] } }, "post": { "tags": [ "Personal" ], "operationId": "createPersonalCategory", "summary": "Create personal category", "description": "Creates a personal finance category for the bearer-token user. This route requires explicit personal.categories.write consent, cannot be called with an API key, and does not create transactions, budgets, postings or tax submissions.", "security": [ { "BearerAuth": [] } ], "parameters": [ { "$ref": "#/components/parameters/RequestId" }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PersonalCategoryCreateRequest" } } } }, "responses": { "201": { "description": "Personal category created.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PersonalCategoryCreateResponse" } } } }, "400": { "description": "The request body or idempotency key is invalid.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1ErrorEnvelope" } } } }, "401": { "description": "Missing, invalid or expired bearer user token.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1ErrorEnvelope" } } } }, "403": { "description": "The bearer token does not grant personal.categories.write consent.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1ErrorEnvelope" } } } }, "405": { "description": "Only GET and POST are allowed for this route.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1ErrorEnvelope" } } } }, "409": { "description": "The idempotency key conflicts with a different request body or an in-progress request.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1ErrorEnvelope" } } } }, "500": { "description": "Generic server failure. Internal database details must not be returned.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1ErrorEnvelope" } } } } }, "x-financial-iq-safety": { "requiresApiKey": false, "apiKeysAllowed": false, "requiresUserBearerToken": true, "scope": "personal.categories.write", "businessMutation": false, "directFinancialMutation": false, "writeLevel": "configuration", "requiresIdempotencyKey": true, "auditedEndpoint": "v1/personal/categories" }, "x-implementation": { "edgeFunction": "supabase/functions/financial-data-api/index.ts", "handler": "createV1PersonalCategory", "tests": [ "supabase/functions/financial-data-api/invoice_idempotency.test.ts" ] } } }, "/v1/personal/categories/{category_id}": { "get": { "tags": [ "Personal" ], "operationId": "getPersonalCategory", "summary": "Get one personal category", "description": "Returns one personal category for the bearer-token user. Inaccessible category IDs are returned as not found to avoid leaking another user's data.", "security": [ { "BearerAuth": [] } ], "parameters": [ { "name": "category_id", "in": "path", "required": true, "description": "Personal category id to fetch.", "schema": { "type": "string", "format": "uuid" } }, { "$ref": "#/components/parameters/RequestId" } ], "responses": { "200": { "description": "User-authorised personal category returned.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PersonalCategoryResponse" } } } }, "400": { "description": "The category_id path parameter is not a valid UUID.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1ErrorEnvelope" } } } }, "401": { "description": "Missing, invalid or expired bearer user token.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1ErrorEnvelope" } } } }, "403": { "description": "The bearer token does not grant personal.categories.read consent.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1ErrorEnvelope" } } } }, "404": { "description": "Personal category not found.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1ErrorEnvelope" } } } }, "405": { "description": "Only GET and PATCH are allowed for this route.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1ErrorEnvelope" } } } }, "500": { "description": "Generic server failure. Internal database details must not be returned.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1ErrorEnvelope" } } } } }, "x-financial-iq-safety": { "requiresApiKey": false, "apiKeysAllowed": false, "requiresUserBearerToken": true, "scope": "personal.categories.read", "businessMutation": false, "directFinancialMutation": false, "writeLevel": "read", "requiresIdempotencyKey": false, "auditedEndpoint": "v1/personal/categories/{category_id}" }, "x-implementation": { "edgeFunction": "supabase/functions/financial-data-api/index.ts", "handler": "handleV1PersonalCategoryDetail", "tests": [ "supabase/functions/financial-data-api/invoice_idempotency.test.ts" ] } }, "patch": { "tags": [ "Personal" ], "operationId": "updatePersonalCategory", "summary": "Update personal category", "description": "Updates safe fields for one personal category owned by the bearer-token user. This route requires explicit personal.categories.write consent and an Idempotency-Key. It cannot be called with an API key and does not create transactions, budgets, move money, post ledger entries, file tax submissions, or mutate business books.", "security": [ { "BearerAuth": [] } ], "parameters": [ { "name": "category_id", "in": "path", "required": true, "description": "Personal category id to update.", "schema": { "type": "string", "format": "uuid" } }, { "$ref": "#/components/parameters/RequestId" }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PersonalCategoryUpdateRequest" } } } }, "responses": { "200": { "description": "Personal category updated.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PersonalCategoryUpdateResponse" } } } }, "400": { "description": "Invalid request body, linked parent category, missing Idempotency-Key, or invalid category_id path parameter.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1ErrorEnvelope" } } } }, "401": { "description": "Missing, invalid or expired bearer user token.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1ErrorEnvelope" } } } }, "403": { "description": "The bearer token does not grant personal.categories.write consent.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1ErrorEnvelope" } } } }, "404": { "description": "Personal category not found.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1ErrorEnvelope" } } } }, "405": { "description": "Only GET and PATCH are allowed for this route.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1ErrorEnvelope" } } } }, "409": { "description": "The Idempotency-Key is currently processing or was used with a different request body.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1ErrorEnvelope" } } } }, "500": { "description": "Generic server failure. Internal database details must not be returned.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1ErrorEnvelope" } } } } }, "x-financial-iq-safety": { "requiresApiKey": false, "apiKeysAllowed": false, "requiresUserBearerToken": true, "scope": "personal.categories.write", "businessMutation": false, "directFinancialMutation": false, "writeLevel": "personal_category", "requiresIdempotencyKey": true, "auditedEndpoint": "v1/personal/categories/{category_id}", "forbiddenFields": [ "id", "user_id", "created_at", "updated_at", "transactions", "budgets", "goals", "business_transaction_ids", "ledger_entries", "company_id" ], "doesNot": [ "create_transactions", "update_transactions", "move_money", "post_ledger_entries", "file_tax_returns", "mutate_business_books" ] }, "x-implementation": { "edgeFunction": "supabase/functions/financial-data-api/index.ts", "handler": "updateV1PersonalCategory", "tests": [ "supabase/functions/financial-data-api/invoice_idempotency.test.ts" ] } } }, "/v1/personal/categorization-rules": { "get": { "tags": [ "Personal" ], "operationId": "listPersonalCategorizationRules", "summary": "List personal categorization rules", "description": "Returns user-owned personal categorization rules for the bearer-token user. This route reads categorization rule metadata and a minimal category label only; it does not return transaction rows, account details, provider payloads, business ledger data or another user's rules.", "security": [ { "BearerAuth": [] } ], "parameters": [ { "$ref": "#/components/parameters/RequestId" }, { "name": "category_id", "in": "query", "required": false, "schema": { "type": "string", "format": "uuid" }, "description": "Only return rules mapped to this personal category." }, { "name": "match_type", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "contains", "starts_with", "equals" ] } }, { "name": "pattern_type", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "merchant", "keyword" ] } }, { "name": "is_active", "in": "query", "required": false, "schema": { "type": "boolean" } }, { "name": "search", "in": "query", "required": false, "schema": { "type": "string", "minLength": 1, "maxLength": 120 }, "description": "Case-insensitive search against the rule pattern." }, { "$ref": "#/components/parameters/Limit" }, { "$ref": "#/components/parameters/Offset" } ], "responses": { "200": { "description": "User-owned personal categorization rules returned.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PersonalCategorizationRuleListResponse" } } } }, "400": { "description": "Invalid filter supplied.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1ErrorEnvelope" } } } }, "401": { "description": "Missing, invalid or expired bearer user token.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1ErrorEnvelope" } } } }, "403": { "description": "The bearer token does not grant every required personal categorization-rule consent scope.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1ErrorEnvelope" } } } }, "405": { "description": "Only GET and POST are allowed for this route.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1ErrorEnvelope" } } } }, "500": { "description": "Generic server failure. Internal database details must not be returned.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1ErrorEnvelope" } } } } }, "x-financial-iq-safety": { "requiresApiKey": false, "apiKeysAllowed": false, "requiresUserBearerToken": true, "scopes": [ "personal.transactions.read", "personal.categories.read" ], "scopeFamily": "personal.categorization_rules", "personalData": true, "businessMutation": false, "directFinancialMutation": false, "writeLevel": "read", "requiresIdempotencyKey": false, "redactedFields": [ "transaction_rows", "transaction_description", "merchant_transaction_rows", "account_number", "sort_code", "account_number_ct", "sort_code_ct", "bank_feed_tokens", "provider_metadata", "business_ledger_rows" ], "doesNot": [ "return_transactions", "return_account_numbers", "return_sort_codes", "return_bank_statement_lines", "return_provider_payloads", "mutate_transactions", "connect_bank_feeds", "move_money", "post_ledger_entries", "raise_invoices", "file_tax", "mutate_business_books" ], "auditedEndpoint": "v1/personal/categorization-rules" }, "x-implementation": { "edgeFunction": "financial-data-api", "handler": "handleV1PersonalCategorizationRules", "sourceFile": "supabase/functions/financial-data-api/v1.ts" } }, "post": { "tags": [ "Personal" ], "operationId": "createPersonalCategorizationRule", "summary": "Create personal categorization rule", "description": "Creates one user-owned personal categorization rule for future transaction categorisation. Requires bearer-user consent, a valid owned category, and Idempotency-Key. The route does not categorise existing transactions and does not allow callers to set usage, success-rate or confidence metrics.", "security": [ { "BearerAuth": [] } ], "parameters": [ { "$ref": "#/components/parameters/RequestId" }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PersonalCategorizationRuleCreateRequest" } } } }, "responses": { "201": { "description": "Personal categorization rule created.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PersonalCategorizationRuleCreateResponse" } } } }, "400": { "description": "Invalid rule payload, missing Idempotency-Key or inaccessible category id.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1ErrorEnvelope" } } } }, "401": { "description": "Missing, invalid or expired bearer user token.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1ErrorEnvelope" } } } }, "403": { "description": "The bearer token does not grant every required personal categorization-rule write consent scope.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1ErrorEnvelope" } } } }, "405": { "description": "Only GET and POST are allowed for this route.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1ErrorEnvelope" } } } }, "409": { "description": "The Idempotency-Key was reused with a different request body.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1ErrorEnvelope" } } } }, "500": { "description": "Generic server failure. Internal database details must not be returned.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1ErrorEnvelope" } } } } }, "x-financial-iq-safety": { "requiresApiKey": false, "apiKeysAllowed": false, "requiresUserBearerToken": true, "scopes": [ "personal.transactions.write", "personal.categories.read" ], "scopeFamily": "personal.categorization_rules", "personalData": true, "businessMutation": false, "directFinancialMutation": false, "writeLevel": "configuration", "requiresIdempotencyKey": true, "redactedFields": [ "transaction_rows", "transaction_description", "merchant_transaction_rows", "account_number", "sort_code", "account_number_ct", "sort_code_ct", "bank_feed_tokens", "provider_metadata", "business_ledger_rows", "usage_count_write", "success_rate_write", "confidence_score_write" ], "doesNot": [ "return_transactions", "return_account_numbers", "return_sort_codes", "return_bank_statement_lines", "return_provider_payloads", "mutate_transactions", "connect_bank_feeds", "move_money", "post_ledger_entries", "raise_invoices", "file_tax", "mutate_business_books", "mutate_rule_metrics", "recategorise_existing_transactions", "create_transactions" ], "auditedEndpoint": "v1/personal/categorization-rules" }, "x-implementation": { "edgeFunction": "financial-data-api", "handler": "createV1PersonalCategorizationRule", "sourceFile": "supabase/functions/financial-data-api/v1.ts" } } }, "/v1/personal/categorization-rules/{rule_id}": { "get": { "tags": [ "Personal" ], "operationId": "getPersonalCategorizationRule", "summary": "Get one personal categorization rule", "description": "Returns one user-owned personal categorization rule. Inaccessible rule IDs are returned as not found to avoid leaking another user's data.", "security": [ { "BearerAuth": [] } ], "parameters": [ { "name": "rule_id", "in": "path", "required": true, "description": "Personal categorization rule id to fetch.", "schema": { "type": "string", "format": "uuid" } }, { "$ref": "#/components/parameters/RequestId" } ], "responses": { "200": { "description": "User-owned personal categorization rule returned.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PersonalCategorizationRuleResponse" } } } }, "400": { "description": "The rule_id path parameter is not a valid UUID.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1ErrorEnvelope" } } } }, "401": { "description": "Missing, invalid or expired bearer user token.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1ErrorEnvelope" } } } }, "403": { "description": "The bearer token does not grant every required personal categorization-rule read consent scope.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1ErrorEnvelope" } } } }, "404": { "description": "Personal categorization rule not found.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1ErrorEnvelope" } } } }, "405": { "description": "Only GET and PATCH are allowed for this route.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1ErrorEnvelope" } } } }, "500": { "description": "Generic server failure. Internal database details must not be returned.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1ErrorEnvelope" } } } } }, "x-financial-iq-safety": { "requiresApiKey": false, "apiKeysAllowed": false, "requiresUserBearerToken": true, "scopes": [ "personal.transactions.read", "personal.categories.read" ], "scopeFamily": "personal.categorization_rules", "personalData": true, "businessMutation": false, "directFinancialMutation": false, "writeLevel": "read", "requiresIdempotencyKey": false, "redactedFields": [ "transaction_rows", "transaction_description", "merchant_transaction_rows", "account_number", "sort_code", "account_number_ct", "sort_code_ct", "bank_feed_tokens", "provider_metadata", "business_ledger_rows" ], "doesNot": [ "return_transactions", "return_account_numbers", "return_sort_codes", "return_bank_statement_lines", "return_provider_payloads", "mutate_transactions", "connect_bank_feeds", "move_money", "post_ledger_entries", "raise_invoices", "file_tax", "mutate_business_books" ], "auditedEndpoint": "v1/personal/categorization-rules/{rule_id}" }, "x-implementation": { "edgeFunction": "financial-data-api", "handler": "handleV1PersonalCategorizationRuleDetail", "sourceFile": "supabase/functions/financial-data-api/v1.ts" } }, "patch": { "tags": [ "Personal" ], "operationId": "updatePersonalCategorizationRule", "summary": "Update personal categorization rule", "description": "Updates safe fields on one user-owned personal categorization rule. Requires bearer-user consent, a valid owned category when category_id is supplied, and Idempotency-Key. This does not re-categorise existing transactions or let callers edit rule metrics.", "security": [ { "BearerAuth": [] } ], "parameters": [ { "name": "rule_id", "in": "path", "required": true, "description": "Personal categorization rule id to update.", "schema": { "type": "string", "format": "uuid" } }, { "$ref": "#/components/parameters/RequestId" }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PersonalCategorizationRuleUpdateRequest" } } } }, "responses": { "200": { "description": "Personal categorization rule updated.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PersonalCategorizationRuleUpdateResponse" } } } }, "400": { "description": "Invalid update payload, invalid rule_id, missing Idempotency-Key or inaccessible category id.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1ErrorEnvelope" } } } }, "401": { "description": "Missing, invalid or expired bearer user token.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1ErrorEnvelope" } } } }, "403": { "description": "The bearer token does not grant every required personal categorization-rule write consent scope.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1ErrorEnvelope" } } } }, "404": { "description": "Personal categorization rule not found.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1ErrorEnvelope" } } } }, "405": { "description": "Only GET and PATCH are allowed for this route.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1ErrorEnvelope" } } } }, "409": { "description": "The Idempotency-Key was reused with a different request body.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1ErrorEnvelope" } } } }, "500": { "description": "Generic server failure. Internal database details must not be returned.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1ErrorEnvelope" } } } } }, "x-financial-iq-safety": { "requiresApiKey": false, "apiKeysAllowed": false, "requiresUserBearerToken": true, "scopes": [ "personal.transactions.write", "personal.categories.read" ], "scopeFamily": "personal.categorization_rules", "personalData": true, "businessMutation": false, "directFinancialMutation": false, "writeLevel": "configuration", "requiresIdempotencyKey": true, "redactedFields": [ "transaction_rows", "transaction_description", "merchant_transaction_rows", "account_number", "sort_code", "account_number_ct", "sort_code_ct", "bank_feed_tokens", "provider_metadata", "business_ledger_rows", "usage_count_write", "success_rate_write", "confidence_score_write" ], "doesNot": [ "return_transactions", "return_account_numbers", "return_sort_codes", "return_bank_statement_lines", "return_provider_payloads", "mutate_transactions", "connect_bank_feeds", "move_money", "post_ledger_entries", "raise_invoices", "file_tax", "mutate_business_books", "mutate_rule_metrics", "recategorise_existing_transactions", "create_transactions" ], "auditedEndpoint": "v1/personal/categorization-rules/{rule_id}" }, "x-implementation": { "edgeFunction": "financial-data-api", "handler": "updateV1PersonalCategorizationRule", "sourceFile": "supabase/functions/financial-data-api/v1.ts" } } }, "/v1/personal/goals": { "get": { "tags": [ "Personal" ], "operationId": "listPersonalGoals", "summary": "List personal goals", "description": "Lists personal finance goals for the bearer-token user. This route requires explicit personal.goals.read consent and cannot be called with an API key.", "security": [ { "BearerAuth": [] } ], "parameters": [ { "$ref": "#/components/parameters/RequestId" }, { "name": "search", "in": "query", "required": false, "description": "Search goals by name.", "schema": { "type": "string", "minLength": 1, "maxLength": 200 } }, { "name": "q", "in": "query", "required": false, "description": "Alias for search.", "schema": { "type": "string", "minLength": 1, "maxLength": 200 } }, { "name": "category_id", "in": "query", "required": false, "description": "Optional personal category id filter.", "schema": { "type": "string", "format": "uuid" } }, { "name": "linked_account_id", "in": "query", "required": false, "description": "Optional linked personal account id filter.", "schema": { "type": "string", "format": "uuid" } }, { "name": "goal_type", "in": "query", "required": false, "description": "Optional goal type filter.", "schema": { "type": "string" } }, { "name": "is_achieved", "in": "query", "required": false, "description": "Optional achieved-state filter.", "schema": { "type": "boolean" } }, { "name": "is_shared", "in": "query", "required": false, "description": "Optional shared-goal filter.", "schema": { "type": "boolean" } }, { "name": "from_target_date", "in": "query", "required": false, "description": "Inclusive target-date lower bound in YYYY-MM-DD format.", "schema": { "type": "string", "format": "date" } }, { "name": "to_target_date", "in": "query", "required": false, "description": "Inclusive target-date upper bound in YYYY-MM-DD format.", "schema": { "type": "string", "format": "date" } }, { "name": "limit", "in": "query", "required": false, "description": "Maximum number of goals to return. Values are clamped between 1 and 200.", "schema": { "type": "integer", "minimum": 1, "maximum": 200, "default": 100 } }, { "name": "offset", "in": "query", "required": false, "description": "Zero-based offset for paginating goals.", "schema": { "type": "integer", "minimum": 0, "default": 0 } } ], "responses": { "200": { "description": "User-authorised personal goals returned.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PersonalGoalListResponse" } } } }, "400": { "description": "A filter parameter is invalid.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1ErrorEnvelope" } } } }, "401": { "description": "Missing, invalid or expired bearer user token.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1ErrorEnvelope" } } } }, "403": { "description": "The bearer token does not grant personal.goals.read consent.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1ErrorEnvelope" } } } }, "405": { "description": "Only GET is allowed for this route.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1ErrorEnvelope" } } } }, "500": { "description": "Generic server failure. Internal database details must not be returned.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1ErrorEnvelope" } } } } }, "x-financial-iq-safety": { "requiresApiKey": false, "apiKeysAllowed": false, "requiresUserBearerToken": true, "scope": "personal.goals.read", "businessMutation": false, "directFinancialMutation": false, "writeLevel": "read", "requiresIdempotencyKey": false, "auditedEndpoint": "v1/personal/goals" }, "x-implementation": { "edgeFunction": "supabase/functions/financial-data-api/index.ts", "handler": "handleV1PersonalGoals", "tests": [ "supabase/functions/financial-data-api/invoice_idempotency.test.ts" ] } }, "post": { "tags": [ "Personal" ], "operationId": "createPersonalGoal", "summary": "Create personal goal", "description": "Creates a personal planning goal for the bearer-token user. This route requires explicit personal.goals.write consent, cannot be called with an API key, and does not create transactions, move money, post ledger entries, or file tax submissions.", "security": [ { "BearerAuth": [] } ], "parameters": [ { "$ref": "#/components/parameters/RequestId" }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PersonalGoalCreateRequest" } } } }, "responses": { "201": { "description": "Personal goal created.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PersonalGoalCreateResponse" } } } }, "400": { "description": "The request body or idempotency key is invalid.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1ErrorEnvelope" } } } }, "401": { "description": "Missing, invalid or expired bearer user token.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1ErrorEnvelope" } } } }, "403": { "description": "The bearer token does not grant personal.goals.write consent.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1ErrorEnvelope" } } } }, "405": { "description": "Only GET and POST are allowed for this route.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1ErrorEnvelope" } } } }, "409": { "description": "The idempotency key conflicts with a different request body or an in-progress request.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1ErrorEnvelope" } } } }, "500": { "description": "Generic server failure. Internal database details must not be returned.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1ErrorEnvelope" } } } } }, "x-financial-iq-safety": { "requiresApiKey": false, "apiKeysAllowed": false, "requiresUserBearerToken": true, "scope": "personal.goals.write", "businessMutation": false, "directFinancialMutation": false, "writeLevel": "configuration", "requiresIdempotencyKey": true, "auditedEndpoint": "v1/personal/goals" }, "x-implementation": { "edgeFunction": "supabase/functions/financial-data-api/index.ts", "handler": "createV1PersonalGoal", "tests": [ "supabase/functions/financial-data-api/invoice_idempotency.test.ts" ] } } }, "/v1/personal/goals/{goal_id}": { "get": { "tags": [ "Personal" ], "operationId": "getPersonalGoal", "summary": "Get one personal goal", "description": "Returns one personal goal for the bearer-token user. Inaccessible goal IDs are returned as not found to avoid leaking another user's data.", "security": [ { "BearerAuth": [] } ], "parameters": [ { "name": "goal_id", "in": "path", "required": true, "description": "Personal goal id to fetch.", "schema": { "type": "string", "format": "uuid" } }, { "$ref": "#/components/parameters/RequestId" } ], "responses": { "200": { "description": "User-authorised personal goal returned.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PersonalGoalResponse" } } } }, "400": { "description": "The goal_id path parameter is not a valid UUID.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1ErrorEnvelope" } } } }, "401": { "description": "Missing, invalid or expired bearer user token.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1ErrorEnvelope" } } } }, "403": { "description": "The bearer token does not grant personal.goals.read consent.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1ErrorEnvelope" } } } }, "404": { "description": "Personal goal not found.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1ErrorEnvelope" } } } }, "405": { "description": "Only GET and PATCH are allowed for this route.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1ErrorEnvelope" } } } }, "500": { "description": "Generic server failure. Internal database details must not be returned.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1ErrorEnvelope" } } } } }, "x-financial-iq-safety": { "requiresApiKey": false, "apiKeysAllowed": false, "requiresUserBearerToken": true, "scope": "personal.goals.read", "businessMutation": false, "directFinancialMutation": false, "writeLevel": "read", "requiresIdempotencyKey": false, "auditedEndpoint": "v1/personal/goals/{goal_id}" }, "x-implementation": { "edgeFunction": "supabase/functions/financial-data-api/index.ts", "handler": "handleV1PersonalGoalDetail", "tests": [ "supabase/functions/financial-data-api/invoice_idempotency.test.ts" ] } }, "patch": { "tags": [ "Personal" ], "operationId": "updatePersonalGoal", "summary": "Update personal goal", "description": "Updates safe planning and progress fields for one personal goal owned by the bearer-token user. This route requires explicit personal.goals.write consent and an Idempotency-Key. It cannot be called with an API key and does not create transactions, move money, post ledger entries, file tax submissions, or mutate business books.", "security": [ { "BearerAuth": [] } ], "parameters": [ { "name": "goal_id", "in": "path", "required": true, "description": "Personal goal id to update.", "schema": { "type": "string", "format": "uuid" } }, { "$ref": "#/components/parameters/RequestId" }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PersonalGoalUpdateRequest" } } } }, "responses": { "200": { "description": "Personal goal updated.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PersonalGoalUpdateResponse" } } } }, "400": { "description": "Invalid request body, linked reference, missing Idempotency-Key, or invalid goal_id path parameter.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1ErrorEnvelope" } } } }, "401": { "description": "Missing, invalid or expired bearer user token.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1ErrorEnvelope" } } } }, "403": { "description": "The bearer token does not grant personal.goals.write consent.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1ErrorEnvelope" } } } }, "404": { "description": "Personal goal not found.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1ErrorEnvelope" } } } }, "405": { "description": "Only GET and PATCH are allowed for this route.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1ErrorEnvelope" } } } }, "409": { "description": "The Idempotency-Key is currently processing or was used with a different request body.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1ErrorEnvelope" } } } }, "500": { "description": "Generic server failure. Internal database details must not be returned.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1ErrorEnvelope" } } } } }, "x-financial-iq-safety": { "requiresApiKey": false, "apiKeysAllowed": false, "requiresUserBearerToken": true, "scope": "personal.goals.write", "businessMutation": false, "directFinancialMutation": false, "writeLevel": "personal_goal", "requiresIdempotencyKey": true, "auditedEndpoint": "v1/personal/goals/{goal_id}", "forbiddenFields": [ "id", "user_id", "created_at", "updated_at", "transactions", "bank_balances", "business_transaction_ids", "ledger_entries", "company_id" ], "doesNot": [ "create_transactions", "move_money", "post_ledger_entries", "file_tax_returns", "mutate_business_books" ] }, "x-implementation": { "edgeFunction": "supabase/functions/financial-data-api/index.ts", "handler": "updateV1PersonalGoal", "tests": [ "supabase/functions/financial-data-api/invoice_idempotency.test.ts" ] } } }, "/v1/personal/transactions": { "get": { "tags": [ "Personal" ], "operationId": "listPersonalTransactions", "summary": "List personal transactions", "description": "Lists personal bank transactions for the bearer-token user. This route requires explicit personal.transactions.read consent and never returns raw provider payloads or external provider transaction identifiers.", "security": [ { "BearerAuth": [] } ], "parameters": [ { "$ref": "#/components/parameters/RequestId" }, { "name": "limit", "in": "query", "required": false, "description": "Maximum number of transactions to return. Values are clamped between 1 and 200.", "schema": { "type": "integer", "minimum": 1, "maximum": 200, "default": 100 } }, { "name": "offset", "in": "query", "required": false, "description": "Zero-based offset for paginating transaction results.", "schema": { "type": "integer", "minimum": 0, "default": 0 } }, { "name": "account_id", "in": "query", "required": false, "description": "Filter to one personal account.", "schema": { "type": "string", "format": "uuid" } }, { "name": "category_id", "in": "query", "required": false, "description": "Filter to one personal category.", "schema": { "type": "string", "format": "uuid" } }, { "name": "transaction_type", "in": "query", "required": false, "description": "Filter by stored transaction type, such as debit, credit, income or expense.", "schema": { "type": "string" } }, { "name": "from_date", "in": "query", "required": false, "description": "Inclusive transaction-date lower bound in YYYY-MM-DD format.", "schema": { "type": "string", "format": "date" } }, { "name": "to_date", "in": "query", "required": false, "description": "Inclusive transaction-date upper bound in YYYY-MM-DD format.", "schema": { "type": "string", "format": "date" } }, { "name": "uncategorised", "in": "query", "required": false, "description": "When true, returns transactions without a personal category.", "schema": { "type": "boolean" } } ], "responses": { "200": { "description": "User-authorised personal transactions returned.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PersonalTransactionListResponse" } } } }, "400": { "description": "Invalid filter parameter.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1ErrorEnvelope" } } } }, "401": { "description": "Missing, invalid or expired bearer user token.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1ErrorEnvelope" } } } }, "403": { "description": "The bearer token does not grant personal.transactions.read consent.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1ErrorEnvelope" } } } }, "405": { "description": "Only GET is allowed for this route.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1ErrorEnvelope" } } } }, "500": { "description": "Generic server failure. Internal database details must not be returned.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1ErrorEnvelope" } } } } }, "x-financial-iq-safety": { "requiresApiKey": false, "apiKeysAllowed": false, "requiresUserBearerToken": true, "scope": "personal.transactions.read", "businessMutation": false, "directFinancialMutation": false, "writeLevel": "read", "requiresIdempotencyKey": false, "redactedFields": [ "provider_metadata", "external_transaction_id", "statement_line_id", "raw_provider_payload" ], "auditedEndpoint": "v1/personal/transactions" }, "x-implementation": { "edgeFunction": "supabase/functions/financial-data-api/index.ts", "handler": "handleV1PersonalTransactions", "tests": [ "supabase/functions/financial-data-api/invoice_idempotency.test.ts" ] } }, "post": { "tags": [ "Personal" ], "operationId": "createPersonalTransaction", "summary": "Create a manual personal transaction", "description": "Creates one manual personal transaction for the bearer-token user. This route requires explicit personal.transactions.write consent and an Idempotency-Key. It does not connect a bank feed, import provider transactions, move money, reconcile statements, post ledger entries, or file tax returns.", "security": [ { "BearerAuth": [] } ], "parameters": [ { "$ref": "#/components/parameters/RequestId" }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PersonalTransactionCreateRequest" } } } }, "responses": { "201": { "description": "Manual personal transaction created.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PersonalTransactionCreateResponse" } } } }, "400": { "description": "Invalid request body, inaccessible account/category, or missing Idempotency-Key.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1ErrorEnvelope" } } } }, "401": { "description": "Missing, invalid or expired bearer user token.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1ErrorEnvelope" } } } }, "403": { "description": "The bearer token does not grant personal.transactions.write consent.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1ErrorEnvelope" } } } }, "405": { "description": "Only GET and POST are allowed for this route.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1ErrorEnvelope" } } } } }, "x-financial-iq-safety": { "requiresApiKey": false, "apiKeysAllowed": false, "requiresUserBearerToken": true, "scope": "personal.transactions.write", "businessMutation": false, "directFinancialMutation": true, "writeLevel": "manual_transaction_record", "requiresIdempotencyKey": true, "auditedEndpoint": "v1/personal/transactions", "forbiddenFields": [ "company_id", "context_type", "external_transaction_id", "provider_metadata", "raw_provider_payload", "statement_line_id", "chart_of_accounts_id", "posted_journal_id", "posting_status", "reconciliation_status", "is_matched", "matched_transaction_id", "vat_amount", "vat_rate" ], "doesNot": [ "connect_bank_feed", "import_provider_transactions", "move_money", "reconcile_statements", "post_ledger_entries", "file_tax_returns", "change_business_books" ] }, "x-implementation": { "edgeFunction": "supabase/functions/financial-data-api/index.ts", "handler": "createV1PersonalTransaction", "tests": [ "supabase/functions/financial-data-api/invoice_idempotency.test.ts" ] } } }, "/v1/personal/transactions/{transaction_id}": { "get": { "tags": [ "Personal" ], "operationId": "getPersonalTransaction", "summary": "Get one personal transaction", "description": "Returns one personal transaction owned by the bearer-token user. Inaccessible transactions are returned as not found.", "security": [ { "BearerAuth": [] } ], "parameters": [ { "name": "transaction_id", "in": "path", "required": true, "description": "Personal transaction id to fetch.", "schema": { "type": "string", "format": "uuid" } }, { "$ref": "#/components/parameters/RequestId" } ], "responses": { "200": { "description": "User-authorised personal transaction returned.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PersonalTransactionResponse" } } } }, "400": { "description": "The transaction_id path parameter is not a valid UUID.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1ErrorEnvelope" } } } }, "401": { "description": "Missing, invalid or expired bearer user token.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1ErrorEnvelope" } } } }, "403": { "description": "The bearer token does not grant personal.transactions.read consent.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1ErrorEnvelope" } } } }, "404": { "description": "Personal transaction not found.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1ErrorEnvelope" } } } }, "405": { "description": "Only GET is allowed for this route.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1ErrorEnvelope" } } } }, "500": { "description": "Generic server failure. Internal database details must not be returned.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1ErrorEnvelope" } } } } }, "x-financial-iq-safety": { "requiresApiKey": false, "apiKeysAllowed": false, "requiresUserBearerToken": true, "scope": "personal.transactions.read", "businessMutation": false, "directFinancialMutation": false, "writeLevel": "read", "requiresIdempotencyKey": false, "redactedFields": [ "provider_metadata", "external_transaction_id", "statement_line_id", "raw_provider_payload" ], "auditedEndpoint": "v1/personal/transactions/{transaction_id}" }, "x-implementation": { "edgeFunction": "supabase/functions/financial-data-api/index.ts", "handler": "handleV1PersonalTransactionDetail", "tests": [ "supabase/functions/financial-data-api/invoice_idempotency.test.ts" ] } }, "patch": { "tags": [ "Personal" ], "operationId": "updatePersonalTransaction", "summary": "Update personal transaction metadata", "description": "Updates safe metadata and categorisation on one personal transaction owned by the bearer-token user. This route requires explicit personal.transactions.write consent and an Idempotency-Key. It cannot change the amount, date, account, currency, source, provider data, reconciliation state, move money, post ledger entries, file tax returns, or change business books.", "security": [ { "BearerAuth": [] } ], "parameters": [ { "name": "transaction_id", "in": "path", "required": true, "description": "Personal transaction id to fetch.", "schema": { "type": "string", "format": "uuid" } }, { "$ref": "#/components/parameters/RequestId" }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PersonalTransactionUpdateRequest" } } } }, "responses": { "200": { "description": "Personal transaction metadata updated.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" }, "X-FIQ-Idempotency-Replayed": { "$ref": "#/components/headers/IdempotencyReplayed" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PersonalTransactionUpdateResponse" } } } }, "400": { "description": "Invalid request body, inaccessible category, or missing Idempotency-Key.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1ErrorEnvelope" } } } }, "401": { "description": "Missing, invalid or expired bearer user token.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1ErrorEnvelope" } } } }, "403": { "description": "The bearer token does not grant personal.transactions.write consent.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1ErrorEnvelope" } } } }, "404": { "description": "Personal transaction not found.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1ErrorEnvelope" } } } }, "405": { "description": "Only GET and PATCH are allowed for this route.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1ErrorEnvelope" } } } }, "500": { "description": "Generic server failure. Internal database details must not be returned.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1ErrorEnvelope" } } } } }, "x-financial-iq-safety": { "requiresApiKey": false, "apiKeysAllowed": false, "requiresUserBearerToken": true, "scope": "personal.transactions.write", "businessMutation": false, "directFinancialMutation": false, "writeLevel": "personal_transaction_metadata", "requiresIdempotencyKey": true, "auditedEndpoint": "v1/personal/transactions/{transaction_id}", "forbiddenFields": [ "bank_account_id", "transaction_date", "gross_amount", "transaction_type", "currency", "company_id", "context_type", "external_transaction_id", "provider_metadata", "raw_provider_payload", "statement_line_id", "balance_after", "transaction_source", "reconciliation_status", "is_matched", "matched_transaction_id", "chart_of_accounts_id", "posted_journal_id", "posting_status", "vat_amount", "vat_rate" ], "doesNot": [ "change_transaction_amount", "change_transaction_date", "change_transaction_account", "connect_bank_feed", "import_provider_transactions", "move_money", "reconcile_statements", "post_ledger_entries", "file_tax_returns", "change_business_books" ] }, "x-implementation": { "edgeFunction": "supabase/functions/financial-data-api/index.ts", "handler": "updateV1PersonalTransaction", "tests": [ "supabase/functions/financial-data-api/invoice_idempotency.test.ts" ] } } }, "/v1/personal/business-links": { "get": { "tags": [ "Personal" ], "operationId": "listPersonalBusinessLinks", "summary": "List personal business links", "description": "Returns explicit personal-to-business links for the authenticated user. Requires a bearer user token with personal.business_links.read consent. API keys cannot call this route, and the response does not grant permission to mutate business books.", "security": [ { "BearerAuth": [] } ], "parameters": [ { "$ref": "#/components/parameters/RequestId" } ], "responses": { "200": { "description": "Personal business links returned for the authenticated user.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PersonalBusinessLinkListResponse" } } } }, "401": { "description": "Missing, invalid or expired bearer user token.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1ErrorEnvelope" } } } }, "403": { "description": "The bearer token does not grant personal.business_links.read consent, or a business API key attempted to access a personal route.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1ErrorEnvelope" } } } }, "405": { "description": "Only GET is allowed for this route.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1ErrorEnvelope" } } } } }, "x-financial-iq-safety": { "requiresApiKey": false, "apiKeysAllowed": false, "requiresUserBearerToken": true, "scope": "personal.business_links.read", "directFinancialMutation": false, "businessMutation": false, "personalData": true, "writeLevel": "read", "requiresIdempotencyKey": false, "auditedEndpoint": "v1/personal/business-links" }, "x-implementation": { "edgeFunction": "supabase/functions/financial-data-api/index.ts", "handler": "handleV1PersonalBusinessLinks", "tests": [ "supabase/functions/financial-data-api/invoice_idempotency.test.ts", "supabase/functions/financial-data-api/v1_openapi_contract.test.ts" ] } }, "post": { "tags": [ "Personal" ], "operationId": "createPersonalBusinessLink", "summary": "Create personal business link", "description": "Creates or reactivates an explicit link between the authenticated user and a company they can access. Requires a bearer user token with personal.business_links.write consent and an Idempotency-Key. API keys cannot call this route.", "security": [ { "BearerAuth": [] } ], "parameters": [ { "$ref": "#/components/parameters/RequestId" }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PersonalBusinessLinkCreateRequest" } } } }, "responses": { "200": { "description": "Existing personal business link returned or reactivated.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" }, "X-FIQ-Idempotency-Replayed": { "$ref": "#/components/headers/IdempotencyReplayed" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PersonalBusinessLinkResponse" } } } }, "201": { "description": "Personal business link created.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" }, "X-FIQ-Idempotency-Replayed": { "$ref": "#/components/headers/IdempotencyReplayed" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PersonalBusinessLinkResponse" } } } }, "400": { "description": "Invalid JSON, company_id or idempotency key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1ErrorEnvelope" } } } }, "401": { "description": "Missing, invalid or expired bearer user token.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1ErrorEnvelope" } } } }, "403": { "description": "Missing write consent or no access to the company.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1ErrorEnvelope" } } } }, "405": { "description": "Only GET and POST are allowed for this route.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1ErrorEnvelope" } } } }, "409": { "description": "Idempotency key is already processing or reused with a different body.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1ErrorEnvelope" } } } } }, "x-financial-iq-safety": { "requiresApiKey": false, "apiKeysAllowed": false, "requiresUserBearerToken": true, "scope": "personal.business_links.write", "directFinancialMutation": false, "businessMutation": false, "personalData": true, "writeLevel": "personal_link_setup", "requiresIdempotencyKey": true, "auditedEndpoint": "v1/personal/business-links" }, "x-implementation": { "edgeFunction": "supabase/functions/financial-data-api/index.ts", "handler": "createV1PersonalBusinessLink", "tests": [ "supabase/functions/financial-data-api/invoice_idempotency.test.ts", "supabase/functions/financial-data-api/v1_openapi_contract.test.ts" ] } } }, "/v1/personal/business-links/{link_id}": { "get": { "tags": [ "Personal" ], "operationId": "getPersonalBusinessLink", "summary": "Get personal business link", "description": "Returns one explicit personal-to-business link owned by the authenticated user. Requires personal.business_links.read consent. API keys cannot call this route, and the response does not grant permission to mutate business books.", "security": [ { "BearerAuth": [] } ], "parameters": [ { "name": "link_id", "in": "path", "required": true, "description": "Personal business link id.", "schema": { "type": "string", "format": "uuid" } }, { "$ref": "#/components/parameters/RequestId" } ], "responses": { "200": { "description": "Personal business link returned for the authenticated user.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PersonalBusinessLinkResponse" } } } }, "400": { "description": "Invalid link id.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1ErrorEnvelope" } } } }, "401": { "description": "Missing, invalid or expired bearer user token.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1ErrorEnvelope" } } } }, "403": { "description": "Missing read consent.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1ErrorEnvelope" } } } }, "404": { "description": "Personal business link not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1ErrorEnvelope" } } } }, "405": { "description": "Only GET and DELETE are allowed for this route.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1ErrorEnvelope" } } } }, "500": { "description": "Generic server failure. Internal database details must not be returned.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1ErrorEnvelope" } } } } }, "x-financial-iq-safety": { "requiresApiKey": false, "apiKeysAllowed": false, "requiresUserBearerToken": true, "scope": "personal.business_links.read", "directFinancialMutation": false, "businessMutation": false, "personalData": true, "writeLevel": "read", "requiresIdempotencyKey": false, "auditedEndpoint": "v1/personal/business-links/{link_id}", "doesNot": [ "grant_business_write_permission", "change_business_books", "create_business_transaction", "post_ledger_entries", "move_money", "file_tax_returns" ] }, "x-implementation": { "edgeFunction": "supabase/functions/financial-data-api/index.ts", "handler": "handleV1PersonalBusinessLinkItem", "tests": [ "supabase/functions/financial-data-api/invoice_idempotency.test.ts", "supabase/functions/financial-data-api/v1_openapi_contract.test.ts" ] } }, "delete": { "tags": [ "Personal" ], "operationId": "revokePersonalBusinessLink", "summary": "Revoke personal business link", "description": "Soft-revokes an explicit personal-to-business link owned by the authenticated user. Requires personal.business_links.write consent and an Idempotency-Key. Historical audit rows remain.", "security": [ { "BearerAuth": [] } ], "parameters": [ { "name": "link_id", "in": "path", "required": true, "description": "Personal business link id.", "schema": { "type": "string", "format": "uuid" } }, { "$ref": "#/components/parameters/RequestId" }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "responses": { "200": { "description": "Personal business link revoked.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" }, "X-FIQ-Idempotency-Replayed": { "$ref": "#/components/headers/IdempotencyReplayed" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PersonalBusinessLinkResponse" } } } }, "400": { "description": "Invalid link id or idempotency key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1ErrorEnvelope" } } } }, "401": { "description": "Missing, invalid or expired bearer user token.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1ErrorEnvelope" } } } }, "403": { "description": "Missing write consent.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1ErrorEnvelope" } } } }, "404": { "description": "Personal business link not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1ErrorEnvelope" } } } }, "405": { "description": "Only GET and DELETE are allowed for this route.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1ErrorEnvelope" } } } }, "409": { "description": "Idempotency key is already processing or reused with a different body.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1ErrorEnvelope" } } } } }, "x-financial-iq-safety": { "requiresApiKey": false, "apiKeysAllowed": false, "requiresUserBearerToken": true, "scope": "personal.business_links.write", "directFinancialMutation": false, "businessMutation": false, "personalData": true, "writeLevel": "personal_link_setup", "requiresIdempotencyKey": true, "deletesEndpointRow": false, "auditedEndpoint": "v1/personal/business-links/{link_id}" }, "x-implementation": { "edgeFunction": "supabase/functions/financial-data-api/index.ts", "handler": "handleV1PersonalBusinessLinkItem", "tests": [ "supabase/functions/financial-data-api/invoice_idempotency.test.ts", "supabase/functions/financial-data-api/v1_openapi_contract.test.ts" ] } } }, "/v1/personal/business-links/{link_id}/shareholders": { "get": { "tags": [ "Personal" ], "operationId": "listPersonalBusinessLinkShareholders", "summary": "List personal business shareholder mappings", "description": "Returns shareholder mappings already attached to one personal business link owned by the authenticated user. Requires personal.business_links.read consent. API keys cannot call this route, and the response does not grant permission to mutate business books.", "security": [ { "BearerAuth": [] } ], "parameters": [ { "name": "link_id", "in": "path", "required": true, "description": "Personal business link id.", "schema": { "type": "string", "format": "uuid" } }, { "$ref": "#/components/parameters/RequestId" } ], "responses": { "200": { "description": "Shareholder mappings returned for the personal business link.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PersonalBusinessShareholderLinkListResponse" } } } }, "400": { "description": "Invalid link id.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1ErrorEnvelope" } } } }, "401": { "description": "Missing, invalid or expired bearer user token.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1ErrorEnvelope" } } } }, "403": { "description": "Missing read consent.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1ErrorEnvelope" } } } }, "404": { "description": "Personal business link not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1ErrorEnvelope" } } } }, "405": { "description": "Only GET and POST are allowed for this route.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1ErrorEnvelope" } } } }, "500": { "description": "Generic server failure. Internal database details must not be returned.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1ErrorEnvelope" } } } } }, "x-financial-iq-safety": { "requiresApiKey": false, "apiKeysAllowed": false, "requiresUserBearerToken": true, "scope": "personal.business_links.read", "directFinancialMutation": false, "businessMutation": false, "personalData": true, "writeLevel": "read", "requiresIdempotencyKey": false, "auditedEndpoint": "v1/personal/business-links/{link_id}/shareholders", "doesNot": [ "map_shareholder", "grant_business_write_permission", "change_business_books", "create_business_transaction", "post_ledger_entries", "move_money", "file_tax_returns" ] }, "x-implementation": { "edgeFunction": "supabase/functions/financial-data-api/index.ts", "handler": "handleV1PersonalBusinessLinkShareholders", "tests": [ "supabase/functions/financial-data-api/invoice_idempotency.test.ts", "supabase/functions/financial-data-api/v1_openapi_contract.test.ts" ] } }, "post": { "tags": [ "Personal" ], "operationId": "mapPersonalBusinessLinkShareholder", "summary": "Map personal business shareholder", "description": "Creates or updates a shareholder mapping for an active personal business link. Requires personal.business_links.write consent and an Idempotency-Key. The shareholder must belong to the linked company under database RLS rules.", "security": [ { "BearerAuth": [] } ], "parameters": [ { "name": "link_id", "in": "path", "required": true, "description": "Active personal business link id.", "schema": { "type": "string", "format": "uuid" } }, { "$ref": "#/components/parameters/RequestId" }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PersonalBusinessShareholderMapRequest" } } } }, "responses": { "200": { "description": "Shareholder mapping created or updated.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" }, "X-FIQ-Idempotency-Replayed": { "$ref": "#/components/headers/IdempotencyReplayed" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PersonalBusinessLinkResponse" } } } }, "400": { "description": "Invalid link id, shareholder id, weight override or idempotency key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1ErrorEnvelope" } } } }, "401": { "description": "Missing, invalid or expired bearer user token.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1ErrorEnvelope" } } } }, "403": { "description": "Missing write consent.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1ErrorEnvelope" } } } }, "404": { "description": "Personal business link not found or inactive.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1ErrorEnvelope" } } } }, "405": { "description": "Only GET and POST are allowed for this route.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1ErrorEnvelope" } } } }, "409": { "description": "Idempotency key is already processing or reused with a different body.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1ErrorEnvelope" } } } } }, "x-financial-iq-safety": { "requiresApiKey": false, "apiKeysAllowed": false, "requiresUserBearerToken": true, "scope": "personal.business_links.write", "directFinancialMutation": false, "businessMutation": false, "personalData": true, "writeLevel": "personal_link_setup", "requiresIdempotencyKey": true, "auditedEndpoint": "v1/personal/business-links/{link_id}/shareholders" }, "x-implementation": { "edgeFunction": "supabase/functions/financial-data-api/index.ts", "handler": "handleV1PersonalBusinessLinkShareholders", "tests": [ "supabase/functions/financial-data-api/invoice_idempotency.test.ts", "supabase/functions/financial-data-api/v1_openapi_contract.test.ts" ] } } }, "/v1/personal/business-links/{link_id}/shareholders/{shareholder_id}": { "get": { "tags": [ "Personal" ], "operationId": "getPersonalBusinessLinkShareholder", "summary": "Get personal business shareholder mapping", "description": "Returns one shareholder mapping already attached to a personal business link owned by the authenticated user. Requires personal.business_links.read consent. API keys cannot call this route, and the response does not grant permission to mutate business books.", "security": [ { "BearerAuth": [] } ], "parameters": [ { "name": "link_id", "in": "path", "required": true, "description": "Personal business link id.", "schema": { "type": "string", "format": "uuid" } }, { "name": "shareholder_id", "in": "path", "required": true, "description": "Business shareholder id already mapped to the personal link.", "schema": { "type": "string", "format": "uuid" } }, { "$ref": "#/components/parameters/RequestId" } ], "responses": { "200": { "description": "Shareholder mapping returned for the personal business link.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PersonalBusinessShareholderLinkResponse" } } } }, "400": { "description": "Invalid link id or shareholder id.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1ErrorEnvelope" } } } }, "401": { "description": "Missing, invalid or expired bearer user token.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1ErrorEnvelope" } } } }, "403": { "description": "Missing read consent.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1ErrorEnvelope" } } } }, "404": { "description": "Personal business link or shareholder mapping not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1ErrorEnvelope" } } } }, "405": { "description": "Only GET, PATCH and DELETE are allowed for this route.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1ErrorEnvelope" } } } }, "500": { "description": "Generic server failure. Internal database details must not be returned.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1ErrorEnvelope" } } } } }, "x-financial-iq-safety": { "requiresApiKey": false, "apiKeysAllowed": false, "requiresUserBearerToken": true, "scope": "personal.business_links.read", "directFinancialMutation": false, "businessMutation": false, "personalData": true, "writeLevel": "read", "requiresIdempotencyKey": false, "auditedEndpoint": "v1/personal/business-links/{link_id}/shareholders/{shareholder_id}", "doesNot": [ "map_shareholder", "unmap_shareholder", "delete_business_shareholder", "grant_business_write_permission", "change_business_books", "create_business_transaction", "post_ledger_entries", "move_money", "file_tax_returns" ] }, "x-implementation": { "edgeFunction": "supabase/functions/financial-data-api/index.ts", "handler": "handleV1PersonalBusinessLinkShareholderDetail", "tests": [ "supabase/functions/financial-data-api/invoice_idempotency.test.ts", "supabase/functions/financial-data-api/v1_openapi_contract.test.ts" ] } }, "delete": { "tags": [ "Personal" ], "operationId": "unmapPersonalBusinessLinkShareholder", "summary": "Unmap personal business shareholder", "description": "Deletes one shareholder mapping row from an active personal business link owned by the authenticated user. Requires personal.business_links.write consent and an Idempotency-Key. This does not delete the business shareholder, alter company registers, change books, post journals, move money or file tax returns.", "security": [ { "BearerAuth": [] } ], "parameters": [ { "name": "link_id", "in": "path", "required": true, "description": "Active personal business link id.", "schema": { "type": "string", "format": "uuid" } }, { "name": "shareholder_id", "in": "path", "required": true, "description": "Business shareholder id to unmap from the personal link.", "schema": { "type": "string", "format": "uuid" } }, { "$ref": "#/components/parameters/RequestId" }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "responses": { "200": { "description": "Shareholder mapping removed from the personal business link.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" }, "X-FIQ-Idempotency-Replayed": { "$ref": "#/components/headers/IdempotencyReplayed" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PersonalBusinessLinkResponse" } } } }, "400": { "description": "Invalid link id, shareholder id or idempotency key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1ErrorEnvelope" } } } }, "401": { "description": "Missing, invalid or expired bearer user token.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1ErrorEnvelope" } } } }, "403": { "description": "Missing write consent.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1ErrorEnvelope" } } } }, "404": { "description": "Personal business link or shareholder mapping not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1ErrorEnvelope" } } } }, "405": { "description": "Only GET, PATCH and DELETE are allowed for this route.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1ErrorEnvelope" } } } }, "409": { "description": "Idempotency key is already processing or reused with a different request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1ErrorEnvelope" } } } }, "500": { "description": "Generic server failure. Internal database details must not be returned.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1ErrorEnvelope" } } } } }, "x-financial-iq-safety": { "requiresApiKey": false, "apiKeysAllowed": false, "requiresUserBearerToken": true, "scope": "personal.business_links.write", "directFinancialMutation": false, "businessMutation": false, "personalData": true, "writeLevel": "personal_link_setup", "requiresIdempotencyKey": true, "deletesEndpointRow": true, "auditedEndpoint": "v1/personal/business-links/{link_id}/shareholders/{shareholder_id}", "doesNot": [ "delete_business_shareholder", "change_business_books", "create_business_transaction", "post_ledger_entries", "move_money", "file_tax_returns" ] }, "x-implementation": { "edgeFunction": "supabase/functions/financial-data-api/index.ts", "handler": "handleV1PersonalBusinessLinkShareholderDetail", "tests": [ "supabase/functions/financial-data-api/invoice_idempotency.test.ts", "supabase/functions/financial-data-api/v1_openapi_contract.test.ts" ] } }, "patch": { "tags": [ "Personal" ], "operationId": "updatePersonalBusinessLinkShareholder", "summary": "Update personal business shareholder mapping", "description": "Updates only the weight_override value on one shareholder mapping for an active personal business link owned by the authenticated user. Requires personal.business_links.write consent and an Idempotency-Key. Passing null clears the override. This does not delete the business shareholder, alter company registers, change books, post journals, move money or file tax returns.", "security": [ { "BearerAuth": [] } ], "parameters": [ { "name": "link_id", "in": "path", "required": true, "description": "Active personal business link id.", "schema": { "type": "string", "format": "uuid" } }, { "name": "shareholder_id", "in": "path", "required": true, "description": "Business shareholder id whose personal link mapping weight override should be updated.", "schema": { "type": "string", "format": "uuid" } }, { "$ref": "#/components/parameters/RequestId" }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PersonalBusinessShareholderUpdateRequest" } } } }, "responses": { "200": { "description": "Shareholder mapping weight override updated for the personal business link.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" }, "X-FIQ-Idempotency-Replayed": { "$ref": "#/components/headers/IdempotencyReplayed" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PersonalBusinessLinkResponse" } } } }, "400": { "description": "Invalid link id, shareholder id, weight override, unsupported field or idempotency key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1ErrorEnvelope" } } } }, "401": { "description": "Missing, invalid or expired bearer user token.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1ErrorEnvelope" } } } }, "403": { "description": "Missing write consent.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1ErrorEnvelope" } } } }, "404": { "description": "Personal business link or shareholder mapping not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1ErrorEnvelope" } } } }, "405": { "description": "Only GET, PATCH and DELETE are allowed for this route.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1ErrorEnvelope" } } } }, "409": { "description": "Idempotency key is already processing or reused with a different request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1ErrorEnvelope" } } } }, "500": { "description": "Generic server failure. Internal database details must not be returned.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1ErrorEnvelope" } } } } }, "x-financial-iq-safety": { "requiresApiKey": false, "apiKeysAllowed": false, "requiresUserBearerToken": true, "scope": "personal.business_links.write", "directFinancialMutation": false, "businessMutation": false, "personalData": true, "writeLevel": "personal_link_setup", "requiresIdempotencyKey": true, "deletesEndpointRow": false, "auditedEndpoint": "v1/personal/business-links/{link_id}/shareholders/{shareholder_id}", "doesNot": [ "delete_business_shareholder", "change_business_books", "create_business_transaction", "post_ledger_entries", "move_money", "file_tax_returns" ] }, "x-implementation": { "edgeFunction": "supabase/functions/financial-data-api/index.ts", "handler": "handleV1PersonalBusinessLinkShareholderDetail", "tests": [ "supabase/functions/financial-data-api/invoice_idempotency.test.ts", "supabase/functions/financial-data-api/v1_openapi_contract.test.ts" ] } } }, "/v1/business/companies/{company_id}/expense-claims": { "get": { "tags": [ "Business" ], "operationId": "listBusinessExpenseClaims", "summary": "List business expense claims", "description": "Lists expense claims for an accessible business company. This route is read-only and supports claim review workflows without creating or approving claims.", "security": [ { "ApiKeyAuth": [] } ], "parameters": [ { "name": "company_id", "in": "path", "required": true, "description": "Business company id.", "schema": { "type": "string", "format": "uuid" } }, { "$ref": "#/components/parameters/RequestId" }, { "name": "status", "in": "query", "required": false, "description": "Optional expense claim status filter.", "schema": { "type": "string" } }, { "name": "claimant_id", "in": "query", "required": false, "description": "Optional claimant id filter.", "schema": { "type": "string", "format": "uuid" } }, { "name": "approval_status", "in": "query", "required": false, "description": "Optional approval status filter.", "schema": { "type": "string" } }, { "name": "payment_status", "in": "query", "required": false, "description": "Optional payment status filter.", "schema": { "type": "string" } }, { "name": "fund_id", "in": "query", "required": false, "description": "Optional fund id filter.", "schema": { "type": "string", "format": "uuid" } }, { "name": "from_date", "in": "query", "required": false, "description": "Inclusive claim-date lower bound in YYYY-MM-DD format.", "schema": { "type": "string", "format": "date" } }, { "name": "to_date", "in": "query", "required": false, "description": "Inclusive claim-date upper bound in YYYY-MM-DD format.", "schema": { "type": "string", "format": "date" } }, { "name": "include_voided", "in": "query", "required": false, "description": "Set to true to include voided claims.", "schema": { "type": "boolean", "default": false } }, { "name": "limit", "in": "query", "required": false, "description": "Maximum number of expense claims to return. Values are clamped between 1 and 200.", "schema": { "type": "integer", "minimum": 1, "maximum": 200, "default": 100 } }, { "name": "offset", "in": "query", "required": false, "description": "Zero-based offset for paginating expense claim results.", "schema": { "type": "integer", "minimum": 0, "default": 0 } } ], "responses": { "200": { "description": "Accessible business expense claims returned.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1BusinessExpenseClaimListResponse" } } } }, "400": { "description": "The company_id, claimant_id, fund_id or date filter is invalid.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1ErrorEnvelope" } } } }, "401": { "description": "Missing, invalid, expired or inactive API key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LegacyErrorResponse" } } } }, "403": { "description": "The API key does not have invoice read permission, or the master key is not allowed to access the company.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1ErrorEnvelope" } } } }, "404": { "description": "Business company not found.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1ErrorEnvelope" } } } }, "405": { "description": "Only GET and POST are allowed for this route.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1ErrorEnvelope" } } } }, "500": { "description": "The API could not fetch expense claims.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1ErrorEnvelope" } } } } }, "x-financial-iq-safety": { "scope": "business.expense_claims.read", "writeLevel": "read", "requiresIdempotencyKey": false, "requiredApiKeyPermission": "invoices", "auditedEndpoint": "v1/business/companies/{company_id}/expense-claims" }, "x-implementation": { "handler": "handleV1BusinessExpenseClaims", "source": "supabase/functions/financial-data-api/v1.ts" } }, "post": { "tags": [ "Business" ], "operationId": "createBusinessExpenseClaim", "summary": "Create draft business expense claim", "description": "Creates a draft staff, director or volunteer expense claim for an accessible business company. The route requires invoice permission and an Idempotency-Key header. It validates claimant, supplier, account, fund, project and document references against the requested company, calculates totals from line items, and does not submit for approval, approve, repay, create a supplier bill, post to ledger, submit tax or make bank payments.", "security": [ { "ApiKeyAuth": [] } ], "parameters": [ { "name": "company_id", "in": "path", "required": true, "description": "Business company id.", "schema": { "type": "string", "format": "uuid" } }, { "$ref": "#/components/parameters/RequestId" }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BusinessExpenseClaimCreateRequest" }, "examples": { "staffClaim": { "summary": "Draft staff expense claim", "value": { "claimant_id": "7c23f940-4d21-4f3f-94e0-353c6f4c1a43", "claim_date": "2026-07-07", "due_date": "2026-08-06", "currency": "GBP", "repayment_method": "bill", "project_id": "d7d2ef9a-3fbb-4fbf-8c2b-402145f8729b", "line_items": [ { "description": "Client travel", "expense_date": "2026-07-07", "quantity": 2, "unit_price": 15, "vat_rate": 20, "receipt_reference": "REC-API-1" } ] } } } } } }, "responses": { "201": { "description": "Draft business expense claim created, or an identical idempotent request replayed.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" }, "X-FIQ-Idempotency-Replayed": { "$ref": "#/components/headers/IdempotencyReplayed" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1BusinessExpenseClaimCreateResponse" } } } }, "400": { "description": "Invalid JSON, missing or invalid idempotency key, invalid company_id, invalid company reference, inactive claimant, or invalid request body.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1ErrorEnvelope" } } } }, "401": { "description": "Missing, invalid, expired or inactive API key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LegacyErrorResponse" } } } }, "403": { "description": "The API key does not have invoice permission, or has no owner for creation.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1ErrorEnvelope" } } } }, "404": { "description": "Business company not found.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1ErrorEnvelope" } } } }, "405": { "description": "Only GET and POST are allowed for this route.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1ErrorEnvelope" } } } }, "409": { "description": "The same idempotency key was reused with a different request body.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1ErrorEnvelope" } } } }, "500": { "description": "Unexpected error while creating the draft expense claim.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1ErrorEnvelope" } } } } }, "x-financial-iq-safety": { "requiresApiKey": true, "apiKeysAllowed": true, "requiresUserBearerToken": false, "scope": "business.expense_claims.create", "requiredApiKeyPermission": "invoices", "businessMutation": true, "directFinancialMutation": false, "writeLevel": "draft", "requiresIdempotencyKey": true, "auditedEndpoint": "v1/business/companies/{company_id}/expense-claims", "forbiddenInThisRoute": [ "submit expense claim for approval", "approve expense claim", "repay claimant", "create supplier bill", "post to ledger", "file VAT", "file CT600", "file Companies House accounts", "make bank payment", "send document", "close accounting period" ] }, "x-implementation": { "edgeFunction": "supabase/functions/financial-data-api/index.ts", "handler": "createV1BusinessExpenseClaim", "tests": [ "supabase/functions/financial-data-api/invoice_idempotency.test.ts" ], "databaseMigration": "supabase/migrations/20260707214653_api_expense_claim_public_api_atomic.sql" } } }, "/v1/business/companies/{company_id}/expense-claims/{expense_claim_id}": { "get": { "tags": [ "Business" ], "operationId": "getBusinessExpenseClaim", "summary": "Get business expense claim", "description": "Returns one expense claim for an accessible business company. Inaccessible ids return not found rather than revealing another company's data.", "security": [ { "ApiKeyAuth": [] } ], "parameters": [ { "name": "company_id", "in": "path", "required": true, "description": "Business company id.", "schema": { "type": "string", "format": "uuid" } }, { "name": "expense_claim_id", "in": "path", "required": true, "description": "Expense claim id.", "schema": { "type": "string", "format": "uuid" } }, { "$ref": "#/components/parameters/RequestId" } ], "responses": { "200": { "description": "Accessible business expense claim returned.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1BusinessExpenseClaimResponse" } } } }, "400": { "description": "The company_id or expense_claim_id path parameter is invalid.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1ErrorEnvelope" } } } }, "401": { "description": "Missing, invalid, expired or inactive API key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LegacyErrorResponse" } } } }, "403": { "description": "The API key does not have invoice read permission, or the master key is not allowed to access the company.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1ErrorEnvelope" } } } }, "404": { "description": "Business expense claim not found.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1ErrorEnvelope" } } } }, "405": { "description": "Only GET is allowed for this route.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1ErrorEnvelope" } } } }, "500": { "description": "The API could not fetch the expense claim.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1ErrorEnvelope" } } } } }, "x-financial-iq-safety": { "scope": "business.expense_claims.read", "writeLevel": "read", "requiresIdempotencyKey": false, "requiredApiKeyPermission": "invoices", "auditedEndpoint": "v1/business/companies/{company_id}/expense-claims/{expense_claim_id}" }, "x-implementation": { "handler": "handleV1BusinessExpenseClaimDetail", "source": "supabase/functions/financial-data-api/v1.ts" } } }, "/v1/business/companies/{company_id}/expense-claims/{expense_claim_id}/submit": { "post": { "tags": [ "Business" ], "operationId": "submitBusinessExpenseClaimForApproval", "summary": "Submit business expense claim for approval", "description": "Creates a pending approval request for a draft expense claim in a business company. The route requires invoice and approval-workflow permissions plus an Idempotency-Key header. It does not approve, repay, create a supplier bill, post to ledger, file tax, create direct journals or make bank payments.", "security": [ { "ApiKeyAuth": [] } ], "parameters": [ { "$ref": "#/components/parameters/BusinessCompanyId" }, { "name": "expense_claim_id", "in": "path", "required": true, "description": "Draft business expense claim id to submit for approval.", "schema": { "type": "string", "format": "uuid" } }, { "$ref": "#/components/parameters/RequestId" }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ExpenseClaimApprovalRequest" }, "examples": { "readyForApproval": { "summary": "Expense claim approval request", "value": { "reason": "Expense claim is ready for approval" } } } } } }, "responses": { "202": { "description": "Approval request created, an existing pending approval returned, or an identical idempotent request replayed.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" }, "X-FIQ-Idempotency-Replayed": { "$ref": "#/components/headers/IdempotencyReplayed" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1ExpenseClaimApprovalRequestResponse" } } } }, "400": { "description": "Invalid JSON, invalid company_id or expense_claim_id path parameter, or missing/invalid idempotency key.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LegacyErrorResponse" } } } }, "401": { "description": "Missing, invalid, expired or inactive API key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LegacyErrorResponse" } } } }, "403": { "description": "The API key does not have invoice or approval-workflow permission.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LegacyErrorResponse" } } } }, "404": { "description": "Business expense claim not found.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LegacyErrorResponse" } } } }, "405": { "description": "Only POST is allowed for this route.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LegacyErrorResponse" } } } }, "409": { "description": "The expense claim is not draft, idempotency key was reused with a changed body, or no expense claim approval workflow is configured.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LegacyErrorResponse" } } } }, "500": { "description": "Generic server failure. Internal database or provider details must not be returned.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1ErrorEnvelope" } } } } }, "x-financial-iq-safety": { "requiresApiKey": true, "apiKeysAllowed": true, "requiresUserBearerToken": false, "scope": "business.expense_claims.approval", "requiredPermissions": [ "invoices", "approval_workflow" ], "businessMutation": true, "directFinancialMutation": false, "writeLevel": "human_approval", "requiresIdempotencyKey": true, "auditedEndpoint": "v1/business/companies/{company_id}/expense-claims/{expense_claim_id}/submit", "createsApprovalRequest": true, "directExecution": false, "forbiddenInThisRoute": [ "approve expense claim immediately", "repay claimant", "post to ledger", "create purchase invoice", "make bank payment", "file VAT", "file CT600", "file Companies House accounts", "close accounting period" ] }, "x-implementation": { "edgeFunction": "supabase/functions/financial-data-api/index.ts", "handler": "handleV1BusinessExpenseClaimSubmitApproval", "databaseFunction": "public.create_expense_claim_approval_api_v1_atomic", "activationGate": "FINANCIAL_API_V1_GUARDED_EXPENSE_CLAIM_SUBMIT_ENABLED", "atomicAuditAfterActivation": true, "masterKeyAllowlistSupported": true, "missingGuardedBridgeBehavior": "fail_closed_503", "tests": [ "supabase/functions/financial-data-api/invoice_idempotency.test.ts", "supabase/functions/financial-data-api/v1_openapi_contract.test.ts", "supabase/tests/api_business_expense_claim_submit_hardening.sql", "scripts/run-api-expense-claim-submit-concurrency.mjs" ] } } }, "/v1/business/companies/{company_id}/expense-claims/{expense_claim_id}/void": { "post": { "tags": [ "Business" ], "operationId": "voidBusinessExpenseClaim", "summary": "Void an unpaid business expense claim", "description": "Voids an unpaid, non-reimbursed expense claim in a business company through a guarded accounting reversal. The route requires invoice permission plus an Idempotency-Key header and a reason. It updates the claim, linked supplier bill and posted journal state where applicable and does not delete the claim, repay claimants, refund money, file tax, send documents or make bank payments.", "security": [ { "ApiKeyAuth": [] } ], "parameters": [ { "$ref": "#/components/parameters/BusinessCompanyId" }, { "name": "expense_claim_id", "in": "path", "required": true, "description": "Unpaid business expense claim id to void.", "schema": { "type": "string", "format": "uuid" } }, { "$ref": "#/components/parameters/RequestId" }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BusinessExpenseClaimVoidRequest" }, "examples": { "raisedInError": { "summary": "Expense claim void reason", "value": { "reason": "Expense claim raised in error" } } } } } }, "responses": { "200": { "description": "Expense claim voided, an existing void returned, or an identical idempotent request replayed.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" }, "X-FIQ-Idempotency-Replayed": { "$ref": "#/components/headers/IdempotencyReplayed" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1BusinessExpenseClaimVoidResponse" } } } }, "400": { "description": "The request body, Idempotency-Key or path parameter is invalid.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "The API key lacks invoice permission or owner context.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "The company or expense claim was not found for this API key.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "405": { "description": "Only POST is allowed for this route.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "409": { "description": "The expense claim cannot be voided from its current state, has payment activity, or failed a guarded reversal check.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Generic server failure. Internal database details must not be returned.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "x-financial-iq-safety": { "writeLevel": "accounting_reversal", "requiresIdempotencyKey": true, "requiredApiKeyPermission": "invoices", "scope": "business.expense_claims.void", "auditedEndpoint": "v1/business/companies/{company_id}/expense-claims/{expense_claim_id}/void", "directExecution": true, "moneyMovementPerformed": false, "paymentRefundPerformed": false, "taxFilingPerformed": false, "forbiddenInThisRoute": [ "repay claimant", "refund money", "make bank payment", "file VAT", "file CT600", "file Companies House accounts", "close accounting period", "delete expense claim" ] }, "x-implementation": { "edgeFunction": "supabase/functions/financial-data-api/index.ts", "handler": "handleV1BusinessExpenseClaimVoid", "databaseFunction": "public.void_expense_claim_api_v1_atomic", "activationGate": "FINANCIAL_API_V1_GUARDED_EXPENSE_CLAIM_VOID_ENABLED", "atomicAuditAfterActivation": true, "masterKeyAllowlistSupported": true, "missingGuardedBridgeBehavior": "fail_closed_503", "tests": [ "supabase/functions/financial-data-api/invoice_idempotency.test.ts", "supabase/functions/financial-data-api/v1_openapi_contract.test.ts", "supabase/tests/api_business_expense_claim_void_hardening.sql", "scripts/run-api-expense-claim-void-concurrency.mjs" ] } } }, "/v1/business/companies/{company_id}/cost-centers/{cost_center_level_id}/options": { "get": { "tags": [ "Business" ], "operationId": "listBusinessCostCenterOptions", "summary": "List business cost centre options", "description": "Returns setup-only cost-centre options under one accessible company-owned cost-centre level. This route is read-only and does not create budgets, account-specific requirements, transactions or ledger entries.", "security": [ { "ApiKeyAuth": [] } ], "parameters": [ { "$ref": "#/components/parameters/BusinessCompanyId" }, { "name": "cost_center_level_id", "in": "path", "required": true, "description": "Business cost-centre level id whose options should be listed.", "schema": { "type": "string", "format": "uuid" } }, { "$ref": "#/components/parameters/RequestId" }, { "name": "search", "in": "query", "required": false, "description": "Optional case-insensitive option name search. q is accepted as an alias.", "schema": { "type": "string" } }, { "name": "code", "in": "query", "required": false, "description": "Optional exact option code filter.", "schema": { "type": "string" } }, { "name": "is_active", "in": "query", "required": false, "description": "Optional active-state filter. active is accepted as an alias.", "schema": { "type": "boolean" } }, { "$ref": "#/components/parameters/Limit" }, { "$ref": "#/components/parameters/Offset" } ], "responses": { "200": { "description": "Business cost-centre options returned.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BusinessCostCenterOptionListResponse" } } } }, "400": { "description": "Invalid company_id or cost_center_level_id path parameter.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1ErrorEnvelope" } } } }, "401": { "description": "Missing, invalid, expired or inactive API key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LegacyErrorResponse" } } } }, "403": { "description": "The API key does not grant cost-centre read permission.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1ErrorEnvelope" } } } }, "404": { "description": "Business cost centre not found.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1ErrorEnvelope" } } } }, "405": { "description": "Only GET and POST are allowed for this route.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1ErrorEnvelope" } } } }, "500": { "description": "Generic server failure. Internal database details must not be returned.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1ErrorEnvelope" } } } } }, "x-financial-iq-safety": { "requiresApiKey": true, "scope": "business.cost_centers.options.read", "requiredAnyPermission": [ "cost_centers", "transactions" ], "directFinancialMutation": false, "businessMutation": false, "writeLevel": "read", "requiresIdempotencyKey": false, "auditedEndpoint": "v1/business/companies/{company_id}/cost-centers/{cost_center_level_id}/options", "doesNot": [ "move_option_between_levels", "create_cost_center_budgets", "create_account_specific_requirements", "create_transactions", "post_ledger_entries", "change_bank_transaction_matching_state", "close_accounting_periods", "submit_tax_returns", "move_money" ] }, "x-implementation": { "edgeFunction": "supabase/functions/financial-data-api/index.ts", "handler": "handleV1BusinessCostCenterOptions", "tests": [ "supabase/functions/financial-data-api/invoice_idempotency.test.ts" ] } }, "post": { "tags": [ "Business" ], "operationId": "createBusinessCostCenterOption", "summary": "Create business cost centre option", "description": "Creates one setup-only option under an accessible business cost centre level. This route creates the option only; it does not create budgets, account-specific requirements, transactions or ledger entries.", "security": [ { "ApiKeyAuth": [] } ], "parameters": [ { "$ref": "#/components/parameters/BusinessCompanyId" }, { "name": "cost_center_level_id", "in": "path", "required": true, "description": "Business cost centre level id.", "schema": { "type": "string", "format": "uuid" } }, { "$ref": "#/components/parameters/RequestId" }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BusinessCostCenterOptionCreateRequest" } } } }, "responses": { "201": { "description": "Business cost centre option created.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BusinessCostCenterOptionCreateResponse" } } } }, "400": { "description": "The request body, idempotency key or path parameter is invalid.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1ErrorEnvelope" } } } }, "401": { "description": "Missing or invalid API key.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1ErrorEnvelope" } } } }, "403": { "description": "The API key does not have cost centre write permission.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1ErrorEnvelope" } } } }, "404": { "description": "The company or cost centre level is not accessible to this API key.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1ErrorEnvelope" } } } }, "405": { "description": "Only POST is allowed for this route.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1ErrorEnvelope" } } } }, "409": { "description": "The option name already exists for this cost centre level, or the idempotency key conflicts with another request.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1ErrorEnvelope" } } } }, "500": { "description": "Generic server failure. Internal database details must not be returned.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1ErrorEnvelope" } } } } }, "x-financial-iq-safety": { "requiresApiKey": true, "apiKeysAllowed": true, "requiresUserBearerToken": false, "scope": "business.cost_centers.options.create", "requiredPermission": "cost_centers", "businessMutation": true, "directFinancialMutation": false, "writeLevel": "configuration", "requiresIdempotencyKey": true, "auditedEndpoint": "v1/business/companies/{company_id}/cost-centers/{cost_center_level_id}/options", "forbiddenInThisRoute": [ "create cost centre level", "create cost centre budget", "create account-specific requirement", "create bank transaction", "change bank transaction matching state", "post to ledger", "create journal entry", "close accounting period" ] }, "x-implementation": { "edgeFunction": "supabase/functions/financial-data-api/index.ts", "handler": "handleV1BusinessCostCenterOptions", "tests": [ "supabase/functions/financial-data-api/invoice_idempotency.test.ts" ] } } }, "/v1/business/companies/{company_id}/cost-centers/{cost_center_level_id}/options/{cost_center_option_id}": { "get": { "tags": [ "Business" ], "operationId": "getBusinessCostCenterOption", "summary": "Get business cost centre option", "description": "Returns one cost-centre option under an accessible company-owned cost-centre level. This route is read-only and does not create budgets, transactions or ledger entries.", "security": [ { "ApiKeyAuth": [] } ], "parameters": [ { "$ref": "#/components/parameters/BusinessCompanyId" }, { "name": "cost_center_level_id", "in": "path", "required": true, "description": "Cost-centre level id containing the option.", "schema": { "type": "string", "format": "uuid" } }, { "name": "cost_center_option_id", "in": "path", "required": true, "description": "Cost-centre option id to return.", "schema": { "type": "string", "format": "uuid" } }, { "$ref": "#/components/parameters/RequestId" } ], "responses": { "200": { "description": "Business cost-centre option returned.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BusinessCostCenterOptionResponse" } } } }, "400": { "description": "Invalid company_id, cost_center_level_id or cost_center_option_id path parameter.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1ErrorEnvelope" } } } }, "401": { "description": "Missing, invalid, expired or inactive API key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LegacyErrorResponse" } } } }, "403": { "description": "The API key does not grant cost-centre read permission.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1ErrorEnvelope" } } } }, "404": { "description": "Business cost centre option not found.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1ErrorEnvelope" } } } }, "405": { "description": "Only GET and PATCH are allowed for this route.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1ErrorEnvelope" } } } }, "500": { "description": "Generic server failure. Internal database details must not be returned.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1ErrorEnvelope" } } } } }, "x-financial-iq-safety": { "requiresApiKey": true, "scope": "business.cost_centers.options.read", "requiredAnyPermission": [ "cost_centers", "transactions" ], "directFinancialMutation": false, "businessMutation": false, "writeLevel": "read", "requiresIdempotencyKey": false, "auditedEndpoint": "v1/business/companies/{company_id}/cost-centers/{cost_center_level_id}/options/{cost_center_option_id}", "doesNot": [ "move_option_between_levels", "create_cost_center_budgets", "create_account_specific_requirements", "create_transactions", "post_ledger_entries", "change_bank_transaction_matching_state", "close_accounting_periods", "submit_tax_returns", "move_money" ] }, "x-implementation": { "edgeFunction": "supabase/functions/financial-data-api/index.ts", "handler": "handleV1BusinessCostCenterOptionDetail", "tests": [ "supabase/functions/financial-data-api/invoice_idempotency.test.ts" ] } }, "patch": { "tags": [ "Business" ], "operationId": "updateBusinessCostCenterOption", "summary": "Update business cost centre option", "description": "Updates safe setup fields for one business cost-centre option under an accessible company-owned cost-centre level. This route requires cost_centers permission and an Idempotency-Key. It does not move the option to another level, create budgets, create account-specific requirements, create transactions, post ledger entries, close accounting periods, submit tax returns or move money.", "security": [ { "ApiKeyAuth": [] } ], "parameters": [ { "$ref": "#/components/parameters/BusinessCompanyId" }, { "name": "cost_center_level_id", "in": "path", "required": true, "description": "Cost-centre level id containing the option.", "schema": { "type": "string", "format": "uuid" } }, { "name": "cost_center_option_id", "in": "path", "required": true, "description": "Cost-centre option id to update.", "schema": { "type": "string", "format": "uuid" } }, { "$ref": "#/components/parameters/RequestId" }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BusinessCostCenterOptionUpdateRequest" } } } }, "responses": { "200": { "description": "Business cost-centre option updated.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" }, "X-FIQ-Idempotency-Replayed": { "$ref": "#/components/headers/IdempotencyReplayed" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BusinessCostCenterOptionUpdateResponse" } } } }, "400": { "description": "Invalid request body, missing Idempotency-Key, or invalid company_id/cost_center_level_id/cost_center_option_id path parameter.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1ErrorEnvelope" } } } }, "401": { "description": "Missing, invalid, expired or inactive API key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LegacyErrorResponse" } } } }, "403": { "description": "The API key does not grant cost-centre write permission.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1ErrorEnvelope" } } } }, "404": { "description": "Business cost centre option not found.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1ErrorEnvelope" } } } }, "405": { "description": "Only GET and PATCH are allowed for this route.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1ErrorEnvelope" } } } }, "409": { "description": "The idempotency key conflicts with a different request body, or the cost-centre option name already exists under this level.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1ErrorEnvelope" } } } }, "500": { "description": "Generic server failure. Internal database details must not be returned.", "headers": { "X-FIQ-API-Version": { "$ref": "#/components/headers/V1ApiVersion" }, "X-FIQ-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1ErrorEnvelope" } } } } }, "x-financial-iq-safety": { "requiresApiKey": true, "scope": "business.cost_centers.options.update", "requiredPermission": "cost_centers", "directFinancialMutation": false, "businessMutation": true, "writeLevel": "configuration", "requiresIdempotencyKey": true, "auditedEndpoint": "v1/business/companies/{company_id}/cost-centers/{cost_center_level_id}/options/{cost_center_option_id}", "forbiddenFields": [ "id", "company_id", "cost_center_level_id", "created_at", "updated_at", "budget", "budget_period_id", "actual_amount", "account_requirements", "account_specific_requirements", "transactions", "journal_entries", "ledger_entries" ], "doesNot": [ "move_option_between_levels", "create_cost_center_budgets", "create_account_specific_requirements", "create_transactions", "post_ledger_entries", "change_bank_transaction_matching_state", "close_accounting_periods", "submit_tax_returns", "move_money" ] }, "x-implementation": { "edgeFunction": "supabase/functions/financial-data-api/index.ts", "handler": "handleV1BusinessCostCenterOptionDetail", "tests": [ "supabase/functions/financial-data-api/invoice_idempotency.test.ts" ] } } } }, "components": { "securitySchemes": { "ApiKeyAuth": { "type": "apiKey", "in": "header", "name": "x-api-key" }, "BearerAuth": { "type": "http", "scheme": "bearer", "bearerFormat": "Supabase user JWT", "description": "User-authorised bearer token carrying Financial IQ personal API consent scopes in auth-controlled metadata." }, "UserSessionBearerAuth": { "type": "http", "scheme": "bearer", "bearerFormat": "Supabase user session JWT", "description": "Signed-in Financial IQ user bearer token used for approving personal API consent requests and managing issued token records." } }, "parameters": { "IdempotencyKey": { "name": "Idempotency-Key", "in": "header", "required": true, "description": "Unique retry key for this write. Keys are scoped by the relevant route ledger, usually company, API key, method and endpoint. Reusing the same key with the same body replays the first response; reusing it with a changed body returns 409.", "schema": { "type": "string", "minLength": 1, "maxLength": 255, "pattern": "^[^\\u0000-\\u001F\\u007F]+$" } }, "RequestId": { "name": "X-Request-Id", "in": "header", "required": false, "description": "Optional caller request id for support and audit correlation. If omitted or unsafe, Financial IQ generates X-FIQ-Request-Id.", "schema": { "type": "string", "minLength": 1, "maxLength": 128, "pattern": "^[^\\u0000-\\u001F\\u007F]+$" } } }, "headers": { "V1ApiVersion": { "description": "Version marker for v1 responses.", "schema": { "type": "string", "const": "v1-2026-07" } }, "RequestId": { "description": "Financial IQ request id for support and audit correlation.", "schema": { "type": "string", "minLength": 1, "maxLength": 128 } }, "IdempotencyReplayed": { "description": "Present with value true when the response is replayed from the idempotency ledger.", "schema": { "type": "string", "enum": [ "true" ] } } }, "responses": { "V1BadRequest": { "description": "Invalid request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1ErrorResponse" } } } }, "V1Unauthorised": { "description": "Missing or invalid API key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1ErrorResponse" } } } }, "V1Forbidden": { "description": "The API key is not authorised for this company or permission.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1ErrorResponse" } } } }, "V1NotFound": { "description": "The requested business document was not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1ErrorResponse" } } } }, "V1Conflict": { "description": "The request conflicts with the current document state or idempotency ledger.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1ErrorResponse" } } } }, "V1Unavailable": { "description": "The audited archive bridge is temporarily unavailable.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1ErrorResponse" } } } } }, "schemas": { "PersonalConsentRequestResponse": { "type": "object", "required": [ "data", "meta" ], "properties": { "data": { "type": "object", "required": [ "object", "api_version", "id", "status", "effective_status", "created_at", "expires_at", "requested_client", "requested_scopes", "consent_screen", "oauth", "safety_boundaries" ], "properties": { "object": { "type": "string", "const": "personal_consent_request" }, "api_version": { "type": "string", "const": "v1-2026-07" }, "id": { "type": "string", "format": "uuid" }, "status": { "type": "string", "enum": [ "pending_user_authorisation", "authorised", "denied", "cancelled", "expired" ] }, "effective_status": { "type": "string" }, "replayed": { "type": "boolean" }, "created_at": { "type": "string", "format": "date-time" }, "expires_at": { "type": "string", "format": "date-time" }, "requested_client": { "type": "object", "additionalProperties": true }, "requested_scopes": { "type": "array", "items": { "type": "string" } }, "consent_screen": { "type": "object", "additionalProperties": true }, "oauth": { "type": "object", "required": [ "consent_request_created", "consent_request_id", "consent_url", "approval_flow", "user_authorisation_required", "token_issuing", "refresh_tokens" ], "properties": { "consent_request_created": { "type": "boolean", "const": true }, "consent_request_id": { "type": "string", "format": "uuid" }, "consent_url": { "type": "null" }, "approval_flow": { "type": "string", "const": "user_authorisation_required" }, "user_authorisation_required": { "type": "boolean", "const": true }, "token_issuing": { "type": "string", "const": "available_after_user_approval" }, "refresh_tokens": { "type": "string", "const": "available_after_user_approval" } } }, "safety_boundaries": { "type": "array", "items": { "type": "string" } } } }, "meta": { "$ref": "#/components/schemas/V1Meta" } } }, "BusinessCompany": { "type": "object", "additionalProperties": false, "required": [ "id", "name", "object" ], "properties": { "object": { "type": "string", "const": "business_company" }, "id": { "type": "string", "format": "uuid" }, "name": { "type": "string" }, "company_number": { "type": [ "string", "null" ] }, "company_type": { "type": [ "string", "null" ] }, "business_type": { "type": [ "string", "null" ] }, "company_email": { "type": [ "string", "null" ] }, "vat_registered": { "type": [ "boolean", "null" ] }, "chart_of_accounts_count": { "type": "integer", "minimum": 0 }, "firm_id": { "type": [ "string", "null" ], "format": "uuid" }, "allowlist_update_required": { "type": "boolean" }, "created_at": { "type": [ "string", "null" ], "format": "date-time" }, "updated_at": { "type": [ "string", "null" ], "format": "date-time" } } }, "V1BusinessCompanyCreateRequest": { "type": "object", "additionalProperties": false, "required": [ "name" ], "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 200 }, "company_number": { "type": ["string", "null"], "maxLength": 100 }, "business_type": { "type": "string", "enum": ["limited_company", "sole_trader", "partnership", "llp", "charity"] }, "business_description": { "type": ["string", "null"], "maxLength": 2000 }, "registered_office_address": { "type": ["string", "null"], "maxLength": 1000 }, "company_email": { "type": ["string", "null"], "maxLength": 320 }, "company_phone": { "type": ["string", "null"], "maxLength": 100 }, "company_website": { "type": ["string", "null"], "maxLength": 2048 }, "vat_registered": { "type": "boolean" }, "vat_number": { "type": ["string", "null"], "maxLength": 100 }, "firm_id": { "type": ["string", "null"], "format": "uuid" } } }, "V1BusinessCompanyCreateResponse": { "type": "object", "required": ["data", "meta"], "properties": { "data": { "$ref": "#/components/schemas/BusinessCompany" }, "meta": { "$ref": "#/components/schemas/V1BusinessCompanyCreateMeta" } } }, "V1BusinessCompanyCreateMeta": { "type": "object", "required": ["api_version", "mode", "request_id", "resource"], "properties": { "api_version": { "type": "string", "const": "v1-2026-07" }, "mode": { "type": "string", "const": "created" }, "request_id": { "type": "string", "minLength": 1, "maxLength": 128 }, "resource": { "type": "string", "const": "business_company" }, "chart_of_accounts_count": { "type": "integer", "minimum": 0 }, "firm_id": { "type": ["string", "null"], "format": "uuid" }, "allowlist_update_required": { "type": "boolean" } } }, "V1BusinessCompanyListResponse": { "type": "object", "required": [ "data", "meta" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/BusinessCompany" } }, "meta": { "$ref": "#/components/schemas/V1BusinessCompanyListMeta" } } }, "V1BusinessCompanyResponse": { "type": "object", "required": [ "data", "meta" ], "properties": { "data": { "$ref": "#/components/schemas/BusinessCompany" }, "meta": { "$ref": "#/components/schemas/V1BusinessCompanyMeta" } } }, "V1BusinessCompanyListMeta": { "type": "object", "required": [ "api_version", "mode", "pagination", "request_id", "resource" ], "properties": { "api_version": { "type": "string", "const": "v1-2026-07" }, "mode": { "type": "string", "const": "list" }, "pagination": { "$ref": "#/components/schemas/V1PaginationMeta" }, "request_id": { "type": "string", "minLength": 1, "maxLength": 128 }, "resource": { "type": "string", "const": "business_company" } } }, "V1BusinessCompanyMeta": { "type": "object", "required": [ "api_version", "mode", "request_id", "resource" ], "properties": { "api_version": { "type": "string", "const": "v1-2026-07" }, "mode": { "type": "string", "const": "detail" }, "request_id": { "type": "string", "minLength": 1, "maxLength": 128 }, "resource": { "type": "string", "const": "business_company" }, "chart_of_accounts_count": { "type": "integer", "minimum": 0 }, "firm_id": { "type": ["string", "null"], "format": "uuid" }, "allowlist_update_required": { "type": "boolean" } } }, "BusinessCustomer": { "type": "object", "additionalProperties": false, "required": [ "id", "company_id", "name", "object" ], "properties": { "object": { "type": "string", "const": "business_customer" }, "id": { "type": "string", "format": "uuid" }, "company_id": { "type": "string", "format": "uuid" }, "name": { "type": "string" }, "customer_reference": { "type": [ "string", "null" ] }, "contact_email": { "type": [ "string", "null" ], "format": "email" }, "contact_phone": { "type": [ "string", "null" ] }, "billing_address": { "type": [ "string", "null" ] }, "vat_number": { "type": [ "string", "null" ] }, "default_vat_rate": { "type": [ "number", "null" ] }, "default_payment_terms_days": { "type": [ "integer", "null" ] }, "is_active": { "type": "boolean" }, "related_party": { "type": "boolean" }, "fao": { "type": [ "string", "null" ] }, "created_at": { "type": [ "string", "null" ], "format": "date-time" }, "updated_at": { "type": [ "string", "null" ], "format": "date-time" } } }, "V1BusinessCustomerListResponse": { "type": "object", "required": [ "data", "meta" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/BusinessCustomer" } }, "meta": { "$ref": "#/components/schemas/V1BusinessCustomerListMeta" } } }, "V1BusinessCustomerResponse": { "type": "object", "required": [ "data", "meta" ], "properties": { "data": { "$ref": "#/components/schemas/BusinessCustomer" }, "meta": { "$ref": "#/components/schemas/V1BusinessCustomerMeta" } } }, "V1BusinessCustomerListMeta": { "type": "object", "required": [ "api_version", "mode", "pagination", "request_id", "resource" ], "properties": { "api_version": { "type": "string", "const": "v1-2026-07" }, "mode": { "type": "string", "const": "list" }, "pagination": { "$ref": "#/components/schemas/V1PaginationMeta" }, "request_id": { "type": "string", "minLength": 1, "maxLength": 128 }, "resource": { "type": "string", "const": "business_customer" } } }, "V1BusinessCustomerMeta": { "type": "object", "required": [ "api_version", "mode", "request_id", "resource" ], "properties": { "api_version": { "type": "string", "const": "v1-2026-07" }, "mode": { "type": "string", "const": "detail" }, "request_id": { "type": "string", "minLength": 1, "maxLength": 128 }, "resource": { "type": "string", "const": "business_customer" } } }, "V1PaginationMeta": { "type": "object", "additionalProperties": false, "required": [ "has_more", "limit", "offset", "total" ], "properties": { "has_more": { "type": "boolean" }, "limit": { "type": "integer", "minimum": 1, "maximum": 200 }, "offset": { "type": "integer", "minimum": 0 }, "total": { "type": "integer", "minimum": 0 } } }, "DraftInvoiceCreateRequest": { "type": "object", "additionalProperties": true, "required": [ "customer_id", "line_items" ], "properties": { "customer_id": { "type": "string", "format": "uuid" }, "status": { "type": "string", "enum": [ "draft" ], "description": "If omitted, the API forces draft status." }, "invoice_date": { "type": "string", "format": "date" }, "due_date": { "type": [ "string", "null" ], "format": "date" }, "payment_terms_days": { "type": "integer", "minimum": 0, "default": 30 }, "currency": { "type": "string", "pattern": "^[A-Z]{3}$", "default": "GBP" }, "fund_id": { "type": [ "string", "null" ], "format": "uuid" }, "line_items": { "type": "array", "minItems": 1, "items": { "$ref": "#/components/schemas/DraftInvoiceLineItemRequest" } }, "is_recurring": { "type": "boolean", "default": false }, "recurring_frequency": { "type": "string", "enum": [ "monthly", "quarterly", "yearly" ], "description": "Required when is_recurring is true. Recurring invoices must also provide exactly one of recurring_end_date or max_occurrences." }, "recurring_interval": { "type": "integer", "minimum": 1, "default": 1 }, "recurring_start_date": { "type": "string", "format": "date" }, "recurring_end_date": { "type": [ "string", "null" ], "format": "date" }, "max_occurrences": { "type": [ "integer", "null" ], "minimum": 1 } } }, "DraftInvoiceLineItemRequest": { "type": "object", "additionalProperties": true, "required": [ "description", "unit_price" ], "properties": { "line_number": { "type": "integer", "minimum": 1 }, "description": { "type": "string" }, "subdescription": { "type": [ "string", "null" ] }, "quantity": { "type": [ "number", "string" ], "minimum": 0.000001, "default": 1 }, "unit_price": { "type": [ "number", "string" ], "minimum": 0, "default": 0 }, "vat_rate": { "type": [ "number", "string" ], "minimum": 0, "maximum": 100, "default": 0 }, "vat_rate_id": { "type": [ "string", "null" ], "format": "uuid" }, "revenue_account_id": { "type": [ "string", "null" ], "format": "uuid" }, "project_id": { "type": [ "string", "null" ], "format": "uuid" }, "cost_center_id": { "type": [ "string", "null" ], "format": "uuid" } } }, "BusinessInvoiceUpdateRequest": { "type": "object", "additionalProperties": false, "minProperties": 2, "required": [ "expected_lock_version" ], "properties": { "expected_lock_version": { "type": "integer", "minimum": 0, "description": "The lock_version returned by the latest invoice read." }, "customer_id": { "type": "string", "format": "uuid" }, "invoice_date": { "type": "string", "format": "date" }, "due_date": { "type": "string", "format": "date" }, "delivery_date": { "type": [ "string", "null" ], "format": "date" }, "service_start_date": { "type": [ "string", "null" ], "format": "date" }, "service_end_date": { "type": [ "string", "null" ], "format": "date" }, "recognition_method": { "type": [ "string", "null" ], "enum": [ "invoice_date", "delivery_date", "spread_evenly", "deferred_income", null ] }, "is_deposit": { "type": "boolean" }, "payment_terms_days": { "type": "integer", "minimum": 0 }, "currency": { "type": "string", "pattern": "^[A-Z]{3}$" }, "fund_id": { "type": [ "string", "null" ], "format": "uuid" }, "line_items": { "type": "array", "minItems": 1, "items": { "$ref": "#/components/schemas/BusinessInvoiceUpdateLineItemRequest" }, "description": "When supplied, replaces the active draft lines atomically. Omit it for a true header-only correction that leaves line IDs and line history unchanged." }, "is_recurring": { "type": "boolean" }, "recurring_frequency": { "type": [ "string", "null" ], "enum": [ "monthly", "quarterly", "yearly", null ], "description": "Required when is_recurring is true. Recurring invoices must also provide exactly one of recurring_end_date or max_occurrences." }, "recurring_interval": { "type": "integer", "minimum": 1 }, "recurring_start_date": { "type": [ "string", "null" ], "format": "date" }, "recurring_end_date": { "type": [ "string", "null" ], "format": "date" }, "max_occurrences": { "type": [ "integer", "null" ], "minimum": 1 } } }, "BusinessInvoiceUpdateLineItemRequest": { "type": "object", "additionalProperties": false, "required": [ "description", "unit_price" ], "properties": { "id": { "type": [ "string", "null" ], "format": "uuid", "description": "Accepted for safe response round-tripping; active lines are replaced atomically." }, "line_number": { "type": "integer", "minimum": 1 }, "line_type": { "type": "string", "enum": [ "sales" ], "default": "sales", "description": "Public API line replacement currently accepts sales lines only. Existing expense-deduction lines remain unchanged when line_items is omitted for a header-only correction." }, "description": { "type": "string", "minLength": 1 }, "subdescription": { "type": [ "string", "null" ] }, "quantity": { "type": [ "number", "string" ], "minimum": 0.000001, "default": 1 }, "unit_price": { "type": [ "number", "string" ], "minimum": 0 }, "vat_rate": { "type": [ "number", "string" ], "minimum": 0, "maximum": 100, "default": 0 }, "vat_rate_id": { "type": [ "string", "null" ], "format": "uuid" }, "revenue_account_id": { "type": [ "string", "null" ], "format": "uuid" }, "inventory_item_id": { "type": [ "string", "null" ], "format": "uuid" }, "project_id": { "type": [ "string", "null" ], "format": "uuid" }, "cost_center_id": { "type": [ "string", "null" ], "format": "uuid" }, "template_id": { "type": [ "string", "null" ], "format": "uuid" }, "fund_id": { "type": [ "string", "null" ], "format": "uuid" }, "charity_activity_id": { "type": [ "string", "null" ], "format": "uuid" } } }, "V1BusinessInvoiceUpdateMeta": { "type": "object", "additionalProperties": false, "required": [ "api_version", "mode", "request_id", "resource", "scope" ], "properties": { "api_version": { "type": "string", "const": "v1-2026-07" }, "mode": { "type": "string", "const": "updated" }, "request_id": { "type": "string", "minLength": 1, "maxLength": 128 }, "resource": { "type": "string", "const": "invoice" }, "scope": { "type": "string", "const": "business.invoices.update" } } }, "V1BusinessInvoiceUpdateResponse": { "type": "object", "additionalProperties": false, "required": [ "data", "meta" ], "properties": { "data": { "$ref": "#/components/schemas/Invoice" }, "meta": { "$ref": "#/components/schemas/V1BusinessInvoiceUpdateMeta" } } }, "V1InvoiceResponse": { "type": "object", "required": [ "data", "meta" ], "properties": { "data": { "$ref": "#/components/schemas/Invoice" }, "meta": { "$ref": "#/components/schemas/V1InvoiceMeta" } } }, "PersonalOwnerDividendSummary": { "type": "object", "additionalProperties": false, "required": [ "approved_total", "posted_total", "records", "status", "total" ], "properties": { "approved_total": { "type": "number" }, "posted_total": { "type": "number" }, "total": { "type": "number" }, "status": { "type": "string", "enum": [ "available", "not_mapped", "unavailable" ] }, "records": { "type": "array", "items": { "type": "object", "additionalProperties": false, "required": [ "amount", "declared_at", "declaration_id", "declaration_reference", "payment_date", "status" ], "properties": { "amount": { "type": "number" }, "declared_at": { "type": [ "string", "null" ], "format": "date" }, "declaration_id": { "type": "string", "format": "uuid" }, "declaration_reference": { "type": [ "string", "null" ] }, "payment_date": { "type": [ "string", "null" ], "format": "date" }, "status": { "type": "string", "enum": [ "approved", "posted" ] } } } } } }, "PersonalOwnerPositionLinkedCompany": { "type": "object", "additionalProperties": false, "required": [ "business_position", "company_id", "link_id", "owner_dividends", "status" ], "properties": { "link_id": { "type": "string", "format": "uuid" }, "company_id": { "type": "string", "format": "uuid" }, "status": { "type": "string", "enum": [ "available", "access_unavailable", "summary_unavailable" ] }, "business_position": { "anyOf": [ { "$ref": "#/components/schemas/BusinessReportSummary" }, { "type": "null" } ] }, "owner_dividends": { "anyOf": [ { "$ref": "#/components/schemas/PersonalOwnerDividendSummary" }, { "type": "null" } ] } } }, "PersonalOwnerPosition": { "type": "object", "additionalProperties": false, "required": [ "generated_at", "linked_companies", "object", "personal", "user_id" ], "properties": { "object": { "type": "string", "const": "personal_owner_position" }, "user_id": { "type": "string", "format": "uuid" }, "personal": { "$ref": "#/components/schemas/PersonalFinancialSummary" }, "linked_companies": { "type": "array", "items": { "$ref": "#/components/schemas/PersonalOwnerPositionLinkedCompany" } }, "generated_at": { "type": "string", "format": "date-time" } } }, "PersonalOwnerPositionMeta": { "type": "object", "additionalProperties": false, "required": [ "api_version", "has_more_linked_companies", "linked_company_limit", "mode", "request_id", "resource", "scopes" ], "properties": { "api_version": { "type": "string" }, "mode": { "type": "string", "const": "position" }, "request_id": { "type": "string" }, "resource": { "type": "string", "const": "personal_owner_position" }, "scopes": { "type": "array", "items": { "type": "string" } }, "has_more_linked_companies": { "type": "boolean" }, "linked_company_limit": { "type": "integer", "minimum": 1, "maximum": 25 } } }, "PersonalOwnerPositionResponse": { "type": "object", "additionalProperties": false, "required": [ "data", "meta" ], "properties": { "data": { "$ref": "#/components/schemas/PersonalOwnerPosition" }, "meta": { "$ref": "#/components/schemas/PersonalOwnerPositionMeta" } } }, "V1ErrorEnvelope": { "type": "object", "required": [ "error", "meta" ], "properties": { "error": { "type": "object", "required": [ "message" ], "properties": { "message": { "type": "string" } } }, "meta": { "$ref": "#/components/schemas/V1ErrorMeta" } } }, "V1ErrorMeta": { "type": "object", "required": [ "api_version", "request_id", "resource" ], "properties": { "api_version": { "type": "string", "const": "v1-2026-07" }, "request_id": { "type": "string", "minLength": 1, "maxLength": 128 }, "resource": { "type": "string", "const": "error" } } }, "EvidenceBundle": { "type": "object", "additionalProperties": false, "required": [ "object", "api_version", "bundle_status", "resource", "generated_at", "evidence", "missing_evidence", "warnings", "audit" ], "properties": { "object": { "type": "string", "const": "evidence_bundle" }, "api_version": { "type": "string", "const": "v1-2026-07" }, "bundle_status": { "type": "string", "enum": [ "complete", "partial", "missing", "not_supported", "lookup_failed" ] }, "resource": { "$ref": "#/components/schemas/EvidenceResource" }, "generated_at": { "type": "string", "format": "date-time" }, "evidence": { "$ref": "#/components/schemas/EvidenceBuckets" }, "missing_evidence": { "type": "array", "items": { "$ref": "#/components/schemas/MissingEvidenceItem" } }, "warnings": { "type": "array", "items": { "$ref": "#/components/schemas/MissingEvidenceItem" } }, "audit": { "$ref": "#/components/schemas/EvidenceBundleAudit" } } }, "EvidenceResource": { "type": "object", "additionalProperties": false, "required": [ "type", "id", "company_id" ], "properties": { "type": { "type": "string" }, "id": { "type": "string", "format": "uuid" }, "company_id": { "type": [ "string", "null" ], "format": "uuid" } } }, "EvidenceBuckets": { "type": "object", "additionalProperties": false, "required": [ "source_record", "documents", "ocr", "ledger", "decisions", "approvals", "audit" ], "properties": { "source_record": { "type": "array", "items": { "$ref": "#/components/schemas/EvidenceRecord" } }, "documents": { "type": "array", "items": { "$ref": "#/components/schemas/EvidenceRecord" } }, "ocr": { "type": "array", "items": { "$ref": "#/components/schemas/EvidenceRecord" } }, "ledger": { "type": "array", "items": { "$ref": "#/components/schemas/EvidenceRecord" } }, "decisions": { "type": "array", "items": { "$ref": "#/components/schemas/EvidenceRecord" } }, "approvals": { "type": "array", "items": { "$ref": "#/components/schemas/EvidenceRecord" } }, "audit": { "type": "array", "items": { "$ref": "#/components/schemas/EvidenceRecord" } } } }, "EvidenceRecord": { "type": "object", "additionalProperties": true }, "MissingEvidenceItem": { "type": "object", "additionalProperties": false, "required": [ "code", "severity", "message" ], "properties": { "code": { "type": "string" }, "severity": { "type": "string", "enum": [ "info", "warning", "error" ] }, "message": { "type": "string" } } }, "EvidenceBundleAudit": { "type": "object", "additionalProperties": false, "required": [ "request_id", "generated_for_scope" ], "properties": { "request_id": { "type": "string", "minLength": 1, "maxLength": 128 }, "generated_for_scope": { "type": "string", "const": "business.evidence.read" } } }, "LegacyErrorResponse": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string" } } }, "V1InvoiceMeta": { "type": "object", "required": [ "api_version", "mode", "request_id", "resource" ], "properties": { "api_version": { "type": "string", "const": "v1-2026-07" }, "mode": { "type": "string", "const": "draft" }, "request_id": { "type": "string", "minLength": 1, "maxLength": 128 }, "resource": { "type": "string", "const": "invoice" } } }, "Invoice": { "type": [ "object", "null" ], "required": [ "id", "company_id", "customer_id", "invoice_number", "status", "currency", "total_amount" ], "properties": { "id": { "type": "string", "format": "uuid" }, "company_id": { "type": "string", "format": "uuid" }, "customer_id": { "type": "string", "format": "uuid" }, "invoice_number": { "type": "string", "description": "Draft invoices currently use DRAFT until issued." }, "invoice_date": { "type": "string", "format": "date" }, "due_date": { "type": [ "string", "null" ], "format": "date" }, "payment_terms_days": { "type": "integer" }, "delivery_date": { "type": [ "string", "null" ], "format": "date" }, "service_start_date": { "type": [ "string", "null" ], "format": "date" }, "service_end_date": { "type": [ "string", "null" ], "format": "date" }, "recognition_method": { "type": [ "string", "null" ] }, "is_deposit": { "type": [ "boolean", "null" ] }, "subtotal_amount": { "type": "number" }, "total_vat_amount": { "type": "number" }, "total_amount": { "type": "number" }, "status": { "type": "string", "enum": [ "draft", "issued", "sent", "paid", "overdue", "void", "voided", "cancelled" ] }, "currency": { "type": "string" }, "payment_status": { "type": "string" }, "outstanding_balance": { "type": "number" }, "amount_paid": { "type": "number" }, "fund_id": { "type": [ "string", "null" ], "format": "uuid" }, "posted_to_ledger": { "type": [ "boolean", "null" ] }, "ledger_transaction_id": { "type": [ "string", "null" ], "format": "uuid" }, "created_by": { "type": [ "string", "null" ], "format": "uuid" }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" }, "lock_version": { "type": "integer", "minimum": 0, "description": "Optimistic concurrency version required by guarded invoice updates." }, "is_recurring": { "type": "boolean" }, "recurring_frequency": { "type": [ "string", "null" ] }, "recurring_interval": { "type": [ "integer", "null" ] }, "recurring_start_date": { "type": [ "string", "null" ], "format": "date" }, "recurring_end_date": { "type": [ "string", "null" ], "format": "date" }, "max_occurrences": { "type": [ "integer", "null" ] }, "next_invoice_date": { "type": [ "string", "null" ], "format": "date" }, "customers": { "$ref": "#/components/schemas/InvoiceCustomer" }, "invoice_line_items": { "type": "array", "items": { "$ref": "#/components/schemas/InvoiceLineItem" } }, "object": { "type": "string", "const": "invoice" }, "voiding_transaction_id": { "type": [ "string", "null" ], "format": "uuid", "description": "Reversal journal transaction id when the invoice has been voided." }, "void_reason": { "type": [ "string", "null" ], "description": "Audit reason recorded when the invoice was voided." } } }, "InvoiceCustomer": { "type": [ "object", "null" ], "properties": { "id": { "type": "string", "format": "uuid" }, "name": { "type": "string" }, "contact_email": { "type": [ "string", "null" ], "format": "email" }, "contact_phone": { "type": [ "string", "null" ] } } }, "InvoiceLineItem": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "line_number": { "type": "integer" }, "line_type": { "type": "string", "enum": [ "sales", "expense_deduction" ] }, "description": { "type": "string" }, "subdescription": { "type": [ "string", "null" ] }, "quantity": { "type": "number" }, "unit_price": { "type": "number" }, "net_amount": { "type": "number" }, "vat_rate": { "type": "number" }, "vat_amount": { "type": "number" }, "gross_amount": { "type": "number" }, "vat_rate_id": { "type": [ "string", "null" ], "format": "uuid" }, "revenue_account_id": { "type": [ "string", "null" ], "format": "uuid" }, "inventory_item_id": { "type": [ "string", "null" ], "format": "uuid" }, "project_id": { "type": [ "string", "null" ], "format": "uuid" }, "cost_center_id": { "type": [ "string", "null" ], "format": "uuid" }, "template_id": { "type": [ "string", "null" ], "format": "uuid" }, "fund_id": { "type": [ "string", "null" ], "format": "uuid" }, "charity_activity_id": { "type": [ "string", "null" ], "format": "uuid" } } }, "InvoiceSendApprovalRequest": { "type": "object", "additionalProperties": false, "properties": { "reason": { "type": "string", "maxLength": 1000 }, "requested_by_name": { "type": "string", "maxLength": 200 }, "requested_by_email": { "type": "string", "format": "email", "maxLength": 320 } } }, "V1ApprovalRequestResponse": { "type": "object", "required": [ "data", "meta" ], "properties": { "data": { "$ref": "#/components/schemas/ApprovalRequest" }, "meta": { "$ref": "#/components/schemas/V1ApprovalRequestMeta" } } }, "V1ApprovalRequestMeta": { "type": "object", "required": [ "api_version", "mode", "request_id", "resource" ], "properties": { "api_version": { "type": "string", "const": "v1-2026-07" }, "mode": { "type": "string", "const": "approval_request" }, "request_id": { "type": "string", "minLength": 1, "maxLength": 128 }, "resource": { "type": "string", "const": "approval_request" } } }, "ApprovalRequest": { "type": "object", "required": [ "id", "object", "status", "resource_type", "resource_id", "requested_action", "policy" ], "properties": { "id": { "type": "string", "format": "uuid" }, "object": { "type": "string", "const": "approval_request" }, "status": { "type": "string", "enum": [ "pending" ] }, "resource_type": { "type": "string", "const": "invoice" }, "resource_id": { "type": "string", "format": "uuid" }, "requested_action": { "type": "string", "const": "send_invoice" }, "current_step_id": { "type": [ "string", "null" ], "format": "uuid" }, "current_step_order": { "type": [ "integer", "null" ] }, "policy": { "type": "object", "required": [ "decision", "reason" ], "properties": { "decision": { "type": "string", "const": "approval_required" }, "reason": { "type": "string" } } } } }, "WebhookEndpointCreateRequest": { "type": "object", "additionalProperties": false, "required": [ "name", "target_url", "enabled_events" ], "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 120 }, "target_url": { "type": "string", "format": "uri", "pattern": "^https://", "maxLength": 2048 }, "enabled_events": { "type": "array", "minItems": 1, "maxItems": 50, "items": { "type": "string", "enum": [ "business.invoice.created", "business.invoice.updated", "business.invoice.issued", "business.invoice.voided", "business.quote.updated", "business.purchase_invoice.voided", "business.expense_claim.voided", "business.credit_note.issued", "business.credit_note.cancelled", "business.approval.created", "agent.action.requires_approval", "*" ] } } } }, "WebhookDelivery": {"type":"object","additionalProperties":false,"required":["attempt_count","created_at","delivered_at","endpoint_id","error_message","event_type","id","last_attempt_at","max_attempts","next_attempt_at","outbox_event_id","request_id","resource_id","resource_type","response_status","status","updated_at"],"properties":{"id":{"type":"string","format":"uuid"},"endpoint_id":{"type":"string","format":"uuid"},"outbox_event_id":{"type":"string","format":"uuid"},"event_type":{"type":["string","null"]},"resource_type":{"type":["string","null"]},"resource_id":{"type":["string","null"]},"status":{"type":"string","enum":["queued","sending","succeeded","failed","dead_letter"]},"attempt_count":{"type":"integer","minimum":0},"max_attempts":{"type":"integer","minimum":1},"next_attempt_at":{"type":"string","format":"date-time"},"last_attempt_at":{"type":["string","null"],"format":"date-time"},"delivered_at":{"type":["string","null"],"format":"date-time"},"response_status":{"type":["integer","null"],"minimum":100,"maximum":599},"error_message":{"type":["string","null"]},"request_id":{"type":"string","format":"uuid"},"created_at":{"type":"string","format":"date-time"},"updated_at":{"type":"string","format":"date-time"}}}, "V1WebhookDeliveryListResponse": {"type":"object","required":["data","meta"],"properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/WebhookDelivery"}},"meta":{"$ref":"#/components/schemas/V1WebhookDeliveryMeta"}}}, "V1WebhookDeliveryMeta": {"type":"object","required":["api_version","mode","pagination","request_id","resource"],"properties":{"api_version":{"type":"string","const":"v1-2026-07"},"mode":{"type":"string","const":"list"},"pagination":{"$ref":"#/components/schemas/V1PaginationMeta"},"request_id":{"type":"string","minLength":1,"maxLength":128},"resource":{"type":"string","const":"webhook_delivery"}}}, "V1WebhookEndpointListResponse": { "type": "object", "required": [ "data", "meta" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/WebhookEndpoint" } }, "meta": { "$ref": "#/components/schemas/V1WebhookEndpointMeta" } } }, "V1WebhookEndpointResponse": { "type": "object", "required": [ "data", "meta" ], "properties": { "data": { "$ref": "#/components/schemas/WebhookEndpoint" }, "meta": { "$ref": "#/components/schemas/V1WebhookEndpointMeta" } } }, "V1WebhookEndpointSecretResponse": { "type": "object", "required": [ "data", "meta" ], "properties": { "data": { "$ref": "#/components/schemas/WebhookEndpointWithSecret" }, "meta": { "$ref": "#/components/schemas/V1WebhookEndpointMeta" } } }, "V1WebhookEndpointMeta": { "type": "object", "required": [ "api_version", "request_id", "resource" ], "properties": { "api_version": { "type": "string", "const": "v1-2026-07" }, "mode": { "type": "string", "enum": [ "created", "rotated", "revoked" ] }, "request_id": { "type": "string", "maxLength": 128 }, "resource": { "type": "string", "const": "webhook_endpoint" } } }, "WebhookEndpoint": { "type": "object", "additionalProperties": false, "required": [ "id", "object", "name", "target_url", "status", "enabled_events", "signing_secret_preview" ], "properties": { "id": { "type": "string", "format": "uuid" }, "object": { "type": "string", "const": "webhook_endpoint" }, "name": { "type": "string" }, "target_url": { "type": "string", "format": "uri" }, "status": { "type": "string", "enum": [ "active", "paused", "disabled", "revoked" ] }, "enabled_events": { "type": "array", "items": { "type": "string" } }, "api_version": { "type": "string" }, "signing_secret_preview": { "type": "string", "minLength": 4, "maxLength": 16 }, "failure_count": { "type": "integer", "minimum": 0 }, "last_success_at": { "type": [ "string", "null" ], "format": "date-time" }, "last_failure_at": { "type": [ "string", "null" ], "format": "date-time" }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" } } }, "WebhookEndpointWithSecret": { "allOf": [ { "$ref": "#/components/schemas/WebhookEndpoint" }, { "type": "object", "required": [ "signing_secret", "signing_secret_displayed_once" ], "properties": { "signing_secret": { "type": "string", "pattern": "^fiqwhsec_" }, "signing_secret_displayed_once": { "type": "boolean", "const": true } } } ] }, "PersonalBusinessLinkListResponse": { "type": "object", "additionalProperties": false, "required": [ "object", "api_version", "data", "meta" ], "properties": { "object": { "type": "string", "const": "list" }, "api_version": { "type": "string", "const": "v1-2026-07" }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/PersonalBusinessLink" } }, "meta": { "$ref": "#/components/schemas/V1PersonalBusinessLinkMeta" } } }, "V1PersonalBusinessLinkMeta": { "type": "object", "additionalProperties": false, "required": [ "api_version", "request_id", "resource", "scope" ], "properties": { "api_version": { "type": "string", "const": "v1-2026-07" }, "request_id": { "type": "string", "maxLength": 128 }, "resource": { "type": "string", "const": "personal_business_link" }, "scope": { "type": "string", "const": "personal.business_links.read" } } }, "PersonalBusinessLink": { "type": "object", "additionalProperties": false, "required": [ "object", "api_version", "id", "user_id", "company_id", "status", "linked_at", "shareholder_links", "permissions" ], "properties": { "object": { "type": "string", "const": "personal_business_link" }, "api_version": { "type": "string", "const": "v1-2026-07" }, "id": { "type": "string", "format": "uuid" }, "user_id": { "type": "string", "format": "uuid" }, "company_id": { "type": "string", "format": "uuid" }, "status": { "type": "string", "enum": [ "active", "inactive" ] }, "linked_at": { "type": "string", "format": "date-time" }, "shareholder_links": { "type": "array", "items": { "$ref": "#/components/schemas/PersonalBusinessShareholderLink" } }, "permissions": { "$ref": "#/components/schemas/PersonalBusinessLinkPermissions" } } }, "PersonalBusinessShareholderLink": { "type": "object", "additionalProperties": false, "required": [ "id", "shareholder_id", "weight_override" ], "properties": { "id": { "type": "string", "format": "uuid" }, "shareholder_id": { "type": "string", "format": "uuid" }, "weight_override": { "type": [ "number", "null" ], "minimum": 0, "maximum": 1 } } }, "PersonalBusinessShareholderLinkListResponse": { "type": "object", "additionalProperties": false, "required": [ "object", "api_version", "data", "meta" ], "properties": { "object": { "type": "string", "const": "list" }, "api_version": { "type": "string", "const": "v1-2026-07" }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/PersonalBusinessShareholderLink" } }, "meta": { "$ref": "#/components/schemas/V1PersonalBusinessShareholderLinkMeta" } } }, "PersonalBusinessShareholderLinkResponse": { "type": "object", "additionalProperties": false, "required": [ "data", "meta" ], "properties": { "data": { "$ref": "#/components/schemas/PersonalBusinessShareholderLink" }, "meta": { "$ref": "#/components/schemas/V1PersonalBusinessShareholderLinkDetailMeta" } } }, "V1PersonalBusinessShareholderLinkDetailMeta": { "type": "object", "additionalProperties": false, "required": [ "api_version", "link_id", "mode", "request_id", "resource", "scope", "shareholder_id" ], "properties": { "api_version": { "type": "string", "const": "v1-2026-07" }, "link_id": { "type": "string", "format": "uuid" }, "mode": { "type": "string", "const": "detail" }, "request_id": { "type": "string", "maxLength": 128 }, "resource": { "type": "string", "const": "personal_business_shareholder_link" }, "scope": { "type": "string", "const": "personal.business_links.read" }, "shareholder_id": { "type": "string", "format": "uuid" } } }, "V1PersonalBusinessShareholderLinkMeta": { "type": "object", "additionalProperties": false, "required": [ "api_version", "link_id", "request_id", "resource", "scope" ], "properties": { "api_version": { "type": "string", "const": "v1-2026-07" }, "link_id": { "type": "string", "format": "uuid" }, "request_id": { "type": "string", "maxLength": 128 }, "resource": { "type": "string", "const": "personal_business_shareholder_link" }, "scope": { "type": "string", "const": "personal.business_links.read" } } }, "PersonalBusinessLinkPermissions": { "type": "object", "additionalProperties": false, "required": [ "can_read_business_value", "can_read_dividends", "can_write_business_books", "can_read_personal_accounts_from_business_scope" ], "properties": { "can_read_business_value": { "type": "boolean" }, "can_read_dividends": { "type": "boolean" }, "can_write_business_books": { "type": "boolean", "const": false }, "can_read_personal_accounts_from_business_scope": { "type": "boolean", "const": false } } }, "PersonalBusinessLinkCreateRequest": { "type": "object", "additionalProperties": false, "required": [ "company_id" ], "properties": { "company_id": { "type": "string", "format": "uuid" } } }, "PersonalBusinessShareholderMapRequest": { "type": "object", "additionalProperties": false, "required": [ "shareholder_id" ], "properties": { "shareholder_id": { "type": "string", "format": "uuid" }, "weight_override": { "type": [ "number", "null" ], "exclusiveMinimum": 0, "maximum": 1 } } }, "PersonalBusinessLinkResponse": { "type": "object", "additionalProperties": false, "required": [ "data", "meta" ], "properties": { "data": { "$ref": "#/components/schemas/PersonalBusinessLink" }, "meta": { "$ref": "#/components/schemas/V1PersonalBusinessLinkMutationMeta" } } }, "V1PersonalBusinessLinkMutationMeta": { "type": "object", "additionalProperties": false, "required": [ "api_version", "mode", "request_id", "resource" ], "properties": { "api_version": { "type": "string", "const": "v1-2026-07" }, "mode": { "type": "string", "enum": [ "created", "active", "detail", "revoked", "shareholder_mapped", "shareholder_updated", "shareholder_unmapped" ] }, "request_id": { "type": "string", "maxLength": 128 }, "resource": { "type": "string", "const": "personal_business_link" } } }, "V1BusinessInvoiceDeliveryEvent": { "type": "object", "additionalProperties": false, "required": ["id", "invoice_id", "event_type", "delivery_status", "created_at"], "properties": { "id": {"type": "string", "format": "uuid"}, "invoice_id": {"type": "string", "format": "uuid"}, "event_type": {"type": "string", "enum": ["sent", "reminder"]}, "delivery_status": {"type": "string", "enum": ["queued", "sent", "delivered", "bounced", "failed"]}, "recipient_email": {"type": ["string", "null"]}, "subject": {"type": ["string", "null"]}, "delivery_provider": {"type": ["string", "null"]}, "error_message": {"type": ["string", "null"]}, "created_at": {"type": "string", "format": "date-time"} } }, "V1BusinessInvoiceDeliveryEventListResponse": { "type": "object", "required": ["data", "meta"], "properties": { "data": {"type": "array", "items": {"$ref": "#/components/schemas/V1BusinessInvoiceDeliveryEvent"}}, "meta": {"$ref": "#/components/schemas/V1BusinessInvoiceDeliveryEventListMeta"} } }, "V1BusinessInvoiceDeliveryEventListMeta": { "type": "object", "required": ["api_version", "mode", "pagination", "request_id", "resource"], "properties": { "api_version": {"type": "string", "const": "v1-2026-07"}, "mode": {"type": "string", "const": "list"}, "pagination": {"$ref": "#/components/schemas/V1PaginationMeta"}, "request_id": {"type": "string"}, "resource": {"type": "string", "const": "invoice_delivery_event"} } }, "V1BusinessQuoteSendExecutionRequest": {"type":"object","additionalProperties":false,"required":["approval_request_id"],"properties":{"approval_request_id":{"type":"string","format":"uuid"},"recipient_email":{"type":"string","format":"email","maxLength":320},"subject":{"type":"string","maxLength":255},"message":{"type":"string","maxLength":10000}}}, "V1BusinessInvoiceSendExecutionRequest": {"type":"object","additionalProperties":false,"required":["approval_request_id"],"properties":{"approval_request_id":{"type":"string","format":"uuid"},"recipient_email":{"type":"string","format":"email","maxLength":320},"subject":{"type":"string","maxLength":255},"message":{"type":"string","maxLength":10000}}}, "V1BusinessInvoiceSendExecutionData": {"type":"object","additionalProperties":false,"required":["approval_request_id","delivery_status","event_id","invoice_id","provider","recipient_email"],"properties":{"approval_request_id":{"type":"string","format":"uuid"},"delivery_status":{"type":["string","null"],"enum":["sent","delivered"]},"event_id":{"type":["string","null"],"format":"uuid"},"invoice_id":{"type":"string","format":"uuid"},"provider":{"type":["string","null"]},"recipient_email":{"type":["string","null"],"format":"email"}}}, "V1BusinessInvoiceSendExecutionMeta": {"type":"object","required":["api_version","mode","request_id","resource"],"properties":{"api_version":{"type":"string","const":"v1-2026-07"},"mode":{"type":"string","const":"executed"},"request_id":{"type":"string","minLength":1,"maxLength":128},"resource":{"type":"string","const":"invoice_delivery"}}}, "V1BusinessQuoteSendExecutionResponse": {"type":"object","required":["data","meta"],"properties":{"data":{"$ref":"#/components/schemas/V1BusinessQuoteSendExecutionData"},"meta":{"$ref":"#/components/schemas/V1BusinessQuoteSendExecutionMeta"}}}, "V1BusinessInvoiceSendExecutionResponse": {"type":"object","required":["data","meta"],"properties":{"data":{"$ref":"#/components/schemas/V1BusinessInvoiceSendExecutionData"},"meta":{"$ref":"#/components/schemas/V1BusinessInvoiceSendExecutionMeta"}}}, "V1BusinessInvoiceListResponse": { "type": "object", "required": [ "data", "meta" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Invoice" } }, "meta": { "$ref": "#/components/schemas/V1BusinessInvoiceListMeta" } } }, "V1BusinessInvoiceResponse": { "type": "object", "required": [ "data", "meta" ], "properties": { "data": { "$ref": "#/components/schemas/Invoice" }, "meta": { "$ref": "#/components/schemas/V1BusinessInvoiceMeta" } } }, "V1BusinessInvoiceListMeta": { "type": "object", "required": [ "api_version", "mode", "pagination", "request_id", "resource" ], "properties": { "api_version": { "type": "string", "const": "v1-2026-07" }, "mode": { "type": "string", "const": "list" }, "pagination": { "$ref": "#/components/schemas/V1PaginationMeta" }, "request_id": { "type": "string", "minLength": 1, "maxLength": 128 }, "resource": { "type": "string", "const": "invoice" } } }, "V1BusinessInvoiceMeta": { "type": "object", "required": [ "api_version", "mode", "request_id", "resource" ], "properties": { "api_version": { "type": "string", "const": "v1-2026-07" }, "mode": { "type": "string", "const": "detail" }, "request_id": { "type": "string", "minLength": 1, "maxLength": 128 }, "resource": { "type": "string", "const": "invoice" } } }, "PersonalAccount": { "type": "object", "additionalProperties": false, "required": [ "id", "object", "user_id" ], "properties": { "object": { "type": "string", "const": "personal_account" }, "id": { "type": "string", "format": "uuid" }, "user_id": { "type": "string", "format": "uuid" }, "account_name": { "type": [ "string", "null" ] }, "bank_name": { "type": [ "string", "null" ] }, "lender_name": { "type": [ "string", "null" ] }, "provider_name": { "type": [ "string", "null" ] }, "logo_url": { "type": [ "string", "null" ], "format": "uri" }, "account_type": { "type": [ "string", "null" ] }, "account_category": { "type": [ "string", "null" ] }, "currency": { "type": [ "string", "null" ] }, "current_balance": { "type": [ "number", "null" ] }, "available_balance": { "type": [ "number", "null" ] }, "actual_balance": { "type": [ "number", "null" ] }, "book_balance": { "type": [ "number", "null" ] }, "connection_status": { "type": [ "string", "null" ] }, "feed_status": { "type": [ "string", "null" ] }, "is_active": { "type": "boolean" }, "interest_rate": { "type": [ "number", "null" ] }, "monthly_payment": { "type": [ "number", "null" ] }, "original_loan_amount": { "type": [ "number", "null" ] }, "loan_type": { "type": [ "string", "null" ] }, "loan_start_date": { "type": [ "string", "null" ], "format": "date" }, "loan_end_date": { "type": [ "string", "null" ], "format": "date" }, "loan_term_months": { "type": [ "number", "null" ] }, "repayment_type": { "type": [ "string", "null" ] }, "last_sync_at": { "type": [ "string", "null" ], "format": "date-time" }, "created_at": { "type": [ "string", "null" ], "format": "date-time" }, "updated_at": { "type": [ "string", "null" ], "format": "date-time" } } }, "PersonalAccountListResponse": { "type": "object", "required": [ "object", "api_version", "data", "meta" ], "properties": { "object": { "type": "string", "const": "list" }, "api_version": { "type": "string", "const": "v1-2026-07" }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/PersonalAccount" } }, "meta": { "$ref": "#/components/schemas/PersonalAccountListMeta" } } }, "PersonalAccountResponse": { "type": "object", "required": [ "data", "meta" ], "properties": { "data": { "$ref": "#/components/schemas/PersonalAccount" }, "meta": { "$ref": "#/components/schemas/PersonalAccountMeta" } } }, "PersonalAccountListMeta": { "type": "object", "required": [ "api_version", "mode", "pagination", "request_id", "resource", "scope" ], "properties": { "api_version": { "type": "string", "const": "v1-2026-07" }, "mode": { "type": "string", "const": "list" }, "pagination": { "$ref": "#/components/schemas/V1PaginationMeta" }, "request_id": { "type": "string", "minLength": 1, "maxLength": 128 }, "resource": { "type": "string", "const": "personal_account" }, "scope": { "type": "string", "const": "personal.accounts.read" } } }, "PersonalAccountMeta": { "type": "object", "required": [ "api_version", "mode", "request_id", "resource", "scope" ], "properties": { "api_version": { "type": "string", "const": "v1-2026-07" }, "mode": { "type": "string", "const": "detail" }, "request_id": { "type": "string", "minLength": 1, "maxLength": 128 }, "resource": { "type": "string", "const": "personal_account" }, "scope": { "type": "string", "const": "personal.accounts.read" } } }, "PersonalAsset": { "type": "object", "additionalProperties": false, "required": [ "id", "user_id", "object" ], "properties": { "object": { "type": "string", "const": "personal_asset" }, "id": { "type": "string", "format": "uuid" }, "user_id": { "type": "string", "format": "uuid" }, "name": { "type": [ "string", "null" ] }, "asset_type": { "type": [ "string", "null" ] }, "current_value": { "type": [ "number", "null" ] }, "purchase_date": { "type": [ "string", "null" ], "format": "date" }, "purchase_price": { "type": [ "number", "null" ] }, "description": { "type": [ "string", "null" ] }, "is_active": { "type": "boolean" }, "created_at": { "type": [ "string", "null" ], "format": "date-time" }, "updated_at": { "type": [ "string", "null" ], "format": "date-time" } } }, "PersonalAssetListResponse": { "type": "object", "required": [ "object", "api_version", "data", "meta" ], "properties": { "object": { "type": "string", "const": "list" }, "api_version": { "type": "string", "const": "v1-2026-07" }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/PersonalAsset" } }, "meta": { "$ref": "#/components/schemas/PersonalAssetListMeta" } } }, "PersonalAssetResponse": { "type": "object", "required": [ "data", "meta" ], "properties": { "data": { "$ref": "#/components/schemas/PersonalAsset" }, "meta": { "$ref": "#/components/schemas/PersonalAssetMeta" } } }, "PersonalAssetListMeta": { "type": "object", "required": [ "api_version", "mode", "pagination", "request_id", "resource", "scope" ], "properties": { "api_version": { "type": "string", "const": "v1-2026-07" }, "mode": { "type": "string", "const": "list" }, "pagination": { "$ref": "#/components/schemas/V1PaginationMeta" }, "request_id": { "type": "string", "minLength": 1, "maxLength": 128 }, "resource": { "type": "string", "const": "personal_asset" }, "scope": { "type": "string", "const": "personal.assets.read" } } }, "PersonalAssetMeta": { "type": "object", "required": [ "api_version", "mode", "request_id", "resource", "scope" ], "properties": { "api_version": { "type": "string", "const": "v1-2026-07" }, "mode": { "type": "string", "const": "detail" }, "request_id": { "type": "string", "minLength": 1, "maxLength": 128 }, "resource": { "type": "string", "const": "personal_asset" }, "scope": { "type": "string", "const": "personal.assets.read" } } }, "PersonalLiability": { "type": "object", "additionalProperties": false, "required": [ "id", "user_id", "object" ], "properties": { "object": { "type": "string", "const": "personal_liability" }, "id": { "type": "string", "format": "uuid" }, "user_id": { "type": "string", "format": "uuid" }, "name": { "type": [ "string", "null" ] }, "liability_type": { "type": [ "string", "null" ] }, "current_balance": { "type": [ "number", "null" ] }, "interest_rate": { "type": [ "number", "null" ] }, "minimum_payment": { "type": [ "number", "null" ] }, "payment_due_date": { "type": [ "number", "null" ] }, "original_amount": { "type": [ "number", "null" ] }, "start_date": { "type": [ "string", "null" ], "format": "date" }, "maturity_date": { "type": [ "string", "null" ], "format": "date" }, "is_active": { "type": "boolean" }, "created_at": { "type": [ "string", "null" ], "format": "date-time" }, "updated_at": { "type": [ "string", "null" ], "format": "date-time" } } }, "PersonalLiabilityListResponse": { "type": "object", "required": [ "object", "api_version", "data", "meta" ], "properties": { "object": { "type": "string", "const": "list" }, "api_version": { "type": "string", "const": "v1-2026-07" }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/PersonalLiability" } }, "meta": { "$ref": "#/components/schemas/PersonalLiabilityListMeta" } } }, "PersonalLiabilityResponse": { "type": "object", "required": [ "data", "meta" ], "properties": { "data": { "$ref": "#/components/schemas/PersonalLiability" }, "meta": { "$ref": "#/components/schemas/PersonalLiabilityMeta" } } }, "PersonalLiabilityListMeta": { "type": "object", "required": [ "api_version", "mode", "pagination", "request_id", "resource", "scope" ], "properties": { "api_version": { "type": "string", "const": "v1-2026-07" }, "mode": { "type": "string", "const": "list" }, "pagination": { "$ref": "#/components/schemas/V1PaginationMeta" }, "request_id": { "type": "string", "minLength": 1, "maxLength": 128 }, "resource": { "type": "string", "const": "personal_liability" }, "scope": { "type": "string", "const": "personal.liabilities.read" } } }, "PersonalLiabilityMeta": { "type": "object", "required": [ "api_version", "mode", "request_id", "resource", "scope" ], "properties": { "api_version": { "type": "string", "const": "v1-2026-07" }, "mode": { "type": "string", "const": "detail" }, "request_id": { "type": "string", "minLength": 1, "maxLength": 128 }, "resource": { "type": "string", "const": "personal_liability" }, "scope": { "type": "string", "const": "personal.liabilities.read" } } }, "PersonalTransactionCategory": { "type": "object", "additionalProperties": false, "required": [ "id" ], "properties": { "id": { "type": "string", "format": "uuid" }, "category_type": { "type": [ "string", "null" ] }, "name": { "type": [ "string", "null" ] } } }, "PersonalTransaction": { "type": "object", "additionalProperties": false, "required": [ "id", "object", "user_id", "bank_account_id" ], "properties": { "object": { "type": "string", "const": "personal_transaction" }, "id": { "type": "string", "format": "uuid" }, "user_id": { "type": "string", "format": "uuid" }, "bank_account_id": { "type": "string", "format": "uuid" }, "transaction_date": { "type": [ "string", "null" ], "format": "date" }, "description": { "type": [ "string", "null" ] }, "merchant_name": { "type": [ "string", "null" ] }, "reference": { "type": [ "string", "null" ] }, "transaction_type": { "type": [ "string", "null" ] }, "gross_amount": { "type": [ "number", "null" ] }, "currency": { "type": [ "string", "null" ] }, "original_amount": { "type": [ "number", "null" ] }, "original_currency": { "type": [ "string", "null" ] }, "exchange_rate": { "type": [ "number", "null" ] }, "gbp_amount": { "type": [ "number", "null" ] }, "balance_after": { "type": [ "number", "null" ] }, "personal_category_id": { "type": [ "string", "null" ], "format": "uuid" }, "category": { "anyOf": [ { "$ref": "#/components/schemas/PersonalTransactionCategory" }, { "type": "null" } ] }, "categorisation_status": { "type": [ "string", "null" ] }, "categorisation_source": { "type": [ "string", "null" ] }, "category_uncertain": { "type": "boolean" }, "receipt_attached": { "type": "boolean" }, "receipt_required": { "type": "boolean" }, "reconciliation_status": { "type": [ "string", "null" ] }, "transaction_source": { "type": [ "string", "null" ] }, "created_at": { "type": [ "string", "null" ], "format": "date-time" }, "updated_at": { "type": [ "string", "null" ], "format": "date-time" } } }, "PersonalTransactionFilters": { "type": "object", "additionalProperties": false, "properties": { "account_id": { "type": [ "string", "null" ], "format": "uuid" }, "category_id": { "type": [ "string", "null" ], "format": "uuid" }, "from_date": { "type": [ "string", "null" ], "format": "date" }, "to_date": { "type": [ "string", "null" ], "format": "date" }, "transaction_type": { "type": [ "string", "null" ] }, "uncategorised": { "type": "boolean" } } }, "PersonalTransactionListMeta": { "type": "object", "required": [ "api_version", "filters", "mode", "pagination", "request_id", "resource", "scope" ], "properties": { "api_version": { "type": "string", "const": "v1-2026-07" }, "filters": { "$ref": "#/components/schemas/PersonalTransactionFilters" }, "mode": { "type": "string", "const": "list" }, "pagination": { "$ref": "#/components/schemas/V1PaginationMeta" }, "request_id": { "type": "string", "minLength": 1, "maxLength": 128 }, "resource": { "type": "string", "const": "personal_transaction" }, "scope": { "type": "string", "const": "personal.transactions.read" } } }, "PersonalTransactionMeta": { "type": "object", "required": [ "api_version", "mode", "request_id", "resource", "scope" ], "properties": { "api_version": { "type": "string", "const": "v1-2026-07" }, "mode": { "type": "string", "const": "detail" }, "request_id": { "type": "string", "minLength": 1, "maxLength": 128 }, "resource": { "type": "string", "const": "personal_transaction" }, "scope": { "type": "string", "const": "personal.transactions.read" } } }, "PersonalTransactionListResponse": { "type": "object", "required": [ "object", "api_version", "data", "meta" ], "properties": { "object": { "type": "string", "const": "list" }, "api_version": { "type": "string", "const": "v1-2026-07" }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/PersonalTransaction" } }, "meta": { "$ref": "#/components/schemas/PersonalTransactionListMeta" } } }, "PersonalTransactionResponse": { "type": "object", "required": [ "data", "meta" ], "properties": { "data": { "$ref": "#/components/schemas/PersonalTransaction" }, "meta": { "$ref": "#/components/schemas/PersonalTransactionMeta" } } }, "BusinessSupplier": { "type": "object", "additionalProperties": false, "required": [ "id", "company_id", "name", "object" ], "properties": { "object": { "type": "string", "const": "business_supplier" }, "id": { "type": "string", "format": "uuid" }, "company_id": { "type": "string", "format": "uuid" }, "name": { "type": "string" }, "supplier_reference": { "type": [ "string", "null" ] }, "contact_email": { "type": [ "string", "null" ], "format": "email" }, "contact_phone": { "type": [ "string", "null" ] }, "address": { "type": [ "string", "null" ] }, "vat_number": { "type": [ "string", "null" ] }, "default_vat_rate": { "type": [ "number", "null" ] }, "payment_terms_days": { "type": [ "integer", "null" ] }, "payment_method": { "type": [ "string", "null" ] }, "default_nominal_code": { "type": [ "string", "null" ] }, "default_chart_of_accounts_id": { "type": [ "string", "null" ], "format": "uuid" }, "budget_limit": { "type": [ "number", "null" ] }, "flag_for_review": { "type": "boolean" }, "related_party": { "type": "boolean" }, "is_active": { "type": "boolean" }, "fao": { "type": [ "string", "null" ] }, "total_outstanding": { "type": [ "number", "null" ] }, "last_invoice_date": { "type": [ "string", "null" ], "format": "date" }, "average_days_to_pay": { "type": [ "number", "null" ] }, "created_at": { "type": [ "string", "null" ], "format": "date-time" }, "updated_at": { "type": [ "string", "null" ], "format": "date-time" } } }, "V1BusinessSupplierListMeta": { "type": "object", "required": [ "api_version", "mode", "pagination", "request_id", "resource" ], "properties": { "api_version": { "type": "string", "const": "v1-2026-07" }, "mode": { "type": "string", "const": "list" }, "pagination": { "$ref": "#/components/schemas/V1PaginationMeta" }, "request_id": { "type": "string", "minLength": 1, "maxLength": 128 }, "resource": { "type": "string", "const": "business_supplier" } } }, "V1BusinessSupplierMeta": { "type": "object", "required": [ "api_version", "mode", "request_id", "resource" ], "properties": { "api_version": { "type": "string", "const": "v1-2026-07" }, "mode": { "type": "string", "const": "detail" }, "request_id": { "type": "string", "minLength": 1, "maxLength": 128 }, "resource": { "type": "string", "const": "business_supplier" } } }, "V1BusinessSupplierListResponse": { "type": "object", "required": [ "data", "meta" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/BusinessSupplier" } }, "meta": { "$ref": "#/components/schemas/V1BusinessSupplierListMeta" } } }, "V1BusinessSupplierResponse": { "type": "object", "required": [ "data", "meta" ], "properties": { "data": { "$ref": "#/components/schemas/BusinessSupplier" }, "meta": { "$ref": "#/components/schemas/V1BusinessSupplierMeta" } } }, "PurchaseInvoiceSupplier": { "type": "object", "additionalProperties": false, "required": [ "id", "name" ], "properties": { "id": { "type": "string", "format": "uuid" }, "name": { "type": "string" }, "contact_email": { "type": [ "string", "null" ], "format": "email" } } }, "PurchaseInvoiceLineItem": { "type": "object", "additionalProperties": false, "required": [ "id" ], "properties": { "id": { "type": "string", "format": "uuid" }, "description": { "type": [ "string", "null" ] }, "quantity": { "type": [ "number", "null" ] }, "unit_price": { "type": [ "number", "null" ] }, "net_amount": { "type": [ "number", "null" ] }, "vat_rate": { "type": [ "number", "null" ] }, "vat_amount": { "type": [ "number", "null" ] }, "gross_amount": { "type": [ "number", "null" ] }, "chart_of_accounts_id": { "type": [ "string", "null" ], "format": "uuid" } } }, "PurchaseInvoice": { "type": "object", "additionalProperties": false, "required": [ "id", "company_id", "object", "supplier_id" ], "properties": { "object": { "type": "string", "const": "purchase_invoice" }, "id": { "type": "string", "format": "uuid" }, "company_id": { "type": "string", "format": "uuid" }, "supplier_id": { "type": "string", "format": "uuid" }, "user_id": { "type": [ "string", "null" ], "format": "uuid" }, "created_by": { "type": [ "string", "null" ], "format": "uuid" }, "internal_reference": { "type": [ "string", "null" ] }, "invoice_number": { "type": [ "string", "null" ] }, "supplier_invoice_number": { "type": [ "string", "null" ] }, "invoice_date": { "type": [ "string", "null" ], "format": "date" }, "due_date": { "type": [ "string", "null" ], "format": "date" }, "currency": { "type": [ "string", "null" ] }, "net_amount": { "type": [ "number", "null" ] }, "vat_amount": { "type": [ "number", "null" ] }, "total_amount": { "type": [ "number", "null" ] }, "notes": { "type": [ "string", "null" ] }, "submitted_by_name": { "type": [ "string", "null" ] }, "status": { "type": [ "string", "null" ] }, "payment_status": { "type": [ "string", "null" ] }, "approval_status": { "type": [ "string", "null" ] }, "cost_center_selections": { "type": [ "object", "null" ], "additionalProperties": true }, "posted_to_ledger": { "type": [ "boolean", "null" ] }, "ledger_transaction_id": { "type": [ "string", "null" ], "format": "uuid" }, "document_id": { "type": [ "string", "null" ], "format": "uuid" }, "created_at": { "type": [ "string", "null" ], "format": "date-time" }, "updated_at": { "type": [ "string", "null" ], "format": "date-time" }, "suppliers": { "anyOf": [ { "$ref": "#/components/schemas/PurchaseInvoiceSupplier" }, { "type": "null" } ] }, "purchase_invoice_line_items": { "type": "array", "items": { "$ref": "#/components/schemas/PurchaseInvoiceLineItem" } }, "voiding_transaction_id": { "type": [ "string", "null" ], "format": "uuid" } } }, "V1BusinessPurchaseInvoiceListMeta": { "type": "object", "required": [ "api_version", "mode", "pagination", "request_id", "resource" ], "properties": { "api_version": { "type": "string", "const": "v1-2026-07" }, "mode": { "type": "string", "const": "list" }, "pagination": { "$ref": "#/components/schemas/V1PaginationMeta" }, "request_id": { "type": "string", "minLength": 1, "maxLength": 128 }, "resource": { "type": "string", "const": "purchase_invoice" } } }, "V1BusinessPurchaseInvoiceMeta": { "type": "object", "required": [ "api_version", "mode", "request_id", "resource" ], "properties": { "api_version": { "type": "string", "const": "v1-2026-07" }, "mode": { "type": "string", "const": "detail" }, "request_id": { "type": "string", "minLength": 1, "maxLength": 128 }, "resource": { "type": "string", "const": "purchase_invoice" } } }, "V1BusinessPurchaseInvoiceListResponse": { "type": "object", "required": [ "data", "meta" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/PurchaseInvoice" } }, "meta": { "$ref": "#/components/schemas/V1BusinessPurchaseInvoiceListMeta" } } }, "V1BusinessPurchaseInvoiceResponse": { "type": "object", "required": [ "data", "meta" ], "properties": { "data": { "$ref": "#/components/schemas/PurchaseInvoice" }, "meta": { "$ref": "#/components/schemas/V1BusinessPurchaseInvoiceMeta" } } }, "BusinessSupplierPaymentRunItem": { "type": "object", "additionalProperties": false, "required": [ "object", "id", "company_id", "payment_run_id", "purchase_invoice_id", "amount", "currency", "status" ], "properties": { "object": { "type": "string", "const": "business_supplier_payment_run_item" }, "id": { "type": "string", "format": "uuid" }, "company_id": { "type": "string", "format": "uuid" }, "payment_run_id": { "type": "string", "format": "uuid" }, "purchase_invoice_id": { "type": "string", "format": "uuid" }, "supplier_id": { "type": [ "string", "null" ], "format": "uuid" }, "due_date": { "type": [ "string", "null" ], "format": "date" }, "amount": { "type": [ "number", "null" ] }, "currency": { "type": [ "string", "null" ] }, "status": { "type": [ "string", "null" ] }, "batch_id": { "type": [ "string", "null" ], "format": "uuid" }, "execution_status": { "type": [ "string", "null" ] }, "failure_reason": { "type": [ "string", "null" ] }, "paid_at": { "type": [ "string", "null" ], "format": "date-time" }, "purchase_payment_id": { "type": [ "string", "null" ], "format": "uuid" }, "created_at": { "type": [ "string", "null" ], "format": "date-time" }, "updated_at": { "type": [ "string", "null" ], "format": "date-time" } }, "description": "Safe supplier payment run item state. Raw Open Banking/Yapily payment ids and supplier bank details are not exposed." }, "BusinessSupplierPaymentRun": { "type": "object", "additionalProperties": false, "required": [ "object", "id", "company_id", "run_number", "status", "currency", "total_amount", "item_count" ], "properties": { "object": { "type": "string", "const": "business_supplier_payment_run" }, "id": { "type": "string", "format": "uuid" }, "company_id": { "type": "string", "format": "uuid" }, "run_number": { "type": [ "string", "null" ] }, "status": { "type": [ "string", "null" ] }, "scheduled_payment_date": { "type": [ "string", "null" ], "format": "date" }, "currency": { "type": [ "string", "null" ] }, "total_amount": { "type": [ "number", "null" ] }, "item_count": { "type": [ "number", "null" ] }, "provider": { "type": [ "string", "null" ] }, "provider_reference": { "type": [ "string", "null" ] }, "notes": { "type": [ "string", "null" ] }, "created_by_user_id": { "type": [ "string", "null" ], "format": "uuid" }, "submitted_by_user_id": { "type": [ "string", "null" ], "format": "uuid" }, "approved_by_user_id": { "type": [ "string", "null" ], "format": "uuid" }, "cancelled_by_user_id": { "type": [ "string", "null" ], "format": "uuid" }, "executed_by_user_id": { "type": [ "string", "null" ], "format": "uuid" }, "submitted_at": { "type": [ "string", "null" ], "format": "date-time" }, "approved_at": { "type": [ "string", "null" ], "format": "date-time" }, "cancelled_at": { "type": [ "string", "null" ], "format": "date-time" }, "executed_at": { "type": [ "string", "null" ], "format": "date-time" }, "created_at": { "type": [ "string", "null" ], "format": "date-time" }, "updated_at": { "type": [ "string", "null" ], "format": "date-time" }, "items": { "type": "array", "items": { "$ref": "#/components/schemas/BusinessSupplierPaymentRunItem" } } }, "description": "Supplier payment run state without supplier bank account details, payment authorisation URLs or raw Open Banking payment identifiers." }, "V1BusinessSupplierPaymentRunListMeta": { "type": "object", "additionalProperties": false, "properties": { "api_version": { "type": "string" }, "mode": { "type": "string", "const": "list" }, "pagination": { "$ref": "#/components/schemas/V1PaginationMeta" }, "request_id": { "type": "string" }, "resource": { "type": "string", "const": "business_supplier_payment_run" } } }, "V1BusinessSupplierPaymentRunMeta": { "type": "object", "additionalProperties": false, "properties": { "api_version": { "type": "string" }, "mode": { "type": "string", "const": "detail" }, "request_id": { "type": "string" }, "resource": { "type": "string", "const": "business_supplier_payment_run" } } }, "V1BusinessSupplierPaymentRunListResponse": { "type": "object", "additionalProperties": false, "required": [ "data", "meta" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/BusinessSupplierPaymentRun" } }, "meta": { "$ref": "#/components/schemas/V1BusinessSupplierPaymentRunListMeta" } } }, "V1BusinessSupplierPaymentRunResponse": { "type": "object", "additionalProperties": false, "required": [ "data", "meta" ], "properties": { "data": { "$ref": "#/components/schemas/BusinessSupplierPaymentRun" }, "meta": { "$ref": "#/components/schemas/V1BusinessSupplierPaymentRunMeta" } } }, "PurchaseOrderSupplier": { "type": "object", "additionalProperties": false, "required": [ "id", "name" ], "properties": { "id": { "type": [ "string", "null" ], "format": "uuid" }, "name": { "type": [ "string", "null" ] } } }, "PurchaseOrderProjectSummary": { "type": "object", "additionalProperties": false, "required": [ "id", "name" ], "properties": { "id": { "type": [ "string", "null" ], "format": "uuid" }, "code": { "type": [ "string", "null" ] }, "name": { "type": [ "string", "null" ] } } }, "PurchaseOrderChartOfAccountSummary": { "type": "object", "additionalProperties": false, "required": [ "id", "name" ], "properties": { "id": { "type": [ "string", "null" ], "format": "uuid" }, "code": { "type": [ "string", "null" ] }, "name": { "type": [ "string", "null" ] } } }, "PurchaseOrderLineItem": { "type": "object", "additionalProperties": false, "required": [ "id" ], "properties": { "id": { "type": "string", "format": "uuid" }, "purchase_order_id": { "type": [ "string", "null" ], "format": "uuid" }, "description": { "type": [ "string", "null" ] }, "sku": { "type": [ "string", "null" ] }, "inventory_item_id": { "type": [ "string", "null" ], "format": "uuid" }, "quantity": { "type": [ "number", "null" ] }, "unit_price": { "type": [ "number", "null" ] }, "vat_rate": { "type": [ "number", "null" ] }, "vat_amount": { "type": [ "number", "null" ] }, "line_total": { "type": [ "number", "null" ] }, "chart_of_accounts_id": { "type": [ "string", "null" ], "format": "uuid" }, "project_id": { "type": [ "string", "null" ], "format": "uuid" }, "sort_order": { "type": [ "number", "null" ] }, "created_at": { "type": [ "string", "null" ], "format": "date-time" }, "updated_at": { "type": [ "string", "null" ], "format": "date-time" } } }, "PurchaseOrder": { "type": "object", "additionalProperties": false, "required": [ "id", "company_id", "object" ], "properties": { "object": { "type": "string", "const": "purchase_order" }, "id": { "type": "string", "format": "uuid" }, "company_id": { "type": "string", "format": "uuid" }, "po_number": { "type": [ "string", "null" ] }, "supplier_id": { "type": [ "string", "null" ], "format": "uuid" }, "supplier_name": { "type": [ "string", "null" ] }, "supplier": { "anyOf": [ { "$ref": "#/components/schemas/PurchaseOrderSupplier" }, { "type": "null" } ] }, "order_date": { "type": [ "string", "null" ], "format": "date" }, "expected_delivery_date": { "type": [ "string", "null" ], "format": "date" }, "currency": { "type": [ "string", "null" ] }, "subtotal": { "type": [ "number", "null" ] }, "vat_amount": { "type": [ "number", "null" ] }, "total_amount": { "type": [ "number", "null" ] }, "status": { "type": [ "string", "null" ] }, "project_id": { "type": [ "string", "null" ], "format": "uuid" }, "project": { "anyOf": [ { "$ref": "#/components/schemas/PurchaseOrderProjectSummary" }, { "type": "null" } ] }, "department": { "type": [ "string", "null" ] }, "budget_code": { "type": [ "string", "null" ] }, "cost_center": { "type": [ "string", "null" ] }, "chart_of_accounts_id": { "type": [ "string", "null" ], "format": "uuid" }, "chart_of_account": { "anyOf": [ { "$ref": "#/components/schemas/PurchaseOrderChartOfAccountSummary" }, { "type": "null" } ] }, "delivery_address": { "type": [ "string", "null" ] }, "payment_terms": { "type": [ "string", "null" ] }, "notes": { "type": [ "string", "null" ] }, "created_by": { "type": [ "string", "null" ], "format": "uuid" }, "approved_by": { "type": [ "string", "null" ], "format": "uuid" }, "approved_at": { "type": [ "string", "null" ], "format": "date-time" }, "created_at": { "type": [ "string", "null" ], "format": "date-time" }, "updated_at": { "type": [ "string", "null" ], "format": "date-time" }, "line_items": { "type": "array", "items": { "$ref": "#/components/schemas/PurchaseOrderLineItem" } } } }, "V1BusinessPurchaseOrderListMeta": { "type": "object", "required": [ "api_version", "mode", "pagination", "request_id", "resource" ], "properties": { "api_version": { "type": "string", "const": "v1-2026-07" }, "mode": { "type": "string", "const": "list" }, "pagination": { "$ref": "#/components/schemas/V1PaginationMeta" }, "request_id": { "type": "string", "minLength": 1, "maxLength": 128 }, "resource": { "type": "string", "const": "purchase_order" } } }, "V1BusinessPurchaseOrderMeta": { "type": "object", "required": [ "api_version", "mode", "request_id", "resource" ], "properties": { "api_version": { "type": "string", "const": "v1-2026-07" }, "mode": { "type": "string", "const": "detail" }, "request_id": { "type": "string", "minLength": 1, "maxLength": 128 }, "resource": { "type": "string", "const": "purchase_order" } } }, "V1BusinessPurchaseOrderListResponse": { "type": "object", "required": [ "data", "meta" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/PurchaseOrder" } }, "meta": { "$ref": "#/components/schemas/V1BusinessPurchaseOrderListMeta" } } }, "V1BusinessPurchaseOrderResponse": { "type": "object", "required": [ "data", "meta" ], "properties": { "data": { "$ref": "#/components/schemas/PurchaseOrder" }, "meta": { "$ref": "#/components/schemas/V1BusinessPurchaseOrderMeta" } } }, "ExpenseClaimant": { "type": "object", "additionalProperties": false, "required": [ "id", "company_id", "object" ], "properties": { "object": { "type": "string", "const": "expense_claimant" }, "id": { "type": "string", "format": "uuid" }, "company_id": { "type": "string", "format": "uuid" }, "email": { "type": [ "string", "null" ] }, "name": { "type": [ "string", "null" ] }, "phone": { "type": [ "string", "null" ] }, "is_active": { "type": [ "boolean", "null" ] }, "created_at": { "type": [ "string", "null" ], "format": "date-time" }, "updated_at": { "type": [ "string", "null" ], "format": "date-time" } } }, "V1BusinessExpenseClaimantListMeta": { "type": "object", "required": [ "api_version", "mode", "pagination", "request_id", "resource" ], "properties": { "api_version": { "type": "string", "const": "v1-2026-07" }, "mode": { "type": "string", "const": "list" }, "pagination": { "$ref": "#/components/schemas/V1PaginationMeta" }, "request_id": { "type": "string", "minLength": 1, "maxLength": 128 }, "resource": { "type": "string", "const": "expense_claimant" } } }, "V1BusinessExpenseClaimantMeta": { "type": "object", "required": [ "api_version", "mode", "request_id", "resource" ], "properties": { "api_version": { "type": "string", "const": "v1-2026-07" }, "mode": { "type": "string", "const": "detail" }, "request_id": { "type": "string", "minLength": 1, "maxLength": 128 }, "resource": { "type": "string", "const": "expense_claimant" } } }, "V1BusinessExpenseClaimantListResponse": { "type": "object", "required": [ "data", "meta" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/ExpenseClaimant" } }, "meta": { "$ref": "#/components/schemas/V1BusinessExpenseClaimantListMeta" } } }, "V1BusinessExpenseClaimantResponse": { "type": "object", "required": [ "data", "meta" ], "properties": { "data": { "$ref": "#/components/schemas/ExpenseClaimant" }, "meta": { "$ref": "#/components/schemas/V1BusinessExpenseClaimantMeta" } } }, "BusinessTransaction": { "type": "object", "additionalProperties": false, "required": [ "id", "company_id", "object" ], "properties": { "object": { "type": "string", "const": "business_transaction" }, "id": { "type": "string", "format": "uuid" }, "company_id": { "type": [ "string", "null" ], "format": "uuid" }, "bank_account_id": { "type": [ "string", "null" ], "format": "uuid" }, "transaction_date": { "type": [ "string", "null" ], "format": "date" }, "description": { "type": [ "string", "null" ] }, "merchant_name": { "type": [ "string", "null" ] }, "reference": { "type": [ "string", "null" ] }, "transaction_type": { "type": [ "string", "null" ] }, "transaction_nature": { "type": [ "string", "null" ] }, "direction": { "type": [ "string", "null" ] }, "gross_amount": { "type": [ "number", "null" ] }, "net_amount": { "type": [ "number", "null" ] }, "vat_amount": { "type": [ "number", "null" ] }, "vat_rate": { "type": [ "number", "null" ] }, "currency": { "type": [ "string", "null" ] }, "original_amount": { "type": [ "number", "null" ] }, "original_currency": { "type": [ "string", "null" ] }, "exchange_rate": { "type": [ "number", "null" ] }, "gbp_amount": { "type": [ "number", "null" ] }, "balance_after": { "type": [ "number", "null" ] }, "chart_of_accounts_id": { "type": [ "string", "null" ], "format": "uuid" }, "customer_id": { "type": [ "string", "null" ], "format": "uuid" }, "supplier_id": { "type": [ "string", "null" ], "format": "uuid" }, "document_id": { "type": [ "string", "null" ], "format": "uuid" }, "project_id": { "type": [ "string", "null" ], "format": "uuid" }, "fund_id": { "type": [ "string", "null" ], "format": "uuid" }, "categorisation_status": { "type": [ "string", "null" ] }, "categorisation_source": { "type": [ "string", "null" ] }, "category_uncertain": { "type": "boolean" }, "receipt_attached": { "type": "boolean" }, "receipt_required": { "type": "boolean" }, "reconciliation_status": { "type": [ "string", "null" ] }, "reconciliation_method": { "type": [ "string", "null" ] }, "is_matched": { "type": "boolean" }, "posting_status": { "type": [ "string", "null" ] }, "lifecycle_status": { "type": [ "string", "null" ] }, "posted_at": { "type": [ "string", "null" ], "format": "date-time" }, "posted_date": { "type": [ "string", "null" ], "format": "date" }, "posted_journal_id": { "type": [ "string", "null" ], "format": "uuid" }, "wallet_name": { "type": [ "string", "null" ] }, "created_at": { "type": [ "string", "null" ], "format": "date-time" }, "updated_at": { "type": [ "string", "null" ], "format": "date-time" } } }, "V1BusinessTransactionListMeta": { "type": "object", "required": [ "api_version", "mode", "pagination", "request_id", "resource" ], "properties": { "api_version": { "type": "string", "const": "v1-2026-07" }, "mode": { "type": "string", "const": "list" }, "pagination": { "$ref": "#/components/schemas/V1PaginationMeta" }, "request_id": { "type": "string", "minLength": 1, "maxLength": 128 }, "resource": { "type": "string", "const": "business_transaction" } } }, "V1BusinessTransactionMeta": { "type": "object", "required": [ "api_version", "mode", "request_id", "resource" ], "properties": { "api_version": { "type": "string", "const": "v1-2026-07" }, "mode": { "type": "string", "const": "detail" }, "request_id": { "type": "string", "minLength": 1, "maxLength": 128 }, "resource": { "type": "string", "const": "business_transaction" } } }, "V1BusinessTransactionListResponse": { "type": "object", "required": [ "data", "meta" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/BusinessTransaction" } }, "meta": { "$ref": "#/components/schemas/V1BusinessTransactionListMeta" } } }, "V1BusinessTransactionResponse": { "type": "object", "required": [ "data", "meta" ], "properties": { "data": { "$ref": "#/components/schemas/BusinessTransaction" }, "meta": { "$ref": "#/components/schemas/V1BusinessTransactionMeta" } } }, "BusinessBankAccount": { "type": "object", "additionalProperties": false, "required": [ "id", "company_id", "account_name", "object" ], "properties": { "object": { "type": "string", "const": "business_bank_account" }, "id": { "type": "string", "format": "uuid" }, "company_id": { "type": [ "string", "null" ], "format": "uuid" }, "chart_of_accounts_id": { "type": [ "string", "null" ], "format": "uuid" }, "account_name": { "type": [ "string", "null" ] }, "bank_name": { "type": [ "string", "null" ] }, "account_type": { "type": [ "string", "null" ] }, "account_category": { "type": [ "string", "null" ] }, "currency": { "type": [ "string", "null" ] }, "current_balance": { "type": [ "number", "null" ] }, "available_balance": { "type": [ "number", "null" ] }, "actual_balance": { "type": [ "number", "null" ] }, "book_balance": { "type": [ "number", "null" ] }, "is_active": { "type": "boolean" }, "connection_status": { "type": [ "string", "null" ] }, "feed_status": { "type": [ "string", "null" ] }, "reconciliation_status": { "type": [ "string", "null" ] }, "reconciliation_difference": { "type": [ "number", "null" ] }, "last_sync_at": { "type": [ "string", "null" ], "format": "date-time" }, "last_reconciled_at": { "type": [ "string", "null" ], "format": "date-time" }, "first_connected_at": { "type": [ "string", "null" ], "format": "date-time" }, "display_order": { "type": [ "number", "null" ] }, "provider_name": { "type": [ "string", "null" ] }, "logo_url": { "type": [ "string", "null" ] }, "created_at": { "type": [ "string", "null" ], "format": "date-time" }, "updated_at": { "type": [ "string", "null" ], "format": "date-time" } } }, "V1BusinessBankAccountListResponse": { "type": "object", "required": [ "data", "meta" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/BusinessBankAccount" } }, "meta": { "$ref": "#/components/schemas/V1BusinessBankAccountListMeta" } } }, "V1BusinessBankAccountResponse": { "type": "object", "required": [ "data", "meta" ], "properties": { "data": { "$ref": "#/components/schemas/BusinessBankAccount" }, "meta": { "$ref": "#/components/schemas/V1BusinessBankAccountMeta" } } }, "BusinessBankStatementLine": { "type": "object", "additionalProperties": false, "required": [ "id", "company_id", "bank_account_id", "line_date", "amount", "object" ], "properties": { "object": { "type": "string", "const": "business_bank_statement_line" }, "id": { "type": "string", "format": "uuid" }, "company_id": { "type": "string", "format": "uuid" }, "bank_account_id": { "type": "string", "format": "uuid" }, "statement_upload_id": { "type": [ "string", "null" ], "format": "uuid" }, "line_date": { "type": "string", "format": "date" }, "description": { "type": [ "string", "null" ] }, "amount": { "type": "number" }, "running_balance": { "type": [ "number", "null" ] }, "matched_bank_transaction_id": { "type": [ "string", "null" ], "format": "uuid" }, "is_matched": { "type": "boolean" }, "created_at": { "type": [ "string", "null" ], "format": "date-time" } } }, "V1BusinessBankStatementLineListMeta": { "type": "object", "required": [ "api_version", "mode", "pagination", "request_id", "resource" ], "properties": { "api_version": { "type": "string", "const": "v1-2026-07" }, "mode": { "type": "string", "const": "list" }, "pagination": { "$ref": "#/components/schemas/V1PaginationMeta" }, "request_id": { "type": "string", "minLength": 1, "maxLength": 128 }, "resource": { "type": "string", "const": "business_bank_statement_line" } } }, "V1BusinessBankStatementLineMeta": { "type": "object", "required": [ "api_version", "mode", "request_id", "resource" ], "properties": { "api_version": { "type": "string", "const": "v1-2026-07" }, "mode": { "type": "string", "const": "detail" }, "request_id": { "type": "string", "minLength": 1, "maxLength": 128 }, "resource": { "type": "string", "const": "business_bank_statement_line" } } }, "V1BusinessBankStatementLineListResponse": { "type": "object", "required": [ "data", "meta" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/BusinessBankStatementLine" } }, "meta": { "$ref": "#/components/schemas/V1BusinessBankStatementLineListMeta" } } }, "V1BusinessBankStatementLineResponse": { "type": "object", "required": [ "data", "meta" ], "properties": { "data": { "$ref": "#/components/schemas/BusinessBankStatementLine" }, "meta": { "$ref": "#/components/schemas/V1BusinessBankStatementLineMeta" } } }, "BusinessBankReconciliation": { "type": "object", "additionalProperties": false, "required": [ "id", "company_id", "bank_account_id", "period_end", "status", "object" ], "properties": { "object": { "type": "string", "const": "business_bank_reconciliation" }, "id": { "type": "string", "format": "uuid" }, "company_id": { "type": "string", "format": "uuid" }, "bank_account_id": { "type": "string", "format": "uuid" }, "period_end": { "type": "string", "format": "date" }, "status": { "type": "string", "enum": [ "unreconciled", "reconciled" ] }, "matched_count": { "type": [ "number", "null" ] }, "exception_count": { "type": [ "number", "null" ] }, "reconciled_by_user_id": { "type": [ "string", "null" ], "format": "uuid" }, "reconciled_at": { "type": [ "string", "null" ], "format": "date-time" }, "created_at": { "type": [ "string", "null" ], "format": "date-time" }, "updated_at": { "type": [ "string", "null" ], "format": "date-time" } } }, "V1BusinessBankReconciliationListMeta": { "type": "object", "required": [ "api_version", "mode", "pagination", "request_id", "resource" ], "properties": { "api_version": { "type": "string", "const": "v1-2026-07" }, "mode": { "type": "string", "const": "list" }, "pagination": { "$ref": "#/components/schemas/V1PaginationMeta" }, "request_id": { "type": "string", "minLength": 1, "maxLength": 128 }, "resource": { "type": "string", "const": "business_bank_reconciliation" } } }, "V1BusinessBankReconciliationMeta": { "type": "object", "required": [ "api_version", "mode", "request_id", "resource" ], "properties": { "api_version": { "type": "string", "const": "v1-2026-07" }, "mode": { "type": "string", "const": "detail" }, "request_id": { "type": "string", "minLength": 1, "maxLength": 128 }, "resource": { "type": "string", "const": "business_bank_reconciliation" } } }, "V1BusinessBankReconciliationListResponse": { "type": "object", "required": [ "data", "meta" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/BusinessBankReconciliation" } }, "meta": { "$ref": "#/components/schemas/V1BusinessBankReconciliationListMeta" } } }, "V1BusinessBankReconciliationResponse": { "type": "object", "required": [ "data", "meta" ], "properties": { "data": { "$ref": "#/components/schemas/BusinessBankReconciliation" }, "meta": { "$ref": "#/components/schemas/V1BusinessBankReconciliationMeta" } } }, "V1BusinessBankAccountListMeta": { "type": "object", "required": [ "api_version", "mode", "pagination", "request_id", "resource" ], "properties": { "api_version": { "type": "string", "const": "v1-2026-07" }, "mode": { "type": "string", "const": "list" }, "pagination": { "$ref": "#/components/schemas/V1PaginationMeta" }, "request_id": { "type": "string", "minLength": 1, "maxLength": 128 }, "resource": { "type": "string", "const": "business_bank_account" } } }, "V1BusinessBankAccountMeta": { "type": "object", "required": [ "api_version", "mode", "request_id", "resource" ], "properties": { "api_version": { "type": "string", "const": "v1-2026-07" }, "mode": { "type": "string", "const": "detail" }, "request_id": { "type": "string", "minLength": 1, "maxLength": 128 }, "resource": { "type": "string", "const": "business_bank_account" } } }, "BusinessChartOfAccount": { "type": "object", "additionalProperties": false, "required": [ "id", "company_id", "code", "name", "object" ], "properties": { "object": { "type": "string", "const": "business_chart_of_account" }, "id": { "type": "string", "format": "uuid" }, "company_id": { "type": [ "string", "null" ], "format": "uuid" }, "code": { "type": [ "string", "null" ] }, "name": { "type": [ "string", "null" ] }, "account_type": { "type": [ "string", "null" ] }, "description": { "type": [ "string", "null" ] }, "financial_statement": { "type": [ "string", "null" ] }, "area": { "type": [ "string", "null" ] }, "ma_category": { "type": [ "string", "null" ] }, "ma_sub_category": { "type": [ "string", "null" ] }, "parent_code": { "type": [ "string", "null" ] }, "standard_category_code": { "type": [ "string", "null" ] }, "tax_treatment": { "type": [ "string", "null" ] }, "statutory_category": { "type": [ "string", "null" ] }, "statutory_subcategory": { "type": [ "string", "null" ] }, "balance": { "type": [ "number", "null" ] }, "is_active": { "type": "boolean" }, "is_system_account": { "type": "boolean" }, "is_deletable": { "type": "boolean" }, "archived_at": { "type": [ "string", "null" ], "format": "date-time" }, "created_at": { "type": [ "string", "null" ], "format": "date-time" }, "updated_at": { "type": [ "string", "null" ], "format": "date-time" } } }, "V1BusinessChartOfAccountListResponse": { "type": "object", "required": [ "data", "meta" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/BusinessChartOfAccount" } }, "meta": { "$ref": "#/components/schemas/V1BusinessChartOfAccountListMeta" } } }, "V1BusinessChartOfAccountResponse": { "type": "object", "required": [ "data", "meta" ], "properties": { "data": { "$ref": "#/components/schemas/BusinessChartOfAccount" }, "meta": { "$ref": "#/components/schemas/V1BusinessChartOfAccountMeta" } } }, "V1BusinessChartOfAccountListMeta": { "type": "object", "required": [ "api_version", "mode", "pagination", "request_id", "resource" ], "properties": { "api_version": { "type": "string", "const": "v1-2026-07" }, "mode": { "type": "string", "const": "list" }, "pagination": { "$ref": "#/components/schemas/V1PaginationMeta" }, "request_id": { "type": "string", "minLength": 1, "maxLength": 128 }, "resource": { "type": "string", "const": "business_chart_of_account" } } }, "V1BusinessChartOfAccountMeta": { "type": "object", "required": [ "api_version", "mode", "request_id", "resource" ], "properties": { "api_version": { "type": "string", "const": "v1-2026-07" }, "mode": { "type": "string", "const": "detail" }, "request_id": { "type": "string", "minLength": 1, "maxLength": 128 }, "resource": { "type": "string", "const": "business_chart_of_account" } } }, "BusinessProject": { "type": "object", "additionalProperties": false, "required": [ "object", "id", "company_id" ], "properties": { "object": { "type": "string", "const": "business_project" }, "id": { "type": "string", "format": "uuid" }, "company_id": { "type": "string", "format": "uuid" }, "code": { "type": [ "string", "null" ] }, "name": { "type": [ "string", "null" ] }, "description": { "type": [ "string", "null" ] }, "budget": { "type": [ "number", "null" ] }, "expected_income": { "type": [ "number", "null" ] }, "expected_costs": { "type": [ "number", "null" ] }, "start_date": { "type": [ "string", "null" ], "format": "date" }, "end_date": { "type": [ "string", "null" ], "format": "date" }, "is_active": { "type": "boolean" }, "created_at": { "type": [ "string", "null" ], "format": "date-time" } } }, "CashflowWindowRange": {"type": "object", "required": ["kind", "start", "end"], "properties": {"kind": {"type": "string", "enum": ["6w", "13w", "12m"]}, "start": {"type": "string", "format": "date"}, "end": {"type": "string", "format": "date"}}}, "CashflowLinePoint": {"type": "object", "required": ["date", "closing_central", "closing_on_time", "closing_slow", "booked_in", "booked_out", "planned_in", "planned_out", "detected_in", "detected_out", "estimated_in", "estimated_out"], "properties": {"date": {"type": "string", "format": "date"}, "closing_central": {"type": "number", "format": "double", "description": "The most likely closing balance for the day."}, "closing_on_time": {"type": "number", "format": "double", "description": "Closing balance if everyone pays on time."}, "closing_slow": {"type": ["number", "null"], "format": "double", "description": "Closing balance if the slow payers are slow again, the tenth percentile of the simulation. Null where the engine holds no distribution."}, "closing_fast": {"type": ["number", "null"], "format": "double", "description": "The ninetieth percentile of the simulation. Null where there is no band."}, "booked_in": {"type": "number", "format": "double", "description": "Pounds, to two decimal places."}, "booked_out": {"type": "number", "format": "double", "description": "Pounds, to two decimal places."}, "planned_in": {"type": "number", "format": "double", "description": "Pounds, to two decimal places."}, "planned_out": {"type": "number", "format": "double", "description": "Pounds, to two decimal places."}, "detected_in": {"type": "number", "format": "double", "description": "Pounds, to two decimal places."}, "detected_out": {"type": "number", "format": "double", "description": "Pounds, to two decimal places."}, "estimated_in": {"type": "number", "format": "double", "description": "Pounds, to two decimal places."}, "estimated_out": {"type": "number", "format": "double", "description": "Pounds, to two decimal places."}}}, "CashflowHistoryPoint": {"type": "object", "required": ["date", "balance"], "properties": {"date": {"type": "string", "format": "date"}, "balance": {"type": "number", "format": "double", "description": "Pounds, to two decimal places."}}}, "CashflowLowestPoint": {"type": "object", "required": ["date", "amount", "cause"], "properties": {"date": {"type": "string", "format": "date"}, "amount": {"type": "number", "format": "double", "description": "Pounds, to two decimal places."}, "cause": {"type": ["object", "null"], "required": ["label", "amount", "date"], "description": "The largest outflow in the five days up to the low point, if any.", "properties": {"label": {"type": "string"}, "amount": {"type": "number", "format": "double", "description": "Pounds, to two decimal places."}, "date": {"type": "string", "format": "date"}}}}}, "CashflowBufferBreach": {"type": "object", "required": ["start", "end", "shortfall"], "properties": {"start": {"type": "string", "format": "date"}, "end": {"type": "string", "format": "date"}, "shortfall": {"type": "number", "format": "double", "description": "Deepest shortfall below the buffer within the breach, as a positive number."}}}, "CashflowLine": {"type": "object", "required": ["scope", "scenario_id", "window", "currency", "opening_cash", "opening_cash_date", "opening_cash_source", "buffer", "generated_at", "stale", "has_band", "history", "points", "lowest", "buffer_breach"], "properties": {"scope": {"type": "object", "required": ["company_id"], "properties": {"company_id": {"type": "string", "format": "uuid"}}}, "scenario_id": {"type": "string", "format": "uuid"}, "window": {"$ref": "#/components/schemas/CashflowWindowRange"}, "currency": {"type": "string", "minLength": 3, "maxLength": 3}, "opening_cash": {"type": "number", "format": "double", "description": "Pounds, to two decimal places."}, "opening_cash_date": {"type": "string", "format": "date"}, "opening_cash_source": {"type": "string", "enum": ["reconciled_daily_balance", "bank_balances", "none"]}, "buffer": {"type": "number", "format": "double", "description": "The minimum cash buffer the company judges itself against."}, "generated_at": {"type": ["string", "null"], "format": "date-time"}, "stale": {"type": "boolean", "description": "True when the line is older than the engine's freshness threshold or has never been generated."}, "has_band": {"type": "boolean", "description": "True only when the slow case is populated for every point."}, "band_note": {"type": ["string", "null"], "description": "Why there is a band, or why there is not, in the owner's words."}, "band_runs": {"type": "integer", "description": "Number of simulated futures behind the band; 0 when there is none."}, "slow_lowest": {"type": ["object", "null"], "required": ["date", "amount"], "properties": {"date": {"type": "string", "format": "date"}, "amount": {"type": "number", "format": "double", "description": "Pounds, to two decimal places."}}}, "history": {"type": "array", "items": {"$ref": "#/components/schemas/CashflowHistoryPoint"}}, "points": {"type": "array", "items": {"$ref": "#/components/schemas/CashflowLinePoint"}}, "lowest": {"oneOf": [{"$ref": "#/components/schemas/CashflowLowestPoint"}, {"type": "null"}]}, "buffer_breach": {"oneOf": [{"$ref": "#/components/schemas/CashflowBufferBreach"}, {"type": "null"}]}}}, "CashflowMoverAction": {"type": "object", "required": ["kind", "target_id"], "properties": {"kind": {"type": "string", "enum": ["chase_invoice", "move_bill", "review_commitment", "edit_manual_event", "view_vat", "view_corporation_tax", "view_payroll", "raise_invoice", "view_payment_plan", "convert_plan", "view_budget"]}, "target_id": {"type": "string"}}}, "CashflowMover": {"type": "object", "required": ["event_id", "date", "label", "detail", "amount", "direction", "provenance", "timing_basis", "basis_text", "source_type", "source_id", "action"], "properties": {"event_id": {"type": "string", "format": "uuid"}, "date": {"type": "string", "format": "date"}, "label": {"type": "string", "description": "Short name for the chart and the list."}, "detail": {"type": "string", "description": "Longer identification, such as the customer and the document number."}, "amount": {"type": "number", "format": "double", "description": "Pounds, to two decimal places."}, "direction": {"type": "string", "enum": ["inflow", "outflow"]}, "provenance": {"type": "string", "enum": ["booked", "planned", "detected", "estimated"], "description": "What kind of thing this is: a document or obligation in the ledger, something a person said, something the machine found in history, or a statistical residual."}, "timing_basis": {"type": "string", "enum": ["fixed", "expected_date", "counterparty_memory", "due_date_prior", "cadence", "distribution"], "description": "Why this date."}, "basis_text": {"type": "string", "description": "Plain-words basis for the date."}, "source_type": {"type": "string", "enum": ["sales_invoice", "purchase_invoice", "creditor_schedule_line", "recurring_commitment", "manual", "residual", "vat_obligation", "ct_obligation", "paye_obligation", "payroll_run", "recurring_invoice_template", "promise_to_pay", "projected_invoice", "budget_bucket"]}, "source_id": {"type": ["string", "null"]}, "action": {"oneOf": [{"$ref": "#/components/schemas/CashflowMoverAction"}, {"type": "null"}]}}}, "CashflowEvent": {"type": "object", "required": ["id", "scenario_id", "direction", "amount", "currency", "event_date", "provenance", "timing_basis", "source_type", "label", "detail", "is_active", "generated_at", "metadata"], "properties": {"id": {"type": "string", "format": "uuid"}, "scenario_id": {"type": "string", "format": "uuid"}, "direction": {"type": "string", "enum": ["inflow", "outflow"]}, "amount": {"type": "number", "format": "double", "description": "Pounds, to two decimal places."}, "amount_low": {"type": ["number", "null"], "format": "double"}, "amount_high": {"type": ["number", "null"], "format": "double"}, "currency": {"type": "string", "minLength": 3, "maxLength": 3}, "event_date": {"type": "string", "format": "date"}, "window_start": {"type": ["string", "null"], "format": "date"}, "window_end": {"type": ["string", "null"], "format": "date"}, "provenance": {"type": "string", "enum": ["booked", "planned", "detected", "estimated"], "description": "What kind of thing this is: a document or obligation in the ledger, something a person said, something the machine found in history, or a statistical residual."}, "timing_basis": {"type": "string", "enum": ["fixed", "expected_date", "counterparty_memory", "due_date_prior", "cadence", "distribution"], "description": "Why this date."}, "source_type": {"type": "string", "enum": ["sales_invoice", "purchase_invoice", "creditor_schedule_line", "recurring_commitment", "manual", "residual", "vat_obligation", "ct_obligation", "paye_obligation", "payroll_run", "recurring_invoice_template", "promise_to_pay", "projected_invoice", "budget_bucket"]}, "source_id": {"type": ["string", "null"]}, "label": {"type": "string"}, "detail": {"type": "string"}, "counterparty_id": {"type": ["string", "null"], "format": "uuid"}, "consumed_by_type": {"type": ["string", "null"], "description": "Set when a later fact has consumed this expectation."}, "consumed_by_id": {"type": ["string", "null"]}, "is_active": {"type": "boolean"}, "generated_at": {"type": "string", "format": "date-time"}, "metadata": {"type": "object", "additionalProperties": true}}}, "CashflowLayerScore": {"type": "object", "required": ["layer", "abs_error", "bias"], "properties": {"layer": {"type": "string", "enum": ["booked", "planned", "detected", "estimated"], "description": "What kind of thing this is: a document or obligation in the ledger, something a person said, something the machine found in history, or a statistical residual."}, "abs_error": {"type": "number", "format": "double", "description": "Pounds, to two decimal places."}, "bias": {"type": "number", "format": "double", "description": "Pounds, to two decimal places."}, "value_added": {"type": ["number", "null"], "format": "double", "description": "Pounds of error this layer removed over the horizon. Negative means it made the line worse."}}}, "CashflowScoreDriver": {"type": "object", "required": ["kind", "label", "impact", "sentence"], "properties": {"kind": {"type": "string", "enum": ["paid_late", "paid_early", "paid_less", "paid_more", "not_paid", "everyday_spending", "budget_line", "other"]}, "label": {"type": "string"}, "impact": {"type": "number", "format": "double", "description": "Pounds of error this driver accounts for, always positive."}, "sentence": {"type": "string"}}}, "CashflowResidualModel": {"type": "object", "required": ["direction", "category", "model", "history_months", "backtest_error", "improvement_pct", "reason", "selected_at"], "properties": {"direction": {"type": "string", "enum": ["inflow", "outflow"]}, "category": {"type": ["string", "null"], "description": "Coarse ledger category, or null for the whole direction."}, "model": {"type": "string", "enum": ["weekday_mean", "seasonal_naive", "seasonal_ratio", "holt_winters"]}, "history_months": {"type": "integer"}, "backtest_error": {"type": ["number", "null"], "format": "double", "description": "Mean absolute error over the rolling backtest, in pounds per 28 days."}, "improvement_pct": {"type": ["number", "null"], "description": "Percentage improvement over the weekday mean; 0 when the weekday mean was kept."}, "reason": {"type": "string"}, "selected_at": {"type": "string", "format": "date-time"}}}, "CashflowCalibration": {"type": "object", "required": ["customers_adjusted", "suppliers_adjusted", "buckets_adjusted", "residual_scale", "residual_note", "calibrated_at"], "properties": {"customers_adjusted": {"type": "integer"}, "suppliers_adjusted": {"type": "integer"}, "buckets_adjusted": {"type": "integer"}, "residual_scale": {"type": "number", "description": "Multiplier applied to the everyday residual; 1 means unchanged, 0 means switched off."}, "residual_note": {"type": ["string", "null"]}, "calibrated_at": {"type": ["string", "null"], "format": "date-time"}, "residual_models": {"type": "array", "items": {"$ref": "#/components/schemas/CashflowResidualModel"}}}}, "CashflowScores": {"type": "object", "required": ["horizon_days", "scored_days", "abs_error", "abs_error_pct", "bias", "band_hit_rate", "sentence", "by_layer"], "properties": {"horizon_days": {"type": "integer"}, "scored_days": {"type": "integer"}, "abs_error": {"type": ["number", "null"], "format": "double"}, "abs_error_pct": {"type": ["number", "null"]}, "bias": {"type": ["number", "null"], "format": "double"}, "band_hit_rate": {"type": ["number", "null"], "description": "Share of days where the actual balance fell inside the band."}, "sentence": {"type": ["string", "null"], "description": "Null until at least four scored weeks exist."}, "by_layer": {"type": "array", "items": {"$ref": "#/components/schemas/CashflowLayerScore"}}, "drivers": {"type": "array", "maxItems": 3, "items": {"$ref": "#/components/schemas/CashflowScoreDriver"}}, "metrics": {"type": ["object", "null"], "properties": {"metric_date": {"type": "string", "format": "date"}, "wape_28d": {"type": ["number", "null"]}, "band_coverage_28d": {"type": ["number", "null"]}, "scored_days_28d": {"type": "integer"}}}, "calibration": {"oneOf": [{"$ref": "#/components/schemas/CashflowCalibration"}, {"type": "null"}]}}}, "CashflowPlanOccurrence": {"type": "object", "required": ["id", "plan_id", "slot", "expected_issue_date", "expected_cash_date", "amount", "status", "linked_invoice_id", "linked_invoice_number", "issued_amount", "settled_on", "updated_at"], "properties": {"id": {"type": "string", "format": "uuid"}, "plan_id": {"type": "string", "format": "uuid"}, "slot": {"type": "integer"}, "expected_issue_date": {"type": "string", "format": "date"}, "expected_cash_date": {"type": ["string", "null"], "format": "date", "description": "The cash date used on the line. Null until the engine has projected it."}, "amount": {"type": "number", "format": "double", "description": "Pounds, to two decimal places."}, "status": {"type": "string", "enum": ["projected", "issued", "settled", "cancelled", "lapsed"]}, "linked_invoice_id": {"type": ["string", "null"], "format": "uuid"}, "linked_invoice_number": {"type": ["string", "null"]}, "issued_amount": {"type": ["number", "null"], "format": "double"}, "settled_on": {"type": ["string", "null"], "format": "date"}, "updated_at": {"type": "string", "format": "date-time"}}}, "CashflowPlan": {"type": "object", "required": ["id", "customer_id", "customer_name", "label", "expected_issue_date", "amount", "vat_treatment", "expected_payment_date", "cadence", "cadence_end_date", "status", "origin", "revision", "created_at", "updated_at", "occurrences"], "properties": {"id": {"type": "string", "format": "uuid"}, "customer_id": {"type": ["string", "null"], "format": "uuid"}, "customer_name": {"type": ["string", "null"]}, "label": {"type": "string"}, "expected_issue_date": {"type": "string", "format": "date"}, "amount": {"type": "number", "format": "double", "description": "Pounds, to two decimal places."}, "amount_low": {"type": ["number", "null"], "format": "double"}, "amount_high": {"type": ["number", "null"], "format": "double"}, "vat_treatment": {"type": "string", "enum": ["standard", "reduced", "zero", "exempt", "none"]}, "expected_payment_date": {"type": ["string", "null"], "format": "date"}, "cadence": {"type": ["string", "null"], "enum": ["weekly", "monthly", "quarterly", "annual", null]}, "cadence_end_date": {"type": ["string", "null"], "format": "date"}, "budget_category_id": {"type": ["string", "null"], "format": "uuid"}, "budget_category_name": {"type": ["string", "null"]}, "status": {"type": "string", "enum": ["active", "cancelled"]}, "origin": {"type": "string", "enum": ["manual", "seeded"]}, "notes": {"type": ["string", "null"]}, "revision": {"type": "integer", "description": "Optimistic concurrency token. Send it back when amending or cancelling."}, "created_at": {"type": "string", "format": "date-time"}, "updated_at": {"type": "string", "format": "date-time"}, "occurrences": {"type": "array", "items": {"$ref": "#/components/schemas/CashflowPlanOccurrence"}}}}, "CashflowPlanList": {"type": "object", "required": ["generated_at", "plans", "lapsed", "totals"], "properties": {"generated_at": {"type": ["string", "null"], "format": "date-time"}, "plans": {"type": "array", "items": {"$ref": "#/components/schemas/CashflowPlan"}}, "lapsed": {"type": "array", "items": {"$ref": "#/components/schemas/CashflowPlanOccurrence"}, "description": "Occurrences whose issue date has passed with nothing raised."}, "totals": {"type": "object", "required": ["projected_next_12m", "issued_this_year", "planned_this_year"], "properties": {"projected_next_12m": {"type": "number", "format": "double", "description": "Pounds, to two decimal places."}, "issued_this_year": {"type": "number", "format": "double", "description": "Pounds, to two decimal places."}, "planned_this_year": {"type": "number", "format": "double", "description": "Pounds, to two decimal places."}}}}}, "CashflowScenarioSwitches": {"type": "object", "additionalProperties": false, "description": "The switches a scenario applies to the primary line's events. All optional; absent means unchanged.", "properties": {"revenue_adjustment_percent": {"type": "number"}, "cost_adjustment_percent": {"type": "number"}, "inflow_delay_days": {"type": "integer"}, "outflow_delay_days": {"type": "integer"}, "one_off_cash_impact": {"type": "number", "description": "Positive is money in, negative is money out."}, "one_off_cash_date": {"type": "string", "format": "date"}, "starting_cash_adjustment": {"type": "number"}, "excluded_events": {"type": "array", "items": {"type": "string"}}, "notes": {"type": "string"}, "hire_monthly_amount": {"type": "number", "description": "A new hire: this monthly cost, money out, from hire_start."}, "hire_start": {"type": "string", "format": "date"}, "lost_customer_id": {"type": "string", "format": "uuid", "description": "A customer lost from lost_from: their repeating and projected invoices stop."}, "lost_from": {"type": "string", "format": "date", "description": "Defaults to the day the scenario is saved."}, "lost_customer_includes_owed": {"type": "boolean", "description": "True: their unpaid invoices are lost too. Defaults to false."}, "dropped_promise_invoice_ids": {"type": "array", "items": {"type": "string", "format": "uuid"}, "description": "Invoices whose promised payment date is set aside; they fall back to the usual lateness estimate."}, "dividend_amount": {"type": "number", "description": "A dividend, money out, on dividend_date."}, "dividend_date": {"type": "string", "format": "date"}}}, "CashflowScenario": {"type": "object", "required": ["id", "name", "is_primary", "status", "switches", "created_at", "updated_at"], "properties": {"id": {"type": "string", "format": "uuid"}, "name": {"type": "string"}, "is_primary": {"type": "boolean"}, "status": {"type": "string", "enum": ["draft", "active", "archived"]}, "switches": {"$ref": "#/components/schemas/CashflowScenarioSwitches"}, "created_at": {"type": "string", "format": "date-time"}, "updated_at": {"type": "string", "format": "date-time"}}}, "CashflowScenarioComparison": {"type": "object", "required": ["scenario", "lowest_central", "end_central", "days_below_buffer", "first_breach_date", "delta_vs_primary", "generated_at"], "properties": {"scenario": {"$ref": "#/components/schemas/CashflowScenario"}, "lowest_central": {"type": ["object", "null"], "required": ["date", "amount"], "properties": {"date": {"type": "string", "format": "date"}, "amount": {"type": "number", "format": "double", "description": "Pounds, to two decimal places."}}}, "end_central": {"type": ["number", "null"], "format": "double"}, "days_below_buffer": {"type": "integer"}, "first_breach_date": {"type": ["string", "null"], "format": "date"}, "delta_vs_primary": {"type": ["object", "null"], "required": ["lowest", "end", "days_below_buffer"], "description": "Differences from the primary scenario; null on the primary row.", "properties": {"lowest": {"type": ["number", "null"], "format": "double"}, "end": {"type": ["number", "null"], "format": "double"}, "days_below_buffer": {"type": "integer"}}}, "generated_at": {"type": ["string", "null"], "format": "date-time"}}}, "CashflowHeadroom": {"type": "object", "required": ["amount", "date", "window", "buffer", "lowest_after", "slow_lowest_after", "stays_above_buffer", "slow_stays_above_buffer", "max_at_buffer", "drivers", "sentence", "generated_at"], "properties": {"amount": {"type": "number", "format": "double", "description": "Pounds, to two decimal places."}, "date": {"type": "string", "format": "date"}, "window": {"$ref": "#/components/schemas/CashflowWindowRange"}, "buffer": {"type": "number", "format": "double", "description": "Pounds, to two decimal places."}, "lowest_after": {"type": "object", "required": ["date", "amount"], "properties": {"date": {"type": "string", "format": "date"}, "amount": {"type": "number", "format": "double", "description": "Pounds, to two decimal places."}}, "description": "Lowest point of the most likely line after the withdrawal."}, "slow_lowest_after": {"type": ["object", "null"], "required": ["date", "amount"], "properties": {"date": {"type": "string", "format": "date"}, "amount": {"type": "number", "format": "double", "description": "Pounds, to two decimal places."}}, "description": "Lowest point of the slow case after the withdrawal; null when there is no band."}, "stays_above_buffer": {"type": "boolean"}, "slow_stays_above_buffer": {"type": ["boolean", "null"]}, "max_at_buffer": {"type": "number", "format": "double", "description": "The largest amount that could leave on that date and keep the most likely line at or above the buffer; 0 when none."}, "drivers": {"type": "array", "maxItems": 3, "items": {"type": "object", "required": ["label", "date", "amount", "direction", "provenance"], "properties": {"label": {"type": "string"}, "date": {"type": "string", "format": "date"}, "amount": {"type": "number", "format": "double", "description": "Pounds, to two decimal places."}, "direction": {"type": "string", "enum": ["inflow", "outflow"]}, "provenance": {"type": "string", "enum": ["booked", "planned", "detected", "estimated"], "description": "What kind of thing this is: a document or obligation in the ledger, something a person said, something the machine found in history, or a statistical residual."}}}}, "sentence": {"type": "string"}, "generated_at": {"type": ["string", "null"], "format": "date-time"}}}, "CashflowCounterpartyTiming": {"type": "object", "required": ["counterparty_type", "counterparty_id", "name", "observations", "applied_days", "basis", "median_days", "p25_days", "p75_days", "last_settled_on", "open_amount"], "properties": {"counterparty_type": {"type": "string", "enum": ["customer", "supplier"]}, "counterparty_id": {"type": "string", "format": "uuid"}, "name": {"type": "string"}, "observations": {"type": "integer"}, "applied_days": {"type": "integer", "description": "Days after the due date applied to this counterparty's open documents. Positive means late."}, "basis": {"type": "string", "enum": ["memory", "prior"]}, "median_days": {"type": ["integer", "null"]}, "p25_days": {"type": ["integer", "null"]}, "p75_days": {"type": ["integer", "null"]}, "last_settled_on": {"type": ["string", "null"], "format": "date"}, "open_amount": {"type": "number", "format": "double", "description": "Pounds, to two decimal places."}, "bias_days": {"type": "integer", "description": "Days added after this counterparty paid later or earlier than the line expected. 0 when no adjustment."}}}, "CashflowTimingSummary": {"type": "object", "required": ["generated_at", "default_lateness_days", "memory_threshold", "customers", "suppliers"], "properties": {"generated_at": {"type": ["string", "null"], "format": "date-time"}, "default_lateness_days": {"type": "integer"}, "memory_threshold": {"type": "integer", "description": "Observations needed before memory replaces the prior."}, "customers": {"type": "array", "items": {"$ref": "#/components/schemas/CashflowCounterpartyTiming"}}, "suppliers": {"type": "array", "items": {"$ref": "#/components/schemas/CashflowCounterpartyTiming"}}}}, "CashflowBucket": {"type": "object", "required": ["id", "budget_category_id", "category_name", "direction", "period_start", "period_end", "budget_amount", "actual_amount", "planned_amount", "remaining_amount", "expected_amount", "fade_profile", "refreshed_at"], "properties": {"id": {"type": "string", "format": "uuid"}, "budget_category_id": {"type": "string", "format": "uuid"}, "category_name": {"type": "string"}, "direction": {"type": "string", "enum": ["inflow", "outflow"]}, "period_start": {"type": "string", "format": "date"}, "period_end": {"type": "string", "format": "date"}, "budget_amount": {"type": "number", "format": "double", "description": "Pounds, to two decimal places."}, "actual_amount": {"type": "number", "format": "double", "description": "Pounds, to two decimal places."}, "planned_amount": {"type": "number", "format": "double", "description": "Specific plans inside this bucket for the period."}, "remaining_amount": {"type": "number", "format": "double", "description": "Budget less actual less planned, never below zero, before fading."}, "expected_amount": {"type": "number", "format": "double", "description": "What the line still expects after the fade for elapsed time."}, "fade_profile": {"type": "string", "enum": ["even", "invoicing_shape"]}, "refreshed_at": {"type": "string", "format": "date-time"}}}, "CashflowBucketList": {"type": "object", "required": ["generated_at", "has_budget", "fade_profile", "buckets"], "properties": {"generated_at": {"type": ["string", "null"], "format": "date-time"}, "has_budget": {"type": "boolean"}, "fade_profile": {"type": "string", "enum": ["even", "invoicing_shape"]}, "buckets": {"type": "array", "items": {"$ref": "#/components/schemas/CashflowBucket"}}}}, "V1BusinessCashflowPlanInput": {"type": "object", "additionalProperties": false, "required": ["label", "expected_issue_date", "amount"], "properties": {"id": {"type": "string", "format": "uuid", "description": "Supply with revision to amend an existing plan; omit to create one."}, "revision": {"type": "integer", "minimum": 0, "description": "Required when id is supplied. The revision the caller last saw."}, "customer_id": {"type": ["string", "null"], "format": "uuid"}, "label": {"type": "string", "minLength": 1, "maxLength": 200}, "expected_issue_date": {"type": "string", "format": "date"}, "amount": {"type": "number", "format": "double", "exclusiveMinimum": 0, "maximum": 999999999.99}, "amount_low": {"type": ["number", "null"], "format": "double"}, "amount_high": {"type": ["number", "null"], "format": "double"}, "vat_treatment": {"type": "string", "enum": ["standard", "reduced", "zero", "exempt", "none"]}, "expected_payment_date": {"type": ["string", "null"], "format": "date"}, "cadence": {"type": ["string", "null"], "enum": ["weekly", "monthly", "quarterly", "annual", null]}, "cadence_end_date": {"type": ["string", "null"], "format": "date"}, "budget_category_id": {"type": ["string", "null"], "format": "uuid"}, "notes": {"type": ["string", "null"], "maxLength": 2000}}}, "V1BusinessCashflowPlanCancelInput": {"type": "object", "additionalProperties": true, "required": ["revision"], "properties": {"revision": {"type": "integer", "minimum": 0, "description": "The plan revision the caller last saw. A stale revision is refused."}}}, "V1BusinessCashflowPlanOccurrenceDecisionInput": {"type": "object", "additionalProperties": true, "properties": {"expected_issue_date": {"type": "string", "format": "date", "description": "Required for the move action; ignored by drop, restore and detach."}}}, "V1BusinessCashflowHeadroomInput": {"type": "object", "additionalProperties": false, "required": ["amount"], "properties": {"amount": {"type": "number", "format": "double", "exclusiveMinimum": 0, "maximum": 999999999.99}, "date": {"type": "string", "format": "date", "description": "The day the money would leave. Defaults to today."}, "window": {"type": "string", "enum": ["6w", "13w", "12m"], "description": "Window to judge against. Defaults to 13w."}}}, "V1BusinessCashflowLineMeta": {"type": "object", "required": ["api_version", "forecast", "mode", "request_id", "resource"], "properties": {"api_version": {"type": "string", "const": "v1-2026-07"}, "forecast": {"type": "boolean", "const": true, "description": "Always true. Cashflow figures are a forecast with provenance, never an accounting record."}, "mode": {"type": "string"}, "request_id": {"type": "string", "minLength": 1, "maxLength": 128}, "resource": {"type": "string", "const": "cashflow_line"}, "limit": {"type": "integer"}, "scope": {"type": "string"}}}, "V1BusinessCashflowLineResponse": {"type": "object", "required": ["data", "meta"], "properties": {"data": {"$ref": "#/components/schemas/CashflowLine"}, "meta": {"$ref": "#/components/schemas/V1BusinessCashflowLineMeta"}}}, "V1BusinessCashflowMoverListMeta": {"type": "object", "required": ["api_version", "forecast", "mode", "request_id", "resource"], "properties": {"api_version": {"type": "string", "const": "v1-2026-07"}, "forecast": {"type": "boolean", "const": true, "description": "Always true. Cashflow figures are a forecast with provenance, never an accounting record."}, "mode": {"type": "string"}, "request_id": {"type": "string", "minLength": 1, "maxLength": 128}, "resource": {"type": "string", "const": "cashflow_mover"}, "limit": {"type": "integer"}, "scope": {"type": "string"}}}, "V1BusinessCashflowMoverListResponse": {"type": "object", "required": ["data", "meta"], "properties": {"data": {"type": "array", "items": {"$ref": "#/components/schemas/CashflowMover"}}, "meta": {"$ref": "#/components/schemas/V1BusinessCashflowMoverListMeta"}}}, "V1BusinessCashflowEventListMeta": {"type": "object", "required": ["api_version", "forecast", "mode", "request_id", "resource"], "properties": {"api_version": {"type": "string", "const": "v1-2026-07"}, "forecast": {"type": "boolean", "const": true, "description": "Always true. Cashflow figures are a forecast with provenance, never an accounting record."}, "mode": {"type": "string"}, "request_id": {"type": "string", "minLength": 1, "maxLength": 128}, "resource": {"type": "string", "const": "cashflow_event"}, "limit": {"type": "integer"}, "scope": {"type": "string"}}}, "V1BusinessCashflowEventListResponse": {"type": "object", "required": ["data", "meta"], "properties": {"data": {"type": "array", "items": {"$ref": "#/components/schemas/CashflowEvent"}}, "meta": {"$ref": "#/components/schemas/V1BusinessCashflowEventListMeta"}}}, "V1BusinessCashflowScoresMeta": {"type": "object", "required": ["api_version", "forecast", "mode", "request_id", "resource"], "properties": {"api_version": {"type": "string", "const": "v1-2026-07"}, "forecast": {"type": "boolean", "const": true, "description": "Always true. Cashflow figures are a forecast with provenance, never an accounting record."}, "mode": {"type": "string"}, "request_id": {"type": "string", "minLength": 1, "maxLength": 128}, "resource": {"type": "string", "const": "cashflow_scores"}, "limit": {"type": "integer"}, "scope": {"type": "string"}}}, "V1BusinessCashflowScoresResponse": {"type": "object", "required": ["data", "meta"], "properties": {"data": {"$ref": "#/components/schemas/CashflowScores"}, "meta": {"$ref": "#/components/schemas/V1BusinessCashflowScoresMeta"}}}, "V1BusinessCashflowPlanListMeta": {"type": "object", "required": ["api_version", "forecast", "mode", "request_id", "resource"], "properties": {"api_version": {"type": "string", "const": "v1-2026-07"}, "forecast": {"type": "boolean", "const": true, "description": "Always true. Cashflow figures are a forecast with provenance, never an accounting record."}, "mode": {"type": "string"}, "request_id": {"type": "string", "minLength": 1, "maxLength": 128}, "resource": {"type": "string", "const": "cashflow_plan"}, "limit": {"type": "integer"}, "scope": {"type": "string"}}}, "V1BusinessCashflowPlanListResponse": {"type": "object", "required": ["data", "meta"], "properties": {"data": {"$ref": "#/components/schemas/CashflowPlanList"}, "meta": {"$ref": "#/components/schemas/V1BusinessCashflowPlanListMeta"}}}, "V1BusinessCashflowPlanMeta": {"type": "object", "required": ["api_version", "forecast", "mode", "request_id", "resource"], "properties": {"api_version": {"type": "string", "const": "v1-2026-07"}, "forecast": {"type": "boolean", "const": true, "description": "Always true. Cashflow figures are a forecast with provenance, never an accounting record."}, "mode": {"type": "string"}, "request_id": {"type": "string", "minLength": 1, "maxLength": 128}, "resource": {"type": "string", "const": "cashflow_plan"}, "limit": {"type": "integer"}, "scope": {"type": "string"}}}, "V1BusinessCashflowPlanResponse": {"type": "object", "required": ["data", "meta"], "properties": {"data": {"$ref": "#/components/schemas/CashflowPlan"}, "meta": {"$ref": "#/components/schemas/V1BusinessCashflowPlanMeta"}}}, "V1BusinessCashflowPlanOccurrenceMeta": {"type": "object", "required": ["api_version", "forecast", "mode", "request_id", "resource"], "properties": {"api_version": {"type": "string", "const": "v1-2026-07"}, "forecast": {"type": "boolean", "const": true, "description": "Always true. Cashflow figures are a forecast with provenance, never an accounting record."}, "mode": {"type": "string"}, "request_id": {"type": "string", "minLength": 1, "maxLength": 128}, "resource": {"type": "string", "const": "cashflow_plan_occurrence"}, "limit": {"type": "integer"}, "scope": {"type": "string"}}}, "V1BusinessCashflowPlanOccurrenceResponse": {"type": "object", "required": ["data", "meta"], "properties": {"data": {"$ref": "#/components/schemas/CashflowPlanOccurrence"}, "meta": {"$ref": "#/components/schemas/V1BusinessCashflowPlanOccurrenceMeta"}}}, "V1BusinessCashflowScenarioListMeta": {"type": "object", "required": ["api_version", "forecast", "mode", "request_id", "resource"], "properties": {"api_version": {"type": "string", "const": "v1-2026-07"}, "forecast": {"type": "boolean", "const": true, "description": "Always true. Cashflow figures are a forecast with provenance, never an accounting record."}, "mode": {"type": "string"}, "request_id": {"type": "string", "minLength": 1, "maxLength": 128}, "resource": {"type": "string", "const": "cashflow_scenario"}, "limit": {"type": "integer"}, "scope": {"type": "string"}}}, "V1BusinessCashflowScenarioListResponse": {"type": "object", "required": ["data", "meta"], "properties": {"data": {"type": "array", "items": {"$ref": "#/components/schemas/CashflowScenario"}}, "meta": {"$ref": "#/components/schemas/V1BusinessCashflowScenarioListMeta"}}}, "V1BusinessCashflowScenarioComparisonListMeta": {"type": "object", "required": ["api_version", "forecast", "mode", "request_id", "resource"], "properties": {"api_version": {"type": "string", "const": "v1-2026-07"}, "forecast": {"type": "boolean", "const": true, "description": "Always true. Cashflow figures are a forecast with provenance, never an accounting record."}, "mode": {"type": "string"}, "request_id": {"type": "string", "minLength": 1, "maxLength": 128}, "resource": {"type": "string", "const": "cashflow_scenario_comparison"}, "limit": {"type": "integer"}, "scope": {"type": "string"}}}, "V1BusinessCashflowScenarioComparisonListResponse": {"type": "object", "required": ["data", "meta"], "properties": {"data": {"type": "array", "items": {"$ref": "#/components/schemas/CashflowScenarioComparison"}}, "meta": {"$ref": "#/components/schemas/V1BusinessCashflowScenarioComparisonListMeta"}}}, "V1BusinessCashflowHeadroomMeta": {"type": "object", "required": ["api_version", "forecast", "mode", "request_id", "resource"], "properties": {"api_version": {"type": "string", "const": "v1-2026-07"}, "forecast": {"type": "boolean", "const": true, "description": "Always true. Cashflow figures are a forecast with provenance, never an accounting record."}, "mode": {"type": "string"}, "request_id": {"type": "string", "minLength": 1, "maxLength": 128}, "resource": {"type": "string", "const": "cashflow_headroom"}, "limit": {"type": "integer"}, "scope": {"type": "string"}}}, "V1BusinessCashflowHeadroomResponse": {"type": "object", "required": ["data", "meta"], "properties": {"data": {"$ref": "#/components/schemas/CashflowHeadroom"}, "meta": {"$ref": "#/components/schemas/V1BusinessCashflowHeadroomMeta"}}}, "V1BusinessCashflowTimingMeta": {"type": "object", "required": ["api_version", "forecast", "mode", "request_id", "resource"], "properties": {"api_version": {"type": "string", "const": "v1-2026-07"}, "forecast": {"type": "boolean", "const": true, "description": "Always true. Cashflow figures are a forecast with provenance, never an accounting record."}, "mode": {"type": "string"}, "request_id": {"type": "string", "minLength": 1, "maxLength": 128}, "resource": {"type": "string", "const": "cashflow_timing"}, "limit": {"type": "integer"}, "scope": {"type": "string"}}}, "V1BusinessCashflowTimingResponse": {"type": "object", "required": ["data", "meta"], "properties": {"data": {"$ref": "#/components/schemas/CashflowTimingSummary"}, "meta": {"$ref": "#/components/schemas/V1BusinessCashflowTimingMeta"}}}, "V1BusinessCashflowBucketListMeta": {"type": "object", "required": ["api_version", "forecast", "mode", "request_id", "resource"], "properties": {"api_version": {"type": "string", "const": "v1-2026-07"}, "forecast": {"type": "boolean", "const": true, "description": "Always true. Cashflow figures are a forecast with provenance, never an accounting record."}, "mode": {"type": "string"}, "request_id": {"type": "string", "minLength": 1, "maxLength": 128}, "resource": {"type": "string", "const": "cashflow_bucket"}, "limit": {"type": "integer"}, "scope": {"type": "string"}}}, "V1BusinessCashflowBucketListResponse": {"type": "object", "required": ["data", "meta"], "properties": {"data": {"$ref": "#/components/schemas/CashflowBucketList"}, "meta": {"$ref": "#/components/schemas/V1BusinessCashflowBucketListMeta"}}}, "V1BusinessProjectListResponse": { "type": "object", "required": [ "data", "meta" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/BusinessProject" } }, "meta": { "$ref": "#/components/schemas/V1BusinessProjectListMeta" } } }, "V1BusinessProjectResponse": { "type": "object", "required": [ "data", "meta" ], "properties": { "data": { "$ref": "#/components/schemas/BusinessProject" }, "meta": { "$ref": "#/components/schemas/V1BusinessProjectMeta" } } }, "V1BusinessProjectListMeta": { "type": "object", "required": [ "api_version", "mode", "pagination", "request_id", "resource" ], "properties": { "api_version": { "type": "string", "const": "v1-2026-07" }, "mode": { "type": "string", "const": "list" }, "pagination": { "$ref": "#/components/schemas/V1PaginationMeta" }, "request_id": { "type": "string", "minLength": 1, "maxLength": 128 }, "resource": { "type": "string", "const": "business_project" } } }, "V1BusinessProjectMeta": { "type": "object", "required": [ "api_version", "mode", "request_id", "resource" ], "properties": { "api_version": { "type": "string", "const": "v1-2026-07" }, "mode": { "type": "string", "const": "detail" }, "request_id": { "type": "string", "minLength": 1, "maxLength": 128 }, "resource": { "type": "string", "const": "business_project" } } }, "PersonalCategory": { "type": "object", "additionalProperties": false, "required": [ "id", "user_id", "name", "category_type", "object" ], "properties": { "object": { "type": "string", "const": "personal_category" }, "id": { "type": "string", "format": "uuid" }, "user_id": { "type": "string", "format": "uuid" }, "name": { "type": [ "string", "null" ] }, "category_type": { "type": [ "string", "null" ], "enum": [ "income", "expense", "transfer", null ] }, "parent_id": { "type": [ "string", "null" ], "format": "uuid" }, "icon": { "type": [ "string", "null" ] }, "color": { "type": [ "string", "null" ] }, "is_active": { "type": "boolean" }, "sort_order": { "type": [ "number", "null" ] }, "created_at": { "type": [ "string", "null" ], "format": "date-time" }, "updated_at": { "type": [ "string", "null" ], "format": "date-time" } } }, "PersonalCategoryListResponse": { "type": "object", "required": [ "object", "api_version", "data", "meta" ], "properties": { "object": { "type": "string", "const": "list" }, "api_version": { "type": "string", "const": "v1-2026-07" }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/PersonalCategory" } }, "meta": { "$ref": "#/components/schemas/PersonalCategoryListMeta" } } }, "PersonalCategoryResponse": { "type": "object", "required": [ "data", "meta" ], "properties": { "data": { "$ref": "#/components/schemas/PersonalCategory" }, "meta": { "$ref": "#/components/schemas/PersonalCategoryMeta" } } }, "PersonalCategoryCreateRequest": { "type": "object", "additionalProperties": false, "required": [ "name", "category_type" ], "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 120, "description": "Category name shown to the user." }, "category_type": { "type": "string", "enum": [ "income", "expense", "transfer" ] }, "parent_id": { "type": [ "string", "null" ], "format": "uuid", "description": "Optional parent category owned by the bearer-token user. The parent must use the same category_type." }, "icon": { "type": [ "string", "null" ], "maxLength": 64 }, "color": { "type": [ "string", "null" ], "maxLength": 32 }, "is_active": { "type": "boolean", "default": true }, "sort_order": { "type": "integer", "minimum": -1000000, "maximum": 1000000, "default": 0 } } }, "PersonalCategoryCreateResponse": { "type": "object", "required": [ "data", "meta" ], "properties": { "data": { "$ref": "#/components/schemas/PersonalCategory" }, "meta": { "$ref": "#/components/schemas/PersonalCategoryCreateMeta" } } }, "PersonalCategoryCreateMeta": { "type": "object", "required": [ "api_version", "mode", "request_id", "resource", "scope" ], "properties": { "api_version": { "type": "string", "const": "v1-2026-07" }, "mode": { "type": "string", "const": "created" }, "request_id": { "type": "string", "minLength": 1, "maxLength": 128 }, "resource": { "type": "string", "const": "personal_category" }, "scope": { "type": "string", "const": "personal.categories.write" } } }, "PersonalCategoryListMeta": { "type": "object", "required": [ "api_version", "mode", "pagination", "request_id", "resource", "scope" ], "properties": { "api_version": { "type": "string", "const": "v1-2026-07" }, "mode": { "type": "string", "const": "list" }, "pagination": { "$ref": "#/components/schemas/V1PaginationMeta" }, "request_id": { "type": "string", "minLength": 1, "maxLength": 128 }, "resource": { "type": "string", "const": "personal_category" }, "scope": { "type": "string", "const": "personal.categories.read" } } }, "PersonalCategoryMeta": { "type": "object", "required": [ "api_version", "mode", "request_id", "resource", "scope" ], "properties": { "api_version": { "type": "string", "const": "v1-2026-07" }, "mode": { "type": "string", "const": "detail" }, "request_id": { "type": "string", "minLength": 1, "maxLength": 128 }, "resource": { "type": "string", "const": "personal_category" }, "scope": { "type": "string", "const": "personal.categories.read" } } }, "PersonalCategorySummary": { "type": "object", "additionalProperties": false, "required": [ "id", "name", "category_type" ], "properties": { "id": { "type": "string", "format": "uuid" }, "category_type": { "type": [ "string", "null" ], "enum": [ "income", "expense", "transfer", null ] }, "name": { "type": [ "string", "null" ] } } }, "PersonalCategorizationRule": { "type": "object", "additionalProperties": false, "required": [ "object", "id", "user_id", "merchant_pattern", "category_id", "category", "match_type", "pattern_type", "usage_count", "success_rate", "confidence_score", "is_active", "created_at", "updated_at" ], "properties": { "object": { "type": "string", "const": "personal_categorization_rule" }, "id": { "type": "string", "format": "uuid" }, "user_id": { "type": "string", "format": "uuid" }, "merchant_pattern": { "type": [ "string", "null" ] }, "category_id": { "type": [ "string", "null" ], "format": "uuid" }, "category": { "anyOf": [ { "$ref": "#/components/schemas/PersonalCategorySummary" }, { "type": "null" } ] }, "match_type": { "type": [ "string", "null" ], "enum": [ "contains", "starts_with", "equals", null ] }, "pattern_type": { "type": [ "string", "null" ], "enum": [ "merchant", "keyword", null ] }, "usage_count": { "type": "number", "minimum": 0 }, "success_rate": { "type": "number", "minimum": 0, "maximum": 1 }, "confidence_score": { "type": "number", "minimum": 0, "maximum": 1 }, "is_active": { "type": "boolean" }, "created_at": { "type": [ "string", "null" ], "format": "date-time" }, "updated_at": { "type": [ "string", "null" ], "format": "date-time" } } }, "PersonalCategorizationRuleListResponse": { "type": "object", "required": [ "object", "api_version", "data", "meta" ], "properties": { "object": { "type": "string", "const": "list" }, "api_version": { "type": "string", "const": "v1-2026-07" }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/PersonalCategorizationRule" } }, "meta": { "$ref": "#/components/schemas/PersonalCategorizationRuleListMeta" } } }, "PersonalCategorizationRuleListMeta": { "type": "object", "additionalProperties": false, "required": [ "api_version", "mode", "pagination", "request_id", "resource", "scopes" ], "properties": { "api_version": { "type": "string", "const": "v1-2026-07" }, "filters": { "type": "object", "additionalProperties": true, "description": "Echoes safe list filters supplied by the caller." }, "mode": { "type": "string", "const": "list" }, "pagination": { "$ref": "#/components/schemas/V1PaginationMeta" }, "request_id": { "type": "string", "minLength": 1, "maxLength": 128 }, "resource": { "type": "string", "const": "personal_categorization_rule" }, "scopes": { "type": "array", "items": { "type": "string", "enum": [ "personal.transactions.read", "personal.categories.read" ] }, "minItems": 2, "maxItems": 2 } } }, "PersonalBudget": { "type": "object", "additionalProperties": false, "required": [ "id", "user_id", "object" ], "properties": { "object": { "type": "string", "const": "personal_budget" }, "id": { "type": "string", "format": "uuid" }, "user_id": { "type": "string", "format": "uuid" }, "category_id": { "type": [ "string", "null" ], "format": "uuid" }, "category_name": { "type": [ "string", "null" ] }, "budget_type": { "type": [ "string", "null" ] }, "period_type": { "type": [ "string", "null" ] }, "budget_month": { "type": [ "string", "null" ], "format": "date" }, "budget_amount": { "type": [ "number", "null" ] }, "spent_amount": { "type": [ "number", "null" ] }, "currency": { "type": [ "string", "null" ] }, "start_date": { "type": [ "string", "null" ], "format": "date" }, "end_date": { "type": [ "string", "null" ], "format": "date" }, "day_of_week": { "type": [ "number", "null" ] }, "is_active": { "type": "boolean" }, "is_template": { "type": [ "boolean", "null" ] }, "rollover_enabled": { "type": [ "boolean", "null" ] }, "template_id": { "type": [ "string", "null" ], "format": "uuid" }, "created_at": { "type": [ "string", "null" ], "format": "date-time" }, "updated_at": { "type": [ "string", "null" ], "format": "date-time" } } }, "PersonalBudgetListResponse": { "type": "object", "required": [ "object", "api_version", "data", "meta" ], "properties": { "object": { "type": "string", "const": "list" }, "api_version": { "type": "string", "const": "v1-2026-07" }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/PersonalBudget" } }, "meta": { "$ref": "#/components/schemas/PersonalBudgetListMeta" } } }, "PersonalBudgetResponse": { "type": "object", "required": [ "data", "meta" ], "properties": { "data": { "$ref": "#/components/schemas/PersonalBudget" }, "meta": { "$ref": "#/components/schemas/PersonalBudgetMeta" } } }, "PersonalBudgetListMeta": { "type": "object", "required": [ "api_version", "mode", "pagination", "request_id", "resource", "scope" ], "properties": { "api_version": { "type": "string", "const": "v1-2026-07" }, "mode": { "type": "string", "const": "list" }, "pagination": { "$ref": "#/components/schemas/V1PaginationMeta" }, "request_id": { "type": "string", "minLength": 1, "maxLength": 128 }, "resource": { "type": "string", "const": "personal_budget" }, "scope": { "type": "string", "const": "personal.budgets.read" } } }, "PersonalBudgetMeta": { "type": "object", "required": [ "api_version", "mode", "request_id", "resource", "scope" ], "properties": { "api_version": { "type": "string", "const": "v1-2026-07" }, "mode": { "type": "string", "const": "detail" }, "request_id": { "type": "string", "minLength": 1, "maxLength": 128 }, "resource": { "type": "string", "const": "personal_budget" }, "scope": { "type": "string", "const": "personal.budgets.read" } } }, "PersonalGoal": { "type": "object", "additionalProperties": false, "required": [ "id", "user_id", "object" ], "properties": { "object": { "type": "string", "const": "personal_goal" }, "id": { "type": "string", "format": "uuid" }, "user_id": { "type": "string", "format": "uuid" }, "name": { "type": [ "string", "null" ] }, "description": { "type": [ "string", "null" ] }, "goal_type": { "type": [ "string", "null" ] }, "category_id": { "type": [ "string", "null" ], "format": "uuid" }, "target_amount": { "type": [ "number", "null" ] }, "current_amount": { "type": [ "number", "null" ] }, "currency": { "type": [ "string", "null" ] }, "priority": { "type": [ "number", "null" ] }, "start_date": { "type": [ "string", "null" ], "format": "date" }, "target_date": { "type": [ "string", "null" ], "format": "date" }, "achieved_at": { "type": [ "string", "null" ], "format": "date-time" }, "is_achieved": { "type": "boolean" }, "is_shared": { "type": "boolean" }, "household_id": { "type": [ "string", "null" ], "format": "uuid" }, "linked_account_id": { "type": [ "string", "null" ], "format": "uuid" }, "linked_debt_budget_id": { "type": [ "string", "null" ], "format": "uuid" }, "contribution_type": { "type": [ "string", "null" ] }, "contribution_amount": { "type": [ "number", "null" ] }, "contribution_percent": { "type": [ "number", "null" ] }, "contribution_frequency": { "type": [ "string", "null" ] }, "debt_apr": { "type": [ "number", "null" ] }, "debt_extra_payment": { "type": [ "number", "null" ] }, "created_at": { "type": [ "string", "null" ], "format": "date-time" }, "updated_at": { "type": [ "string", "null" ], "format": "date-time" } } }, "PersonalGoalListResponse": { "type": "object", "required": [ "object", "api_version", "data", "meta" ], "properties": { "object": { "type": "string", "const": "list" }, "api_version": { "type": "string", "const": "v1-2026-07" }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/PersonalGoal" } }, "meta": { "$ref": "#/components/schemas/PersonalGoalListMeta" } } }, "PersonalGoalResponse": { "type": "object", "required": [ "data", "meta" ], "properties": { "data": { "$ref": "#/components/schemas/PersonalGoal" }, "meta": { "$ref": "#/components/schemas/PersonalGoalMeta" } } }, "PersonalGoalCreateRequest": { "type": "object", "additionalProperties": false, "required": [ "name", "goal_type", "target_amount" ], "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 120 }, "description": { "type": [ "string", "null" ], "maxLength": 500 }, "goal_type": { "type": "string", "enum": [ "savings", "debt_payoff", "investment", "expense_reduction", "income", "other" ] }, "category_id": { "type": [ "string", "null" ], "format": "uuid", "description": "Optional personal category owned by the bearer-token user." }, "target_amount": { "type": "number", "exclusiveMinimum": 0, "maximum": 999999999999.99 }, "current_amount": { "type": "number", "minimum": 0, "maximum": 999999999999.99, "default": 0 }, "currency": { "type": "string", "pattern": "^[A-Z]{3}$", "default": "GBP" }, "priority": { "type": "integer", "minimum": 1, "maximum": 10, "default": 1 }, "start_date": { "type": [ "string", "null" ], "format": "date" }, "target_date": { "type": [ "string", "null" ], "format": "date" }, "is_shared": { "type": "boolean", "default": false }, "linked_account_id": { "type": [ "string", "null" ], "format": "uuid", "description": "Optional personal account owned by the bearer-token user." }, "contribution_type": { "type": [ "string", "null" ], "enum": [ "fixed", "percentage", null ] }, "contribution_amount": { "type": [ "number", "null" ], "minimum": 0, "maximum": 999999999999.99 }, "contribution_percent": { "type": [ "number", "null" ], "minimum": 0, "maximum": 100 }, "contribution_frequency": { "type": [ "string", "null" ], "enum": [ "weekly", "monthly", "quarterly", "yearly", "annually", null ] }, "debt_apr": { "type": [ "number", "null" ], "minimum": 0, "maximum": 100 }, "debt_extra_payment": { "type": [ "number", "null" ], "minimum": 0, "maximum": 999999999999.99 } } }, "PersonalGoalCreateResponse": { "type": "object", "required": [ "data", "meta" ], "properties": { "data": { "$ref": "#/components/schemas/PersonalGoal" }, "meta": { "$ref": "#/components/schemas/PersonalGoalCreateMeta" } } }, "PersonalGoalCreateMeta": { "type": "object", "required": [ "api_version", "mode", "request_id", "resource", "scope" ], "properties": { "api_version": { "type": "string", "const": "v1-2026-07" }, "mode": { "type": "string", "const": "created" }, "request_id": { "type": "string", "minLength": 1, "maxLength": 128 }, "resource": { "type": "string", "const": "personal_goal" }, "scope": { "type": "string", "const": "personal.goals.write" } } }, "PersonalGoalListMeta": { "type": "object", "required": [ "api_version", "mode", "pagination", "request_id", "resource", "scope" ], "properties": { "api_version": { "type": "string", "const": "v1-2026-07" }, "mode": { "type": "string", "const": "list" }, "pagination": { "$ref": "#/components/schemas/V1PaginationMeta" }, "request_id": { "type": "string", "minLength": 1, "maxLength": 128 }, "resource": { "type": "string", "const": "personal_goal" }, "scope": { "type": "string", "const": "personal.goals.read" } } }, "PersonalGoalMeta": { "type": "object", "required": [ "api_version", "mode", "request_id", "resource", "scope" ], "properties": { "api_version": { "type": "string", "const": "v1-2026-07" }, "mode": { "type": "string", "const": "detail" }, "request_id": { "type": "string", "minLength": 1, "maxLength": 128 }, "resource": { "type": "string", "const": "personal_goal" }, "scope": { "type": "string", "const": "personal.goals.read" } } }, "BusinessFund": { "type": "object", "additionalProperties": false, "required": [ "object", "id", "company_id" ], "properties": { "object": { "type": "string", "const": "business_fund" }, "id": { "type": "string", "format": "uuid" }, "company_id": { "type": "string", "format": "uuid" }, "name": { "type": [ "string", "null" ] }, "code": { "type": [ "string", "null" ] }, "fund_type": { "type": [ "string", "null" ] }, "fund_class": { "type": [ "string", "null" ] }, "unrestricted_subtype": { "type": [ "string", "null" ] }, "endowment_subtype": { "type": [ "string", "null" ] }, "purpose": { "type": [ "string", "null" ] }, "restriction_summary": { "type": [ "string", "null" ] }, "restriction_reference": { "type": [ "string", "null" ] }, "opened_on": { "type": [ "string", "null" ], "format": "date" }, "closed_on": { "type": [ "string", "null" ], "format": "date" }, "display_order": { "type": [ "number", "null" ] }, "is_default": { "type": "boolean" }, "is_active": { "type": "boolean" }, "is_closed": { "type": "boolean" }, "created_at": { "type": [ "string", "null" ], "format": "date-time" }, "updated_at": { "type": [ "string", "null" ], "format": "date-time" } } }, "V1BusinessFundListResponse": { "type": "object", "required": [ "data", "meta" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/BusinessFund" } }, "meta": { "$ref": "#/components/schemas/V1BusinessFundListMeta" } } }, "V1BusinessFundResponse": { "type": "object", "required": [ "data", "meta" ], "properties": { "data": { "$ref": "#/components/schemas/BusinessFund" }, "meta": { "$ref": "#/components/schemas/V1BusinessFundMeta" } } }, "BusinessGiftAidDonor": { "type": "object", "additionalProperties": false, "required": [ "object", "address_line_1", "address_line_2", "city", "company_id", "country", "county", "created_at", "email", "external_id", "first_name", "id", "is_active", "last_name", "notes", "postcode", "telephone", "title", "updated_at" ], "properties": { "object": { "type": "string", "const": "business_gift_aid_donor" }, "address_line_1": { "type": "string", "nullable": true }, "address_line_2": { "type": "string", "nullable": true }, "city": { "type": "string", "nullable": true }, "company_id": { "type": "string", "format": "uuid" }, "country": { "type": "string", "nullable": true }, "county": { "type": "string", "nullable": true }, "created_at": { "type": "string", "format": "date-time", "nullable": true }, "email": { "type": "string", "format": "email", "nullable": true }, "external_id": { "type": "string", "nullable": true }, "first_name": { "type": "string", "nullable": true }, "id": { "type": "string", "format": "uuid" }, "is_active": { "type": "boolean" }, "last_name": { "type": "string", "nullable": true }, "notes": { "type": "string", "nullable": true }, "postcode": { "type": "string", "nullable": true }, "telephone": { "type": "string", "nullable": true }, "title": { "type": "string", "nullable": true }, "updated_at": { "type": "string", "format": "date-time", "nullable": true } } }, "V1BusinessGiftAidDonorListMeta": { "type": "object", "required": [ "api_version", "mode", "pagination", "request_id", "resource" ], "properties": { "api_version": { "type": "string", "const": "v1-2026-07" }, "mode": { "type": "string", "const": "list" }, "pagination": { "$ref": "#/components/schemas/V1Pagination" }, "request_id": { "type": "string", "minLength": 1, "maxLength": 128 }, "resource": { "type": "string", "const": "business_gift_aid_donor" } } }, "V1BusinessGiftAidDonorMeta": { "type": "object", "required": [ "api_version", "mode", "request_id", "resource" ], "properties": { "api_version": { "type": "string", "const": "v1-2026-07" }, "mode": { "type": "string", "const": "detail" }, "request_id": { "type": "string", "minLength": 1, "maxLength": 128 }, "resource": { "type": "string", "const": "business_gift_aid_donor" } } }, "V1BusinessGiftAidDonorListResponse": { "type": "object", "required": [ "data", "meta" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/BusinessGiftAidDonor" } }, "meta": { "$ref": "#/components/schemas/V1BusinessGiftAidDonorListMeta" } } }, "V1BusinessGiftAidDonorResponse": { "type": "object", "required": [ "data", "meta" ], "properties": { "data": { "$ref": "#/components/schemas/BusinessGiftAidDonor" }, "meta": { "$ref": "#/components/schemas/V1BusinessGiftAidDonorMeta" } } }, "V1BusinessFundListMeta": { "type": "object", "required": [ "api_version", "mode", "pagination", "request_id", "resource" ], "properties": { "api_version": { "type": "string", "const": "v1-2026-07" }, "mode": { "type": "string", "const": "list" }, "pagination": { "$ref": "#/components/schemas/V1PaginationMeta" }, "request_id": { "type": "string", "minLength": 1, "maxLength": 128 }, "resource": { "type": "string", "const": "business_fund" } } }, "V1BusinessFundMeta": { "type": "object", "required": [ "api_version", "mode", "request_id", "resource" ], "properties": { "api_version": { "type": "string", "const": "v1-2026-07" }, "mode": { "type": "string", "const": "detail" }, "request_id": { "type": "string", "minLength": 1, "maxLength": 128 }, "resource": { "type": "string", "const": "business_fund" } } }, "BusinessCostCenterOption": { "type": "object", "additionalProperties": false, "required": [ "object", "id", "cost_center_level_id" ], "properties": { "object": { "type": "string", "const": "business_cost_center_option" }, "id": { "type": "string", "format": "uuid" }, "cost_center_level_id": { "type": "string", "format": "uuid" }, "name": { "type": [ "string", "null" ] }, "code": { "type": [ "string", "null" ] }, "description": { "type": [ "string", "null" ] }, "is_active": { "type": "boolean" }, "created_at": { "type": [ "string", "null" ], "format": "date-time" }, "updated_at": { "type": [ "string", "null" ], "format": "date-time" } } }, "BusinessCostCenterLevel": { "type": "object", "additionalProperties": false, "required": [ "object", "id", "company_id", "options" ], "properties": { "object": { "type": "string", "const": "business_cost_center_level" }, "id": { "type": "string", "format": "uuid" }, "company_id": { "type": "string", "format": "uuid" }, "name": { "type": [ "string", "null" ] }, "description": { "type": [ "string", "null" ] }, "requirement_type": { "type": [ "string", "null" ] }, "display_order": { "type": [ "number", "null" ] }, "is_active": { "type": "boolean" }, "created_at": { "type": [ "string", "null" ], "format": "date-time" }, "updated_at": { "type": [ "string", "null" ], "format": "date-time" }, "options": { "type": "array", "items": { "$ref": "#/components/schemas/BusinessCostCenterOption" } } } }, "V1BusinessCostCenterListResponse": { "type": "object", "required": [ "data", "meta" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/BusinessCostCenterLevel" } }, "meta": { "$ref": "#/components/schemas/V1BusinessCostCenterListMeta" } } }, "V1BusinessCostCenterResponse": { "type": "object", "required": [ "data", "meta" ], "properties": { "data": { "$ref": "#/components/schemas/BusinessCostCenterLevel" }, "meta": { "$ref": "#/components/schemas/V1BusinessCostCenterMeta" } } }, "V1BusinessCostCenterListMeta": { "type": "object", "required": [ "api_version", "mode", "pagination", "request_id", "resource", "total_options" ], "properties": { "api_version": { "type": "string", "const": "v1-2026-07" }, "mode": { "type": "string", "const": "list" }, "pagination": { "$ref": "#/components/schemas/V1PaginationMeta" }, "request_id": { "type": "string", "minLength": 1, "maxLength": 128 }, "resource": { "type": "string", "const": "business_cost_center" }, "total_options": { "type": "integer", "minimum": 0 } } }, "V1BusinessCostCenterMeta": { "type": "object", "required": [ "api_version", "mode", "request_id", "resource", "total_options" ], "properties": { "api_version": { "type": "string", "const": "v1-2026-07" }, "mode": { "type": "string", "const": "detail" }, "request_id": { "type": "string", "minLength": 1, "maxLength": 128 }, "resource": { "type": "string", "const": "business_cost_center" }, "total_options": { "type": "integer", "minimum": 0 } } }, "BusinessCostCenterBudgetRow": { "type": "object", "additionalProperties": false, "required": [ "object" ], "properties": { "object": { "type": "string", "const": "business_cost_center_budget_row" }, "cost_center_level_id": { "type": [ "string", "null" ] }, "cost_center_option_id": { "type": [ "string", "null" ] }, "cost_center_option_name": { "type": [ "string", "null" ] }, "cost_center_option_code": { "type": [ "string", "null" ] }, "target_month": { "type": [ "string", "null" ], "format": "date" }, "budget_amount": { "type": "number" }, "actual_amount": { "type": "number" } } }, "BusinessCostCenterBudgetRollup": { "type": "object", "additionalProperties": false, "required": [ "object" ], "properties": { "object": { "type": "string", "const": "business_cost_center_budget_rollup" }, "cost_center_option_id": { "type": [ "string", "null" ] }, "cost_center_option_name": { "type": [ "string", "null" ] }, "cost_center_option_code": { "type": [ "string", "null" ] }, "budget_amount": { "type": "number" }, "actual_amount": { "type": "number" }, "variance_amount": { "type": "number" } } }, "V1BusinessCostCenterBudgetListResponse": { "type": "object", "required": [ "data", "by_option", "meta" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/BusinessCostCenterBudgetRow" } }, "by_option": { "type": "array", "items": { "$ref": "#/components/schemas/BusinessCostCenterBudgetRollup" } }, "meta": { "$ref": "#/components/schemas/V1BusinessCostCenterBudgetMeta" } } }, "V1BusinessCostCenterBudgetMeta": { "type": "object", "required": [ "api_version", "budget_period_id", "cost_center_level_id", "mode", "request_id", "resource", "total_rows" ], "properties": { "api_version": { "type": "string", "const": "v1-2026-07" }, "budget_period_id": { "type": "string", "format": "uuid" }, "cost_center_level_id": { "type": "string", "format": "uuid" }, "mode": { "type": "string", "const": "list" }, "request_id": { "type": "string", "minLength": 1, "maxLength": 128 }, "resource": { "type": "string", "const": "business_cost_center_budget" }, "total_rows": { "type": "integer", "minimum": 0 } } }, "BusinessCostCenterBudgetTarget": { "type": "object", "additionalProperties": false, "required": [ "object", "id", "company_id", "budget_period_id", "cost_center_level_id", "cost_center_option_id", "target_month", "target_amount" ], "properties": { "object": { "type": "string", "const": "business_cost_center_budget_target" }, "id": { "type": "string", "format": "uuid" }, "company_id": { "type": "string", "format": "uuid" }, "budget_period_id": { "type": "string", "format": "uuid" }, "cost_center_level_id": { "type": "string", "format": "uuid" }, "cost_center_option_id": { "type": "string", "format": "uuid" }, "budget_category_id": { "type": [ "string", "null" ], "format": "uuid" }, "target_month": { "type": "string", "format": "date", "pattern": "^\\d{4}-\\d{2}-01$" }, "target_amount": { "type": "number", "minimum": 0, "multipleOf": 0.01 }, "notes": { "type": [ "string", "null" ], "maxLength": 1000 }, "created_at": { "type": [ "string", "null" ], "format": "date-time" }, "updated_at": { "type": [ "string", "null" ], "format": "date-time" } } }, "BusinessCostCenterBudgetTargetCreateRequest": { "type": "object", "additionalProperties": false, "required": [ "budget_period_id", "cost_center_level_id", "cost_center_option_id", "target_month", "target_amount" ], "properties": { "budget_period_id": { "type": "string", "format": "uuid" }, "cost_center_level_id": { "type": "string", "format": "uuid" }, "cost_center_option_id": { "type": "string", "format": "uuid" }, "target_month": { "type": "string", "format": "date", "pattern": "^\\d{4}-\\d{2}-01$" }, "target_amount": { "type": "number", "minimum": 0, "maximum": 9999999999999.99, "multipleOf": 0.01 }, "notes": { "type": [ "string", "null" ], "maxLength": 1000 } } }, "BusinessCostCenterBudgetTargetCreateMeta": { "type": "object", "required": [ "api_version", "mode", "request_id", "resource" ], "properties": { "api_version": { "type": "string", "const": "v1-2026-07" }, "mode": { "type": "string", "const": "created" }, "request_id": { "type": "string", "minLength": 1, "maxLength": 128 }, "resource": { "type": "string", "const": "business_cost_center_budget_target" } } }, "BusinessCostCenterBudgetTargetCreateResponse": { "type": "object", "required": [ "data", "meta" ], "properties": { "data": { "$ref": "#/components/schemas/BusinessCostCenterBudgetTarget" }, "meta": { "$ref": "#/components/schemas/BusinessCostCenterBudgetTargetCreateMeta" } } }, "BusinessAccountingPeriod": { "type": "object", "additionalProperties": false, "required": [ "object", "id", "company_id" ], "properties": { "object": { "type": "string", "const": "business_accounting_period" }, "id": { "type": "string", "format": "uuid" }, "company_id": { "type": "string", "format": "uuid" }, "period_type": { "type": [ "string", "null" ] }, "start_date": { "type": [ "string", "null" ], "format": "date" }, "end_date": { "type": [ "string", "null" ], "format": "date" }, "filing_deadline": { "type": [ "string", "null" ], "format": "date" }, "locked": { "type": "boolean" }, "locked_at": { "type": [ "string", "null" ], "format": "date-time" }, "locked_by": { "type": [ "string", "null" ] }, "created_at": { "type": [ "string", "null" ], "format": "date-time" }, "updated_at": { "type": [ "string", "null" ], "format": "date-time" }, "period_label": { "type": "string" }, "is_current": { "type": "boolean" }, "days_until_deadline": { "type": [ "integer", "null" ] } } }, "BusinessAccountingPeriodMonth": { "type": "object", "additionalProperties": false, "required": [ "month", "start_date", "end_date" ], "properties": { "month": { "type": "string" }, "start_date": { "type": "string", "format": "date" }, "end_date": { "type": "string", "format": "date" } } }, "BusinessAccountingPeriodMonthlyBreakdown": { "type": "object", "additionalProperties": false, "required": [ "statutory_period_id", "statutory_period_label", "months" ], "properties": { "statutory_period_id": { "type": [ "string", "null" ] }, "statutory_period_label": { "type": "string" }, "months": { "type": "array", "items": { "$ref": "#/components/schemas/BusinessAccountingPeriodMonth" } } } }, "V1BusinessAccountingPeriodListResponse": { "type": "object", "required": [ "data", "meta" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/BusinessAccountingPeriod" } }, "monthly_breakdown": { "type": "array", "items": { "$ref": "#/components/schemas/BusinessAccountingPeriodMonthlyBreakdown" } }, "meta": { "$ref": "#/components/schemas/V1BusinessAccountingPeriodListMeta" } } }, "V1BusinessAccountingPeriodResponse": { "type": "object", "required": [ "data", "meta" ], "properties": { "data": { "$ref": "#/components/schemas/BusinessAccountingPeriod" }, "meta": { "$ref": "#/components/schemas/V1BusinessAccountingPeriodMeta" } } }, "V1BusinessAccountingPeriodListMeta": { "type": "object", "required": [ "api_version", "mode", "pagination", "request_id", "resource" ], "properties": { "api_version": { "type": "string", "const": "v1-2026-07" }, "mode": { "type": "string", "const": "list" }, "pagination": { "$ref": "#/components/schemas/V1PaginationMeta" }, "request_id": { "type": "string", "minLength": 1, "maxLength": 128 }, "resource": { "type": "string", "const": "business_accounting_period" } } }, "BusinessAccountingPeriodCreateRequest": { "type": "object", "additionalProperties": false, "required": [ "start_date", "end_date" ], "properties": { "start_date": { "type": "string", "format": "date", "pattern": "^\\d{4}-\\d{2}-\\d{2}$" }, "end_date": { "type": "string", "format": "date", "pattern": "^\\d{4}-\\d{2}-\\d{2}$" }, "filing_deadline": { "type": [ "string", "null" ], "format": "date", "pattern": "^\\d{4}-\\d{2}-\\d{2}$" }, "period_type": { "type": "string", "enum": [ "annual", "statutory", "short", "long", "year" ], "default": "annual", "description": "`statutory` and `year` are accepted API aliases and stored as the platform annual period type." } } }, "V1BusinessAccountingPeriodCreateMeta": { "type": "object", "required": [ "api_version", "mode", "request_id", "resource" ], "properties": { "api_version": { "type": "string", "const": "v1-2026-07" }, "mode": { "type": "string", "const": "created" }, "request_id": { "type": "string", "minLength": 1, "maxLength": 128 }, "resource": { "type": "string", "const": "business_accounting_period" } } }, "V1BusinessAccountingPeriodCreateResponse": { "type": "object", "required": [ "data", "meta" ], "properties": { "data": { "$ref": "#/components/schemas/BusinessAccountingPeriod" }, "meta": { "$ref": "#/components/schemas/V1BusinessAccountingPeriodCreateMeta" } } }, "V1BusinessAccountingPeriodMeta": { "type": "object", "required": [ "api_version", "mode", "request_id", "resource" ], "properties": { "api_version": { "type": "string", "const": "v1-2026-07" }, "mode": { "type": "string", "const": "detail" }, "request_id": { "type": "string", "minLength": 1, "maxLength": 128 }, "resource": { "type": "string", "const": "business_accounting_period" } } }, "QuoteLineItem": { "type": "object", "additionalProperties": false, "properties": { "id": { "type": "string", "format": "uuid" }, "line_number": { "type": [ "integer", "null" ] }, "description": { "type": [ "string", "null" ] }, "quantity": { "type": [ "number", "null" ] }, "unit_price": { "type": [ "number", "null" ] }, "net_amount": { "type": [ "number", "null" ] }, "vat_rate": { "type": [ "number", "null" ] }, "vat_amount": { "type": [ "number", "null" ] }, "gross_amount": { "type": [ "number", "null" ] }, "revenue_account_id": { "type": [ "string", "null" ] }, "project_id": { "type": [ "string", "null" ] }, "cost_center_id": { "type": [ "string", "null" ] }, "fund_id": { "type": [ "string", "null" ] }, "subdescription": { "type": [ "string", "null" ] } } }, "Quote": { "type": "object", "additionalProperties": false, "required": [ "object", "id", "company_id", "approval_status", "lock_version" ], "properties": { "object": { "type": "string", "const": "quote" }, "id": { "type": "string", "format": "uuid" }, "company_id": { "type": "string", "format": "uuid" }, "customer_id": { "type": [ "string", "null" ] }, "quote_number": { "type": [ "string", "null" ] }, "quote_date": { "type": [ "string", "null" ], "format": "date" }, "valid_until": { "type": [ "string", "null" ], "format": "date" }, "reference": { "type": [ "string", "null" ] }, "subtotal_amount": { "type": [ "number", "null" ] }, "total_vat_amount": { "type": [ "number", "null" ] }, "total_amount": { "type": [ "number", "null" ] }, "status": { "type": [ "string", "null" ] }, "approval_status": { "type": "string", "enum": [ "not_applicable", "pending", "approved", "rejected", "on_hold" ] }, "lock_version": { "type": "integer", "minimum": 1, "description": "Use this value as expected_lock_version when correcting a draft quote." }, "currency": { "type": [ "string", "null" ] }, "notes": { "type": [ "string", "null" ] }, "internal_notes": { "type": [ "string", "null" ] }, "fund_id": { "type": [ "string", "null" ] }, "converted_invoice_id": { "type": [ "string", "null" ] }, "converted_at": { "type": [ "string", "null" ], "format": "date-time" }, "sent_at": { "type": [ "string", "null" ], "format": "date-time" }, "accepted_at": { "type": [ "string", "null" ], "format": "date-time" }, "declined_at": { "type": [ "string", "null" ], "format": "date-time" }, "created_by": { "type": [ "string", "null" ] }, "created_at": { "type": [ "string", "null" ], "format": "date-time" }, "updated_at": { "type": [ "string", "null" ], "format": "date-time" }, "customers": { "type": [ "object", "null" ], "additionalProperties": false, "properties": { "id": { "type": "string", "format": "uuid" }, "name": { "type": [ "string", "null" ] }, "contact_email": { "type": [ "string", "null" ] }, "contact_phone": { "type": [ "string", "null" ] } } }, "quote_line_items": { "type": "array", "items": { "$ref": "#/components/schemas/QuoteLineItem" } } } }, "V1BusinessQuoteListResponse": { "type": "object", "required": [ "data", "meta" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Quote" } }, "meta": { "$ref": "#/components/schemas/V1BusinessQuoteListMeta" } } }, "V1BusinessQuoteResponse": { "type": "object", "required": [ "data", "meta" ], "properties": { "data": { "$ref": "#/components/schemas/Quote" }, "meta": { "$ref": "#/components/schemas/V1BusinessQuoteMeta" } } }, "V1BusinessQuoteListMeta": { "type": "object", "required": [ "api_version", "mode", "pagination", "request_id", "resource" ], "properties": { "api_version": { "type": "string", "const": "v1-2026-07" }, "mode": { "type": "string", "const": "list" }, "pagination": { "$ref": "#/components/schemas/V1PaginationMeta" }, "request_id": { "type": "string", "minLength": 1, "maxLength": 128 }, "resource": { "type": "string", "const": "quote" } } }, "V1BusinessQuoteMeta": { "type": "object", "required": [ "api_version", "mode", "request_id", "resource" ], "properties": { "api_version": { "type": "string", "const": "v1-2026-07" }, "mode": { "type": "string", "const": "detail" }, "request_id": { "type": "string", "minLength": 1, "maxLength": 128 }, "resource": { "type": "string", "const": "quote" } } }, "CreditNoteLineItem": { "type": "object", "additionalProperties": false, "properties": { "id": { "type": "string", "format": "uuid" }, "line_number": { "type": [ "integer", "null" ] }, "description": { "type": [ "string", "null" ] }, "quantity": { "type": [ "number", "null" ] }, "unit_price": { "type": [ "number", "null" ] }, "net_amount": { "type": [ "number", "null" ] }, "vat_rate": { "type": [ "number", "null" ] }, "vat_amount": { "type": [ "number", "null" ] }, "gross_amount": { "type": [ "number", "null" ] }, "revenue_account_id": { "type": [ "string", "null" ] }, "project_id": { "type": [ "string", "null" ] }, "cost_center_id": { "type": [ "string", "null" ] }, "fund_id": { "type": [ "string", "null" ] } } }, "CreditNote": { "type": "object", "additionalProperties": false, "required": [ "object", "id", "company_id" ], "properties": { "object": { "type": "string", "const": "credit_note" }, "id": { "type": "string", "format": "uuid" }, "company_id": { "type": "string", "format": "uuid" }, "customer_id": { "type": [ "string", "null" ] }, "original_invoice_id": { "type": [ "string", "null" ] }, "credit_note_number": { "type": [ "string", "null" ] }, "credit_note_date": { "type": [ "string", "null" ], "format": "date" }, "reason": { "type": [ "string", "null" ] }, "subtotal_amount": { "type": [ "number", "null" ] }, "total_vat_amount": { "type": [ "number", "null" ] }, "total_amount": { "type": [ "number", "null" ] }, "currency": { "type": [ "string", "null" ] }, "status": { "type": [ "string", "null" ] }, "notes": { "type": [ "string", "null" ] }, "internal_notes": { "type": [ "string", "null" ] }, "fund_id": { "type": [ "string", "null" ] }, "posted_to_ledger": { "type": [ "boolean", "null" ] }, "ledger_transaction_id": { "type": [ "string", "null" ] }, "ledger_posting_error": { "type": [ "string", "null" ] }, "sent_at": { "type": [ "string", "null" ], "format": "date-time" }, "created_by": { "type": [ "string", "null" ] }, "created_at": { "type": [ "string", "null" ], "format": "date-time" }, "updated_at": { "type": [ "string", "null" ], "format": "date-time" }, "customers": { "type": [ "object", "null" ], "additionalProperties": false, "properties": { "id": { "type": "string", "format": "uuid" }, "name": { "type": [ "string", "null" ] }, "contact_email": { "type": [ "string", "null" ] }, "contact_phone": { "type": [ "string", "null" ] } } }, "credit_note_line_items": { "type": "array", "items": { "$ref": "#/components/schemas/CreditNoteLineItem" } } } }, "V1BusinessCreditNoteListResponse": { "type": "object", "required": [ "data", "meta" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/CreditNote" } }, "meta": { "$ref": "#/components/schemas/V1BusinessCreditNoteListMeta" } } }, "V1BusinessCreditNoteResponse": { "type": "object", "required": [ "data", "meta" ], "properties": { "data": { "$ref": "#/components/schemas/CreditNote" }, "meta": { "$ref": "#/components/schemas/V1BusinessCreditNoteMeta" } } }, "V1BusinessCreditNoteListMeta": { "type": "object", "required": [ "api_version", "mode", "pagination", "request_id", "resource" ], "properties": { "api_version": { "type": "string", "const": "v1-2026-07" }, "mode": { "type": "string", "const": "list" }, "pagination": { "$ref": "#/components/schemas/V1PaginationMeta" }, "request_id": { "type": "string", "minLength": 1, "maxLength": 128 }, "resource": { "type": "string", "const": "credit_note" } } }, "V1BusinessCreditNoteMeta": { "type": "object", "required": [ "api_version", "mode", "request_id", "resource" ], "properties": { "api_version": { "type": "string", "const": "v1-2026-07" }, "mode": { "type": "string", "const": "detail" }, "request_id": { "type": "string", "minLength": 1, "maxLength": 128 }, "resource": { "type": "string", "const": "credit_note" } } }, "BusinessDocument": { "type": "object", "additionalProperties": false, "required": [ "object", "id", "company_id" ], "properties": { "object": { "type": "string", "const": "business_document" }, "id": { "type": "string", "format": "uuid" }, "company_id": { "type": "string", "format": "uuid" }, "file_name": { "type": [ "string", "null" ] }, "file_size": { "type": [ "integer", "null" ] }, "file_type": { "type": [ "string", "null" ] }, "status": { "type": [ "string", "null" ] }, "filed_for_reference_at": { "type": [ "string", "null" ], "format": "date-time", "description": "When the document was filed for reference without an accounting posting. Null means it has not been filed for reference." }, "ocr_processed": { "type": [ "boolean", "null" ] }, "document_type": { "type": [ "string", "null" ] }, "document_classification": { "type": [ "string", "null" ] }, "description": { "type": [ "string", "null" ] }, "notes": { "type": [ "string", "null" ] }, "supplier_name": { "type": [ "string", "null" ] }, "invoice_number": { "type": [ "string", "null" ] }, "invoice_date": { "type": [ "string", "null" ], "format": "date" }, "net_amount": { "type": [ "number", "null" ] }, "vat_amount": { "type": [ "number", "null" ] }, "gross_amount": { "type": [ "number", "null" ] }, "currency": { "type": [ "string", "null" ] }, "linked_invoice_id": { "type": [ "string", "null" ], "format": "uuid" }, "linked_purchase_invoice_id": { "type": [ "string", "null" ], "format": "uuid" }, "linked_purchase_order_id": { "type": [ "string", "null" ], "format": "uuid" }, "linked_bank_transaction_id": { "type": [ "string", "null" ], "format": "uuid" }, "customer_id": { "type": [ "string", "null" ], "format": "uuid" }, "supplier_id": { "type": [ "string", "null" ], "format": "uuid" }, "created_at": { "type": [ "string", "null" ], "format": "date-time" }, "updated_at": { "type": [ "string", "null" ], "format": "date-time" } } }, "V1BusinessDocumentListResponse": { "type": "object", "required": [ "data", "meta" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/BusinessDocument" } }, "meta": { "$ref": "#/components/schemas/V1BusinessDocumentListMeta" } } }, "V1BusinessDocumentResponse": { "type": "object", "required": [ "data", "meta" ], "properties": { "data": { "$ref": "#/components/schemas/BusinessDocument" }, "meta": { "$ref": "#/components/schemas/V1BusinessDocumentMeta" } } }, "V1BusinessDocumentListMeta": { "type": "object", "required": [ "api_version", "mode", "pagination", "request_id", "resource" ], "properties": { "api_version": { "type": "string", "const": "v1-2026-07" }, "mode": { "type": "string", "const": "list" }, "pagination": { "$ref": "#/components/schemas/V1PaginationMeta" }, "request_id": { "type": "string", "minLength": 1, "maxLength": 128 }, "resource": { "type": "string", "const": "business_document" } } }, "V1BusinessDocumentMeta": { "type": "object", "required": [ "api_version", "mode", "request_id", "resource" ], "properties": { "api_version": { "type": "string", "const": "v1-2026-07" }, "mode": { "type": "string", "const": "detail" }, "request_id": { "type": "string", "minLength": 1, "maxLength": 128 }, "resource": { "type": "string", "const": "business_document" } } }, "BusinessApprovalRequest": { "type": "object", "additionalProperties": false, "required": [ "object", "id", "company_id", "status", "resource_type" ], "properties": { "object": { "type": "string", "const": "approval_request" }, "id": { "type": "string", "format": "uuid" }, "company_id": { "type": "string", "format": "uuid" }, "workflow_id": { "type": [ "string", "null" ], "format": "uuid" }, "resource_type": { "type": [ "string", "null" ] }, "resource_id": { "type": [ "string", "null" ] }, "requested_action": { "type": "string" }, "requested_by": { "type": [ "string", "null" ], "format": "uuid" }, "status": { "type": "string" }, "current_step_id": { "type": [ "string", "null" ], "format": "uuid" }, "current_step_order": { "type": [ "integer", "null" ] }, "info_requested_at": { "type": [ "string", "null" ], "format": "date-time" }, "info_requested_by": { "type": [ "string", "null" ], "format": "uuid" }, "info_request_message": { "type": [ "string", "null" ] }, "rejection_reason": { "type": [ "string", "null" ] }, "approved_by": { "type": [ "string", "null" ], "format": "uuid" }, "approved_at": { "type": [ "string", "null" ], "format": "date-time" }, "created_at": { "type": [ "string", "null" ], "format": "date-time" }, "updated_at": { "type": [ "string", "null" ], "format": "date-time" }, "policy": { "type": "object", "additionalProperties": false, "required": [ "decision", "reason" ], "properties": { "decision": { "type": "string" }, "reason": { "type": "string" } } } } }, "BusinessApprovalRequestApproveRequest": { "type": "object", "additionalProperties": false, "properties": { "comment": { "type": [ "string", "null" ], "maxLength": 1000, "description": "Optional approval comment to write to the approval audit trail." } } }, "BusinessApprovalRequestRejectRequest": { "type": "object", "additionalProperties": false, "required": [ "reason" ], "properties": { "reason": { "type": "string", "minLength": 1, "maxLength": 1000, "description": "Required reason to write to the rejection audit trail." } } }, "V1BusinessApprovalRequestListResponse": { "type": "object", "required": [ "data", "meta" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/BusinessApprovalRequest" } }, "meta": { "$ref": "#/components/schemas/V1BusinessApprovalRequestListMeta" } } }, "V1BusinessApprovalRequestResponse": { "type": "object", "required": [ "data", "meta" ], "properties": { "data": { "$ref": "#/components/schemas/BusinessApprovalRequest" }, "meta": { "$ref": "#/components/schemas/V1BusinessApprovalRequestMeta" } } }, "V1BusinessApprovalRequestApproveResponse": { "type": "object", "required": [ "data", "meta" ], "properties": { "data": { "$ref": "#/components/schemas/BusinessApprovalRequest" }, "meta": { "$ref": "#/components/schemas/V1BusinessApprovalRequestApproveMeta" } } }, "V1BusinessApprovalRequestRejectResponse": { "type": "object", "required": [ "data", "meta" ], "properties": { "data": { "$ref": "#/components/schemas/BusinessApprovalRequest" }, "meta": { "$ref": "#/components/schemas/V1BusinessApprovalRequestRejectMeta" } } }, "V1BusinessApprovalRequestListMeta": { "type": "object", "required": [ "api_version", "mode", "pagination", "request_id", "resource" ], "properties": { "api_version": { "type": "string", "const": "v1-2026-07" }, "mode": { "type": "string", "const": "list" }, "pagination": { "$ref": "#/components/schemas/V1PaginationMeta" }, "request_id": { "type": "string", "minLength": 1, "maxLength": 128 }, "resource": { "type": "string", "const": "approval_request" } } }, "V1BusinessApprovalRequestApproveMeta": { "type": "object", "required": [ "api_version", "mode", "request_id", "resource", "scope" ], "properties": { "api_version": { "type": "string", "const": "v1-2026-07" }, "mode": { "type": "string", "enum": [ "approved", "approval_recorded" ] }, "request_id": { "type": "string", "minLength": 1, "maxLength": 128 }, "resource": { "type": "string", "const": "approval_request" }, "scope": { "type": "string", "const": "business.approval_requests.approve" } } }, "V1BusinessApprovalRequestRejectMeta": { "type": "object", "required": [ "api_version", "mode", "request_id", "resource", "scope" ], "properties": { "api_version": { "type": "string", "const": "v1-2026-07" }, "mode": { "type": "string", "const": "rejected" }, "request_id": { "type": "string", "minLength": 1, "maxLength": 128 }, "resource": { "type": "string", "const": "approval_request" }, "scope": { "type": "string", "const": "business.approval_requests.reject" } } }, "V1BusinessApprovalRequestMeta": { "type": "object", "required": [ "api_version", "mode", "request_id", "resource" ], "properties": { "api_version": { "type": "string", "const": "v1-2026-07" }, "mode": { "type": "string", "const": "detail" }, "request_id": { "type": "string", "minLength": 1, "maxLength": 128 }, "resource": { "type": "string", "const": "approval_request" } } }, "BusinessAuditLog": { "type": "object", "additionalProperties": false, "required": [ "object", "id", "company_id", "action", "resource_type", "resource_id", "created_at" ], "properties": { "object": { "type": "string", "const": "business_audit_log" }, "id": { "type": "string", "format": "uuid" }, "company_id": { "type": "string", "format": "uuid" }, "action": { "type": "string" }, "resource_type": { "type": "string" }, "resource_id": { "type": "string" }, "created_at": { "type": [ "string", "null" ], "format": "date-time" } } }, "V1BusinessAuditLogListMeta": { "type": "object", "additionalProperties": false, "required": [ "api_version", "mode", "resource", "request_id", "pagination" ], "properties": { "api_version": { "type": "string", "const": "v1-2026-07" }, "mode": { "type": "string", "const": "list" }, "resource": { "type": "string", "const": "business_audit_log" }, "request_id": { "type": "string", "minLength": 1, "maxLength": 128 }, "pagination": { "$ref": "#/components/schemas/V1PaginationMeta" } } }, "V1BusinessAuditLogDetailMeta": { "type": "object", "additionalProperties": false, "required": [ "api_version", "mode", "resource", "request_id" ], "properties": { "api_version": { "type": "string", "const": "v1-2026-07" }, "mode": { "type": "string", "const": "detail" }, "resource": { "type": "string", "const": "business_audit_log" }, "request_id": { "type": "string", "minLength": 1, "maxLength": 128 } } }, "BusinessAuditLogListResponse": { "type": "object", "additionalProperties": false, "required": [ "data", "meta" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/BusinessAuditLog" } }, "meta": { "$ref": "#/components/schemas/V1BusinessAuditLogListMeta" } } }, "BusinessAuditLogDetailResponse": { "type": "object", "additionalProperties": false, "required": [ "data", "meta" ], "properties": { "data": { "$ref": "#/components/schemas/BusinessAuditLog" }, "meta": { "$ref": "#/components/schemas/V1BusinessAuditLogDetailMeta" } } }, "ExpenseClaimClaimant": { "type": "object", "additionalProperties": false, "required": [ "id", "name" ], "properties": { "id": { "type": "string", "format": "uuid" }, "name": { "type": [ "string", "null" ] } } }, "ExpenseClaimFund": { "type": "object", "additionalProperties": false, "required": [ "id", "name" ], "properties": { "id": { "type": "string", "format": "uuid" }, "name": { "type": [ "string", "null" ] } } }, "ExpenseClaimLineItemSupplier": { "type": "object", "additionalProperties": false, "required": [ "id", "name" ], "properties": { "id": { "type": "string", "format": "uuid" }, "name": { "type": [ "string", "null" ] } } }, "ExpenseClaimLineItem": { "type": "object", "additionalProperties": false, "required": [ "id" ], "properties": { "id": { "type": "string", "format": "uuid" }, "expense_claim_id": { "type": [ "string", "null" ], "format": "uuid" }, "supplier_id": { "type": [ "string", "null" ], "format": "uuid" }, "supplier_name_freetext": { "type": [ "string", "null" ] }, "supplier": { "anyOf": [ { "$ref": "#/components/schemas/ExpenseClaimLineItemSupplier" }, { "type": "null" } ] }, "description": { "type": [ "string", "null" ] }, "expense_date": { "type": [ "string", "null" ], "format": "date" }, "receipt_reference": { "type": [ "string", "null" ] }, "quantity": { "type": [ "number", "null" ] }, "unit_price": { "type": [ "number", "null" ] }, "vat_rate": { "type": [ "number", "null" ] }, "net_amount": { "type": [ "number", "null" ] }, "vat_amount": { "type": [ "number", "null" ] }, "gross_amount": { "type": [ "number", "null" ] }, "chart_of_accounts_id": { "type": [ "string", "null" ], "format": "uuid" }, "document_id": { "type": [ "string", "null" ], "format": "uuid" }, "fund_id": { "type": [ "string", "null" ], "format": "uuid" }, "charity_activity_id": { "type": [ "string", "null" ], "format": "uuid" }, "created_at": { "type": [ "string", "null" ], "format": "date-time" }, "project_id": { "type": [ "string", "null" ], "format": "uuid" } } }, "ExpenseClaim": { "type": "object", "additionalProperties": false, "required": [ "id", "company_id", "object", "claimant_id" ], "properties": { "object": { "type": "string", "const": "expense_claim" }, "id": { "type": "string", "format": "uuid" }, "company_id": { "type": "string", "format": "uuid" }, "claimant_id": { "type": [ "string", "null" ], "format": "uuid" }, "claimant": { "anyOf": [ { "$ref": "#/components/schemas/ExpenseClaimClaimant" }, { "type": "null" } ] }, "internal_reference": { "type": [ "string", "null" ] }, "claim_date": { "type": [ "string", "null" ], "format": "date" }, "due_date": { "type": [ "string", "null" ], "format": "date" }, "currency": { "type": [ "string", "null" ] }, "gross_amount": { "type": [ "number", "null" ] }, "net_amount": { "type": [ "number", "null" ] }, "vat_amount": { "type": [ "number", "null" ] }, "status": { "type": [ "string", "null" ] }, "payment_status": { "type": [ "string", "null" ] }, "approval_status": { "type": [ "string", "null" ] }, "notes": { "type": [ "string", "null" ] }, "fund_id": { "type": [ "string", "null" ], "format": "uuid" }, "fund": { "anyOf": [ { "$ref": "#/components/schemas/ExpenseClaimFund" }, { "type": "null" } ] }, "cost_center_selections": { "type": [ "object", "null" ], "additionalProperties": true }, "journal_transaction_id": { "type": [ "string", "null" ], "format": "uuid" }, "reversing_transaction_id": { "type": [ "string", "null" ], "format": "uuid" }, "document_id": { "type": [ "string", "null" ], "format": "uuid" }, "submitted_by_name": { "type": [ "string", "null" ] }, "created_by": { "type": [ "string", "null" ], "format": "uuid" }, "created_at": { "type": [ "string", "null" ], "format": "date-time" }, "updated_at": { "type": [ "string", "null" ], "format": "date-time" }, "lock_version": { "type": [ "number", "null" ] }, "repayment_method": { "type": [ "string", "null" ] }, "dla_account_id": { "type": [ "string", "null" ], "format": "uuid" }, "purchase_invoice_id": { "type": [ "string", "null" ], "format": "uuid" }, "linked_supplier_id": { "type": [ "string", "null" ], "format": "uuid" }, "line_items": { "type": "array", "items": { "$ref": "#/components/schemas/ExpenseClaimLineItem" } } } }, "V1BusinessExpenseClaimListResponse": { "type": "object", "required": [ "data", "meta" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/ExpenseClaim" } }, "meta": { "$ref": "#/components/schemas/V1BusinessExpenseClaimListMeta" } } }, "V1BusinessExpenseClaimResponse": { "type": "object", "required": [ "data", "meta" ], "properties": { "data": { "$ref": "#/components/schemas/ExpenseClaim" }, "meta": { "$ref": "#/components/schemas/V1BusinessExpenseClaimMeta" } } }, "V1BusinessExpenseClaimListMeta": { "type": "object", "required": [ "api_version", "mode", "pagination", "request_id", "resource" ], "properties": { "api_version": { "type": "string", "const": "v1-2026-07" }, "mode": { "type": "string", "const": "list" }, "pagination": { "$ref": "#/components/schemas/V1PaginationMeta" }, "request_id": { "type": "string", "minLength": 1, "maxLength": 128 }, "resource": { "type": "string", "const": "expense_claim" } } }, "V1BusinessExpenseClaimMeta": { "type": "object", "required": [ "api_version", "mode", "request_id", "resource" ], "properties": { "api_version": { "type": "string", "const": "v1-2026-07" }, "mode": { "type": "string", "const": "detail" }, "request_id": { "type": "string", "minLength": 1, "maxLength": 128 }, "resource": { "type": "string", "const": "expense_claim" } } }, "BusinessReportSummaryPeriod": { "type": "object", "additionalProperties": false, "required": [ "from_date", "to_date" ], "properties": { "from_date": { "type": "string", "format": "date" }, "to_date": { "type": "string", "format": "date" } } }, "BusinessReportSummaryTotals": { "type": "object", "additionalProperties": false, "required": [ "net_cash_movement", "total_cash_expenses", "total_cash_income", "total_invoiced" ], "properties": { "net_cash_movement": { "type": "number", "description": "Cash income less cash expenses for the period." }, "total_cash_expenses": { "type": "number", "description": "Absolute value of cash outflows for the period." }, "total_cash_income": { "type": "number", "description": "Cash inflows for the period." }, "total_invoiced": { "type": "number", "description": "Invoice totals dated inside the period." } } }, "BusinessReportSummaryCounts": { "type": "object", "additionalProperties": false, "required": [ "cash_expense_count", "cash_income_count", "invoice_count", "transaction_count" ], "properties": { "cash_expense_count": { "type": "integer", "minimum": 0 }, "cash_income_count": { "type": "integer", "minimum": 0 }, "invoice_count": { "type": "integer", "minimum": 0 }, "transaction_count": { "type": "integer", "minimum": 0 } } }, "BusinessReportSummaryFreshness": { "type": "object", "additionalProperties": false, "required": [ "latest_transaction_date", "pending_approval_count", "unprocessed_document_count" ], "properties": { "latest_transaction_date": { "type": [ "string", "null" ], "format": "date" }, "pending_approval_count": { "type": "integer", "minimum": 0 }, "unprocessed_document_count": { "type": "integer", "minimum": 0 } } }, "BusinessFundMovementRow": {"type":"object","additionalProperties":false,"required":["closing_balance","closing_reconciliation_diff","expenditure_total","fund_class","fund_id","fund_name","gains_losses_total","income_total","opening_balance","transfers_total","unrestricted_subtype"],"properties":{"closing_balance":{"type":"number"},"closing_reconciliation_diff":{"type":"number"},"expenditure_total":{"type":"number"},"fund_class":{"type":"string"},"fund_id":{"type":"string","format":"uuid"},"fund_name":{"type":"string"},"gains_losses_total":{"type":"number"},"income_total":{"type":"number"},"opening_balance":{"type":"number"},"transfers_total":{"type":"number"},"unrestricted_subtype":{"type":["string","null"]}}}, "BusinessFundMovementReport": {"type":"object","additionalProperties":false,"required":["company_id","funds","generated_at","object","period","report_type"],"properties":{"object":{"type":"string","const":"business_fund_movement_report"},"company_id":{"type":"string","format":"uuid"},"report_type":{"type":"string","const":"fund_movement"},"period":{"type":"object","additionalProperties":false,"required":["from","to"],"properties":{"from":{"type":"string","format":"date"},"to":{"type":"string","format":"date"}}},"funds":{"type":"array","items":{"$ref":"#/components/schemas/BusinessFundMovementRow"}},"generated_at":{"type":"string","format":"date-time"}}}, "V1BusinessFundMovementReportMeta": {"type":"object","required":["api_version","mode","request_id","resource"],"properties":{"api_version":{"type":"string","const":"v1-2026-07"},"mode":{"type":"string","const":"report"},"request_id":{"type":"string","minLength":1,"maxLength":128},"resource":{"type":"string","const":"business_fund_movement_report"}}}, "V1BusinessFundMovementReportResponse": {"type":"object","required":["data","meta"],"properties":{"data":{"$ref":"#/components/schemas/BusinessFundMovementReport"},"meta":{"$ref":"#/components/schemas/V1BusinessFundMovementReportMeta"}}}, "BusinessReportSummary": { "type": "object", "additionalProperties": false, "required": [ "company_id", "counts", "generated_at", "freshness", "object", "period", "report_type", "totals" ], "properties": { "object": { "type": "string", "const": "business_report_summary" }, "company_id": { "type": "string", "format": "uuid" }, "report_type": { "type": "string", "const": "summary" }, "period": { "$ref": "#/components/schemas/BusinessReportSummaryPeriod" }, "totals": { "$ref": "#/components/schemas/BusinessReportSummaryTotals" }, "counts": { "$ref": "#/components/schemas/BusinessReportSummaryCounts" }, "generated_at": { "type": "string", "format": "date-time" }, "freshness": { "$ref": "#/components/schemas/BusinessReportSummaryFreshness" } } }, "V1BusinessReportSummaryMeta": { "type": "object", "required": [ "api_version", "mode", "request_id", "resource" ], "properties": { "api_version": { "type": "string", "const": "v1-2026-07" }, "mode": { "type": "string", "const": "summary" }, "request_id": { "type": "string", "minLength": 1, "maxLength": 128 }, "resource": { "type": "string", "const": "business_report" } } }, "V1BusinessReportSummaryResponse": { "type": "object", "required": [ "data", "meta" ], "properties": { "data": { "$ref": "#/components/schemas/BusinessReportSummary" }, "meta": { "$ref": "#/components/schemas/V1BusinessReportSummaryMeta" } } }, "BusinessProfitLossAccountLine": { "type": "object", "additionalProperties": false, "required": [ "object", "chart_of_accounts_id", "code", "name", "account_type", "financial_statement", "area", "ma_category", "ma_sub_category", "amount" ], "properties": { "object": { "type": "string", "const": "business_profit_loss_account_line" }, "chart_of_accounts_id": { "type": [ "string", "null" ], "format": "uuid" }, "code": { "type": [ "string", "null" ] }, "name": { "type": [ "string", "null" ] }, "account_type": { "type": [ "string", "null" ] }, "financial_statement": { "type": [ "string", "null" ] }, "area": { "type": [ "string", "null" ] }, "ma_category": { "type": [ "string", "null" ] }, "ma_sub_category": { "type": [ "string", "null" ] }, "amount": { "type": "number" } } }, "BusinessProfitLossSection": { "type": "object", "additionalProperties": false, "required": [ "object", "section", "accounts", "total" ], "properties": { "object": { "type": "string", "const": "business_profit_loss_section" }, "section": { "type": "string", "enum": [ "revenue", "cost_of_sales", "operating_expenses", "other_operating_income", "interest_receivable", "interest_payable", "tax_on_profit", "uncategorised" ] }, "accounts": { "type": "array", "items": { "$ref": "#/components/schemas/BusinessProfitLossAccountLine" } }, "total": { "type": "number" } } }, "BusinessProfitLossSections": { "type": "object", "additionalProperties": false, "description": "The statutory profit-and-loss lines, as the statutory accounts show them. Each account sits on the line its statutory heading names; figures read positive when they are what the line's name says.", "required": [ "revenue", "cost_of_sales", "operating_expenses", "other_operating_income", "interest_receivable", "interest_payable", "tax_on_profit", "uncategorised" ], "properties": { "revenue": { "$ref": "#/components/schemas/BusinessProfitLossSection", "description": "Turnover: accounts headed Turnover in the statutory mapping." }, "cost_of_sales": { "$ref": "#/components/schemas/BusinessProfitLossSection", "description": "Cost of sales." }, "operating_expenses": { "$ref": "#/components/schemas/BusinessProfitLossSection", "description": "Administrative expenses. Other operating income, interest and tax are reported in their own sections." }, "other_operating_income": { "$ref": "#/components/schemas/BusinessProfitLossSection", "description": "Other operating income." }, "interest_receivable": { "$ref": "#/components/schemas/BusinessProfitLossSection", "description": "Interest receivable and similar income." }, "interest_payable": { "$ref": "#/components/schemas/BusinessProfitLossSection", "description": "Interest payable and similar charges." }, "tax_on_profit": { "$ref": "#/components/schemas/BusinessProfitLossSection", "description": "Tax on profit." }, "uncategorised": { "$ref": "#/components/schemas/BusinessProfitLossSection", "description": "Money on the profit-and-loss holding accounts, not yet categorised. Amounts are the net effect on profit: receipts positive, payments negative." } } }, "BusinessProfitLossTotals": { "type": "object", "additionalProperties": false, "required": [ "total_revenue", "total_cost_of_sales", "gross_profit", "total_operating_expenses", "total_other_operating_income", "operating_profit", "total_interest_receivable", "total_interest_payable", "profit_before_tax", "total_tax_on_profit", "total_uncategorised", "net_profit" ], "properties": { "total_revenue": { "type": "number" }, "total_cost_of_sales": { "type": "number" }, "gross_profit": { "type": "number" }, "total_operating_expenses": { "type": "number", "description": "Administrative expenses only." }, "total_other_operating_income": { "type": "number" }, "operating_profit": { "type": "number", "description": "Gross profit less administrative expenses plus other operating income." }, "total_interest_receivable": { "type": "number" }, "total_interest_payable": { "type": "number" }, "profit_before_tax": { "type": "number", "description": "Operating profit plus interest receivable less interest payable." }, "total_tax_on_profit": { "type": "number" }, "total_uncategorised": { "type": "number", "description": "Net effect on profit of money not yet categorised." }, "net_profit": { "type": "number", "description": "Profit before tax less tax on profit, plus money not yet categorised: the bottom line after every line of the report." } } }, "BusinessProfitLossReport": { "type": "object", "additionalProperties": false, "required": [ "object", "company_id", "report_type", "accounting_basis", "period", "sections", "totals", "generated_at" ], "properties": { "object": { "type": "string", "const": "business_profit_loss_report" }, "company_id": { "type": "string", "format": "uuid" }, "report_type": { "type": "string", "const": "profit_loss" }, "accounting_basis": { "type": "string", "const": "accrual" }, "period": { "$ref": "#/components/schemas/BusinessReportSummaryPeriod" }, "sections": { "$ref": "#/components/schemas/BusinessProfitLossSections" }, "totals": { "$ref": "#/components/schemas/BusinessProfitLossTotals" }, "generated_at": { "type": "string", "format": "date-time" } } }, "V1BusinessProfitLossReportMeta": { "type": "object", "additionalProperties": false, "required": [ "api_version", "mode", "request_id", "resource" ], "properties": { "api_version": { "type": "string", "const": "v1-2026-07" }, "mode": { "type": "string", "const": "report" }, "request_id": { "type": "string", "minLength": 1, "maxLength": 128 }, "resource": { "type": "string", "const": "business_profit_loss_report" } } }, "V1BusinessProfitLossReportResponse": { "type": "object", "additionalProperties": false, "required": [ "data", "meta" ], "properties": { "data": { "$ref": "#/components/schemas/BusinessProfitLossReport" }, "meta": { "$ref": "#/components/schemas/V1BusinessProfitLossReportMeta" } } }, "BusinessTrialBalanceAccountLine": { "type": "object", "additionalProperties": false, "required": [ "object", "account_id", "code", "name", "account_type", "financial_statement", "area", "ma_sub_category", "statutory_category", "statutory_subcategory", "debit_balance", "credit_balance", "net_balance" ], "properties": { "object": { "type": "string", "const": "business_trial_balance_account_line" }, "account_id": { "type": [ "string", "null" ], "format": "uuid" }, "code": { "type": [ "string", "null" ] }, "name": { "type": [ "string", "null" ] }, "account_type": { "type": [ "string", "null" ] }, "financial_statement": { "type": [ "string", "null" ] }, "area": { "type": [ "string", "null" ] }, "ma_sub_category": { "type": [ "string", "null" ] }, "statutory_category": { "type": [ "string", "null" ] }, "statutory_subcategory": { "type": [ "string", "null" ] }, "debit_balance": { "type": "number" }, "credit_balance": { "type": "number" }, "net_balance": { "type": "number" } } }, "BusinessTrialBalanceTotals": { "type": "object", "additionalProperties": false, "required": [ "account_count", "total_debits", "total_credits" ], "properties": { "account_count": { "type": "integer", "minimum": 0 }, "total_debits": { "type": "number" }, "total_credits": { "type": "number" } } }, "BusinessTrialBalanceReport": { "type": "object", "additionalProperties": false, "required": [ "object", "company_id", "report_type", "currency", "as_at_date", "current_period_start", "generated_at", "is_balanced", "lines", "totals" ], "properties": { "object": { "type": "string", "const": "business_trial_balance_report" }, "company_id": { "type": "string", "format": "uuid" }, "report_type": { "type": "string", "const": "trial_balance" }, "currency": { "type": "string", "const": "GBP" }, "as_at_date": { "type": "string", "format": "date" }, "current_period_start": { "type": [ "string", "null" ], "format": "date" }, "generated_at": { "type": "string", "format": "date-time" }, "is_balanced": { "type": "boolean" }, "lines": { "type": "array", "items": { "$ref": "#/components/schemas/BusinessTrialBalanceAccountLine" } }, "totals": { "$ref": "#/components/schemas/BusinessTrialBalanceTotals" } } }, "V1BusinessTrialBalanceReportMeta": { "type": "object", "additionalProperties": false, "required": [ "api_version", "mode", "request_id", "resource" ], "properties": { "api_version": { "type": "string", "const": "v1-2026-07" }, "mode": { "type": "string", "const": "report" }, "request_id": { "type": "string", "minLength": 1, "maxLength": 128 }, "resource": { "type": "string", "const": "business_trial_balance_report" } } }, "V1BusinessTrialBalanceReportResponse": { "type": "object", "additionalProperties": false, "required": [ "data", "meta" ], "properties": { "data": { "$ref": "#/components/schemas/BusinessTrialBalanceReport" }, "meta": { "$ref": "#/components/schemas/V1BusinessTrialBalanceReportMeta" } } }, "BusinessBalanceSheetAccountLine": { "type": "object", "additionalProperties": false, "required": [ "object", "line_type", "side", "account_id", "code", "name", "account_type", "financial_statement", "area", "ma_category", "ma_sub_category", "statutory_category", "statutory_subcategory", "debit_total", "credit_total", "amount" ], "properties": { "object": { "type": "string", "const": "business_balance_sheet_account_line" }, "line_type": { "type": "string", "enum": [ "account", "current_period_profit" ] }, "side": { "type": "string", "enum": [ "asset", "liability", "equity", "unclassified" ] }, "account_id": { "type": [ "string", "null" ], "format": "uuid" }, "code": { "type": [ "string", "null" ] }, "name": { "type": [ "string", "null" ] }, "account_type": { "type": [ "string", "null" ] }, "financial_statement": { "type": [ "string", "null" ] }, "area": { "type": [ "string", "null" ] }, "ma_category": { "type": [ "string", "null" ] }, "ma_sub_category": { "type": [ "string", "null" ] }, "statutory_category": { "type": [ "string", "null" ] }, "statutory_subcategory": { "type": [ "string", "null" ] }, "debit_total": { "type": [ "number", "null" ] }, "credit_total": { "type": [ "number", "null" ] }, "amount": { "type": "number" } } }, "BusinessBalanceSheetSection": { "type": "object", "additionalProperties": false, "required": [ "object", "section", "accounts", "total" ], "properties": { "object": { "type": "string", "const": "business_balance_sheet_section" }, "section": { "type": "string", "enum": [ "asset", "liability", "equity", "unclassified" ] }, "accounts": { "type": "array", "items": { "$ref": "#/components/schemas/BusinessBalanceSheetAccountLine" } }, "total": { "type": "number" } } }, "BusinessBalanceSheetSections": { "type": "object", "additionalProperties": false, "required": [ "assets", "liabilities", "equity", "unclassified" ], "properties": { "assets": { "$ref": "#/components/schemas/BusinessBalanceSheetSection" }, "liabilities": { "$ref": "#/components/schemas/BusinessBalanceSheetSection" }, "equity": { "$ref": "#/components/schemas/BusinessBalanceSheetSection" }, "unclassified": { "$ref": "#/components/schemas/BusinessBalanceSheetSection" } } }, "BusinessBalanceSheetTotals": { "type": "object", "additionalProperties": false, "required": [ "total_assets", "total_liabilities", "total_equity", "total_liabilities_and_equity", "total_unclassified", "current_period_profit", "balance_check" ], "properties": { "total_assets": { "type": "number" }, "total_liabilities": { "type": "number" }, "total_equity": { "type": "number" }, "total_liabilities_and_equity": { "type": "number" }, "total_unclassified": { "type": "number" }, "current_period_profit": { "type": "number" }, "balance_check": { "type": "number" } } }, "BusinessBalanceSheetReport": { "type": "object", "additionalProperties": false, "required": [ "object", "company_id", "report_type", "accounting_basis", "currency", "as_at_date", "current_period_start", "generated_at", "is_balanced", "sections", "totals" ], "properties": { "object": { "type": "string", "const": "business_balance_sheet_report" }, "company_id": { "type": "string", "format": "uuid" }, "report_type": { "type": "string", "const": "balance_sheet" }, "accounting_basis": { "type": "string", "const": "accrual" }, "currency": { "type": "string", "const": "GBP" }, "as_at_date": { "type": "string", "format": "date" }, "current_period_start": { "type": "string", "format": "date" }, "generated_at": { "type": "string", "format": "date-time" }, "is_balanced": { "type": "boolean" }, "sections": { "$ref": "#/components/schemas/BusinessBalanceSheetSections" }, "totals": { "$ref": "#/components/schemas/BusinessBalanceSheetTotals" } } }, "V1BusinessBalanceSheetReportMeta": { "type": "object", "additionalProperties": false, "required": [ "api_version", "mode", "request_id", "resource" ], "properties": { "api_version": { "type": "string", "const": "v1-2026-07" }, "mode": { "type": "string", "const": "report" }, "request_id": { "type": "string", "minLength": 1, "maxLength": 128 }, "resource": { "type": "string", "const": "business_balance_sheet_report" } } }, "V1BusinessBalanceSheetReportResponse": { "type": "object", "additionalProperties": false, "required": [ "data", "meta" ], "properties": { "data": { "$ref": "#/components/schemas/BusinessBalanceSheetReport" }, "meta": { "$ref": "#/components/schemas/V1BusinessBalanceSheetReportMeta" } } }, "BusinessCashFlowLine": { "type": "object", "additionalProperties": false, "required": [ "object", "label", "amount" ], "properties": { "object": { "type": "string", "const": "business_cash_flow_line" }, "label": { "type": "string", "minLength": 1 }, "amount": { "type": "number" } } }, "BusinessCashFlowSection": { "type": "object", "additionalProperties": false, "required": [ "object", "section", "title", "rows", "total" ], "properties": { "object": { "type": "string", "const": "business_cash_flow_section" }, "section": { "type": "string", "enum": [ "operating_activities", "investing_activities", "financing_activities" ] }, "title": { "type": "string" }, "rows": { "type": "array", "items": { "$ref": "#/components/schemas/BusinessCashFlowLine" } }, "total": { "type": "number" } } }, "BusinessCashFlowSections": { "type": "object", "additionalProperties": false, "required": [ "operating_activities", "investing_activities", "financing_activities" ], "properties": { "operating_activities": { "$ref": "#/components/schemas/BusinessCashFlowSection" }, "investing_activities": { "$ref": "#/components/schemas/BusinessCashFlowSection" }, "financing_activities": { "$ref": "#/components/schemas/BusinessCashFlowSection" } } }, "BusinessCashFlowPeriod": { "type": "object", "additionalProperties": false, "required": [ "from_date", "opening_balance_date", "to_date" ], "properties": { "from_date": { "type": "string", "format": "date" }, "opening_balance_date": { "type": "string", "format": "date" }, "to_date": { "type": "string", "format": "date" } } }, "BusinessCashFlowTotals": { "type": "object", "additionalProperties": false, "required": [ "opening_cash", "closing_cash", "net_change", "total_operating_activities", "total_investing_activities", "total_financing_activities", "activity_total", "reconciliation_difference" ], "properties": { "opening_cash": { "type": "number" }, "closing_cash": { "type": "number" }, "net_change": { "type": "number" }, "total_operating_activities": { "type": "number" }, "total_investing_activities": { "type": "number" }, "total_financing_activities": { "type": "number" }, "activity_total": { "type": "number" }, "reconciliation_difference": { "type": "number" } } }, "BusinessCashFlowReport": { "type": "object", "additionalProperties": false, "required": [ "object", "company_id", "report_type", "accounting_basis", "currency", "period", "generated_at", "is_reconciled", "sections", "totals" ], "properties": { "object": { "type": "string", "const": "business_cash_flow_report" }, "company_id": { "type": "string", "format": "uuid" }, "report_type": { "type": "string", "const": "cash_flow" }, "accounting_basis": { "type": "string", "const": "indirect" }, "currency": { "type": "string", "const": "GBP" }, "period": { "$ref": "#/components/schemas/BusinessCashFlowPeriod" }, "generated_at": { "type": "string", "format": "date-time" }, "is_reconciled": { "type": "boolean" }, "sections": { "$ref": "#/components/schemas/BusinessCashFlowSections" }, "totals": { "$ref": "#/components/schemas/BusinessCashFlowTotals" } } }, "V1BusinessCashFlowReportMeta": { "type": "object", "additionalProperties": false, "required": [ "api_version", "mode", "request_id", "resource" ], "properties": { "api_version": { "type": "string", "const": "v1-2026-07" }, "mode": { "type": "string", "const": "report" }, "request_id": { "type": "string", "minLength": 1, "maxLength": 128 }, "resource": { "type": "string", "const": "business_cash_flow_report" } } }, "V1BusinessCashFlowReportResponse": { "type": "object", "additionalProperties": false, "required": [ "data", "meta" ], "properties": { "data": { "$ref": "#/components/schemas/BusinessCashFlowReport" }, "meta": { "$ref": "#/components/schemas/V1BusinessCashFlowReportMeta" } } }, "BusinessGeneralLedgerAccount": { "type": "object", "additionalProperties": false, "required": [ "object", "id", "code", "name", "account_type", "normal_balance", "is_active" ], "properties": { "object": { "type": "string", "const": "business_general_ledger_account" }, "id": { "type": "string", "format": "uuid", "nullable": true }, "code": { "type": "string", "nullable": true }, "name": { "type": "string", "nullable": true }, "account_type": { "type": "string", "nullable": true }, "financial_statement": { "type": "string", "nullable": true }, "normal_balance": { "type": "string", "enum": [ "debit", "credit" ] }, "is_active": { "type": "boolean" } } }, "BusinessGeneralLedgerPeriod": { "type": "object", "additionalProperties": false, "required": [ "from_date", "opening_balance_date", "to_date" ], "properties": { "from_date": { "type": "string", "format": "date" }, "opening_balance_date": { "type": "string", "format": "date" }, "to_date": { "type": "string", "format": "date" } } }, "BusinessGeneralLedgerLine": { "type": "object", "additionalProperties": false, "required": [ "object", "id", "journal_transaction_id", "chart_of_accounts_id", "transaction_date", "debit_amount", "credit_amount", "net_movement", "display_movement", "running_balance" ], "properties": { "object": { "type": "string", "const": "business_general_ledger_line" }, "id": { "type": "string", "format": "uuid", "nullable": true }, "journal_transaction_id": { "type": "string", "format": "uuid", "nullable": true }, "chart_of_accounts_id": { "type": "string", "format": "uuid", "nullable": true }, "transaction_date": { "type": "string", "nullable": true, "format": "date" }, "reference": { "type": "string", "nullable": true }, "description": { "type": "string", "nullable": true }, "debit_amount": { "type": "number" }, "credit_amount": { "type": "number" }, "net_movement": { "type": "number" }, "display_movement": { "type": "number" }, "running_balance": { "type": "number" }, "line_order": { "type": "number", "nullable": true }, "transaction_type": { "type": "string", "nullable": true }, "source_type": { "type": "string", "nullable": true }, "source_id": { "type": "string", "format": "uuid", "nullable": true }, "posting_origin": { "type": "string", "nullable": true }, "project_id": { "type": "string", "format": "uuid", "nullable": true }, "cost_center_id": { "type": "string", "format": "uuid", "nullable": true }, "fund_id": { "type": "string", "format": "uuid", "nullable": true }, "user_reference": { "type": "string", "nullable": true }, "created_at": { "type": "string", "format": "date-time", "nullable": true }, "updated_at": { "type": "string", "format": "date-time", "nullable": true } } }, "BusinessGeneralLedgerTotals": { "type": "object", "additionalProperties": false, "required": [ "opening_balance", "closing_balance", "total_net_movement", "matching_line_count", "page_line_count", "page_debit_total", "page_credit_total", "page_net_movement", "page_closing_balance" ], "properties": { "opening_balance": { "type": "number" }, "closing_balance": { "type": "number" }, "total_net_movement": { "type": "number" }, "matching_line_count": { "type": "integer", "minimum": 0 }, "page_line_count": { "type": "integer", "minimum": 0 }, "page_debit_total": { "type": "number" }, "page_credit_total": { "type": "number" }, "page_net_movement": { "type": "number" }, "page_closing_balance": { "type": "number" } } }, "BusinessGeneralLedgerReport": { "type": "object", "additionalProperties": false, "required": [ "object", "company_id", "report_type", "currency", "generated_at", "account", "period", "lines", "totals" ], "properties": { "object": { "type": "string", "const": "business_general_ledger_report" }, "company_id": { "type": "string", "format": "uuid" }, "report_type": { "type": "string", "const": "general_ledger" }, "currency": { "type": "string", "const": "GBP" }, "generated_at": { "type": "string", "format": "date-time" }, "account": { "$ref": "#/components/schemas/BusinessGeneralLedgerAccount" }, "period": { "$ref": "#/components/schemas/BusinessGeneralLedgerPeriod" }, "lines": { "type": "array", "items": { "$ref": "#/components/schemas/BusinessGeneralLedgerLine" } }, "totals": { "$ref": "#/components/schemas/BusinessGeneralLedgerTotals" } } }, "V1BusinessGeneralLedgerReportMeta": { "type": "object", "additionalProperties": false, "required": [ "api_version", "mode", "request_id", "resource", "pagination" ], "properties": { "api_version": { "type": "string", "const": "v1-2026-07" }, "mode": { "type": "string", "const": "report" }, "request_id": { "type": "string", "minLength": 1, "maxLength": 128 }, "resource": { "type": "string", "const": "business_general_ledger_report" }, "pagination": { "$ref": "#/components/schemas/V1PaginationMeta" } } }, "V1BusinessGeneralLedgerReportResponse": { "type": "object", "additionalProperties": false, "required": [ "data", "meta" ], "properties": { "data": { "$ref": "#/components/schemas/BusinessGeneralLedgerReport" }, "meta": { "$ref": "#/components/schemas/V1BusinessGeneralLedgerReportMeta" } } }, "BusinessAgedDebtorsBuckets": { "type": "object", "additionalProperties": false, "required": [ "current", "days_1_to_30", "days_31_to_60", "days_61_to_90", "over_90" ], "properties": { "current": { "type": "number" }, "days_1_to_30": { "type": "number" }, "days_31_to_60": { "type": "number" }, "days_61_to_90": { "type": "number" }, "over_90": { "type": "number" } } }, "BusinessAgedDebtorsInvoice": { "type": "object", "additionalProperties": false, "required": [ "object", "id", "customer_id", "customer_name", "invoice_number", "invoice_date", "due_date", "status", "days_overdue", "bucket", "total_amount", "amount_paid_at_date", "outstanding_at_date", "payment_status_at_date" ], "properties": { "object": { "type": "string", "const": "business_aged_debtors_invoice" }, "id": { "type": "string", "format": "uuid", "nullable": true }, "customer_id": { "type": "string", "format": "uuid", "nullable": true }, "customer_name": { "type": "string" }, "invoice_number": { "type": "string", "nullable": true }, "invoice_date": { "type": "string", "format": "date", "nullable": true }, "due_date": { "type": "string", "format": "date", "nullable": true }, "status": { "type": "string", "nullable": true }, "days_overdue": { "type": "integer", "minimum": 0 }, "bucket": { "type": "string", "enum": [ "current", "days_1_to_30", "days_31_to_60", "days_61_to_90", "over_90" ] }, "total_amount": { "type": "number" }, "amount_paid_at_date": { "type": "number" }, "outstanding_at_date": { "type": "number" }, "payment_status_at_date": { "type": "string", "enum": [ "unpaid", "partially_paid", "fully_paid" ] } } }, "BusinessAgedDebtorsCustomerSummary": { "type": "object", "additionalProperties": false, "required": [ "object", "customer_id", "customer_name", "invoice_count", "buckets", "total_outstanding" ], "properties": { "object": { "type": "string", "const": "business_aged_debtors_customer" }, "customer_id": { "type": "string", "format": "uuid", "nullable": true }, "customer_name": { "type": "string" }, "invoice_count": { "type": "integer", "minimum": 0 }, "buckets": { "$ref": "#/components/schemas/BusinessAgedDebtorsBuckets" }, "total_outstanding": { "type": "number" } } }, "BusinessAgedDebtorsTotals": { "type": "object", "additionalProperties": false, "required": [ "invoice_count", "page_invoice_count", "customer_count", "total_outstanding" ], "properties": { "invoice_count": { "type": "integer", "minimum": 0 }, "page_invoice_count": { "type": "integer", "minimum": 0 }, "customer_count": { "type": "integer", "minimum": 0 }, "total_outstanding": { "type": "number" } } }, "BusinessAgedDebtorsReport": { "type": "object", "additionalProperties": false, "required": [ "object", "company_id", "report_type", "scope", "currency", "generated_at", "as_of_date", "buckets", "customers", "invoices", "totals" ], "properties": { "object": { "type": "string", "const": "business_aged_debtors_report" }, "company_id": { "type": "string", "format": "uuid" }, "report_type": { "type": "string", "const": "aged_debtors" }, "scope": { "type": "string", "const": "invoice_backed" }, "currency": { "type": "string", "const": "GBP" }, "generated_at": { "type": "string", "format": "date-time" }, "as_of_date": { "type": "string", "format": "date" }, "buckets": { "$ref": "#/components/schemas/BusinessAgedDebtorsBuckets" }, "customers": { "type": "array", "items": { "$ref": "#/components/schemas/BusinessAgedDebtorsCustomerSummary" } }, "invoices": { "type": "array", "items": { "$ref": "#/components/schemas/BusinessAgedDebtorsInvoice" } }, "totals": { "$ref": "#/components/schemas/BusinessAgedDebtorsTotals" } } }, "V1BusinessAgedDebtorsReportMeta": { "type": "object", "additionalProperties": false, "required": [ "api_version", "mode", "request_id", "resource", "pagination" ], "properties": { "api_version": { "type": "string", "const": "v1-2026-07" }, "mode": { "type": "string", "const": "report" }, "request_id": { "type": "string", "minLength": 1, "maxLength": 128 }, "resource": { "type": "string", "const": "business_aged_debtors_report" }, "pagination": { "$ref": "#/components/schemas/V1PaginationMeta" } } }, "V1BusinessAgedDebtorsReportResponse": { "type": "object", "additionalProperties": false, "required": [ "data", "meta" ], "properties": { "data": { "$ref": "#/components/schemas/BusinessAgedDebtorsReport" }, "meta": { "$ref": "#/components/schemas/V1BusinessAgedDebtorsReportMeta" } } }, "BusinessAgedCreditorsBuckets": { "type": "object", "additionalProperties": false, "required": [ "current", "days_1_to_30", "days_31_to_60", "days_61_to_90", "over_90" ], "properties": { "current": { "type": "number" }, "days_1_to_30": { "type": "number" }, "days_31_to_60": { "type": "number" }, "days_61_to_90": { "type": "number" }, "over_90": { "type": "number" } } }, "BusinessAgedCreditorsPurchaseInvoice": { "type": "object", "additionalProperties": false, "required": [ "object", "id", "supplier_id", "supplier_name", "supplier_invoice_number", "internal_reference", "invoice_date", "due_date", "status", "payment_status", "days_overdue", "bucket", "total_amount", "amount_paid_at_date", "outstanding_at_date", "payment_status_at_date" ], "properties": { "object": { "type": "string", "const": "business_aged_creditors_purchase_invoice" }, "id": { "type": "string", "format": "uuid", "nullable": true }, "supplier_id": { "type": "string", "format": "uuid", "nullable": true }, "supplier_name": { "type": "string" }, "supplier_invoice_number": { "type": "string", "nullable": true }, "internal_reference": { "type": "string", "nullable": true }, "invoice_date": { "type": "string", "format": "date", "nullable": true }, "due_date": { "type": "string", "format": "date", "nullable": true }, "status": { "type": "string", "nullable": true }, "payment_status": { "type": "string", "nullable": true }, "days_overdue": { "type": "integer", "minimum": 0 }, "bucket": { "type": "string", "enum": [ "current", "days_1_to_30", "days_31_to_60", "days_61_to_90", "over_90" ] }, "total_amount": { "type": "number" }, "amount_paid_at_date": { "type": "number" }, "outstanding_at_date": { "type": "number" }, "payment_status_at_date": { "type": "string", "enum": [ "unpaid", "partially_paid", "fully_paid" ] } } }, "BusinessAgedCreditorsSupplierSummary": { "type": "object", "additionalProperties": false, "required": [ "object", "supplier_id", "supplier_name", "purchase_invoice_count", "buckets", "total_outstanding" ], "properties": { "object": { "type": "string", "const": "business_aged_creditors_supplier" }, "supplier_id": { "type": "string", "format": "uuid", "nullable": true }, "supplier_name": { "type": "string" }, "purchase_invoice_count": { "type": "integer", "minimum": 0 }, "buckets": { "$ref": "#/components/schemas/BusinessAgedCreditorsBuckets" }, "total_outstanding": { "type": "number" } } }, "BusinessAgedCreditorsTotals": { "type": "object", "additionalProperties": false, "required": [ "purchase_invoice_count", "page_purchase_invoice_count", "supplier_count", "total_outstanding" ], "properties": { "purchase_invoice_count": { "type": "integer", "minimum": 0 }, "page_purchase_invoice_count": { "type": "integer", "minimum": 0 }, "supplier_count": { "type": "integer", "minimum": 0 }, "total_outstanding": { "type": "number" } } }, "BusinessAgedCreditorsReport": { "type": "object", "additionalProperties": false, "required": [ "object", "company_id", "report_type", "scope", "currency", "generated_at", "as_of_date", "buckets", "suppliers", "purchase_invoices", "totals" ], "properties": { "object": { "type": "string", "const": "business_aged_creditors_report" }, "company_id": { "type": "string", "format": "uuid" }, "report_type": { "type": "string", "const": "aged_creditors" }, "scope": { "type": "string", "const": "purchase_invoice_backed" }, "currency": { "type": "string", "const": "GBP" }, "generated_at": { "type": "string", "format": "date-time" }, "as_of_date": { "type": "string", "format": "date" }, "buckets": { "$ref": "#/components/schemas/BusinessAgedCreditorsBuckets" }, "suppliers": { "type": "array", "items": { "$ref": "#/components/schemas/BusinessAgedCreditorsSupplierSummary" } }, "purchase_invoices": { "type": "array", "items": { "$ref": "#/components/schemas/BusinessAgedCreditorsPurchaseInvoice" } }, "totals": { "$ref": "#/components/schemas/BusinessAgedCreditorsTotals" } } }, "V1BusinessAgedCreditorsReportMeta": { "type": "object", "additionalProperties": false, "required": [ "api_version", "mode", "request_id", "resource", "pagination" ], "properties": { "api_version": { "type": "string", "const": "v1-2026-07" }, "mode": { "type": "string", "const": "report" }, "request_id": { "type": "string", "minLength": 1, "maxLength": 128 }, "resource": { "type": "string", "const": "business_aged_creditors_report" }, "pagination": { "$ref": "#/components/schemas/V1PaginationMeta" } } }, "V1BusinessAgedCreditorsReportResponse": { "type": "object", "additionalProperties": false, "required": [ "data", "meta" ], "properties": { "data": { "$ref": "#/components/schemas/BusinessAgedCreditorsReport" }, "meta": { "$ref": "#/components/schemas/V1BusinessAgedCreditorsReportMeta" } } }, "BusinessHmrcCorrespondence": { "type": "object", "additionalProperties": false, "required": [ "object", "id", "company_id", "title", "received_date", "tax_area", "category", "urgency", "status", "response_required", "response_due_date", "amount", "hmrc_reference", "summary", "recommended_action", "source_document_id", "reviewed_at", "created_at", "updated_at" ], "properties": { "object": { "type": "string", "const": "business_hmrc_correspondence" }, "id": { "type": "string", "format": "uuid" }, "company_id": { "type": "string", "format": "uuid" }, "title": { "type": "string" }, "received_date": { "type": "string", "format": "date" }, "tax_area": { "type": "string", "enum": [ "vat", "corporation_tax", "paye", "cis", "companies_house", "unknown" ] }, "category": { "type": "string", "enum": [ "assessment", "demand", "enquiry", "refund", "information" ] }, "urgency": { "type": "string", "enum": [ "low", "medium", "high" ] }, "status": { "type": "string", "enum": [ "needs_review", "waiting_on_client", "responded", "resolved", "archived" ] }, "response_required": { "type": "boolean" }, "response_due_date": { "type": [ "string", "null" ], "format": "date" }, "amount": { "type": [ "number", "null" ] }, "hmrc_reference": { "type": [ "string", "null" ] }, "summary": { "type": [ "string", "null" ] }, "recommended_action": { "type": [ "string", "null" ] }, "source_document_id": { "type": [ "string", "null" ], "format": "uuid" }, "reviewed_at": { "type": [ "string", "null" ], "format": "date-time" }, "created_at": { "type": [ "string", "null" ], "format": "date-time" }, "updated_at": { "type": [ "string", "null" ], "format": "date-time" } } }, "V1BusinessHmrcCorrespondenceListMeta": { "type": "object", "additionalProperties": false, "required": [ "api_version", "mode", "resource", "request_id", "pagination" ], "properties": { "api_version": { "type": "string", "const": "v1-2026-07" }, "mode": { "type": "string", "const": "list" }, "resource": { "type": "string", "const": "business_hmrc_correspondence" }, "request_id": { "type": "string", "minLength": 1, "maxLength": 128 }, "pagination": { "$ref": "#/components/schemas/V1PaginationMeta" } } }, "V1BusinessHmrcCorrespondenceDetailMeta": { "type": "object", "additionalProperties": false, "required": [ "api_version", "mode", "resource", "request_id" ], "properties": { "api_version": { "type": "string", "const": "v1-2026-07" }, "mode": { "type": "string", "const": "detail" }, "resource": { "type": "string", "const": "business_hmrc_correspondence" }, "request_id": { "type": "string", "minLength": 1, "maxLength": 128 } } }, "BusinessHmrcCorrespondenceListResponse": { "type": "object", "additionalProperties": false, "required": [ "data", "meta" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/BusinessHmrcCorrespondence" } }, "meta": { "$ref": "#/components/schemas/V1BusinessHmrcCorrespondenceListMeta" } } }, "BusinessHmrcCorrespondenceDetailResponse": { "type": "object", "additionalProperties": false, "required": [ "data", "meta" ], "properties": { "data": { "$ref": "#/components/schemas/BusinessHmrcCorrespondence" }, "meta": { "$ref": "#/components/schemas/V1BusinessHmrcCorrespondenceDetailMeta" } } }, "BusinessCustomerVolume": { "type": "object", "additionalProperties": false, "required": [ "customer_id", "customer_name", "invoice_count", "object", "total_revenue" ], "properties": { "object": { "type": "string", "const": "business_customer_volume" }, "customer_id": { "type": "string", "format": "uuid", "nullable": true }, "customer_name": { "type": "string", "nullable": true }, "invoice_count": { "type": "number", "minimum": 0 }, "total_revenue": { "type": "number", "description": "Revenue for the customer in the requested period." } } }, "BusinessCustomerVolumeSummary": { "type": "object", "additionalProperties": false, "required": [ "branch", "object", "period", "total_customers", "total_invoices", "total_revenue" ], "properties": { "object": { "type": "string", "const": "business_customer_volume_summary" }, "branch": { "type": "string", "nullable": true }, "period": { "$ref": "#/components/schemas/BusinessReportSummaryPeriod" }, "total_customers": { "type": "integer", "minimum": 0 }, "total_invoices": { "type": "number", "minimum": 0 }, "total_revenue": { "type": "number" } } }, "V1BusinessCustomerVolumeListMeta": { "type": "object", "required": [ "api_version", "mode", "request_id", "resource", "total_rows" ], "properties": { "api_version": { "type": "string", "const": "v1-2026-07" }, "mode": { "type": "string", "const": "list" }, "request_id": { "type": "string", "minLength": 1, "maxLength": 128 }, "resource": { "type": "string", "const": "business_customer_volume" }, "total_rows": { "type": "integer", "minimum": 0 } } }, "V1BusinessCustomerVolumeListResponse": { "type": "object", "required": [ "data", "meta", "summary" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/BusinessCustomerVolume" } }, "meta": { "$ref": "#/components/schemas/V1BusinessCustomerVolumeListMeta" }, "summary": { "$ref": "#/components/schemas/BusinessCustomerVolumeSummary" } } }, "BusinessSupplierVolume": { "type": "object", "additionalProperties": false, "required": [ "bill_count", "object", "supplier_id", "supplier_name", "total_spend" ], "properties": { "object": { "type": "string", "const": "business_supplier_volume" }, "supplier_id": { "type": "string", "format": "uuid", "nullable": true }, "supplier_name": { "type": "string", "nullable": true }, "bill_count": { "type": "number", "minimum": 0 }, "total_spend": { "type": "number", "description": "Purchase invoice spend for the supplier in the requested period." } } }, "BusinessSupplierVolumeSummary": { "type": "object", "additionalProperties": false, "required": [ "branch", "object", "period", "source", "total_bills", "total_spend", "total_suppliers" ], "properties": { "object": { "type": "string", "const": "business_supplier_volume_summary" }, "branch": { "type": "string", "nullable": true }, "period": { "$ref": "#/components/schemas/BusinessReportSummaryPeriod" }, "source": { "type": "string", "const": "purchase_invoices" }, "total_bills": { "type": "number", "minimum": 0 }, "total_spend": { "type": "number" }, "total_suppliers": { "type": "integer", "minimum": 0 } } }, "V1BusinessSupplierVolumeListMeta": { "type": "object", "required": [ "api_version", "mode", "request_id", "resource", "total_rows" ], "properties": { "api_version": { "type": "string", "const": "v1-2026-07" }, "mode": { "type": "string", "const": "list" }, "request_id": { "type": "string", "minLength": 1, "maxLength": 128 }, "resource": { "type": "string", "const": "business_supplier_volume" }, "total_rows": { "type": "integer", "minimum": 0 } } }, "V1BusinessSupplierVolumeListResponse": { "type": "object", "required": [ "data", "meta", "summary" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/BusinessSupplierVolume" } }, "meta": { "$ref": "#/components/schemas/V1BusinessSupplierVolumeListMeta" }, "summary": { "$ref": "#/components/schemas/BusinessSupplierVolumeSummary" } } }, "BusinessBankFeedInstitution": { "type": "object", "additionalProperties": false, "required": [ "object", "countries", "id", "logo_url", "name", "transaction_total_days" ], "properties": { "object": { "type": "string", "const": "business_bank_feed_institution" }, "countries": { "type": "array", "items": { "type": "string", "pattern": "^[A-Z]{2}$" } }, "id": { "type": "string", "minLength": 1 }, "logo_url": { "type": "string", "format": "uri", "nullable": true }, "name": { "type": "string", "minLength": 1 }, "transaction_total_days": { "type": "integer", "minimum": 0, "nullable": true } } }, "V1BusinessBankFeedInstitutionListMeta": { "type": "object", "required": [ "api_version", "country", "mode", "request_id", "resource", "total_rows" ], "properties": { "api_version": { "type": "string", "const": "v1-2026-07" }, "country": { "type": "string", "pattern": "^[A-Z]{2}$" }, "mode": { "type": "string", "const": "list" }, "request_id": { "type": "string", "minLength": 1, "maxLength": 128 }, "resource": { "type": "string", "const": "business_bank_feed_institution" }, "total_rows": { "type": "integer", "minimum": 0 } } }, "V1BusinessBankFeedInstitutionListResponse": { "type": "object", "required": [ "data", "meta" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/BusinessBankFeedInstitution" } }, "meta": { "$ref": "#/components/schemas/V1BusinessBankFeedInstitutionListMeta" } } }, "BusinessGiftAidDeclarationDonor": { "type": "object", "additionalProperties": false, "required": [ "address_line_1", "city", "email", "first_name", "id", "last_name", "postcode" ], "properties": { "address_line_1": { "type": "string", "nullable": true }, "city": { "type": "string", "nullable": true }, "email": { "type": "string", "nullable": true, "format": "email" }, "first_name": { "type": "string", "nullable": true }, "id": { "type": "string", "format": "uuid" }, "last_name": { "type": "string", "nullable": true }, "postcode": { "type": "string", "nullable": true } } }, "BusinessGiftAidDeclaration": { "type": "object", "additionalProperties": false, "required": [ "object", "cancellation_date", "cancellation_reason", "channel", "company_id", "created_at", "declaration_date", "declaration_text", "declaration_type", "donor", "donor_id", "effective_from", "evidence_file_reference", "evidence_ip_address", "evidence_timestamp", "id", "status", "updated_at", "wording_version" ], "properties": { "object": { "type": "string", "const": "business_gift_aid_declaration" }, "cancellation_date": { "type": "string", "nullable": true, "format": "date" }, "cancellation_reason": { "type": "string", "nullable": true }, "channel": { "type": "string", "nullable": true }, "company_id": { "type": "string", "format": "uuid" }, "created_at": { "type": "string", "nullable": true, "format": "date-time" }, "declaration_date": { "type": "string", "nullable": true, "format": "date" }, "declaration_text": { "type": "string", "nullable": true }, "declaration_type": { "type": "string", "nullable": true }, "donor": { "$ref": "#/components/schemas/BusinessGiftAidDeclarationDonor", "nullable": true }, "donor_id": { "type": "string", "format": "uuid", "nullable": true }, "effective_from": { "type": "string", "nullable": true, "format": "date" }, "evidence_file_reference": { "type": "string", "nullable": true }, "evidence_ip_address": { "type": "string", "nullable": true }, "evidence_timestamp": { "type": "string", "nullable": true, "format": "date-time" }, "id": { "type": "string", "format": "uuid" }, "status": { "type": "string", "nullable": true }, "updated_at": { "type": "string", "nullable": true, "format": "date-time" }, "wording_version": { "type": "string", "nullable": true } } }, "V1BusinessGiftAidDeclarationListMeta": { "type": "object", "required": [ "api_version", "mode", "pagination", "request_id", "resource" ], "properties": { "api_version": { "type": "string", "const": "v1-2026-07" }, "mode": { "type": "string", "const": "list" }, "pagination": { "$ref": "#/components/schemas/V1Pagination" }, "request_id": { "type": "string", "minLength": 1, "maxLength": 128 }, "resource": { "type": "string", "const": "business_gift_aid_declaration" } } }, "V1BusinessGiftAidDeclarationMeta": { "type": "object", "required": [ "api_version", "mode", "request_id", "resource" ], "properties": { "api_version": { "type": "string", "const": "v1-2026-07" }, "mode": { "type": "string", "const": "detail" }, "request_id": { "type": "string", "minLength": 1, "maxLength": 128 }, "resource": { "type": "string", "const": "business_gift_aid_declaration" } } }, "V1BusinessGiftAidDeclarationListResponse": { "type": "object", "additionalProperties": false, "required": [ "data", "meta" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/BusinessGiftAidDeclaration" } }, "meta": { "$ref": "#/components/schemas/V1BusinessGiftAidDeclarationListMeta" } } }, "V1BusinessGiftAidDeclarationResponse": { "type": "object", "additionalProperties": false, "required": [ "data", "meta" ], "properties": { "data": { "$ref": "#/components/schemas/BusinessGiftAidDeclaration" }, "meta": { "$ref": "#/components/schemas/V1BusinessGiftAidDeclarationMeta" } } }, "BusinessGiftAidDonationDonor": { "type": "object", "additionalProperties": false, "required": [ "address_line_1", "address_line_2", "city", "email", "first_name", "id", "last_name", "postcode" ], "properties": { "address_line_1": { "type": "string", "nullable": true }, "address_line_2": { "type": "string", "nullable": true }, "city": { "type": "string", "nullable": true }, "email": { "type": "string", "nullable": true, "format": "email" }, "first_name": { "type": "string", "nullable": true }, "id": { "type": "string", "format": "uuid" }, "last_name": { "type": "string", "nullable": true }, "postcode": { "type": "string", "nullable": true } } }, "BusinessGiftAidDonationDeclaration": { "type": "object", "additionalProperties": false, "required": [ "declaration_date", "declaration_type", "id", "status" ], "properties": { "declaration_date": { "type": "string", "nullable": true, "format": "date" }, "declaration_type": { "type": "string", "nullable": true }, "id": { "type": "string", "format": "uuid" }, "status": { "type": "string", "nullable": true } } }, "BusinessGiftAidDonationFund": { "type": "object", "additionalProperties": false, "required": [ "code", "fund_type", "id", "name" ], "properties": { "code": { "type": "string", "nullable": true }, "fund_type": { "type": "string", "nullable": true }, "id": { "type": "string", "format": "uuid" }, "name": { "type": "string", "nullable": true } } }, "BusinessGiftAidDonation": { "type": "object", "additionalProperties": false, "required": [ "object", "bank_transaction_id", "benefit_description", "benefit_provided", "benefit_value", "claim_status", "company_id", "created_at", "currency", "declaration", "declaration_id", "description", "donation_date", "donor", "donor_id", "fund", "fund_id", "gift_aid_eligible", "gross_amount", "id", "ineligibility_reason", "is_sponsored_event", "payment_method", "reference", "updated_at" ], "properties": { "object": { "type": "string", "const": "business_gift_aid_donation" }, "bank_transaction_id": { "type": "string", "nullable": true, "format": "uuid" }, "benefit_description": { "type": "string", "nullable": true }, "benefit_provided": { "type": "boolean" }, "benefit_value": { "type": "number", "nullable": true }, "claim_status": { "type": "string", "nullable": true }, "company_id": { "type": "string", "format": "uuid" }, "created_at": { "type": "string", "nullable": true, "format": "date-time" }, "currency": { "type": "string", "nullable": true }, "declaration": { "$ref": "#/components/schemas/BusinessGiftAidDonationDeclaration", "nullable": true }, "declaration_id": { "type": "string", "nullable": true, "format": "uuid" }, "description": { "type": "string", "nullable": true }, "donation_date": { "type": "string", "nullable": true, "format": "date" }, "donor": { "$ref": "#/components/schemas/BusinessGiftAidDonationDonor", "nullable": true }, "donor_id": { "type": "string", "nullable": true, "format": "uuid" }, "fund": { "$ref": "#/components/schemas/BusinessGiftAidDonationFund", "nullable": true }, "fund_id": { "type": "string", "nullable": true, "format": "uuid" }, "gift_aid_eligible": { "type": "boolean", "nullable": true }, "gross_amount": { "type": "number", "nullable": true }, "id": { "type": "string", "format": "uuid" }, "ineligibility_reason": { "type": "string", "nullable": true }, "is_sponsored_event": { "type": "boolean" }, "payment_method": { "type": "string", "nullable": true }, "reference": { "type": "string", "nullable": true }, "updated_at": { "type": "string", "nullable": true, "format": "date-time" } } }, "V1BusinessGiftAidDonationListMeta": { "type": "object", "required": [ "api_version", "mode", "pagination", "request_id", "resource" ], "properties": { "api_version": { "type": "string", "const": "v1-2026-07" }, "mode": { "type": "string", "const": "list" }, "pagination": { "$ref": "#/components/schemas/V1Pagination" }, "request_id": { "type": "string", "minLength": 1, "maxLength": 128 }, "resource": { "type": "string", "const": "business_gift_aid_donation" } } }, "V1BusinessGiftAidDonationMeta": { "type": "object", "required": [ "api_version", "mode", "request_id", "resource" ], "properties": { "api_version": { "type": "string", "const": "v1-2026-07" }, "mode": { "type": "string", "const": "detail" }, "request_id": { "type": "string", "minLength": 1, "maxLength": 128 }, "resource": { "type": "string", "const": "business_gift_aid_donation" } } }, "V1BusinessGiftAidDonationListResponse": { "type": "object", "additionalProperties": false, "required": [ "data", "meta" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/BusinessGiftAidDonation" } }, "meta": { "$ref": "#/components/schemas/V1BusinessGiftAidDonationListMeta" } } }, "V1BusinessGiftAidDonationResponse": { "type": "object", "additionalProperties": false, "required": [ "data", "meta" ], "properties": { "data": { "$ref": "#/components/schemas/BusinessGiftAidDonation" }, "meta": { "$ref": "#/components/schemas/V1BusinessGiftAidDonationMeta" } } }, "BusinessGiftAidClaimItemDonor": { "type": "object", "additionalProperties": false, "required": [ "first_name", "id", "last_name" ], "properties": { "first_name": { "type": "string", "nullable": true }, "id": { "type": "string", "format": "uuid" }, "last_name": { "type": "string", "nullable": true } } }, "BusinessGiftAidClaimItemDonation": { "type": "object", "additionalProperties": false, "required": [ "donation_date", "donor", "gross_amount", "id" ], "properties": { "donation_date": { "type": "string", "nullable": true, "format": "date" }, "donor": { "$ref": "#/components/schemas/BusinessGiftAidClaimItemDonor", "nullable": true }, "gross_amount": { "type": "number", "nullable": true }, "id": { "type": "string", "format": "uuid" } } }, "BusinessGiftAidClaimItem": { "type": "object", "additionalProperties": false, "required": [ "object", "amount", "claim_amount", "created_at", "donation", "donation_id", "error_code", "error_message", "gasds_collection_id", "id", "item_type", "status" ], "properties": { "object": { "type": "string", "const": "business_gift_aid_claim_item" }, "amount": { "type": "number", "nullable": true }, "claim_amount": { "type": "number", "nullable": true }, "created_at": { "type": "string", "nullable": true, "format": "date-time" }, "donation": { "$ref": "#/components/schemas/BusinessGiftAidClaimItemDonation", "nullable": true }, "donation_id": { "type": "string", "nullable": true, "format": "uuid" }, "error_code": { "type": "string", "nullable": true }, "error_message": { "type": "string", "nullable": true }, "gasds_collection_id": { "type": "string", "nullable": true, "format": "uuid" }, "id": { "type": "string", "format": "uuid" }, "item_type": { "type": "string", "nullable": true }, "status": { "type": "string", "nullable": true } } }, "BusinessGiftAidClaimBatch": { "type": "object", "additionalProperties": false, "required": [ "object", "batch_reference", "claim_type", "company_id", "created_at", "donation_count", "gasds_count", "hmrc_correlation_id", "hmrc_response", "hmrc_response_at", "hmrc_submission_id", "id", "items", "period_end", "period_start", "status", "submitted_at", "total_donations", "total_gasds", "total_gasds_claim", "total_gift_aid_claim", "updated_at" ], "properties": { "object": { "type": "string", "const": "business_gift_aid_claim_batch" }, "batch_reference": { "type": "string", "nullable": true }, "claim_type": { "type": "string", "nullable": true }, "company_id": { "type": "string", "format": "uuid" }, "created_at": { "type": "string", "nullable": true, "format": "date-time" }, "donation_count": { "type": "number", "nullable": true }, "gasds_count": { "type": "number", "nullable": true }, "hmrc_correlation_id": { "type": "string", "nullable": true }, "hmrc_response": { "type": "string", "nullable": true }, "hmrc_response_at": { "type": "string", "nullable": true, "format": "date-time" }, "hmrc_submission_id": { "type": "string", "nullable": true }, "id": { "type": "string", "format": "uuid" }, "items": { "type": "array", "nullable": true, "items": { "$ref": "#/components/schemas/BusinessGiftAidClaimItem" } }, "period_end": { "type": "string", "nullable": true, "format": "date" }, "period_start": { "type": "string", "nullable": true, "format": "date" }, "status": { "type": "string", "nullable": true }, "submitted_at": { "type": "string", "nullable": true, "format": "date-time" }, "total_donations": { "type": "number", "nullable": true }, "total_gasds": { "type": "number", "nullable": true }, "total_gasds_claim": { "type": "number", "nullable": true }, "total_gift_aid_claim": { "type": "number", "nullable": true }, "updated_at": { "type": "string", "nullable": true, "format": "date-time" } } }, "V1BusinessGiftAidClaimBatchListMeta": { "type": "object", "required": [ "api_version", "mode", "pagination", "request_id", "resource" ], "properties": { "api_version": { "type": "string", "const": "v1-2026-07" }, "mode": { "type": "string", "const": "list" }, "pagination": { "$ref": "#/components/schemas/V1Pagination" }, "request_id": { "type": "string", "minLength": 1, "maxLength": 128 }, "resource": { "type": "string", "const": "business_gift_aid_claim_batch" } } }, "V1BusinessGiftAidClaimBatchMeta": { "type": "object", "required": [ "api_version", "mode", "request_id", "resource" ], "properties": { "api_version": { "type": "string", "const": "v1-2026-07" }, "mode": { "type": "string", "const": "detail" }, "request_id": { "type": "string", "minLength": 1, "maxLength": 128 }, "resource": { "type": "string", "const": "business_gift_aid_claim_batch" } } }, "V1BusinessGiftAidClaimBatchListResponse": { "type": "object", "additionalProperties": false, "required": [ "data", "meta" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/BusinessGiftAidClaimBatch" } }, "meta": { "$ref": "#/components/schemas/V1BusinessGiftAidClaimBatchListMeta" } } }, "V1BusinessGiftAidClaimBatchResponse": { "type": "object", "additionalProperties": false, "required": [ "data", "meta" ], "properties": { "data": { "$ref": "#/components/schemas/BusinessGiftAidClaimBatch" }, "meta": { "$ref": "#/components/schemas/V1BusinessGiftAidClaimBatchMeta" } } }, "BusinessCashOfferingAccount": { "type": "object", "additionalProperties": false, "required": [ "id", "code", "name" ], "properties": { "id": { "type": "string", "format": "uuid" }, "code": { "type": [ "string", "null" ] }, "name": { "type": [ "string", "null" ] } } }, "BusinessCashOfferingSetup": { "type": "object", "additionalProperties": false, "required": [ "object", "company_id", "donation_income_account_count", "donation_income_accounts", "ready" ], "properties": { "object": { "type": "string", "const": "business_cash_offering_setup" }, "company_id": { "type": "string", "format": "uuid" }, "donation_income_account_count": { "type": "number" }, "donation_income_accounts": { "type": "array", "items": { "$ref": "#/components/schemas/BusinessCashOfferingAccount" } }, "ready": { "type": "boolean" } } }, "V1BusinessCashOfferingSetupMeta": { "type": "object", "required": [ "api_version", "mode", "request_id", "resource" ], "properties": { "api_version": { "type": "string", "const": "v1-2026-07" }, "mode": { "type": "string", "const": "detail" }, "request_id": { "type": "string", "minLength": 1, "maxLength": 128 }, "resource": { "type": "string", "const": "business_cash_offering_setup" } } }, "V1BusinessCashOfferingSetupResponse": { "type": "object", "additionalProperties": false, "required": [ "data", "meta" ], "properties": { "data": { "$ref": "#/components/schemas/BusinessCashOfferingSetup" }, "meta": { "$ref": "#/components/schemas/V1BusinessCashOfferingSetupMeta" } } }, "BusinessCashOfferingBatchLine": { "type": "object", "additionalProperties": false, "required": [ "object", "id", "company_id", "batch_id", "amount", "line_order" ], "properties": { "object": { "type": "string", "const": "business_cash_offering_batch_line" }, "id": { "type": "string", "format": "uuid" }, "company_id": { "type": "string", "format": "uuid" }, "batch_id": { "type": "string", "format": "uuid" }, "donor_id": { "type": [ "string", "null" ], "format": "uuid" }, "declaration_id": { "type": [ "string", "null" ], "format": "uuid" }, "gift_aid_donation_id": { "type": [ "string", "null" ], "format": "uuid" }, "fund_id": { "type": [ "string", "null" ], "format": "uuid" }, "amount": { "type": [ "number", "null" ] }, "line_order": { "type": [ "number", "null" ] }, "created_at": { "type": [ "string", "null" ], "format": "date-time" }, "donor": { "type": [ "object", "null" ], "additionalProperties": false, "required": [ "id" ], "properties": { "id": { "type": "string", "format": "uuid" }, "external_id": { "type": [ "string", "null" ] }, "first_name": { "type": [ "string", "null" ] }, "last_name": { "type": [ "string", "null" ] } } }, "declaration": { "type": [ "object", "null" ], "additionalProperties": false, "required": [ "id" ], "properties": { "id": { "type": "string", "format": "uuid" }, "declaration_date": { "type": [ "string", "null" ], "format": "date" }, "declaration_type": { "type": [ "string", "null" ] }, "status": { "type": [ "string", "null" ] } } }, "fund": { "type": [ "object", "null" ], "additionalProperties": false, "required": [ "id" ], "properties": { "id": { "type": "string", "format": "uuid" }, "code": { "type": [ "string", "null" ] }, "fund_type": { "type": [ "string", "null" ] }, "name": { "type": [ "string", "null" ] } } }, "gift_aid_donation": { "type": [ "object", "null" ], "additionalProperties": false, "required": [ "id" ], "properties": { "id": { "type": "string", "format": "uuid" }, "claim_status": { "type": [ "string", "null" ] }, "gift_aid_eligible": { "type": [ "boolean", "null" ] } } } } }, "BusinessCashOfferingBatch": { "type": "object", "additionalProperties": false, "required": [ "object", "id", "company_id", "lines" ], "properties": { "object": { "type": "string", "const": "business_cash_offering_batch" }, "id": { "type": "string", "format": "uuid" }, "company_id": { "type": "string", "format": "uuid" }, "external_batch_id": { "type": [ "string", "null" ] }, "branch_id": { "type": [ "string", "null" ] }, "branch_name": { "type": [ "string", "null" ] }, "collection_date": { "type": [ "string", "null" ], "format": "date" }, "count_date": { "type": [ "string", "null" ], "format": "date" }, "bank_by_date": { "type": [ "string", "null" ], "format": "date" }, "total_amount": { "type": [ "number", "null" ] }, "prepared_amount": { "type": [ "number", "null" ] }, "banked_amount": { "type": [ "number", "null" ] }, "available_amount": { "type": [ "number", "null" ] }, "unbanked_amount": { "type": [ "number", "null" ] }, "petty_cash_bank_account_id": { "type": [ "string", "null" ], "format": "uuid" }, "petty_cash_chart_of_accounts_id": { "type": [ "string", "null" ], "format": "uuid" }, "donation_income_chart_of_accounts_id": { "type": [ "string", "null" ], "format": "uuid" }, "journal_transaction_id": { "type": [ "string", "null" ], "format": "uuid" }, "counted_by_external_id": { "type": [ "string", "null" ] }, "counted_by_name": { "type": [ "string", "null" ] }, "counted_at": { "type": [ "string", "null" ], "format": "date-time" }, "created_at": { "type": [ "string", "null" ], "format": "date-time" }, "updated_at": { "type": [ "string", "null" ], "format": "date-time" }, "status": { "type": [ "string", "null" ] }, "record_status": { "type": [ "string", "null" ] }, "reversal_journal_transaction_id": { "type": [ "string", "null" ], "format": "uuid" }, "reversal_reason": { "type": [ "string", "null" ] }, "reversed_at": { "type": [ "string", "null" ], "format": "date-time" }, "reversed_by_external_id": { "type": [ "string", "null" ] }, "reversed_by_name": { "type": [ "string", "null" ] }, "lines": { "type": [ "array", "null" ], "items": { "$ref": "#/components/schemas/BusinessCashOfferingBatchLine" } } } }, "V1BusinessCashOfferingBatchListMeta": { "type": "object", "required": [ "api_version", "mode", "pagination", "request_id", "resource" ], "properties": { "api_version": { "type": "string", "const": "v1-2026-07" }, "mode": { "type": "string", "const": "list" }, "pagination": { "$ref": "#/components/schemas/PaginationMeta" }, "request_id": { "type": "string", "minLength": 1, "maxLength": 128 }, "resource": { "type": "string", "const": "business_cash_offering_batch" } } }, "V1BusinessCashOfferingBatchMeta": { "type": "object", "required": [ "api_version", "mode", "request_id", "resource" ], "properties": { "api_version": { "type": "string", "const": "v1-2026-07" }, "mode": { "type": "string", "const": "detail" }, "request_id": { "type": "string", "minLength": 1, "maxLength": 128 }, "resource": { "type": "string", "const": "business_cash_offering_batch" } } }, "V1BusinessCashOfferingBatchListResponse": { "type": "object", "additionalProperties": false, "required": [ "data", "meta" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/BusinessCashOfferingBatch" } }, "meta": { "$ref": "#/components/schemas/V1BusinessCashOfferingBatchListMeta" } } }, "V1BusinessCashOfferingBatchResponse": { "type": "object", "additionalProperties": false, "required": [ "data", "meta" ], "properties": { "data": { "$ref": "#/components/schemas/BusinessCashOfferingBatch" }, "meta": { "$ref": "#/components/schemas/V1BusinessCashOfferingBatchMeta" } } }, "BusinessCashDepositPreparationFundAllocation": { "type": "object", "additionalProperties": false, "required": [ "object", "id", "company_id", "allocation_id", "batch_id", "fund_id", "allocated_amount" ], "properties": { "object": { "type": "string", "const": "business_cash_deposit_preparation_fund_allocation" }, "id": { "type": "string", "format": "uuid" }, "company_id": { "type": "string", "format": "uuid" }, "allocation_id": { "type": "string", "format": "uuid" }, "batch_id": { "type": "string", "format": "uuid" }, "fund_id": { "type": [ "string", "null" ], "format": "uuid" }, "allocated_amount": { "type": [ "number", "null" ] }, "created_at": { "type": [ "string", "null" ], "format": "date-time" }, "fund": { "type": [ "object", "null" ], "additionalProperties": false, "required": [ "id" ], "properties": { "id": { "type": "string", "format": "uuid" }, "code": { "type": [ "string", "null" ] }, "fund_type": { "type": [ "string", "null" ] }, "name": { "type": [ "string", "null" ] } } } } }, "BusinessCashDepositPreparationAllocation": { "type": "object", "additionalProperties": false, "required": [ "object", "id", "company_id", "preparation_id", "batch_id", "allocated_amount", "fund_allocations" ], "properties": { "object": { "type": "string", "const": "business_cash_deposit_preparation_allocation" }, "id": { "type": "string", "format": "uuid" }, "company_id": { "type": "string", "format": "uuid" }, "preparation_id": { "type": "string", "format": "uuid" }, "batch_id": { "type": "string", "format": "uuid" }, "allocated_amount": { "type": [ "number", "null" ] }, "created_at": { "type": [ "string", "null" ], "format": "date-time" }, "fund_allocations": { "type": "array", "items": { "$ref": "#/components/schemas/BusinessCashDepositPreparationFundAllocation" } } } }, "BusinessCashDepositPreparation": { "type": "object", "additionalProperties": false, "required": [ "object", "id", "company_id", "allocations" ], "properties": { "object": { "type": "string", "const": "business_cash_deposit_preparation" }, "id": { "type": "string", "format": "uuid" }, "company_id": { "type": "string", "format": "uuid" }, "external_preparation_id": { "type": [ "string", "null" ] }, "branch_id": { "type": [ "string", "null" ] }, "branch_name": { "type": [ "string", "null" ] }, "deposit_date": { "type": [ "string", "null" ], "format": "date" }, "bank_account_id": { "type": [ "string", "null" ], "format": "uuid" }, "bank_account_name": { "type": [ "string", "null" ] }, "bank_name": { "type": [ "string", "null" ] }, "bank_chart_of_accounts_id": { "type": [ "string", "null" ], "format": "uuid" }, "petty_cash_bank_account_id": { "type": [ "string", "null" ], "format": "uuid" }, "petty_cash_chart_of_accounts_id": { "type": [ "string", "null" ], "format": "uuid" }, "total_amount": { "type": [ "number", "null" ] }, "reference": { "type": [ "string", "null" ] }, "status": { "type": [ "string", "null" ] }, "prepared_by_external_id": { "type": [ "string", "null" ] }, "prepared_by_name": { "type": [ "string", "null" ] }, "bank_transaction_id": { "type": [ "string", "null" ], "format": "uuid" }, "journal_transaction_id": { "type": [ "string", "null" ], "format": "uuid" }, "banked_at": { "type": [ "string", "null" ], "format": "date-time" }, "created_at": { "type": [ "string", "null" ], "format": "date-time" }, "updated_at": { "type": [ "string", "null" ], "format": "date-time" }, "batch_count": { "type": [ "number", "null" ] }, "cancelled_at": { "type": [ "string", "null" ], "format": "date-time" }, "cancelled_by_external_id": { "type": [ "string", "null" ] }, "cancelled_by_name": { "type": [ "string", "null" ] }, "cancellation_reason": { "type": [ "string", "null" ] }, "allocations": { "type": [ "array", "null" ], "items": { "$ref": "#/components/schemas/BusinessCashDepositPreparationAllocation" } } } }, "V1BusinessCashDepositPreparationListMeta": { "type": "object", "required": [ "api_version", "mode", "pagination", "request_id", "resource" ], "properties": { "api_version": { "type": "string", "const": "v1-2026-07" }, "mode": { "type": "string", "const": "list" }, "pagination": { "$ref": "#/components/schemas/PaginationMeta" }, "request_id": { "type": "string", "minLength": 1, "maxLength": 128 }, "resource": { "type": "string", "const": "business_cash_deposit_preparation" } } }, "V1BusinessCashDepositPreparationMeta": { "type": "object", "required": [ "api_version", "mode", "request_id", "resource" ], "properties": { "api_version": { "type": "string", "const": "v1-2026-07" }, "mode": { "type": "string", "const": "detail" }, "request_id": { "type": "string", "minLength": 1, "maxLength": 128 }, "resource": { "type": "string", "const": "business_cash_deposit_preparation" } } }, "V1BusinessCashDepositPreparationListResponse": { "type": "object", "additionalProperties": false, "required": [ "data", "meta" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/BusinessCashDepositPreparation" } }, "meta": { "$ref": "#/components/schemas/V1BusinessCashDepositPreparationListMeta" } } }, "V1BusinessCashDepositPreparationResponse": { "type": "object", "additionalProperties": false, "required": [ "data", "meta" ], "properties": { "data": { "$ref": "#/components/schemas/BusinessCashDepositPreparation" }, "meta": { "$ref": "#/components/schemas/V1BusinessCashDepositPreparationMeta" } } }, "BusinessDonationBankInflow": { "type": "object", "additionalProperties": false, "required": [ "object", "id", "company_id" ], "properties": { "object": { "type": "string", "const": "business_donation_bank_inflow" }, "id": { "type": "string", "format": "uuid" }, "company_id": { "type": "string", "format": "uuid" }, "transaction_date": { "type": [ "string", "null" ], "format": "date" }, "description": { "type": [ "string", "null" ] }, "gross_amount": { "type": [ "number", "null" ] }, "reference": { "type": [ "string", "null" ] }, "merchant_name": { "type": [ "string", "null" ] }, "is_matched": { "type": [ "boolean", "null" ] }, "categorisation_status": { "type": [ "string", "null" ] }, "reconciliation_status": { "type": [ "string", "null" ] }, "lifecycle_status": { "type": [ "string", "null" ] }, "bank_account_id": { "type": [ "string", "null" ], "format": "uuid" }, "bank_account": { "type": [ "object", "null" ], "additionalProperties": false, "required": [ "id" ], "properties": { "id": { "type": "string", "format": "uuid" }, "account_name": { "type": [ "string", "null" ] }, "bank_name": { "type": [ "string", "null" ] } } } } }, "V1BusinessDonationBankInflowListMeta": { "type": "object", "required": [ "api_version", "mode", "pagination", "request_id", "resource" ], "properties": { "api_version": { "type": "string", "const": "v1-2026-07" }, "mode": { "type": "string", "const": "list" }, "pagination": { "$ref": "#/components/schemas/PaginationMeta" }, "request_id": { "type": "string", "minLength": 1, "maxLength": 128 }, "resource": { "type": "string", "const": "business_donation_bank_inflow" } } }, "V1BusinessDonationBankInflowListResponse": { "type": "object", "additionalProperties": false, "required": [ "data", "meta" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/BusinessDonationBankInflow" } }, "meta": { "$ref": "#/components/schemas/V1BusinessDonationBankInflowListMeta" } } }, "BusinessDonorMatchQueueCandidate": { "type": "object", "additionalProperties": false, "properties": { "confidence": { "type": [ "number", "null" ] }, "donor_id": { "type": [ "string", "null" ], "format": "uuid" }, "first_name": { "type": [ "string", "null" ] }, "last_name": { "type": [ "string", "null" ] }, "reason": { "type": [ "string", "null" ] } } }, "BusinessDonorMatchQueueDonor": { "type": "object", "additionalProperties": false, "required": [ "id" ], "properties": { "id": { "type": "string", "format": "uuid" }, "first_name": { "type": [ "string", "null" ] }, "last_name": { "type": [ "string", "null" ] } } }, "BusinessDonorMatchQueueBankAccount": { "type": "object", "additionalProperties": false, "required": [ "id" ], "properties": { "id": { "type": "string", "format": "uuid" }, "account_name": { "type": [ "string", "null" ] }, "bank_name": { "type": [ "string", "null" ] } } }, "BusinessDonorMatchQueueBankTransaction": { "type": "object", "additionalProperties": false, "required": [ "id" ], "properties": { "id": { "type": "string", "format": "uuid" }, "transaction_date": { "type": [ "string", "null" ], "format": "date" }, "gross_amount": { "type": [ "number", "null" ] }, "reference": { "type": [ "string", "null" ] }, "description": { "type": [ "string", "null" ] }, "bank_account_id": { "type": [ "string", "null" ], "format": "uuid" }, "bank_account": { "type": [ "object", "null" ], "additionalProperties": false, "required": [ "id" ], "properties": { "id": { "type": "string", "format": "uuid" }, "account_name": { "type": [ "string", "null" ] }, "bank_name": { "type": [ "string", "null" ] } } } } }, "BusinessDonorMatchQueueItem": { "type": "object", "additionalProperties": false, "required": [ "object", "id", "company_id" ], "properties": { "object": { "type": "string", "const": "business_donor_match_queue_item" }, "id": { "type": "string", "format": "uuid" }, "company_id": { "type": "string", "format": "uuid" }, "bank_transaction_id": { "type": [ "string", "null" ], "format": "uuid" }, "suggested_donor_id": { "type": [ "string", "null" ], "format": "uuid" }, "match_confidence": { "type": [ "number", "null" ] }, "match_method": { "type": [ "string", "null" ] }, "candidate_donors": { "type": "array", "items": { "$ref": "#/components/schemas/BusinessDonorMatchQueueCandidate" } }, "parsed_name": { "type": [ "string", "null" ] }, "parsed_purpose": { "type": [ "string", "null" ] }, "suggested_action": { "type": [ "string", "null" ] }, "status": { "type": [ "string", "null" ] }, "resolved_donor_id": { "type": [ "string", "null" ], "format": "uuid" }, "resolved_by_external_id": { "type": [ "string", "null" ] }, "resolved_by_name": { "type": [ "string", "null" ] }, "resolved_at": { "type": [ "string", "null" ], "format": "date-time" }, "created_at": { "type": [ "string", "null" ], "format": "date-time" }, "updated_at": { "type": [ "string", "null" ], "format": "date-time" }, "bank_transaction": { "type": [ "object", "null" ], "additionalProperties": false, "required": [ "id" ], "properties": { "id": { "type": "string", "format": "uuid" }, "transaction_date": { "type": [ "string", "null" ], "format": "date" }, "gross_amount": { "type": [ "number", "null" ] }, "reference": { "type": [ "string", "null" ] }, "description": { "type": [ "string", "null" ] }, "bank_account_id": { "type": [ "string", "null" ], "format": "uuid" }, "bank_account": { "type": [ "object", "null" ], "additionalProperties": false, "required": [ "id" ], "properties": { "id": { "type": "string", "format": "uuid" }, "account_name": { "type": [ "string", "null" ] }, "bank_name": { "type": [ "string", "null" ] } } } } }, "suggested_donor": { "type": [ "object", "null" ], "additionalProperties": false, "required": [ "id" ], "properties": { "id": { "type": "string", "format": "uuid" }, "first_name": { "type": [ "string", "null" ] }, "last_name": { "type": [ "string", "null" ] } } }, "resolved_donor": { "type": [ "object", "null" ], "additionalProperties": false, "required": [ "id" ], "properties": { "id": { "type": "string", "format": "uuid" }, "first_name": { "type": [ "string", "null" ] }, "last_name": { "type": [ "string", "null" ] } } } } }, "V1BusinessDonorMatchQueueListMeta": { "type": "object", "required": [ "api_version", "mode", "pagination", "request_id", "resource" ], "properties": { "api_version": { "type": "string", "const": "v1-2026-07" }, "mode": { "type": "string", "const": "list" }, "pagination": { "$ref": "#/components/schemas/PaginationMeta" }, "request_id": { "type": "string", "minLength": 1, "maxLength": 128 }, "resource": { "type": "string", "const": "business_donor_match_queue_item" } } }, "V1BusinessDonorMatchQueueListResponse": { "type": "object", "additionalProperties": false, "required": [ "data", "meta" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/BusinessDonorMatchQueueItem" } }, "meta": { "$ref": "#/components/schemas/V1BusinessDonorMatchQueueListMeta" } } }, "BusinessDonorMatchQueueStatsCounts": { "type": "object", "additionalProperties": false, "required": [ "pending", "resolved", "skipped", "high_confidence", "create_new" ], "properties": { "pending": { "type": "integer", "minimum": 0 }, "resolved": { "type": "integer", "minimum": 0 }, "skipped": { "type": "integer", "minimum": 0 }, "high_confidence": { "type": "integer", "minimum": 0 }, "create_new": { "type": "integer", "minimum": 0 } } }, "BusinessDonorMatchQueueStatsBankAccount": { "type": "object", "additionalProperties": false, "required": [ "bank_account_id", "pending", "resolved", "skipped", "high_confidence", "create_new" ], "properties": { "bank_account_id": { "type": "string" }, "account_name": { "type": [ "string", "null" ] }, "bank_name": { "type": [ "string", "null" ] }, "pending": { "type": "integer", "minimum": 0 }, "resolved": { "type": "integer", "minimum": 0 }, "skipped": { "type": "integer", "minimum": 0 }, "high_confidence": { "type": "integer", "minimum": 0 }, "create_new": { "type": "integer", "minimum": 0 } } }, "BusinessDonorMatchQueueStats": { "type": "object", "additionalProperties": false, "required": [ "object", "totals", "by_bank_account" ], "properties": { "object": { "type": "string", "const": "business_donor_match_queue_stats" }, "totals": { "$ref": "#/components/schemas/BusinessDonorMatchQueueStatsCounts" }, "by_bank_account": { "type": "array", "items": { "$ref": "#/components/schemas/BusinessDonorMatchQueueStatsBankAccount" } } } }, "V1BusinessDonorMatchQueueStatsMeta": { "type": "object", "required": [ "api_version", "mode", "request_id", "resource" ], "properties": { "api_version": { "type": "string", "const": "v1-2026-07" }, "mode": { "type": "string", "const": "stats" }, "request_id": { "type": "string", "minLength": 1, "maxLength": 128 }, "resource": { "type": "string", "const": "business_donor_match_queue_stats" } } }, "V1BusinessDonorMatchQueueStatsResponse": { "type": "object", "additionalProperties": false, "required": [ "data", "meta" ], "properties": { "data": { "$ref": "#/components/schemas/BusinessDonorMatchQueueStats" }, "meta": { "$ref": "#/components/schemas/V1BusinessDonorMatchQueueStatsMeta" } } }, "V1BusinessDonorMatchQueueMeta": { "type": "object", "required": [ "api_version", "mode", "request_id", "resource" ], "properties": { "api_version": { "type": "string", "const": "v1-2026-07" }, "mode": { "type": "string", "const": "detail" }, "request_id": { "type": "string", "minLength": 1, "maxLength": 128 }, "resource": { "type": "string", "const": "business_donor_match_queue_item" } } }, "V1BusinessDonorMatchQueueResponse": { "type": "object", "additionalProperties": false, "required": [ "data", "meta" ], "properties": { "data": { "$ref": "#/components/schemas/BusinessDonorMatchQueueItem" }, "meta": { "$ref": "#/components/schemas/V1BusinessDonorMatchQueueMeta" } } }, "BusinessCashOfferingBatchCreateLine": { "type": "object", "additionalProperties": false, "required": [ "donor_id", "fund_id", "amount" ], "properties": { "donor_id": { "type": "string", "format": "uuid" }, "fund_id": { "type": "string", "format": "uuid" }, "amount": { "type": "number", "exclusiveMinimum": 0, "description": "Cash amount for this donor/fund line. Use no more than 2 decimal places." } } }, "BusinessCashOfferingBatchCreateRequest": { "type": "object", "additionalProperties": false, "required": [ "external_batch_id", "branch_id", "collection_date", "count_date", "confirmed_cash_total", "petty_cash_bank_account_id", "lines" ], "properties": { "external_batch_id": { "type": "string", "minLength": 1, "maxLength": 200 }, "branch_id": { "type": "string", "minLength": 1, "maxLength": 200 }, "branch_name": { "type": [ "string", "null" ], "maxLength": 200 }, "collection_date": { "type": "string", "format": "date" }, "count_date": { "type": "string", "format": "date" }, "confirmed_cash_total": { "type": "number", "exclusiveMinimum": 0, "description": "Must exactly equal the sum of lines[].amount after rounding to pennies." }, "petty_cash_bank_account_id": { "type": "string", "format": "uuid" }, "counted_by_external_id": { "type": [ "string", "null" ], "maxLength": 200 }, "counted_by_name": { "type": [ "string", "null" ], "maxLength": 200 }, "lines": { "type": "array", "minItems": 1, "maxItems": 500, "items": { "$ref": "#/components/schemas/BusinessCashOfferingBatchCreateLine" } } } }, "V1BusinessCashOfferingBatchCreateMeta": { "type": "object", "required": [ "api_version", "mode", "request_id", "resource" ], "properties": { "api_version": { "type": "string", "const": "v1-2026-07" }, "mode": { "type": "string", "enum": [ "created", "existing" ] }, "request_id": { "type": "string", "minLength": 1, "maxLength": 128 }, "resource": { "type": "string", "const": "business_cash_offering_batch" } } }, "V1BusinessCashOfferingBatchCreateResponse": { "type": "object", "additionalProperties": false, "required": [ "data", "meta" ], "properties": { "data": { "$ref": "#/components/schemas/BusinessCashOfferingBatch" }, "meta": { "$ref": "#/components/schemas/V1BusinessCashOfferingBatchCreateMeta" } } }, "BusinessCashDepositPreparationCreateAllocation": { "type": "object", "additionalProperties": false, "required": [ "batch_id", "allocated_amount" ], "properties": { "batch_id": { "type": "string", "format": "uuid" }, "allocated_amount": { "type": "number", "exclusiveMinimum": 0, "description": "Cash amount allocated from this counted cash batch. Use no more than 2 decimal places." } } }, "BusinessCashDepositPreparationCreateRequest": { "type": "object", "additionalProperties": false, "required": [ "external_preparation_id", "branch_id", "deposit_date", "bank_account_id", "confirmed_deposit_total", "allocations" ], "properties": { "external_preparation_id": { "type": "string", "minLength": 1, "maxLength": 200 }, "branch_id": { "type": "string", "minLength": 1, "maxLength": 200 }, "branch_name": { "type": [ "string", "null" ], "maxLength": 200 }, "deposit_date": { "type": "string", "format": "date" }, "bank_account_id": { "type": "string", "format": "uuid" }, "confirmed_deposit_total": { "type": "number", "exclusiveMinimum": 0, "description": "Must exactly equal the sum of allocations[].allocated_amount after rounding to pennies." }, "reference": { "type": [ "string", "null" ], "maxLength": 300 }, "prepared_by_external_id": { "type": [ "string", "null" ], "maxLength": 200 }, "prepared_by_name": { "type": [ "string", "null" ], "maxLength": 200 }, "allocations": { "type": "array", "minItems": 1, "maxItems": 500, "items": { "$ref": "#/components/schemas/BusinessCashDepositPreparationCreateAllocation" } } } }, "V1BusinessCashDepositPreparationCreateMeta": { "type": "object", "required": [ "api_version", "mode", "request_id", "resource" ], "properties": { "api_version": { "type": "string", "const": "v1-2026-07" }, "mode": { "type": "string", "enum": [ "created", "existing" ] }, "request_id": { "type": "string", "minLength": 1, "maxLength": 128 }, "resource": { "type": "string", "const": "business_cash_deposit_preparation" } } }, "V1BusinessCashDepositPreparationCreateResponse": { "type": "object", "additionalProperties": false, "required": [ "data", "meta" ], "properties": { "data": { "$ref": "#/components/schemas/BusinessCashDepositPreparation" }, "meta": { "$ref": "#/components/schemas/V1BusinessCashDepositPreparationCreateMeta" } } }, "BusinessCashDepositPreparationCancelRequest": { "type": "object", "additionalProperties": false, "required": [ "reason" ], "properties": { "reason": { "type": "string", "minLength": 1, "maxLength": 500, "description": "Reason shown in the audit trail for cancelling the preparation." }, "cancelled_by_external_id": { "type": [ "string", "null" ], "maxLength": 200 }, "cancelled_by_name": { "type": [ "string", "null" ], "maxLength": 200 } } }, "V1BusinessCashDepositPreparationCancelMeta": { "type": "object", "required": [ "api_version", "mode", "request_id", "resource" ], "properties": { "api_version": { "type": "string", "const": "v1-2026-07" }, "mode": { "type": "string", "enum": [ "cancelled", "existing" ] }, "request_id": { "type": "string", "minLength": 1, "maxLength": 128 }, "resource": { "type": "string", "const": "business_cash_deposit_preparation" } } }, "V1BusinessCashDepositPreparationCancelResponse": { "type": "object", "required": [ "data", "meta" ], "properties": { "data": { "$ref": "#/components/schemas/BusinessCashDepositPreparation" }, "meta": { "$ref": "#/components/schemas/V1BusinessCashDepositPreparationCancelMeta" } } }, "BusinessCustomerCreateRequest": { "type": "object", "additionalProperties": false, "required": [ "name" ], "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 200 }, "customer_reference": { "type": [ "string", "null" ], "maxLength": 100 }, "contact_email": { "type": [ "string", "null" ], "format": "email", "maxLength": 320 }, "contact_phone": { "type": [ "string", "null" ], "maxLength": 100 }, "billing_address": { "type": [ "string", "null" ], "maxLength": 1000 }, "vat_number": { "type": [ "string", "null" ], "maxLength": 50 }, "default_vat_rate": { "type": [ "number", "null" ], "minimum": 0, "maximum": 100, "description": "Optional default VAT rate percentage, with no more than 2 decimal places." }, "default_payment_terms_days": { "type": [ "integer", "null" ], "minimum": 0, "maximum": 3650 }, "is_active": { "type": "boolean", "default": true }, "related_party": { "type": "boolean", "default": false }, "fao": { "type": [ "string", "null" ], "maxLength": 200 } } }, "V1BusinessCustomerCreateMeta": { "type": "object", "required": [ "api_version", "mode", "request_id", "resource" ], "properties": { "api_version": { "type": "string", "const": "v1-2026-07" }, "mode": { "type": "string", "const": "created" }, "request_id": { "type": "string", "minLength": 1, "maxLength": 128 }, "resource": { "type": "string", "const": "business_customer" } } }, "V1BusinessCustomerCreateResponse": { "type": "object", "required": [ "data", "meta" ], "properties": { "data": { "$ref": "#/components/schemas/BusinessCustomer" }, "meta": { "$ref": "#/components/schemas/V1BusinessCustomerCreateMeta" } } }, "BusinessSupplierCreateRequest": { "type": "object", "additionalProperties": false, "required": [ "name" ], "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 200 }, "supplier_reference": { "type": [ "string", "null" ], "maxLength": 100 }, "contact_email": { "type": [ "string", "null" ], "format": "email", "maxLength": 320 }, "contact_phone": { "type": [ "string", "null" ], "maxLength": 100 }, "address": { "type": [ "string", "null" ], "maxLength": 1000 }, "vat_number": { "type": [ "string", "null" ], "maxLength": 50 }, "default_vat_rate": { "type": [ "number", "null" ], "minimum": 0, "maximum": 100, "description": "Optional default VAT rate percentage, with no more than 2 decimal places." }, "payment_terms_days": { "type": [ "integer", "null" ], "minimum": 0, "maximum": 3650 }, "payment_method": { "type": [ "string", "null" ], "maxLength": 100 }, "default_nominal_code": { "type": [ "string", "null" ], "maxLength": 100 }, "default_chart_of_accounts_id": { "type": [ "string", "null" ], "format": "uuid" }, "budget_limit": { "type": [ "number", "null" ], "minimum": 0, "maximum": 9999999999999.99, "description": "Optional supplier budget limit, with no more than 2 decimal places." }, "flag_for_review": { "type": "boolean", "default": false }, "is_active": { "type": "boolean", "default": true }, "related_party": { "type": "boolean", "default": false }, "fao": { "type": [ "string", "null" ], "maxLength": 200 } } }, "V1BusinessSupplierCreateMeta": { "type": "object", "required": [ "api_version", "mode", "request_id", "resource" ], "properties": { "api_version": { "type": "string", "const": "v1-2026-07" }, "mode": { "type": "string", "const": "created" }, "request_id": { "type": "string", "minLength": 1, "maxLength": 128 }, "resource": { "type": "string", "const": "business_supplier" } } }, "V1BusinessSupplierCreateResponse": { "type": "object", "required": [ "data", "meta" ], "properties": { "data": { "$ref": "#/components/schemas/BusinessSupplier" }, "meta": { "$ref": "#/components/schemas/V1BusinessSupplierCreateMeta" } } }, "BusinessPurchaseInvoiceLineItemCreateRequest": { "type": "object", "additionalProperties": false, "required": [ "description", "unit_price" ], "properties": { "description": { "type": "string", "minLength": 1, "maxLength": 500 }, "quantity": { "type": "number", "exclusiveMinimum": 0, "maximum": 999999, "default": 1, "description": "Quantity with no more than 4 decimal places." }, "unit_price": { "type": "number", "minimum": 0, "maximum": 9999999999999.99, "description": "Net unit price with no more than 2 decimal places." }, "vat_rate": { "type": "number", "minimum": 0, "maximum": 100, "default": 0, "description": "VAT rate percentage with no more than 2 decimal places." }, "chart_of_accounts_id": { "type": [ "string", "null" ], "format": "uuid" }, "project_id": { "type": [ "string", "null" ], "format": "uuid" }, "fund_id": { "type": [ "string", "null" ], "format": "uuid" }, "cost_center_selections": { "type": "object", "default": {}, "additionalProperties": { "type": [ "string", "null" ] } }, "sort_order": { "type": "integer", "minimum": 0, "maximum": 1000 } } }, "BusinessPurchaseInvoiceCreateRequest": { "type": "object", "additionalProperties": false, "required": [ "supplier_id", "supplier_invoice_number", "invoice_date", "line_items" ], "properties": { "supplier_id": { "type": "string", "format": "uuid" }, "supplier_invoice_number": { "type": "string", "minLength": 1, "maxLength": 100 }, "invoice_date": { "type": "string", "format": "date" }, "due_date": { "type": [ "string", "null" ], "format": "date" }, "expected_payment_date": { "type": [ "string", "null" ], "format": "date" }, "currency": { "type": "string", "pattern": "^[A-Z]{3}$", "default": "GBP" }, "status": { "type": "string", "enum": [ "draft" ], "default": "draft" }, "notes": { "type": [ "string", "null" ], "maxLength": 2000 }, "purchase_order_id": { "type": [ "string", "null" ], "format": "uuid" }, "document_id": { "type": [ "string", "null" ], "format": "uuid" }, "chart_of_accounts_id": { "type": [ "string", "null" ], "format": "uuid" }, "project_id": { "type": [ "string", "null" ], "format": "uuid" }, "cost_center_id": { "type": [ "string", "null" ], "format": "uuid" }, "fund_id": { "type": [ "string", "null" ], "format": "uuid" }, "cost_center_selections": { "type": "object", "default": {}, "additionalProperties": { "type": [ "string", "null" ] } }, "document_required": { "type": "boolean", "default": true }, "line_items": { "type": "array", "minItems": 1, "maxItems": 100, "items": { "$ref": "#/components/schemas/BusinessPurchaseInvoiceLineItemCreateRequest" } } } }, "V1BusinessPurchaseInvoiceCreateMeta": { "type": "object", "required": [ "api_version", "mode", "request_id", "resource" ], "properties": { "api_version": { "type": "string", "const": "v1-2026-07" }, "mode": { "type": "string", "const": "created" }, "request_id": { "type": "string", "minLength": 1, "maxLength": 128 }, "resource": { "type": "string", "const": "purchase_invoice" } } }, "V1BusinessPurchaseInvoiceCreateResponse": { "type": "object", "required": [ "data", "meta" ], "properties": { "data": { "$ref": "#/components/schemas/PurchaseInvoice" }, "meta": { "$ref": "#/components/schemas/V1BusinessPurchaseInvoiceCreateMeta" } } }, "BusinessPurchaseOrderLineItemCreateRequest": { "type": "object", "additionalProperties": false, "required": [ "description", "unit_price" ], "properties": { "description": { "type": "string", "minLength": 1, "maxLength": 500 }, "sku": { "type": [ "string", "null" ], "maxLength": 100 }, "quantity": { "type": "number", "exclusiveMinimum": 0, "maximum": 999999, "default": 1, "description": "Quantity with no more than 4 decimal places." }, "unit_price": { "type": "number", "minimum": 0, "maximum": 9999999999999.99, "description": "Net unit price with no more than 2 decimal places." }, "vat_rate": { "type": "number", "minimum": 0, "maximum": 100, "default": 20, "description": "VAT rate percentage with no more than 2 decimal places." }, "chart_of_accounts_id": { "type": [ "string", "null" ], "format": "uuid", "description": "Optional line-level account. Defaults to the purchase order chart_of_accounts_id when omitted." }, "project_id": { "type": [ "string", "null" ], "format": "uuid", "description": "Optional line-level project. Defaults to the purchase order project_id when omitted." }, "sort_order": { "type": "integer", "minimum": 0, "maximum": 1000 } } }, "BusinessPurchaseOrderCreateRequest": { "type": "object", "additionalProperties": false, "required": [ "supplier_id", "line_items" ], "properties": { "supplier_id": { "type": "string", "format": "uuid" }, "order_date": { "type": "string", "format": "date", "description": "Defaults to the request date when omitted." }, "expected_delivery_date": { "type": [ "string", "null" ], "format": "date" }, "currency": { "type": "string", "pattern": "^[A-Z]{3}$", "default": "GBP" }, "status": { "type": "string", "enum": [ "draft" ], "default": "draft" }, "project_id": { "type": [ "string", "null" ], "format": "uuid" }, "chart_of_accounts_id": { "type": [ "string", "null" ], "format": "uuid" }, "department": { "type": [ "string", "null" ], "maxLength": 100 }, "budget_code": { "type": [ "string", "null" ], "maxLength": 100 }, "cost_center": { "type": [ "string", "null" ], "maxLength": 100 }, "delivery_address": { "type": [ "string", "null" ], "maxLength": 1000 }, "payment_terms": { "type": [ "string", "null" ], "maxLength": 200 }, "notes": { "type": [ "string", "null" ], "maxLength": 2000 }, "line_items": { "type": "array", "minItems": 1, "maxItems": 100, "items": { "$ref": "#/components/schemas/BusinessPurchaseOrderLineItemCreateRequest" } } } }, "V1BusinessPurchaseOrderCreateMeta": { "type": "object", "required": [ "api_version", "mode", "request_id", "resource" ], "properties": { "api_version": { "type": "string", "const": "v1-2026-07" }, "mode": { "type": "string", "const": "created" }, "request_id": { "type": "string", "minLength": 1, "maxLength": 128 }, "resource": { "type": "string", "const": "purchase_order" } } }, "V1BusinessPurchaseOrderCreateResponse": { "type": "object", "required": [ "data", "meta" ], "properties": { "data": { "$ref": "#/components/schemas/PurchaseOrder" }, "meta": { "$ref": "#/components/schemas/V1BusinessPurchaseOrderCreateMeta" } } }, "BusinessExpenseClaimantCreateRequest": { "type": "object", "additionalProperties": false, "required": [ "name", "email" ], "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 200 }, "email": { "type": "string", "format": "email", "minLength": 3, "maxLength": 320, "description": "Stored lowercase and unique per company." }, "phone": { "type": [ "string", "null" ], "maxLength": 100 }, "is_active": { "type": "boolean", "default": true } } }, "V1BusinessExpenseClaimantCreateMeta": { "type": "object", "required": [ "api_version", "mode", "request_id", "resource" ], "properties": { "api_version": { "type": "string", "const": "v1-2026-07" }, "mode": { "type": "string", "const": "created" }, "request_id": { "type": "string", "minLength": 1, "maxLength": 128 }, "resource": { "type": "string", "const": "expense_claimant" } } }, "V1BusinessExpenseClaimantCreateResponse": { "type": "object", "required": [ "data", "meta" ], "properties": { "data": { "$ref": "#/components/schemas/ExpenseClaimant" }, "meta": { "$ref": "#/components/schemas/V1BusinessExpenseClaimantCreateMeta" } } }, "BusinessExpenseClaimLineItemCreateRequest": { "type": "object", "additionalProperties": false, "required": [ "description", "unit_price" ], "properties": { "description": { "type": "string", "maxLength": 500 }, "expense_date": { "type": "string", "format": "date", "description": "Defaults to the claim_date when omitted." }, "supplier_id": { "type": [ "string", "null" ], "format": "uuid" }, "supplier_name_freetext": { "type": [ "string", "null" ], "maxLength": 200 }, "receipt_reference": { "type": [ "string", "null" ], "maxLength": 200 }, "quantity": { "type": "number", "exclusiveMinimum": 0, "maximum": 999999, "default": 1, "description": "Maximum 4 decimal places." }, "unit_price": { "type": "number", "minimum": 0, "maximum": 9999999999999.99, "description": "Maximum 2 decimal places." }, "vat_rate": { "type": "number", "minimum": 0, "maximum": 100, "default": 0, "description": "Maximum 2 decimal places." }, "chart_of_accounts_id": { "type": [ "string", "null" ], "format": "uuid" }, "document_id": { "type": [ "string", "null" ], "format": "uuid" }, "fund_id": { "type": [ "string", "null" ], "format": "uuid" }, "charity_activity_id": { "type": [ "string", "null" ], "format": "uuid" }, "project_id": { "type": [ "string", "null" ], "format": "uuid" } } }, "BusinessExpenseClaimCreateRequest": { "type": "object", "additionalProperties": false, "required": [ "claimant_id", "claim_date", "line_items" ], "properties": { "claimant_id": { "type": "string", "format": "uuid" }, "claim_date": { "type": "string", "format": "date" }, "due_date": { "type": [ "string", "null" ], "format": "date" }, "currency": { "type": "string", "pattern": "^[A-Z]{3}$", "default": "GBP" }, "status": { "type": "string", "enum": [ "draft" ], "default": "draft" }, "repayment_method": { "type": "string", "enum": [ "bill", "dla" ], "default": "bill" }, "dla_account_id": { "type": [ "string", "null" ], "format": "uuid", "description": "Required when repayment_method is dla; otherwise omit." }, "document_id": { "type": [ "string", "null" ], "format": "uuid" }, "fund_id": { "type": [ "string", "null" ], "format": "uuid" }, "project_id": { "type": [ "string", "null" ], "format": "uuid", "description": "Optional header project applied to lines unless a line-level project_id is provided." }, "cost_center_selections": { "type": "object", "additionalProperties": true, "default": {} }, "notes": { "type": [ "string", "null" ], "maxLength": 2000 }, "submitted_by_name": { "type": [ "string", "null" ], "maxLength": 200 }, "line_items": { "type": "array", "minItems": 1, "maxItems": 100, "items": { "$ref": "#/components/schemas/BusinessExpenseClaimLineItemCreateRequest" } } } }, "V1BusinessExpenseClaimCreateMeta": { "type": "object", "required": [ "api_version", "mode", "request_id", "resource" ], "properties": { "api_version": { "type": "string", "const": "v1-2026-07" }, "mode": { "type": "string", "const": "created" }, "request_id": { "type": "string" }, "resource": { "type": "string", "const": "expense_claim" } } }, "V1BusinessExpenseClaimCreateResponse": { "type": "object", "required": [ "data", "meta" ], "properties": { "data": { "$ref": "#/components/schemas/ExpenseClaim" }, "meta": { "$ref": "#/components/schemas/V1BusinessExpenseClaimCreateMeta" } } }, "BusinessQuoteLineItemCreateRequest": { "type": "object", "additionalProperties": true, "required": [ "description", "unit_price" ], "properties": { "line_number": { "type": "integer", "minimum": 1, "maximum": 2147483647 }, "description": { "type": "string" }, "subdescription": { "type": [ "string", "null" ] }, "quantity": { "type": [ "number", "string" ], "minimum": 0.000001, "default": 1 }, "unit_price": { "type": [ "number", "string" ], "minimum": 0, "default": 0 }, "vat_rate": { "type": [ "number", "string" ], "minimum": 0, "maximum": 100, "default": 0 }, "vat_rate_id": { "type": [ "string", "null" ], "format": "uuid" }, "revenue_account_id": { "type": [ "string", "null" ], "format": "uuid" }, "project_id": { "type": [ "string", "null" ], "format": "uuid" }, "cost_center_id": { "type": [ "string", "null" ], "format": "uuid" }, "fund_id": { "type": [ "string", "null" ], "format": "uuid" } } }, "BusinessQuoteCreateRequest": { "type": "object", "additionalProperties": true, "required": [ "customer_id", "line_items" ], "properties": { "customer_id": { "type": "string", "format": "uuid" }, "status": { "type": "string", "enum": [ "draft" ], "description": "If omitted, the API forces draft status." }, "quote_date": { "type": "string", "format": "date" }, "valid_until": { "type": [ "string", "null" ], "format": "date" }, "reference": { "type": [ "string", "null" ], "maxLength": 200 }, "currency": { "type": "string", "pattern": "^[A-Z]{3}$", "default": "GBP" }, "notes": { "type": [ "string", "null" ], "maxLength": 2000 }, "internal_notes": { "type": [ "string", "null" ], "maxLength": 2000 }, "fund_id": { "type": [ "string", "null" ], "format": "uuid" }, "line_items": { "type": "array", "minItems": 1, "items": { "$ref": "#/components/schemas/BusinessQuoteLineItemCreateRequest" } } } }, "V1BusinessQuoteCreateMeta": { "type": "object", "required": [ "api_version", "mode", "request_id", "resource" ], "properties": { "api_version": { "type": "string", "const": "v1-2026-07" }, "mode": { "type": "string", "const": "draft" }, "request_id": { "type": "string", "minLength": 1, "maxLength": 128 }, "resource": { "type": "string", "const": "quote" } } }, "V1BusinessQuoteCreateResponse": { "type": "object", "required": [ "data", "meta" ], "properties": { "data": { "$ref": "#/components/schemas/Quote" }, "meta": { "$ref": "#/components/schemas/V1BusinessQuoteCreateMeta" } } }, "BusinessQuoteLineItemUpdateRequest": { "type": "object", "additionalProperties": false, "required": [ "description", "unit_price" ], "properties": { "id": { "type": "string", "format": "uuid", "description": "Accepted for round-trip convenience. Replacing lines creates new active line records." }, "line_number": { "type": "integer", "minimum": 1, "maximum": 2147483647 }, "description": { "type": "string", "minLength": 1 }, "subdescription": { "type": [ "string", "null" ] }, "quantity": { "type": [ "number", "string" ], "minimum": 0.001, "default": 1 }, "unit_price": { "type": [ "number", "string" ], "minimum": 0 }, "vat_rate": { "type": [ "number", "string" ], "minimum": 0, "maximum": 100, "default": 0 }, "vat_rate_id": { "type": [ "string", "null" ], "format": "uuid" }, "revenue_account_id": { "type": [ "string", "null" ], "format": "uuid" }, "project_id": { "type": [ "string", "null" ], "format": "uuid" }, "cost_center_id": { "type": [ "string", "null" ], "format": "uuid" }, "fund_id": { "type": [ "string", "null" ], "format": "uuid" } } }, "BusinessQuoteUpdateRequest": { "type": "object", "additionalProperties": false, "minProperties": 2, "required": [ "expected_lock_version" ], "properties": { "expected_lock_version": { "type": "integer", "minimum": 1, "maximum": 2147483647, "description": "The lock_version returned by the latest quote read." }, "customer_id": { "type": "string", "format": "uuid" }, "quote_date": { "type": "string", "format": "date" }, "valid_until": { "type": [ "string", "null" ], "format": "date" }, "reference": { "type": [ "string", "null" ], "maxLength": 200 }, "currency": { "type": "string", "pattern": "^[A-Z]{3}$" }, "notes": { "type": [ "string", "null" ], "maxLength": 2000 }, "internal_notes": { "type": [ "string", "null" ], "maxLength": 2000 }, "fund_id": { "type": [ "string", "null" ], "format": "uuid" }, "line_items": { "type": "array", "minItems": 1, "description": "When supplied, replaces the active line set while retaining prior rows as archived history.", "items": { "$ref": "#/components/schemas/BusinessQuoteLineItemUpdateRequest" } } } }, "V1BusinessQuoteUpdateMeta": { "type": "object", "additionalProperties": false, "required": [ "api_version", "mode", "request_id", "resource", "scope" ], "properties": { "api_version": { "type": "string", "const": "v1-2026-07" }, "mode": { "type": "string", "const": "updated" }, "request_id": { "type": "string", "minLength": 1, "maxLength": 128 }, "resource": { "type": "string", "const": "quote" }, "scope": { "type": "string", "const": "business.quotes.update" } } }, "V1BusinessQuoteUpdateResponse": { "type": "object", "additionalProperties": false, "required": [ "data", "meta" ], "properties": { "data": { "$ref": "#/components/schemas/Quote" }, "meta": { "$ref": "#/components/schemas/V1BusinessQuoteUpdateMeta" } } }, "BusinessCreditNoteLineItemCreateRequest": { "type": "object", "additionalProperties": true, "required": [ "description", "unit_price" ], "properties": { "line_number": { "type": "integer", "minimum": 1 }, "description": { "type": "string" }, "quantity": { "type": [ "number", "string" ], "minimum": 0.000001, "default": 1 }, "unit_price": { "type": [ "number", "string" ], "minimum": 0, "default": 0 }, "vat_rate": { "type": [ "number", "string" ], "minimum": 0, "maximum": 100, "default": 0 }, "vat_rate_id": { "type": [ "string", "null" ], "format": "uuid" }, "revenue_account_id": { "type": [ "string", "null" ], "format": "uuid" }, "project_id": { "type": [ "string", "null" ], "format": "uuid" }, "cost_center_id": { "type": [ "string", "null" ], "format": "uuid" }, "fund_id": { "type": [ "string", "null" ], "format": "uuid" } } }, "BusinessCreditNoteCreateRequest": { "type": "object", "additionalProperties": true, "required": [ "customer_id", "line_items" ], "properties": { "customer_id": { "type": "string", "format": "uuid" }, "status": { "type": "string", "enum": [ "draft" ], "description": "If omitted, the API forces draft status." }, "original_invoice_id": { "type": [ "string", "null" ], "format": "uuid" }, "credit_note_date": { "type": "string", "format": "date" }, "reason": { "type": [ "string", "null" ], "maxLength": 500 }, "currency": { "type": "string", "pattern": "^[A-Z]{3}$", "default": "GBP" }, "notes": { "type": [ "string", "null" ], "maxLength": 2000 }, "internal_notes": { "type": [ "string", "null" ], "maxLength": 2000 }, "fund_id": { "type": [ "string", "null" ], "format": "uuid" }, "line_items": { "type": "array", "minItems": 1, "items": { "$ref": "#/components/schemas/BusinessCreditNoteLineItemCreateRequest" } } } }, "V1BusinessCreditNoteCreateMeta": { "type": "object", "required": [ "api_version", "mode", "request_id", "resource" ], "properties": { "api_version": { "type": "string", "const": "v1-2026-07" }, "mode": { "type": "string", "const": "draft" }, "request_id": { "type": "string", "minLength": 1, "maxLength": 128 }, "resource": { "type": "string", "const": "credit_note" } } }, "V1BusinessCreditNoteCreateResponse": { "type": "object", "required": [ "data", "meta" ], "properties": { "data": { "$ref": "#/components/schemas/CreditNote" }, "meta": { "$ref": "#/components/schemas/V1BusinessCreditNoteCreateMeta" } } }, "BusinessDocumentUploadRequest": { "type": "object", "additionalProperties": true, "required": [ "file_name", "file_content" ], "properties": { "file_name": { "type": "string", "minLength": 1 }, "file_content": { "type": "string", "format": "byte", "description": "Base64-encoded file content." }, "file_type": { "type": [ "string", "null" ], "description": "Optional MIME type. If supplied, it must match the file extension." }, "status": { "type": [ "string", "null" ] }, "document_type": { "type": [ "string", "null" ] }, "document_classification": { "type": [ "string", "null" ] }, "description": { "type": [ "string", "null" ], "maxLength": 2000 }, "notes": { "type": [ "string", "null" ], "maxLength": 2000 }, "linked_purchase_invoice_id": { "type": [ "string", "null" ], "format": "uuid" }, "linked_purchase_order_id": { "type": [ "string", "null" ], "format": "uuid" }, "linked_bank_transaction_id": { "type": [ "string", "null" ], "format": "uuid" }, "customer_id": { "type": [ "string", "null" ], "format": "uuid" }, "supplier_id": { "type": [ "string", "null" ], "format": "uuid" } } }, "V1BusinessDocumentUploadMeta": { "type": "object", "required": [ "api_version", "mode", "request_id", "resource" ], "properties": { "api_version": { "type": "string", "const": "v1-2026-07" }, "mode": { "type": "string", "const": "uploaded" }, "request_id": { "type": "string", "minLength": 1, "maxLength": 128 }, "resource": { "type": "string", "const": "business_document" } } }, "V1BusinessDocumentUploadResponse": { "type": "object", "required": [ "data", "meta" ], "properties": { "data": { "$ref": "#/components/schemas/BusinessDocument" }, "meta": { "$ref": "#/components/schemas/V1BusinessDocumentUploadMeta" } } }, "PersonalAssetCreateRequest": { "type": "object", "additionalProperties": false, "required": [ "name", "asset_type", "current_value" ], "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 120 }, "asset_type": { "type": "string", "enum": [ "property", "vehicle", "investment", "savings", "other" ] }, "current_value": { "type": "number", "minimum": 0, "maximum": 999999999999.99 }, "purchase_date": { "type": [ "string", "null" ], "format": "date" }, "purchase_price": { "type": [ "number", "null" ], "minimum": 0, "maximum": 999999999999.99 }, "description": { "type": [ "string", "null" ], "maxLength": 500 }, "is_active": { "type": "boolean", "default": true } } }, "PersonalAssetCreateResponse": { "type": "object", "required": [ "data", "meta" ], "properties": { "data": { "$ref": "#/components/schemas/PersonalAsset" }, "meta": { "$ref": "#/components/schemas/PersonalAssetCreateMeta" } } }, "PersonalAssetCreateMeta": { "type": "object", "required": [ "api_version", "mode", "request_id", "resource", "scope" ], "properties": { "api_version": { "type": "string", "const": "v1-2026-07" }, "mode": { "type": "string", "const": "created" }, "request_id": { "type": "string", "minLength": 1, "maxLength": 128 }, "resource": { "type": "string", "const": "personal_asset" }, "scope": { "type": "string", "const": "personal.assets.write" } } }, "PersonalLiabilityCreateRequest": { "type": "object", "additionalProperties": false, "required": [ "name", "liability_type", "current_balance" ], "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 120 }, "liability_type": { "type": "string", "enum": [ "mortgage", "loan", "credit_card", "other" ] }, "current_balance": { "type": "number", "minimum": 0, "maximum": 999999999999.99 }, "interest_rate": { "type": [ "number", "null" ], "minimum": 0, "maximum": 100 }, "minimum_payment": { "type": [ "number", "null" ], "minimum": 0, "maximum": 999999999999.99 }, "payment_due_date": { "type": [ "integer", "null" ], "minimum": 1, "maximum": 31 }, "original_amount": { "type": [ "number", "null" ], "minimum": 0, "maximum": 999999999999.99 }, "start_date": { "type": [ "string", "null" ], "format": "date" }, "maturity_date": { "type": [ "string", "null" ], "format": "date" }, "is_active": { "type": "boolean", "default": true } } }, "PersonalLiabilityCreateResponse": { "type": "object", "required": [ "data", "meta" ], "properties": { "data": { "$ref": "#/components/schemas/PersonalLiability" }, "meta": { "$ref": "#/components/schemas/PersonalLiabilityCreateMeta" } } }, "PersonalLiabilityCreateMeta": { "type": "object", "required": [ "api_version", "mode", "request_id", "resource", "scope" ], "properties": { "api_version": { "type": "string", "const": "v1-2026-07" }, "mode": { "type": "string", "const": "created" }, "request_id": { "type": "string", "minLength": 1, "maxLength": 128 }, "resource": { "type": "string", "const": "personal_liability" }, "scope": { "type": "string", "const": "personal.liabilities.write" } } }, "PersonalBudgetCreateRequest": { "type": "object", "additionalProperties": false, "required": [ "budget_amount", "start_date", "end_date" ], "properties": { "category_id": { "type": [ "string", "null" ], "format": "uuid", "description": "Optional personal category owned by the bearer-token user. Required when category_name is omitted." }, "category_name": { "type": "string", "minLength": 1, "maxLength": 120, "description": "Required when category_id is omitted. If category_id is supplied without category_name, the category name is copied from the owned category." }, "budget_type": { "type": "string", "enum": [ "expense", "income", "savings" ], "default": "expense" }, "period_type": { "type": "string", "enum": [ "weekly", "monthly", "yearly" ], "default": "monthly" }, "budget_month": { "type": [ "string", "null" ], "format": "date", "description": "Defaults to start_date when omitted." }, "budget_amount": { "type": "number", "minimum": 0, "maximum": 999999999999.99 }, "spent_amount": { "type": [ "number", "null" ], "minimum": 0, "maximum": 999999999999.99 }, "currency": { "type": "string", "pattern": "^[A-Z]{3}$", "default": "GBP" }, "start_date": { "type": "string", "format": "date" }, "end_date": { "type": "string", "format": "date" }, "day_of_week": { "type": [ "integer", "null" ], "minimum": 1, "maximum": 7 }, "is_active": { "type": "boolean", "default": true }, "is_template": { "type": [ "boolean", "null" ], "default": true }, "rollover_enabled": { "type": [ "boolean", "null" ], "default": false }, "template_id": { "type": [ "string", "null" ], "format": "uuid", "description": "Optional budget template owned by the bearer-token user." } } }, "PersonalBudgetCreateResponse": { "type": "object", "required": [ "data", "meta" ], "properties": { "data": { "$ref": "#/components/schemas/PersonalBudget" }, "meta": { "$ref": "#/components/schemas/PersonalBudgetCreateMeta" } } }, "PersonalBudgetCreateMeta": { "type": "object", "required": [ "api_version", "mode", "request_id", "resource", "scope" ], "properties": { "api_version": { "type": "string", "const": "v1-2026-07" }, "mode": { "type": "string", "const": "created" }, "request_id": { "type": "string", "minLength": 1, "maxLength": 128 }, "resource": { "type": "string", "const": "personal_budget" }, "scope": { "type": "string", "const": "personal.budgets.write" } } }, "BusinessProjectCreateRequest": { "type": "object", "additionalProperties": false, "required": [ "code", "name" ], "properties": { "code": { "type": "string", "minLength": 1, "maxLength": 50 }, "name": { "type": "string", "minLength": 1, "maxLength": 160 }, "description": { "type": [ "string", "null" ], "maxLength": 1000 }, "budget": { "type": [ "number", "null" ], "minimum": 0, "maximum": 999999999999.99 }, "expected_income": { "type": [ "number", "null" ], "minimum": 0, "maximum": 999999999999.99 }, "expected_costs": { "type": [ "number", "null" ], "minimum": 0, "maximum": 999999999999.99 }, "start_date": { "type": [ "string", "null" ], "format": "date" }, "end_date": { "type": [ "string", "null" ], "format": "date" }, "is_active": { "type": "boolean", "default": true } } }, "BusinessProjectCreateResponse": { "type": "object", "required": [ "data", "meta" ], "properties": { "data": { "$ref": "#/components/schemas/BusinessProject" }, "meta": { "$ref": "#/components/schemas/BusinessProjectCreateMeta" } } }, "BusinessProjectCreateMeta": { "type": "object", "required": [ "api_version", "mode", "request_id", "resource" ], "properties": { "api_version": { "type": "string", "const": "v1-2026-07" }, "mode": { "type": "string", "const": "created" }, "request_id": { "type": "string", "minLength": 1, "maxLength": 128 }, "resource": { "type": "string", "const": "business_project" } } }, "BusinessFundCreateRequest": { "type": "object", "additionalProperties": false, "required": [ "name" ], "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 160 }, "code": { "type": [ "string", "null" ], "maxLength": 50 }, "fund_class": { "type": "string", "enum": [ "unrestricted", "restricted_income", "endowment" ], "default": "unrestricted" }, "fund_type": { "type": "string", "enum": [ "unrestricted", "restricted", "designated", "endowment" ], "description": "Legacy fund-type input. If supplied with fund_class, both values must describe the same fund class." }, "unrestricted_subtype": { "type": [ "string", "null" ], "enum": [ "general", "designated", null ], "description": "Allowed only for unrestricted funds." }, "endowment_subtype": { "type": [ "string", "null" ], "enum": [ "permanent", "expendable", null ], "description": "Allowed only for endowment funds." }, "purpose": { "type": [ "string", "null" ], "maxLength": 1000 }, "restriction_summary": { "type": [ "string", "null" ], "maxLength": 1000 }, "restriction_reference": { "type": [ "string", "null" ], "maxLength": 1000 }, "opened_on": { "type": "string", "format": "date" }, "display_order": { "type": "integer", "minimum": 0, "maximum": 999999 }, "is_active": { "type": "boolean", "default": true } } }, "BusinessFundCreateResponse": { "type": "object", "required": [ "data", "meta" ], "properties": { "data": { "$ref": "#/components/schemas/BusinessFund" }, "meta": { "$ref": "#/components/schemas/BusinessFundCreateMeta" } } }, "BusinessFundCreateMeta": { "type": "object", "required": [ "api_version", "mode", "request_id", "resource" ], "properties": { "api_version": { "type": "string", "const": "v1-2026-07" }, "mode": { "type": "string", "const": "created" }, "request_id": { "type": "string", "minLength": 1, "maxLength": 128 }, "resource": { "type": "string", "const": "business_fund" } } }, "BusinessGiftAidDonorCreateRequest": { "type": "object", "additionalProperties": false, "required": [ "first_name", "last_name", "address_line_1", "city", "postcode" ], "properties": { "title": { "type": [ "string", "null" ], "maxLength": 50 }, "first_name": { "type": "string", "minLength": 1, "maxLength": 100 }, "last_name": { "type": "string", "minLength": 1, "maxLength": 100 }, "address_line_1": { "type": "string", "minLength": 1, "maxLength": 200 }, "address_line_2": { "type": [ "string", "null" ], "maxLength": 200 }, "city": { "type": "string", "minLength": 1, "maxLength": 100 }, "county": { "type": [ "string", "null" ], "maxLength": 100 }, "postcode": { "type": "string", "minLength": 1, "maxLength": 20 }, "country": { "type": [ "string", "null" ], "maxLength": 100, "default": "United Kingdom" }, "email": { "type": [ "string", "null" ], "format": "email", "maxLength": 320 }, "telephone": { "type": [ "string", "null" ], "maxLength": 50 }, "external_id": { "type": [ "string", "null" ], "maxLength": 100 }, "notes": { "type": [ "string", "null" ], "maxLength": 2000 }, "is_active": { "type": "boolean", "default": true } } }, "BusinessGiftAidDonorCreateResponse": { "type": "object", "required": [ "data", "meta" ], "properties": { "data": { "$ref": "#/components/schemas/BusinessGiftAidDonor" }, "meta": { "$ref": "#/components/schemas/BusinessGiftAidDonorCreateMeta" } } }, "BusinessGiftAidDonorCreateMeta": { "type": "object", "required": [ "api_version", "mode", "request_id", "resource" ], "properties": { "api_version": { "type": "string", "const": "v1-2026-07" }, "mode": { "type": "string", "const": "created" }, "request_id": { "type": "string", "minLength": 1, "maxLength": 128 }, "resource": { "type": "string", "const": "business_gift_aid_donor" } } }, "BusinessGiftAidDeclarationCreateRequest": { "type": "object", "additionalProperties": false, "required": [ "channel", "declaration_date", "declaration_type", "donor_id", "wording_version" ], "properties": { "donor_id": { "type": "string", "format": "uuid", "description": "Existing Gift Aid donor id for the same business company." }, "declaration_type": { "type": "string", "enum": [ "single", "ongoing", "retrospective_ongoing" ] }, "declaration_date": { "type": "string", "format": "date", "description": "Date the declaration was made." }, "effective_from": { "type": "string", "format": "date", "nullable": true, "description": "Optional effective date. Required for retrospective_ongoing declarations and must be on or before declaration_date." }, "channel": { "type": "string", "enum": [ "paper", "online", "phone", "email" ] }, "wording_version": { "type": "string", "maxLength": 100, "description": "Version identifier for the declaration wording shown to the donor." }, "declaration_text": { "type": "string", "maxLength": 4000, "nullable": true }, "evidence_ip_address": { "type": "string", "maxLength": 100, "nullable": true }, "evidence_timestamp": { "type": "string", "format": "date-time", "nullable": true }, "evidence_file_reference": { "type": "string", "maxLength": 500, "nullable": true } } }, "V1BusinessGiftAidDeclarationCreateMeta": { "type": "object", "required": [ "api_version", "mode", "request_id", "resource" ], "properties": { "api_version": { "type": "string", "const": "v1-2026-07" }, "mode": { "type": "string", "const": "created" }, "request_id": { "type": "string", "minLength": 1, "maxLength": 128 }, "resource": { "type": "string", "const": "business_gift_aid_declaration" } } }, "BusinessGiftAidDeclarationCreateResponse": { "type": "object", "additionalProperties": false, "required": [ "data", "meta" ], "properties": { "data": { "$ref": "#/components/schemas/BusinessGiftAidDeclaration" }, "meta": { "$ref": "#/components/schemas/V1BusinessGiftAidDeclarationCreateMeta" } } }, "BusinessGiftAidDonationCreateRequest": { "type": "object", "additionalProperties": false, "required": [ "donor_id", "donation_date", "gross_amount" ], "properties": { "donor_id": { "type": "string", "format": "uuid", "description": "Existing Gift Aid donor id for the same business company." }, "declaration_id": { "type": "string", "format": "uuid", "nullable": true, "description": "Existing active declaration id for the same donor. Required when gift_aid_eligible is true or omitted." }, "bank_transaction_id": { "type": "string", "format": "uuid", "nullable": true, "description": "Optional existing incoming bank transaction id for the same business company." }, "fund_id": { "type": "string", "format": "uuid", "nullable": true, "description": "Optional existing fund id for the same business company." }, "donation_date": { "type": "string", "format": "date" }, "gross_amount": { "type": "number", "exclusiveMinimum": 0, "description": "Donation amount in GBP, with no more than 2 decimal places." }, "currency": { "type": "string", "enum": [ "GBP" ], "default": "GBP" }, "payment_method": { "type": "string", "nullable": true, "enum": [ "bank_transfer", "cash", "card", "cheque", "direct_debit", "open_banking", "other" ] }, "reference": { "type": "string", "maxLength": 200, "nullable": true }, "description": { "type": "string", "maxLength": 1000, "nullable": true }, "gift_aid_eligible": { "type": "boolean", "default": true }, "ineligibility_reason": { "type": "string", "maxLength": 1000, "nullable": true, "description": "Required when gift_aid_eligible is false. Not accepted when gift_aid_eligible is true." }, "is_sponsored_event": { "type": "boolean", "default": false }, "benefit_provided": { "type": "boolean", "default": false }, "benefit_description": { "type": "string", "maxLength": 1000, "nullable": true, "description": "Required when benefit_provided is true." }, "benefit_value": { "type": "number", "minimum": 0, "default": 0, "description": "Benefit value in GBP, with no more than 2 decimal places." } } }, "V1BusinessGiftAidDonationCreateMeta": { "type": "object", "required": [ "api_version", "mode", "request_id", "resource" ], "properties": { "api_version": { "type": "string", "const": "v1-2026-07" }, "mode": { "type": "string", "const": "created" }, "request_id": { "type": "string", "minLength": 1, "maxLength": 128 }, "resource": { "type": "string", "const": "business_gift_aid_donation" } } }, "BusinessGiftAidDonationCreateResponse": { "type": "object", "additionalProperties": false, "required": [ "data", "meta" ], "properties": { "data": { "$ref": "#/components/schemas/BusinessGiftAidDonation" }, "meta": { "$ref": "#/components/schemas/V1BusinessGiftAidDonationCreateMeta" } } }, "BusinessChartOfAccountCreateRequest": { "type": "object", "additionalProperties": false, "required": [ "code", "name", "account_type", "statutory_category" ], "properties": { "code": { "type": "string", "minLength": 1, "maxLength": 50 }, "name": { "type": "string", "minLength": 1, "maxLength": 200 }, "account_type": { "type": "string", "enum": [ "Fixed Asset", "Current Asset", "Bank & Cash", "Liability", "Capital & Reserves", "Revenue", "Cost of Sales", "Administrative Expenses", "Other Income & Expenses", "Tax & Appropriations", "Control & Suspense" ] }, "statutory_category": { "type": "string", "enum": [ "Turnover", "Other Operating Income", "Cost of Sales", "Administrative Expenses", "Interest Receivable and Similar Income", "Interest Payable and Similar Charges", "Tax on Profit", "Fixed Assets", "Current Assets", "Creditors: amounts falling due within one year", "Creditors: amounts falling due after more than one year", "Provisions for Liabilities", "Capital and Reserves" ] }, "financial_statement": { "type": [ "string", "null" ], "enum": [ "Balance Sheet", "Profit & Loss", null ] }, "description": { "type": [ "string", "null" ], "maxLength": 1000 }, "area": { "type": [ "string", "null" ], "maxLength": 160 }, "ma_category": { "type": [ "string", "null" ], "maxLength": 160 }, "ma_sub_category": { "type": [ "string", "null" ], "maxLength": 160 }, "parent_code": { "type": [ "string", "null" ], "maxLength": 50 }, "standard_category_code": { "type": [ "string", "null" ], "maxLength": 100 }, "statutory_subcategory": { "type": [ "string", "null" ], "maxLength": 160 }, "tax_treatment": { "type": [ "string", "null" ], "maxLength": 160 }, "is_active": { "type": "boolean", "default": true } } }, "V1BusinessChartOfAccountCreateMeta": { "type": "object", "required": [ "api_version", "mode", "request_id", "resource" ], "properties": { "api_version": { "type": "string", "const": "v1-2026-07" }, "mode": { "type": "string", "const": "created" }, "request_id": { "type": "string", "minLength": 1, "maxLength": 128 }, "resource": { "type": "string", "const": "business_chart_of_account" } } }, "BusinessChartOfAccountCreateResponse": { "type": "object", "required": [ "data", "meta" ], "properties": { "data": { "$ref": "#/components/schemas/BusinessChartOfAccount" }, "meta": { "$ref": "#/components/schemas/V1BusinessChartOfAccountCreateMeta" } } }, "BusinessCostCenterLevelCreateRequest": { "type": "object", "additionalProperties": false, "required": [ "name" ], "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 160 }, "description": { "type": [ "string", "null" ], "maxLength": 1000 }, "requirement_type": { "type": "string", "enum": [ "optional", "always_required", "account_specific" ], "default": "optional" }, "display_order": { "type": "integer", "minimum": 0, "maximum": 999999, "default": 0 }, "is_active": { "type": "boolean", "default": true } } }, "BusinessCostCenterLevelCreateMeta": { "type": "object", "required": [ "api_version", "mode", "request_id", "resource", "total_options" ], "properties": { "api_version": { "type": "string", "const": "v1-2026-07" }, "mode": { "type": "string", "const": "created" }, "request_id": { "type": "string", "minLength": 1, "maxLength": 128 }, "resource": { "type": "string", "const": "business_cost_center" }, "total_options": { "type": "integer", "minimum": 0, "const": 0 } } }, "BusinessCostCenterLevelCreateResponse": { "type": "object", "required": [ "data", "meta" ], "properties": { "data": { "$ref": "#/components/schemas/BusinessCostCenterLevel" }, "meta": { "$ref": "#/components/schemas/BusinessCostCenterLevelCreateMeta" } } }, "BusinessCostCenterOptionCreateRequest": { "type": "object", "additionalProperties": false, "required": [ "name" ], "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 160 }, "code": { "type": [ "string", "null" ], "maxLength": 50 }, "description": { "type": [ "string", "null" ], "maxLength": 1000 }, "is_active": { "type": "boolean", "default": true } } }, "BusinessCostCenterOptionMeta": { "type": "object", "required": [ "api_version", "mode", "request_id", "resource" ], "properties": { "api_version": { "type": "string", "const": "v1-2026-07" }, "mode": { "type": "string", "const": "detail" }, "request_id": { "type": "string", "minLength": 1, "maxLength": 128 }, "resource": { "type": "string", "const": "business_cost_center_option" } } }, "BusinessCostCenterOptionResponse": { "type": "object", "required": [ "data", "meta" ], "properties": { "data": { "$ref": "#/components/schemas/BusinessCostCenterOption" }, "meta": { "$ref": "#/components/schemas/BusinessCostCenterOptionMeta" } } }, "BusinessCostCenterOptionCreateMeta": { "type": "object", "required": [ "api_version", "mode", "request_id", "resource" ], "properties": { "api_version": { "type": "string", "const": "v1-2026-07" }, "mode": { "type": "string", "const": "created" }, "request_id": { "type": "string", "minLength": 1, "maxLength": 128 }, "resource": { "type": "string", "const": "business_cost_center_option" } } }, "BusinessCostCenterOptionCreateResponse": { "type": "object", "required": [ "data", "meta" ], "properties": { "data": { "$ref": "#/components/schemas/BusinessCostCenterOption" }, "meta": { "$ref": "#/components/schemas/BusinessCostCenterOptionCreateMeta" } } }, "PersonalAccountCreateRequest": { "type": "object", "additionalProperties": false, "required": [ "account_name" ], "properties": { "account_name": { "type": "string", "minLength": 1, "maxLength": 120, "description": "Display name for the manual personal account." }, "bank_name": { "type": "string", "minLength": 1, "maxLength": 120, "default": "Manual", "description": "Institution label shown for the manual account." }, "account_type": { "type": "string", "enum": [ "current", "savings", "credit_card", "loan", "investment" ], "default": "current" }, "account_category": { "type": [ "string", "null" ], "enum": [ "current_account", "corporation_tax", "vat", "savings", "petty_cash", "expense_card", null ], "description": "Optional category. Defaults from account_type where a safe default exists." }, "currency": { "type": "string", "pattern": "^[A-Z]{3}$", "default": "GBP" }, "current_balance": { "type": "number", "minimum": -999999999999.99, "maximum": 999999999999.99, "default": 0, "description": "Opening display balance for the manual account. It does not create transactions or ledger entries." }, "is_active": { "type": "boolean", "default": true } } }, "PersonalAccountCreateMeta": { "type": "object", "required": [ "api_version", "mode", "request_id", "resource", "scope" ], "properties": { "api_version": { "type": "string", "const": "v1-2026-07" }, "mode": { "type": "string", "const": "created" }, "request_id": { "type": "string", "minLength": 1, "maxLength": 128 }, "resource": { "type": "string", "const": "personal_account" }, "scope": { "type": "string", "const": "personal.accounts.write" } } }, "PersonalAccountCreateResponse": { "type": "object", "required": [ "data", "meta" ], "properties": { "data": { "$ref": "#/components/schemas/PersonalAccount" }, "meta": { "$ref": "#/components/schemas/PersonalAccountCreateMeta" } } }, "V1BusinessBankAccountCreateRequest": { "type": "object", "additionalProperties": false, "required": [ "account_name" ], "properties": { "account_name": { "type": "string", "minLength": 1, "maxLength": 120, "description": "Display name for the manual business bank account." }, "bank_name": { "type": "string", "minLength": 1, "maxLength": 120, "default": "Manual", "description": "Institution label shown for the manual account." }, "account_type": { "type": "string", "enum": [ "current", "savings", "credit_card", "loan", "investment" ], "default": "current" }, "account_category": { "type": [ "string", "null" ], "enum": [ "current_account", "corporation_tax", "vat", "savings", "petty_cash", "expense_card", null ], "description": "Optional bank account category. Defaults from account_type where a safe default exists." }, "chart_of_accounts_id": { "type": [ "string", "null" ], "format": "uuid", "description": "Optional existing chart-of-accounts entry owned by the same business company." }, "currency": { "type": "string", "pattern": "^[A-Z]{3}$", "default": "GBP" }, "current_balance": { "type": "number", "minimum": -999999999999.99, "maximum": 999999999999.99, "default": 0, "description": "Opening display balance. This does not create transactions, reconciliation lines or ledger entries." }, "is_active": { "type": "boolean", "default": true } } }, "V1BusinessBankAccountCreateMeta": { "type": "object", "required": [ "api_version", "mode", "request_id", "resource" ], "properties": { "api_version": { "type": "string", "const": "v1-2026-07" }, "mode": { "type": "string", "const": "created" }, "request_id": { "type": "string", "minLength": 1, "maxLength": 128 }, "resource": { "type": "string", "const": "business_bank_account" } } }, "V1BusinessBankAccountCreateResponse": { "type": "object", "required": [ "data", "meta" ], "properties": { "data": { "$ref": "#/components/schemas/BusinessBankAccount" }, "meta": { "$ref": "#/components/schemas/V1BusinessBankAccountCreateMeta" } } }, "PersonalTransactionCreateRequest": { "type": "object", "additionalProperties": false, "required": [ "bank_account_id", "transaction_date", "description", "gross_amount" ], "properties": { "bank_account_id": { "type": "string", "format": "uuid", "description": "Owned personal account that the manual transaction belongs to." }, "transaction_date": { "type": "string", "format": "date", "description": "Transaction date in YYYY-MM-DD format." }, "description": { "type": "string", "minLength": 1, "maxLength": 240 }, "gross_amount": { "type": "number", "minimum": -999999999999.99, "maximum": 999999999999.99, "description": "Signed amount. Debits are negative and credits are positive." }, "transaction_type": { "type": "string", "enum": [ "debit", "credit" ], "description": "Optional. If supplied it must match the sign of gross_amount." }, "currency": { "type": "string", "pattern": "^[A-Z]{3}$", "default": "GBP" }, "personal_category_id": { "type": [ "string", "null" ], "format": "uuid", "description": "Optional owned personal category to mark the transaction as categorised." }, "merchant_name": { "type": [ "string", "null" ], "maxLength": 140 }, "reference": { "type": [ "string", "null" ], "maxLength": 200 }, "receipt_attached": { "type": "boolean", "default": false }, "receipt_required": { "type": "boolean", "default": false } } }, "PersonalTransactionCreateMeta": { "type": "object", "required": [ "api_version", "mode", "request_id", "resource", "scope" ], "properties": { "api_version": { "type": "string", "const": "v1-2026-07" }, "mode": { "type": "string", "const": "created" }, "request_id": { "type": "string", "minLength": 1, "maxLength": 128 }, "resource": { "type": "string", "const": "personal_transaction" }, "scope": { "type": "string", "const": "personal.transactions.write" } } }, "PersonalTransactionCreateResponse": { "type": "object", "required": [ "data", "meta" ], "properties": { "data": { "$ref": "#/components/schemas/PersonalTransaction" }, "meta": { "$ref": "#/components/schemas/PersonalTransactionCreateMeta" } } }, "BusinessTransactionCreateRequest": { "type": "object", "additionalProperties": false, "required": [ "bank_account_id", "transaction_date", "description", "gross_amount" ], "properties": { "bank_account_id": { "type": "string", "format": "uuid", "description": "Business bank account owned by the requested company." }, "transaction_date": { "type": "string", "format": "date", "description": "Transaction date in YYYY-MM-DD format." }, "description": { "type": "string", "minLength": 1, "maxLength": 240 }, "gross_amount": { "type": "number", "minimum": -999999999999.99, "maximum": 999999999999.99, "description": "Signed amount. Debits are negative and credits are positive." }, "transaction_type": { "type": "string", "enum": [ "debit", "credit" ], "description": "Optional. If supplied it must match the sign of gross_amount." }, "currency": { "type": "string", "pattern": "^[A-Z]{3}$", "default": "GBP" }, "chart_of_accounts_id": { "type": [ "string", "null" ], "format": "uuid", "description": "Optional chart of accounts category owned by the requested company." }, "merchant_name": { "type": [ "string", "null" ], "maxLength": 140 }, "reference": { "type": [ "string", "null" ], "maxLength": 200 }, "receipt_attached": { "type": "boolean", "default": false }, "receipt_required": { "type": "boolean", "default": false } } }, "V1BusinessTransactionCreateMeta": { "type": "object", "required": [ "api_version", "mode", "request_id", "resource" ], "properties": { "api_version": { "type": "string", "const": "v1-2026-07" }, "mode": { "type": "string", "const": "created" }, "request_id": { "type": "string", "minLength": 1, "maxLength": 128 }, "resource": { "type": "string", "const": "business_transaction" } } }, "BusinessTransactionCreateResponse": { "type": "object", "required": [ "data", "meta" ], "properties": { "data": { "$ref": "#/components/schemas/BusinessTransaction" }, "meta": { "$ref": "#/components/schemas/V1BusinessTransactionCreateMeta" } } }, "BusinessJournalEntryAccount": { "type": "object", "nullable": true, "additionalProperties": false, "required": [ "id", "code", "name", "account_type", "financial_statement" ], "properties": { "id": { "type": "string", "format": "uuid" }, "code": { "type": "string", "nullable": true }, "name": { "type": "string", "nullable": true }, "account_type": { "type": "string", "nullable": true }, "financial_statement": { "type": "string", "nullable": true } } }, "BusinessJournalEntry": { "type": "object", "additionalProperties": false, "required": [ "object", "id", "transaction_id", "chart_of_accounts_id", "account", "debit_amount", "credit_amount", "description", "line_order" ], "properties": { "object": { "type": "string", "enum": [ "business_journal_entry" ] }, "id": { "type": "string", "format": "uuid", "nullable": true }, "transaction_id": { "type": "string", "format": "uuid", "nullable": true }, "chart_of_accounts_id": { "type": "string", "format": "uuid", "nullable": true }, "account": { "$ref": "#/components/schemas/BusinessJournalEntryAccount" }, "debit_amount": { "type": "number", "nullable": true }, "credit_amount": { "type": "number", "nullable": true }, "description": { "type": "string", "nullable": true }, "vat_amount": { "type": "number", "nullable": true }, "vat_rate": { "type": "number", "nullable": true }, "user_reference": { "type": "string", "nullable": true }, "line_order": { "type": "number", "nullable": true }, "project_id": { "type": "string", "format": "uuid", "nullable": true }, "cost_center_id": { "type": "string", "format": "uuid", "nullable": true }, "fund_id": { "type": "string", "format": "uuid", "nullable": true }, "original_currency": { "type": "string", "nullable": true }, "original_debit_amount": { "type": "number", "nullable": true }, "original_credit_amount": { "type": "number", "nullable": true }, "exchange_rate": { "type": "number", "nullable": true }, "created_at": { "type": "string", "format": "date-time", "nullable": true }, "updated_at": { "type": "string", "format": "date-time", "nullable": true } } }, "BusinessJournalDraftLineInput": { "type": "object", "additionalProperties": false, "required": [ "account_id" ], "description": "One draft journal line. Exactly one of debit_amount or credit_amount must be greater than zero.", "properties": { "account_id": { "type": "string", "format": "uuid", "description": "Company-owned chart of accounts id." }, "debit_amount": { "type": "number", "minimum": 0, "multipleOf": 0.01, "default": 0 }, "credit_amount": { "type": "number", "minimum": 0, "multipleOf": 0.01, "default": 0 }, "description": { "type": "string", "maxLength": 500 }, "project_id": { "type": "string", "format": "uuid" }, "cost_center_id": { "type": "string", "format": "uuid" }, "fund_id": { "type": "string", "format": "uuid" }, "user_reference": { "type": "string", "maxLength": 100 } } }, "BusinessJournalDraftCreateRequest": { "type": "object", "additionalProperties": false, "required": [ "transaction_date", "description", "lines" ], "properties": { "transaction_date": { "type": "string", "format": "date" }, "description": { "type": "string", "maxLength": 500 }, "reference": { "type": "string", "maxLength": 100 }, "transaction_type": { "type": "string", "maxLength": 50, "default": "manual" }, "lines": { "type": "array", "minItems": 2, "maxItems": 100, "items": { "$ref": "#/components/schemas/BusinessJournalDraftLineInput" }, "description": "Debit and credit totals must be equal." } } }, "V1BusinessJournalTransactionCreateMeta": { "type": "object", "additionalProperties": false, "required": [ "api_version", "mode", "request_id", "resource", "scope" ], "properties": { "api_version": { "type": "string", "const": "v1-2026-07" }, "mode": { "type": "string", "const": "created" }, "request_id": { "type": "string", "minLength": 1, "maxLength": 128 }, "resource": { "type": "string", "const": "business_journal_transaction" }, "scope": { "type": "string", "const": "business.journal_transactions.create" } } }, "BusinessJournalTransactionCreateResponse": { "type": "object", "additionalProperties": false, "required": [ "data", "meta" ], "properties": { "data": { "$ref": "#/components/schemas/BusinessJournalTransaction" }, "meta": { "$ref": "#/components/schemas/V1BusinessJournalTransactionCreateMeta" } } }, "BusinessJournalTransaction": { "type": "object", "additionalProperties": false, "required": [ "object", "id", "company_id", "transaction_date", "status", "line_count", "debit_total", "credit_total", "is_balanced", "lines" ], "properties": { "object": { "type": "string", "enum": [ "business_journal_transaction" ] }, "id": { "type": "string", "format": "uuid", "nullable": true }, "company_id": { "type": "string", "format": "uuid", "nullable": true }, "transaction_date": { "type": "string", "format": "date", "nullable": true }, "description": { "type": "string", "nullable": true }, "reference": { "type": "string", "nullable": true }, "total_amount": { "type": "number", "nullable": true }, "debit_total": { "type": "number" }, "credit_total": { "type": "number" }, "is_balanced": { "type": "boolean" }, "status": { "type": "string", "nullable": true }, "transaction_type": { "type": "string", "nullable": true }, "source_type": { "type": "string", "nullable": true }, "source_id": { "type": "string", "format": "uuid", "nullable": true }, "posting_origin": { "type": "string", "nullable": true }, "original_transaction_id": { "type": "string", "format": "uuid", "nullable": true }, "is_current": { "type": "boolean" }, "version": { "type": "number", "nullable": true }, "amended_at": { "type": "string", "format": "date-time", "nullable": true }, "amendment_reason": { "type": "string", "nullable": true }, "line_count": { "type": "number" }, "lines": { "type": "array", "items": { "$ref": "#/components/schemas/BusinessJournalEntry" } }, "created_at": { "type": "string", "format": "date-time", "nullable": true }, "updated_at": { "type": "string", "format": "date-time", "nullable": true } } }, "V1BusinessJournalTransactionListMeta": { "type": "object", "additionalProperties": false, "required": [ "api_version", "mode", "resource", "request_id", "pagination" ], "properties": { "api_version": { "type": "string", "enum": [ "v1-2026-07" ] }, "mode": { "type": "string", "enum": [ "list" ] }, "resource": { "type": "string", "enum": [ "business_journal_transaction" ] }, "request_id": { "type": "string" }, "pagination": { "$ref": "#/components/schemas/V1PaginationMeta" } } }, "V1BusinessJournalTransactionDetailMeta": { "type": "object", "additionalProperties": false, "required": [ "api_version", "mode", "resource", "request_id" ], "properties": { "api_version": { "type": "string", "enum": [ "v1-2026-07" ] }, "mode": { "type": "string", "enum": [ "detail" ] }, "resource": { "type": "string", "enum": [ "business_journal_transaction" ] }, "request_id": { "type": "string" } } }, "BusinessJournalTransactionListResponse": { "type": "object", "additionalProperties": false, "required": [ "data", "meta" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/BusinessJournalTransaction" } }, "meta": { "$ref": "#/components/schemas/V1BusinessJournalTransactionListMeta" } } }, "BusinessJournalTransactionDetailResponse": { "type": "object", "additionalProperties": false, "required": [ "data", "meta" ], "properties": { "data": { "$ref": "#/components/schemas/BusinessJournalTransaction" }, "meta": { "$ref": "#/components/schemas/V1BusinessJournalTransactionDetailMeta" } } }, "BusinessDocumentDownload": { "type": "object", "additionalProperties": false, "required": [ "object", "document", "signed_url", "expires_at", "expires_in_seconds" ], "properties": { "object": { "type": "string", "const": "business_document_download" }, "document": { "$ref": "#/components/schemas/BusinessDocument" }, "signed_url": { "type": "string", "format": "uri" }, "expires_at": { "type": "string", "format": "date-time" }, "expires_in_seconds": { "type": "integer", "const": 300 } } }, "V1BusinessDocumentDownloadMeta": { "type": "object", "required": [ "api_version", "mode", "request_id", "resource", "scope" ], "properties": { "api_version": { "type": "string", "const": "v1-2026-07" }, "mode": { "type": "string", "const": "download" }, "request_id": { "type": "string", "minLength": 1, "maxLength": 128 }, "resource": { "type": "string", "const": "business_document_download" }, "scope": { "type": "string", "const": "business.documents.download" } } }, "V1BusinessDocumentDownloadResponse": { "type": "object", "required": [ "data", "meta" ], "properties": { "data": { "$ref": "#/components/schemas/BusinessDocumentDownload" }, "meta": { "$ref": "#/components/schemas/V1BusinessDocumentDownloadMeta" } } }, "BusinessDocumentFileVersion": { "type": "object", "required": [ "object", "id", "company_id", "document_id", "file_name", "file_size", "file_type", "replaced_at", "replacement_reason" ], "properties": { "object": { "type": "string", "const": "business_document_file_version" }, "id": { "type": "string", "format": "uuid" }, "company_id": { "type": "string", "format": "uuid" }, "document_id": { "type": "string", "format": "uuid" }, "file_name": { "type": [ "string", "null" ] }, "file_size": { "type": [ "integer", "null" ], "minimum": 0 }, "file_type": { "type": [ "string", "null" ] }, "replaced_at": { "type": [ "string", "null" ], "format": "date-time" }, "replacement_reason": { "type": [ "string", "null" ] } } }, "V1BusinessDocumentFileVersionsMeta": { "type": "object", "required": [ "api_version", "mode", "request_id", "resource", "scope", "pagination" ], "properties": { "api_version": { "type": "string", "const": "v1-2026-07" }, "mode": { "type": "string", "const": "list" }, "request_id": { "type": "string" }, "resource": { "type": "string", "const": "business_document_file_version" }, "scope": { "type": "string", "const": "business.documents.read_versions" }, "pagination": { "$ref": "#/components/schemas/V1Pagination" } } }, "V1BusinessDocumentFileVersionsResponse": { "type": "object", "required": [ "data", "meta" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/BusinessDocumentFileVersion" } }, "meta": { "$ref": "#/components/schemas/V1BusinessDocumentFileVersionsMeta" } } }, "BusinessDocumentFileVersionDownload": { "type": "object", "required": [ "object", "version", "signed_url", "expires_at", "expires_in_seconds" ], "properties": { "object": { "type": "string", "const": "business_document_file_version_download" }, "version": { "$ref": "#/components/schemas/BusinessDocumentFileVersion" }, "signed_url": { "type": "string", "format": "uri" }, "expires_at": { "type": "string", "format": "date-time" }, "expires_in_seconds": { "type": "integer", "const": 300 } } }, "V1BusinessDocumentFileVersionDownloadMeta": { "type": "object", "required": [ "api_version", "mode", "request_id", "resource", "scope" ], "properties": { "api_version": { "type": "string", "const": "v1-2026-07" }, "mode": { "type": "string", "const": "download" }, "request_id": { "type": "string" }, "resource": { "type": "string", "const": "business_document_file_version_download" }, "scope": { "type": "string", "const": "business.documents.download_version" } } }, "V1BusinessDocumentFileVersionDownloadResponse": { "type": "object", "required": [ "data", "meta" ], "properties": { "data": { "$ref": "#/components/schemas/BusinessDocumentFileVersionDownload" }, "meta": { "$ref": "#/components/schemas/V1BusinessDocumentFileVersionDownloadMeta" } } }, "BusinessDocumentProcessingStatus": { "type": "object", "required": [ "object", "company_id", "document_id", "status", "ocr_processed", "queued_at", "processing_started_at", "processing_completed_at", "retry_count", "error_code" ], "properties": { "object": { "type": "string", "const": "business_document_processing_status" }, "company_id": { "type": "string", "format": "uuid" }, "document_id": { "type": "string", "format": "uuid" }, "status": { "type": "string", "enum": [ "not_queued", "queued", "processing", "completed", "failed" ] }, "ocr_processed": { "type": "boolean" }, "queued_at": { "type": [ "string", "null" ], "format": "date-time" }, "processing_started_at": { "type": [ "string", "null" ], "format": "date-time" }, "processing_completed_at": { "type": [ "string", "null" ], "format": "date-time" }, "retry_count": { "type": "integer", "minimum": 0 }, "error_code": { "type": [ "string", "null" ] } } }, "V1BusinessDocumentProcessingStatusMeta": { "type": "object", "required": [ "api_version", "mode", "request_id", "resource", "scope" ], "properties": { "api_version": { "type": "string", "const": "v1-2026-07" }, "mode": { "type": "string", "const": "status" }, "request_id": { "type": "string" }, "resource": { "type": "string", "const": "business_document_processing_status" }, "scope": { "type": "string", "const": "business.documents.processing_status" } } }, "V1BusinessDocumentProcessingStatusResponse": { "type": "object", "required": [ "data", "meta" ], "properties": { "data": { "$ref": "#/components/schemas/BusinessDocumentProcessingStatus" }, "meta": { "$ref": "#/components/schemas/V1BusinessDocumentProcessingStatusMeta" } } }, "BusinessDocumentExtractedData": { "type": "object", "required": [ "object", "category_confidence", "category_source", "currency", "document_type", "due_date", "gross_amount", "invoice_date", "invoice_number", "matched_supplier_id", "net_amount", "needs_review", "ocr_confidence", "ocr_default_action", "ocr_field_confidences", "ocr_review_reason", "ocr_review_verdict", "ocr_verdict_reasons", "suggested_category_id", "supplier_name", "vat_amount", "vat_number" ], "properties": { "object": { "type": "string", "const": "business_document_extracted_data" }, "category_confidence": { "type": [ "number", "null" ] }, "category_source": { "type": [ "string", "null" ] }, "currency": { "type": "string" }, "document_type": { "type": "string" }, "due_date": { "type": [ "string", "null" ] }, "gross_amount": { "type": [ "number", "null" ] }, "invoice_date": { "type": [ "string", "null" ] }, "invoice_number": { "type": [ "string", "null" ] }, "matched_supplier_id": { "type": [ "string", "null" ], "format": "uuid" }, "net_amount": { "type": [ "number", "null" ] }, "needs_review": { "type": "boolean" }, "ocr_confidence": { "type": [ "number", "null" ] }, "ocr_default_action": { "type": [ "string", "null" ] }, "ocr_field_confidences": { "type": [ "object", "null" ], "additionalProperties": { "type": "number" } }, "ocr_review_reason": { "type": [ "string", "null" ] }, "ocr_review_verdict": { "type": [ "string", "null" ] }, "ocr_verdict_reasons": { "type": "array", "items": {} }, "suggested_category_id": { "type": [ "string", "null" ], "format": "uuid" }, "supplier_name": { "type": [ "string", "null" ] }, "vat_amount": { "type": [ "number", "null" ] }, "vat_number": { "type": [ "string", "null" ] } } }, "V1BusinessDocumentExtractedDataMeta": { "type": "object", "required": [ "api_version", "mode", "request_id", "resource", "scope" ], "properties": { "api_version": { "type": "string", "const": "v1-2026-07" }, "mode": { "type": "string", "const": "extracted_data" }, "request_id": { "type": "string" }, "resource": { "type": "string", "const": "business_document_extraction" }, "scope": { "type": "string", "const": "business.documents.extracted_data" } } }, "V1BusinessDocumentExtractedDataResponse": { "type": "object", "required": [ "data", "meta" ], "properties": { "data": { "type": "object", "required": [ "document_id", "extracted_data", "object", "ready" ], "properties": { "document_id": { "type": "string", "format": "uuid" }, "extracted_data": { "anyOf": [ { "$ref": "#/components/schemas/BusinessDocumentExtractedData" }, { "type": "null" } ] }, "object": { "type": "string", "const": "business_document_extraction" }, "ready": { "type": "boolean" } } }, "meta": { "$ref": "#/components/schemas/V1BusinessDocumentExtractedDataMeta" } } }, "BusinessDocumentUpdateRequest": { "type": "object", "additionalProperties": false, "minProperties": 1, "properties": { "status": { "type": [ "string", "null" ], "maxLength": 100 }, "document_type": { "type": [ "string", "null" ], "maxLength": 100 }, "document_classification": { "type": [ "string", "null" ], "maxLength": 200 }, "description": { "type": [ "string", "null" ], "maxLength": 2000 }, "notes": { "type": [ "string", "null" ], "maxLength": 2000 }, "customer_id": { "type": [ "string", "null" ], "format": "uuid" }, "supplier_id": { "type": [ "string", "null" ], "format": "uuid" }, "linked_invoice_id": { "type": [ "string", "null" ], "format": "uuid" }, "linked_purchase_invoice_id": { "type": [ "string", "null" ], "format": "uuid" }, "linked_purchase_order_id": { "type": [ "string", "null" ], "format": "uuid" }, "linked_bank_transaction_id": { "type": [ "string", "null" ], "format": "uuid" } } }, "V1BusinessDocumentUpdateMeta": { "type": "object", "required": [ "api_version", "mode", "request_id", "resource", "scope" ], "properties": { "api_version": { "type": "string", "const": "v1-2026-07" }, "mode": { "type": "string", "const": "updated" }, "request_id": { "type": "string", "minLength": 1, "maxLength": 128 }, "resource": { "type": "string", "const": "business_document" }, "scope": { "type": "string", "const": "business.documents.update" } } }, "V1BusinessDocumentUpdateResponse": { "type": "object", "required": [ "data", "meta" ], "properties": { "data": { "$ref": "#/components/schemas/BusinessDocument" }, "meta": { "$ref": "#/components/schemas/V1BusinessDocumentUpdateMeta" } } }, "PersonalTransactionUpdateRequest": { "type": "object", "additionalProperties": false, "minProperties": 1, "properties": { "description": { "type": "string", "minLength": 1, "maxLength": 240, "description": "Optional replacement description. If supplied it must be non-empty." }, "personal_category_id": { "type": [ "string", "null" ], "format": "uuid", "description": "Owned personal category to mark the transaction as categorised, or null to clear categorisation." }, "merchant_name": { "type": [ "string", "null" ], "maxLength": 140 }, "reference": { "type": [ "string", "null" ], "maxLength": 200 }, "receipt_attached": { "type": "boolean" }, "receipt_required": { "type": "boolean" } } }, "PersonalTransactionUpdateMeta": { "type": "object", "required": [ "api_version", "mode", "request_id", "resource", "scope" ], "properties": { "api_version": { "type": "string", "const": "v1-2026-07" }, "mode": { "type": "string", "const": "updated" }, "request_id": { "type": "string", "minLength": 1, "maxLength": 128 }, "resource": { "type": "string", "const": "personal_transaction" }, "scope": { "type": "string", "const": "personal.transactions.write" } } }, "PersonalTransactionUpdateResponse": { "type": "object", "required": [ "data", "meta" ], "properties": { "data": { "$ref": "#/components/schemas/PersonalTransaction" }, "meta": { "$ref": "#/components/schemas/PersonalTransactionUpdateMeta" } } }, "BusinessTransactionUpdateRequest": { "type": "object", "additionalProperties": false, "minProperties": 1, "properties": { "description": { "type": "string", "minLength": 1, "maxLength": 240, "description": "Optional replacement description. If supplied it must be non-empty." }, "chart_of_accounts_id": { "type": [ "string", "null" ], "format": "uuid", "description": "Company-owned chart of accounts category to post the transaction to, or null to return it to holding. The posting is provisional: it is not confirmed and does not teach treatment memory until the company's client confirms it in Financial IQ." }, "customer_id": { "type": [ "string", "null" ], "format": "uuid", "description": "Company-owned customer to link to the transaction, or null to clear the link." }, "supplier_id": { "type": [ "string", "null" ], "format": "uuid", "description": "Company-owned supplier to link to the transaction, or null to clear the link." }, "project_id": { "type": [ "string", "null" ], "format": "uuid", "description": "Company-owned project to link to the transaction, or null to clear the link." }, "fund_id": { "type": [ "string", "null" ], "format": "uuid", "description": "Company-owned fund to link to the transaction, or null to clear the link." }, "merchant_name": { "type": [ "string", "null" ], "maxLength": 140 }, "reference": { "type": [ "string", "null" ], "maxLength": 200 }, "receipt_attached": { "type": "boolean" }, "receipt_required": { "type": "boolean" }, "uncertainty_reason_code": { "type": [ "string", "null" ], "enum": [ "caller_low_confidence", "several_accounts_plausible", "counterparty_unidentified", "no_supporting_document", "unusual_for_counterparty", "possibly_personal", "possibly_capital", null ], "description": "Why the caller is unsure of the category. Requires chart_of_accounts_id. It only moves the transaction up the client's quick checks; Financial IQ never displays it." }, "uncertainty_note": { "type": [ "string", "null" ], "maxLength": 500, "description": "Optional detail for uncertainty_reason_code. Recorded for audit, never displayed." } } }, "V1BusinessTransactionUpdateMeta": { "type": "object", "required": [ "api_version", "mode", "request_id", "resource", "scope" ], "properties": { "api_version": { "type": "string", "const": "v1-2026-07" }, "mode": { "type": "string", "const": "updated" }, "request_id": { "type": "string", "minLength": 1, "maxLength": 128 }, "resource": { "type": "string", "const": "business_transaction" }, "scope": { "type": "string", "const": "business.transactions.update" } } }, "BusinessTransactionUpdateResponse": { "type": "object", "required": [ "data", "meta" ], "properties": { "data": { "$ref": "#/components/schemas/BusinessTransaction" }, "meta": { "$ref": "#/components/schemas/V1BusinessTransactionUpdateMeta" } } }, "BusinessCustomerUpdateRequest": { "type": "object", "additionalProperties": false, "minProperties": 1, "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 200, "description": "Optional replacement customer name. If supplied it must be non-empty." }, "customer_reference": { "type": [ "string", "null" ], "maxLength": 100 }, "contact_email": { "type": [ "string", "null" ], "format": "email", "maxLength": 320 }, "contact_phone": { "type": [ "string", "null" ], "maxLength": 100 }, "billing_address": { "type": [ "string", "null" ], "maxLength": 1000 }, "vat_number": { "type": [ "string", "null" ], "maxLength": 50 }, "default_vat_rate": { "type": [ "number", "null" ], "minimum": 0, "maximum": 100, "description": "Optional default VAT rate percentage, with no more than 2 decimal places, or null to clear." }, "default_payment_terms_days": { "type": [ "integer", "null" ], "minimum": 0, "maximum": 3650 }, "is_active": { "type": "boolean" }, "related_party": { "type": "boolean" }, "fao": { "type": [ "string", "null" ], "maxLength": 200 } } }, "V1BusinessCustomerUpdateMeta": { "type": "object", "required": [ "api_version", "mode", "request_id", "resource", "scope" ], "properties": { "api_version": { "type": "string", "const": "v1-2026-07" }, "mode": { "type": "string", "const": "updated" }, "request_id": { "type": "string", "minLength": 1, "maxLength": 128 }, "resource": { "type": "string", "const": "business_customer" }, "scope": { "type": "string", "const": "business.customers.update" } } }, "V1BusinessCustomerUpdateResponse": { "type": "object", "required": [ "data", "meta" ], "properties": { "data": { "$ref": "#/components/schemas/BusinessCustomer" }, "meta": { "$ref": "#/components/schemas/V1BusinessCustomerUpdateMeta" } } }, "BusinessSupplierUpdateRequest": { "type": "object", "additionalProperties": false, "minProperties": 1, "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 200 }, "supplier_reference": { "type": [ "string", "null" ], "maxLength": 100 }, "contact_email": { "type": [ "string", "null" ], "format": "email", "maxLength": 320 }, "contact_phone": { "type": [ "string", "null" ], "maxLength": 100 }, "address": { "type": [ "string", "null" ], "maxLength": 1000 }, "vat_number": { "type": [ "string", "null" ], "maxLength": 50 }, "default_vat_rate": { "type": [ "number", "null" ], "minimum": 0, "maximum": 100, "description": "Optional default VAT rate percentage, with no more than 2 decimal places." }, "payment_terms_days": { "type": [ "integer", "null" ], "minimum": 0, "maximum": 3650 }, "payment_method": { "type": [ "string", "null" ], "maxLength": 100 }, "default_nominal_code": { "type": [ "string", "null" ], "maxLength": 100 }, "default_chart_of_accounts_id": { "type": [ "string", "null" ], "format": "uuid" }, "budget_limit": { "type": [ "number", "null" ], "minimum": 0, "maximum": 9999999999999.99, "description": "Optional supplier budget limit, with no more than 2 decimal places." }, "flag_for_review": { "type": "boolean", "default": false }, "is_active": { "type": "boolean", "default": true }, "related_party": { "type": "boolean", "default": false }, "fao": { "type": [ "string", "null" ], "maxLength": 200 } } }, "V1BusinessSupplierUpdateMeta": { "type": "object", "required": [ "api_version", "mode", "request_id", "resource", "scope" ], "properties": { "api_version": { "type": "string", "const": "v1-2026-07" }, "mode": { "type": "string", "const": "updated" }, "request_id": { "type": "string", "minLength": 1, "maxLength": 128 }, "resource": { "type": "string", "const": "business_supplier" }, "scope": { "type": "string", "const": "business.suppliers.update" } } }, "V1BusinessSupplierUpdateResponse": { "type": "object", "required": [ "data", "meta" ], "properties": { "data": { "$ref": "#/components/schemas/BusinessSupplier" }, "meta": { "$ref": "#/components/schemas/V1BusinessSupplierUpdateMeta" } } }, "PersonalAccountUpdateRequest": { "type": "object", "additionalProperties": false, "minProperties": 1, "properties": { "account_name": { "type": "string", "minLength": 1, "maxLength": 120, "description": "Display name for the manual personal account." }, "bank_name": { "type": "string", "minLength": 1, "maxLength": 120, "default": "Manual", "description": "Institution label shown for the manual account." }, "account_type": { "type": "string", "enum": [ "current", "savings", "credit_card", "loan", "investment" ], "default": "current" }, "account_category": { "type": [ "string", "null" ], "enum": [ "current_account", "corporation_tax", "vat", "savings", "petty_cash", "expense_card", null ], "description": "Optional category. Defaults from account_type where a safe default exists." }, "currency": { "type": "string", "pattern": "^[A-Z]{3}$", "default": "GBP" }, "is_active": { "type": "boolean", "default": true } } }, "PersonalAccountUpdateMeta": { "type": "object", "required": [ "api_version", "mode", "request_id", "resource", "scope" ], "properties": { "api_version": { "type": "string", "const": "v1-2026-07" }, "mode": { "type": "string", "const": "updated" }, "request_id": { "type": "string", "minLength": 1, "maxLength": 128 }, "resource": { "type": "string", "const": "personal_account" }, "scope": { "type": "string", "const": "personal.accounts.write" } } }, "PersonalAccountUpdateResponse": { "type": "object", "required": [ "data", "meta" ], "properties": { "data": { "$ref": "#/components/schemas/PersonalAccount" }, "meta": { "$ref": "#/components/schemas/PersonalAccountUpdateMeta" } } }, "PersonalAssetUpdateRequest": { "type": "object", "additionalProperties": false, "minProperties": 1, "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 120 }, "asset_type": { "type": "string", "enum": [ "property", "vehicle", "investment", "savings", "other" ] }, "current_value": { "type": "number", "minimum": 0, "maximum": 999999999999.99 }, "purchase_date": { "type": [ "string", "null" ], "format": "date" }, "purchase_price": { "type": [ "number", "null" ], "minimum": 0, "maximum": 999999999999.99 }, "description": { "type": [ "string", "null" ], "maxLength": 500 }, "is_active": { "type": "boolean", "default": true } } }, "PersonalAssetUpdateMeta": { "type": "object", "required": [ "api_version", "mode", "request_id", "resource", "scope" ], "properties": { "api_version": { "type": "string", "const": "v1-2026-07" }, "mode": { "type": "string", "const": "updated" }, "request_id": { "type": "string", "minLength": 1, "maxLength": 128 }, "resource": { "type": "string", "const": "personal_asset" }, "scope": { "type": "string", "const": "personal.assets.write" } } }, "PersonalAssetUpdateResponse": { "type": "object", "required": [ "data", "meta" ], "properties": { "data": { "$ref": "#/components/schemas/PersonalAsset" }, "meta": { "$ref": "#/components/schemas/PersonalAssetUpdateMeta" } } }, "PersonalLiabilityUpdateRequest": { "type": "object", "additionalProperties": false, "minProperties": 1, "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 120 }, "liability_type": { "type": "string", "enum": [ "mortgage", "loan", "credit_card", "other" ] }, "current_balance": { "type": "number", "minimum": 0, "maximum": 999999999999.99 }, "interest_rate": { "type": [ "number", "null" ], "minimum": 0, "maximum": 100 }, "minimum_payment": { "type": [ "number", "null" ], "minimum": 0, "maximum": 999999999999.99 }, "payment_due_date": { "type": [ "integer", "null" ], "minimum": 1, "maximum": 31 }, "original_amount": { "type": [ "number", "null" ], "minimum": 0, "maximum": 999999999999.99 }, "start_date": { "type": [ "string", "null" ], "format": "date" }, "maturity_date": { "type": [ "string", "null" ], "format": "date" }, "is_active": { "type": "boolean", "default": true } } }, "PersonalLiabilityUpdateMeta": { "type": "object", "required": [ "api_version", "mode", "request_id", "resource", "scope" ], "properties": { "api_version": { "type": "string", "const": "v1-2026-07" }, "mode": { "type": "string", "const": "updated" }, "request_id": { "type": "string", "minLength": 1, "maxLength": 128 }, "resource": { "type": "string", "const": "personal_liability" }, "scope": { "type": "string", "const": "personal.liabilities.write" } } }, "PersonalLiabilityUpdateResponse": { "type": "object", "required": [ "data", "meta" ], "properties": { "data": { "$ref": "#/components/schemas/PersonalLiability" }, "meta": { "$ref": "#/components/schemas/PersonalLiabilityUpdateMeta" } } }, "PersonalBudgetUpdateRequest": { "type": "object", "additionalProperties": false, "minProperties": 1, "properties": { "category_id": { "type": [ "string", "null" ], "format": "uuid", "description": "Optional personal category owned by the bearer-token user. Required when category_name is omitted." }, "category_name": { "type": "string", "minLength": 1, "maxLength": 120, "description": "Required when category_id is omitted. If category_id is supplied without category_name, the category name is copied from the owned category." }, "budget_type": { "type": "string", "enum": [ "expense", "income", "savings" ], "default": "expense" }, "period_type": { "type": "string", "enum": [ "weekly", "monthly", "yearly" ], "default": "monthly" }, "budget_month": { "type": [ "string", "null" ], "format": "date", "description": "Defaults to start_date when omitted." }, "budget_amount": { "type": "number", "minimum": 0, "maximum": 999999999999.99 }, "spent_amount": { "type": [ "number", "null" ], "minimum": 0, "maximum": 999999999999.99 }, "currency": { "type": "string", "pattern": "^[A-Z]{3}$", "default": "GBP" }, "start_date": { "type": "string", "format": "date" }, "end_date": { "type": "string", "format": "date" }, "day_of_week": { "type": [ "integer", "null" ], "minimum": 1, "maximum": 7 }, "is_active": { "type": "boolean", "default": true }, "is_template": { "type": [ "boolean", "null" ], "default": true }, "rollover_enabled": { "type": [ "boolean", "null" ], "default": false }, "template_id": { "type": [ "string", "null" ], "format": "uuid", "description": "Optional budget template owned by the bearer-token user." } } }, "PersonalBudgetUpdateMeta": { "type": "object", "required": [ "api_version", "mode", "request_id", "resource", "scope" ], "properties": { "api_version": { "type": "string", "const": "v1-2026-07" }, "mode": { "type": "string", "const": "updated" }, "request_id": { "type": "string", "minLength": 1, "maxLength": 128 }, "resource": { "type": "string", "const": "personal_budget" }, "scope": { "type": "string", "const": "personal.budgets.write" } } }, "PersonalBudgetUpdateResponse": { "type": "object", "required": [ "data", "meta" ], "properties": { "data": { "$ref": "#/components/schemas/PersonalBudget" }, "meta": { "$ref": "#/components/schemas/PersonalBudgetUpdateMeta" } } }, "PersonalCategoryUpdateRequest": { "type": "object", "additionalProperties": false, "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 120, "description": "Category name shown to the user." }, "category_type": { "type": "string", "enum": [ "income", "expense", "transfer" ] }, "parent_id": { "type": [ "string", "null" ], "format": "uuid", "description": "Optional parent category owned by the bearer-token user. The parent must use the same category_type." }, "icon": { "type": [ "string", "null" ], "maxLength": 64 }, "color": { "type": [ "string", "null" ], "maxLength": 32 }, "is_active": { "type": "boolean", "default": true }, "sort_order": { "type": "integer", "minimum": -1000000, "maximum": 1000000, "default": 0 } }, "minProperties": 1 }, "PersonalCategoryUpdateResponse": { "type": "object", "required": [ "data", "meta" ], "properties": { "data": { "$ref": "#/components/schemas/PersonalCategory" }, "meta": { "$ref": "#/components/schemas/PersonalCategoryUpdateMeta" } } }, "PersonalCategoryUpdateMeta": { "type": "object", "required": [ "api_version", "mode", "request_id", "resource", "scope" ], "properties": { "api_version": { "type": "string", "const": "v1-2026-07" }, "mode": { "type": "string", "const": "updated" }, "request_id": { "type": "string", "minLength": 1, "maxLength": 128 }, "resource": { "type": "string", "const": "personal_category" }, "scope": { "type": "string", "const": "personal.categories.write" } } }, "PersonalGoalUpdateRequest": { "type": "object", "additionalProperties": false, "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 120 }, "description": { "type": [ "string", "null" ], "maxLength": 500 }, "goal_type": { "type": "string", "enum": [ "savings", "debt_payoff", "investment", "expense_reduction", "income", "other" ] }, "category_id": { "type": [ "string", "null" ], "format": "uuid", "description": "Optional personal category owned by the bearer-token user." }, "target_amount": { "type": "number", "exclusiveMinimum": 0, "maximum": 999999999999.99 }, "current_amount": { "type": [ "number", "null" ], "minimum": 0, "maximum": 999999999999.99, "default": 0 }, "currency": { "type": "string", "pattern": "^[A-Z]{3}$", "default": "GBP" }, "priority": { "type": "integer", "minimum": 1, "maximum": 10, "default": 1 }, "start_date": { "type": [ "string", "null" ], "format": "date" }, "target_date": { "type": [ "string", "null" ], "format": "date" }, "is_shared": { "type": "boolean", "default": false }, "linked_account_id": { "type": [ "string", "null" ], "format": "uuid", "description": "Optional personal account owned by the bearer-token user." }, "contribution_type": { "type": [ "string", "null" ], "enum": [ "fixed", "percentage", null ] }, "contribution_amount": { "type": [ "number", "null" ], "minimum": 0, "maximum": 999999999999.99 }, "contribution_percent": { "type": [ "number", "null" ], "minimum": 0, "maximum": 100 }, "contribution_frequency": { "type": [ "string", "null" ], "enum": [ "weekly", "monthly", "quarterly", "yearly", "annually", null ] }, "debt_apr": { "type": [ "number", "null" ], "minimum": 0, "maximum": 100 }, "debt_extra_payment": { "type": [ "number", "null" ], "minimum": 0, "maximum": 999999999999.99 }, "is_achieved": { "type": "boolean", "default": false } }, "minProperties": 1 }, "PersonalGoalUpdateResponse": { "type": "object", "required": [ "data", "meta" ], "properties": { "data": { "$ref": "#/components/schemas/PersonalGoal" }, "meta": { "$ref": "#/components/schemas/PersonalGoalUpdateMeta" } } }, "PersonalGoalUpdateMeta": { "type": "object", "required": [ "api_version", "mode", "request_id", "resource", "scope" ], "properties": { "api_version": { "type": "string", "const": "v1-2026-07" }, "mode": { "type": "string", "const": "updated" }, "request_id": { "type": "string", "minLength": 1, "maxLength": 128 }, "resource": { "type": "string", "const": "personal_goal" }, "scope": { "type": "string", "const": "personal.goals.write" } } }, "BusinessProjectUpdateRequest": { "type": "object", "additionalProperties": false, "properties": { "code": { "type": "string", "minLength": 1, "maxLength": 50 }, "name": { "type": "string", "minLength": 1, "maxLength": 160 }, "description": { "type": [ "string", "null" ], "maxLength": 1000 }, "budget": { "type": [ "number", "null" ], "minimum": 0, "maximum": 999999999999.99 }, "expected_income": { "type": [ "number", "null" ], "minimum": 0, "maximum": 999999999999.99 }, "expected_costs": { "type": [ "number", "null" ], "minimum": 0, "maximum": 999999999999.99 }, "start_date": { "type": [ "string", "null" ], "format": "date" }, "end_date": { "type": [ "string", "null" ], "format": "date" }, "is_active": { "type": "boolean", "default": true } }, "minProperties": 1 }, "BusinessProjectUpdateResponse": { "type": "object", "required": [ "data", "meta" ], "properties": { "data": { "$ref": "#/components/schemas/BusinessProject" }, "meta": { "$ref": "#/components/schemas/BusinessProjectUpdateMeta" } } }, "BusinessProjectUpdateMeta": { "type": "object", "required": [ "api_version", "mode", "request_id", "resource" ], "properties": { "api_version": { "type": "string", "const": "v1-2026-07" }, "mode": { "type": "string", "const": "updated" }, "request_id": { "type": "string", "minLength": 1, "maxLength": 128 }, "resource": { "type": "string", "const": "business_project" }, "scope": { "type": "string", "const": "business.projects.update" } } }, "BusinessFundUpdateRequest": { "type": "object", "additionalProperties": false, "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 160 }, "code": { "type": [ "string", "null" ], "maxLength": 50 }, "purpose": { "type": [ "string", "null" ], "maxLength": 1000 }, "restriction_summary": { "type": [ "string", "null" ], "maxLength": 1000 }, "restriction_reference": { "type": [ "string", "null" ], "maxLength": 1000 }, "opened_on": { "type": "string", "format": "date" }, "display_order": { "type": "integer", "minimum": 0, "maximum": 999999 }, "is_active": { "type": "boolean", "default": true } }, "minProperties": 1 }, "BusinessFundUpdateResponse": { "type": "object", "required": [ "data", "meta" ], "properties": { "data": { "$ref": "#/components/schemas/BusinessFund" }, "meta": { "$ref": "#/components/schemas/BusinessFundUpdateMeta" } } }, "BusinessFundUpdateMeta": { "type": "object", "required": [ "api_version", "mode", "request_id", "resource" ], "properties": { "api_version": { "type": "string", "const": "v1-2026-07" }, "mode": { "type": "string", "const": "updated" }, "request_id": { "type": "string", "minLength": 1, "maxLength": 128 }, "resource": { "type": "string", "const": "business_fund" }, "scope": { "type": "string", "const": "business.funds.update" } } }, "BusinessExpenseClaimantUpdateRequest": { "type": "object", "additionalProperties": false, "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 200 }, "email": { "type": "string", "format": "email", "minLength": 3, "maxLength": 320, "description": "Stored lowercase and unique per company." }, "phone": { "type": [ "string", "null" ], "maxLength": 100 }, "is_active": { "type": "boolean", "default": true } }, "minProperties": 1 }, "BusinessExpenseClaimantUpdateResponse": { "type": "object", "required": [ "data", "meta" ], "properties": { "data": { "$ref": "#/components/schemas/ExpenseClaimant" }, "meta": { "$ref": "#/components/schemas/V1BusinessExpenseClaimantUpdateMeta" } } }, "V1BusinessExpenseClaimantUpdateMeta": { "type": "object", "required": [ "api_version", "mode", "request_id", "resource", "scope" ], "properties": { "api_version": { "type": "string", "const": "v1-2026-07" }, "mode": { "type": "string", "const": "updated" }, "request_id": { "type": "string", "minLength": 1, "maxLength": 128 }, "resource": { "type": "string", "const": "expense_claimant" }, "scope": { "type": "string", "const": "business.expense_claimants.update" } } }, "BusinessCostCenterLevelUpdateRequest": { "type": "object", "additionalProperties": false, "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 160 }, "description": { "type": [ "string", "null" ], "maxLength": 1000 }, "display_order": { "type": "integer", "minimum": 0, "maximum": 999999 }, "is_active": { "type": "boolean", "default": true } }, "minProperties": 1 }, "BusinessCostCenterLevelUpdateMeta": { "type": "object", "required": [ "api_version", "mode", "request_id", "resource", "scope", "total_options" ], "properties": { "api_version": { "type": "string", "const": "v1-2026-07" }, "mode": { "type": "string", "const": "updated" }, "request_id": { "type": "string", "minLength": 1, "maxLength": 128 }, "resource": { "type": "string", "const": "business_cost_center" }, "scope": { "type": "string", "const": "business.cost_centers.levels.update" }, "total_options": { "type": "integer", "minimum": 0 } } }, "BusinessCostCenterLevelUpdateResponse": { "type": "object", "required": [ "data", "meta" ], "properties": { "data": { "$ref": "#/components/schemas/BusinessCostCenterLevel" }, "meta": { "$ref": "#/components/schemas/BusinessCostCenterLevelUpdateMeta" } } }, "BusinessCostCenterOptionUpdateRequest": { "type": "object", "additionalProperties": false, "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 160 }, "code": { "type": [ "string", "null" ], "maxLength": 50 }, "description": { "type": [ "string", "null" ], "maxLength": 1000 }, "is_active": { "type": "boolean", "default": true } }, "minProperties": 1 }, "BusinessCostCenterOptionUpdateMeta": { "type": "object", "required": [ "api_version", "mode", "request_id", "resource", "scope" ], "properties": { "api_version": { "type": "string", "const": "v1-2026-07" }, "mode": { "type": "string", "const": "updated" }, "request_id": { "type": "string", "minLength": 1, "maxLength": 128 }, "resource": { "type": "string", "const": "business_cost_center_option" }, "scope": { "type": "string", "const": "business.cost_centers.options.update" } } }, "BusinessCostCenterOptionUpdateResponse": { "type": "object", "required": [ "data", "meta" ], "properties": { "data": { "$ref": "#/components/schemas/BusinessCostCenterOption" }, "meta": { "$ref": "#/components/schemas/BusinessCostCenterOptionUpdateMeta" } } }, "BusinessCostCenterBudgetTargetUpdateRequest": { "type": "object", "additionalProperties": false, "minProperties": 1, "properties": { "target_month": { "type": "string", "format": "date", "pattern": "^\\d{4}-\\d{2}-01$" }, "target_amount": { "type": "number", "minimum": 0, "maximum": 9999999999999.99, "multipleOf": 0.01 }, "notes": { "type": [ "string", "null" ], "maxLength": 1000 } } }, "BusinessCostCenterBudgetTargetUpdateMeta": { "type": "object", "required": [ "api_version", "mode", "request_id", "resource", "scope" ], "properties": { "api_version": { "type": "string", "const": "v1-2026-07" }, "mode": { "type": "string", "const": "updated" }, "request_id": { "type": "string", "minLength": 1, "maxLength": 128 }, "resource": { "type": "string", "const": "business_cost_center_budget_target" }, "scope": { "type": "string", "const": "business.cost_center_budgets.update" } } }, "BusinessCostCenterBudgetTargetUpdateResponse": { "type": "object", "required": [ "data", "meta" ], "properties": { "data": { "$ref": "#/components/schemas/BusinessCostCenterBudgetTarget" }, "meta": { "$ref": "#/components/schemas/BusinessCostCenterBudgetTargetUpdateMeta" } } }, "BusinessAccountingPeriodUpdateRequest": { "type": "object", "additionalProperties": false, "minProperties": 1, "properties": { "start_date": { "type": "string", "format": "date", "pattern": "^\\d{4}-\\d{2}-\\d{2}$" }, "end_date": { "type": "string", "format": "date", "pattern": "^\\d{4}-\\d{2}-\\d{2}$" }, "filing_deadline": { "type": [ "string", "null" ], "format": "date", "pattern": "^\\d{4}-\\d{2}-\\d{2}$" }, "period_type": { "type": "string", "enum": [ "annual", "statutory", "short", "long", "year" ], "description": "`statutory` and `year` are accepted API aliases and stored as the platform annual period type." } } }, "V1BusinessAccountingPeriodUpdateMeta": { "type": "object", "required": [ "api_version", "mode", "request_id", "resource", "scope" ], "properties": { "api_version": { "type": "string", "const": "v1-2026-07" }, "mode": { "type": "string", "const": "updated" }, "request_id": { "type": "string", "minLength": 1, "maxLength": 128 }, "resource": { "type": "string", "const": "business_accounting_period" }, "scope": { "type": "string", "const": "business.accounting_periods.update" } } }, "V1BusinessAccountingPeriodUpdateResponse": { "type": "object", "required": [ "data", "meta" ], "properties": { "data": { "$ref": "#/components/schemas/BusinessAccountingPeriod" }, "meta": { "$ref": "#/components/schemas/V1BusinessAccountingPeriodUpdateMeta" } } }, "BusinessChartOfAccountUpdateRequest": { "type": "object", "additionalProperties": false, "minProperties": 1, "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 200 }, "description": { "type": [ "string", "null" ], "maxLength": 1000 }, "area": { "type": [ "string", "null" ], "maxLength": 160 }, "ma_category": { "type": [ "string", "null" ], "maxLength": 160 }, "ma_sub_category": { "type": [ "string", "null" ], "maxLength": 160 }, "parent_code": { "type": [ "string", "null" ], "maxLength": 50 }, "is_active": { "type": "boolean" } } }, "V1BusinessChartOfAccountUpdateMeta": { "type": "object", "required": [ "api_version", "mode", "request_id", "resource", "scope" ], "properties": { "api_version": { "type": "string", "const": "v1-2026-07" }, "mode": { "type": "string", "const": "updated" }, "request_id": { "type": "string", "minLength": 1, "maxLength": 128 }, "resource": { "type": "string", "const": "business_chart_of_account" }, "scope": { "type": "string", "const": "business.chart_of_accounts.update" } } }, "BusinessChartOfAccountUpdateResponse": { "type": "object", "required": [ "data", "meta" ], "properties": { "data": { "$ref": "#/components/schemas/BusinessChartOfAccount" }, "meta": { "$ref": "#/components/schemas/V1BusinessChartOfAccountUpdateMeta" } } }, "V1BusinessBankAccountUpdateRequest": { "type": "object", "additionalProperties": false, "minProperties": 1, "properties": { "account_name": { "type": "string", "minLength": 1, "maxLength": 120 }, "bank_name": { "type": "string", "minLength": 1, "maxLength": 120 }, "account_type": { "type": "string", "enum": [ "current", "savings", "credit_card", "loan", "investment" ] }, "account_category": { "type": [ "string", "null" ], "enum": [ "current_account", "corporation_tax", "vat", "savings", "petty_cash", "expense_card", null ] }, "chart_of_accounts_id": { "type": [ "string", "null" ], "format": "uuid", "description": "Optional chart-of-accounts entry owned by the same business company. Null clears the link." }, "is_active": { "type": "boolean" } } }, "V1BusinessBankAccountUpdateMeta": { "type": "object", "required": [ "api_version", "mode", "request_id", "resource", "scope" ], "properties": { "api_version": { "type": "string", "const": "v1-2026-07" }, "mode": { "type": "string", "const": "updated" }, "request_id": { "type": "string", "minLength": 1, "maxLength": 128 }, "resource": { "type": "string", "const": "business_bank_account" }, "scope": { "type": "string", "const": "business.bank_accounts.update" } } }, "V1BusinessBankAccountUpdateResponse": { "type": "object", "required": [ "data", "meta" ], "properties": { "data": { "$ref": "#/components/schemas/BusinessBankAccount" }, "meta": { "$ref": "#/components/schemas/V1BusinessBankAccountUpdateMeta" } } }, "BusinessVatReturn": { "type": "object", "additionalProperties": false, "required": [ "object", "id", "company_id", "period_start", "period_end", "box1", "box2", "box3", "box4", "box5", "box6", "box7", "box8", "box9", "submission_status", "submission_date", "hmrc_submission_id", "submitted_by_user_id", "flat_rate_scheme", "created_at", "updated_at" ], "properties": { "object": { "type": "string", "const": "business_vat_return" }, "id": { "type": "string", "format": "uuid" }, "company_id": { "type": "string", "format": "uuid" }, "period_start": { "type": "string", "format": "date" }, "period_end": { "type": "string", "format": "date" }, "box1": { "type": "number", "description": "VAT due on sales and other outputs." }, "box2": { "type": "number", "description": "VAT due on acquisitions from EU member states where applicable." }, "box3": { "type": "number", "description": "Total VAT due." }, "box4": { "type": "number", "description": "VAT reclaimed on purchases and other inputs." }, "box5": { "type": "number", "description": "Net VAT to pay to HMRC or reclaim." }, "box6": { "type": "number", "description": "Total sales and outputs excluding VAT." }, "box7": { "type": "number", "description": "Total purchases and inputs excluding VAT." }, "box8": { "type": "number", "description": "Total supplies of goods to EU member states where applicable." }, "box9": { "type": "number", "description": "Total acquisitions of goods from EU member states where applicable." }, "submission_status": { "type": [ "string", "null" ], "enum": [ "draft", "submitted", "cancelled", "error", null ] }, "submission_date": { "type": [ "string", "null" ], "format": "date" }, "hmrc_submission_id": { "type": [ "string", "null" ] }, "submitted_by_user_id": { "type": [ "string", "null" ], "format": "uuid" }, "flat_rate_scheme": { "type": "boolean" }, "created_at": { "type": [ "string", "null" ], "format": "date-time" }, "updated_at": { "type": [ "string", "null" ], "format": "date-time" } } }, "V1BusinessVatReturnListMeta": { "type": "object", "additionalProperties": false, "required": [ "api_version", "mode", "resource", "request_id", "pagination" ], "properties": { "api_version": { "type": "string", "enum": [ "v1-2026-07" ] }, "mode": { "type": "string", "enum": [ "list" ] }, "resource": { "type": "string", "enum": [ "business_vat_return" ] }, "request_id": { "type": "string" }, "pagination": { "$ref": "#/components/schemas/V1PaginationMeta" } } }, "V1BusinessVatReturnDetailMeta": { "type": "object", "additionalProperties": false, "required": [ "api_version", "mode", "resource", "request_id" ], "properties": { "api_version": { "type": "string", "enum": [ "v1-2026-07" ] }, "mode": { "type": "string", "enum": [ "detail" ] }, "resource": { "type": "string", "enum": [ "business_vat_return" ] }, "request_id": { "type": "string" } } }, "V1BusinessVatReturnListResponse": { "type": "object", "additionalProperties": false, "required": [ "data", "meta" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/BusinessVatReturn" } }, "meta": { "$ref": "#/components/schemas/V1BusinessVatReturnListMeta" } } }, "V1BusinessVatReturnDetailResponse": { "type": "object", "additionalProperties": false, "required": [ "data", "meta" ], "properties": { "data": { "$ref": "#/components/schemas/BusinessVatReturn" }, "meta": { "$ref": "#/components/schemas/V1BusinessVatReturnDetailMeta" } } }, "BusinessVatSubmissionRequest": { "type": "object", "additionalProperties": false, "required": ["object", "id", "vat_return_id", "status", "approval_url", "created_at", "expires_at", "completed_at", "failure_code", "hmrc_reference", "updated_at"], "properties": { "object": {"type": "string", "const": "business_vat_submission_request"}, "id": {"type": "string", "format": "uuid"}, "vat_return_id": {"type": "string", "format": "uuid"}, "status": {"type": "string", "enum": ["pending", "consumed", "submitted", "failed", "expired"]}, "approval_url": {"type": ["string", "null"], "format": "uri"}, "created_at": {"type": "string", "format": "date-time"}, "expires_at": {"type": "string", "format": "date-time"}, "completed_at": {"type": ["string", "null"], "format": "date-time"}, "failure_code": {"type": ["string", "null"]}, "hmrc_reference": {"type": ["string", "null"]}, "updated_at": {"type": "string", "format": "date-time"} } }, "V1BusinessVatSubmissionRequestResponse": { "type": "object", "additionalProperties": false, "required": ["data", "meta"], "properties": { "data": {"$ref": "#/components/schemas/BusinessVatSubmissionRequest"}, "meta": {"$ref": "#/components/schemas/V1Meta"} } }, "V1BusinessCt600SubmissionRequestCreate": { "type": "object", "additionalProperties": false, "required": ["computation_id", "accounting_period_id", "declarant_name", "declarant_status"], "properties": { "computation_id": {"type": "string", "format": "uuid"}, "accounting_period_id": {"type": "string", "format": "uuid"}, "declarant_name": {"type": "string", "minLength": 1, "maxLength": 200}, "declarant_status": {"type": "string", "minLength": 1, "maxLength": 120}, "use_test_endpoint": {"type": "boolean", "default": true} } }, "BusinessCt600SubmissionRequest": { "type": "object", "additionalProperties": false, "required": ["object", "id", "computation_id", "accounting_period_id", "status", "approval_url", "declarant_name", "declarant_status", "use_test_endpoint", "created_at", "expires_at", "completed_at", "failure_code", "hmrc_reference", "updated_at"], "properties": { "object": {"type": "string", "const": "business_ct600_submission_request"}, "id": {"type": "string", "format": "uuid"}, "computation_id": {"type": "string", "format": "uuid"}, "accounting_period_id": {"type": "string", "format": "uuid"}, "status": {"type": "string", "enum": ["pending", "consumed", "submitted", "failed", "expired"]}, "approval_url": {"type": ["string", "null"], "format": "uri"}, "declarant_name": {"type": "string"}, "declarant_status": {"type": "string"}, "use_test_endpoint": {"type": "boolean"}, "created_at": {"type": "string", "format": "date-time"}, "expires_at": {"type": "string", "format": "date-time"}, "completed_at": {"type": ["string", "null"], "format": "date-time"}, "failure_code": {"type": ["string", "null"]}, "hmrc_reference": {"type": ["string", "null"]}, "updated_at": {"type": "string", "format": "date-time"} } }, "V1BusinessCt600SubmissionRequestResponse": { "type": "object", "additionalProperties": false, "required": ["data", "meta"], "properties": { "data": {"$ref": "#/components/schemas/BusinessCt600SubmissionRequest"}, "meta": {"$ref": "#/components/schemas/V1Meta"} } }, "V1BusinessCompaniesHouseSubmissionRequestCreate": { "type": "object", "additionalProperties": false, "required": ["accounting_period_id", "submission_type"], "properties": { "accounting_period_id": {"type": "string", "format": "uuid"}, "version_id": {"type": ["string", "null"], "format": "uuid"}, "submission_type": {"type": "string", "enum": ["test", "production"], "default": "test"} } }, "BusinessCompaniesHouseSubmissionRequest": { "type": "object", "additionalProperties": false, "required": ["object", "id", "accounting_period_id", "version_id", "status", "approval_url", "submission_type", "created_at", "expires_at", "completed_at", "failure_code", "provider_reference", "updated_at"], "properties": { "object": {"type": "string", "const": "business_companies_house_submission_request"}, "id": {"type": "string", "format": "uuid"}, "accounting_period_id": {"type": "string", "format": "uuid"}, "version_id": {"type": ["string", "null"], "format": "uuid"}, "status": {"type": "string", "enum": ["pending", "consumed", "submitted", "failed", "expired"]}, "approval_url": {"type": ["string", "null"], "format": "uri"}, "submission_type": {"type": "string", "enum": ["test", "production"]}, "created_at": {"type": "string", "format": "date-time"}, "expires_at": {"type": "string", "format": "date-time"}, "completed_at": {"type": ["string", "null"], "format": "date-time"}, "failure_code": {"type": ["string", "null"]}, "provider_reference": {"type": ["string", "null"]}, "updated_at": {"type": "string", "format": "date-time"} } }, "V1BusinessCompaniesHouseSubmissionRequestResponse": { "type": "object", "additionalProperties": false, "required": ["data", "meta"], "properties": { "data": {"$ref": "#/components/schemas/BusinessCompaniesHouseSubmissionRequest"}, "meta": {"$ref": "#/components/schemas/V1Meta"} } }, "BusinessCt600Filing": { "type": "object", "additionalProperties": false, "required": [ "object", "id", "company_id", "computation_id", "accounting_period_id", "status", "environment", "hmrc_submission_id", "submitted_at", "accepted_at", "submitted_by_user_id", "has_errors", "error_count", "created_at", "updated_at" ], "properties": { "object": { "type": "string", "const": "business_ct600_filing" }, "id": { "type": "string", "format": "uuid" }, "company_id": { "type": "string", "format": "uuid" }, "computation_id": { "type": "string", "format": "uuid" }, "accounting_period_id": { "type": "string", "format": "uuid" }, "status": { "type": [ "string", "null" ], "enum": [ "draft", "pending", "submitted", "accepted", "rejected", "failed", null ] }, "environment": { "type": [ "string", "null" ], "enum": [ "sandbox", "production", null ] }, "hmrc_submission_id": { "type": [ "string", "null" ] }, "submitted_at": { "type": [ "string", "null" ], "format": "date-time" }, "accepted_at": { "type": [ "string", "null" ], "format": "date-time" }, "submitted_by_user_id": { "type": [ "string", "null" ], "format": "uuid" }, "has_errors": { "type": "boolean" }, "error_count": { "type": "integer", "minimum": 0 }, "created_at": { "type": [ "string", "null" ], "format": "date-time" }, "updated_at": { "type": [ "string", "null" ], "format": "date-time" } } }, "V1BusinessCt600FilingListMeta": { "type": "object", "additionalProperties": false, "required": [ "api_version", "mode", "resource", "request_id", "pagination" ], "properties": { "api_version": { "type": "string", "enum": [ "v1-2026-07" ] }, "mode": { "type": "string", "enum": [ "list" ] }, "resource": { "type": "string", "enum": [ "business_ct600_filing" ] }, "request_id": { "type": "string" }, "pagination": { "$ref": "#/components/schemas/V1PaginationMeta" } } }, "V1BusinessCt600FilingDetailMeta": { "type": "object", "additionalProperties": false, "required": [ "api_version", "mode", "resource", "request_id" ], "properties": { "api_version": { "type": "string", "enum": [ "v1-2026-07" ] }, "mode": { "type": "string", "enum": [ "detail" ] }, "resource": { "type": "string", "enum": [ "business_ct600_filing" ] }, "request_id": { "type": "string" } } }, "V1BusinessCt600FilingListResponse": { "type": "object", "additionalProperties": false, "required": [ "data", "meta" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/BusinessCt600Filing" } }, "meta": { "$ref": "#/components/schemas/V1BusinessCt600FilingListMeta" } } }, "V1BusinessCt600FilingDetailResponse": { "type": "object", "additionalProperties": false, "required": [ "data", "meta" ], "properties": { "data": { "$ref": "#/components/schemas/BusinessCt600Filing" }, "meta": { "$ref": "#/components/schemas/V1BusinessCt600FilingDetailMeta" } } }, "BusinessStatutoryAccountsVersion": { "type": "object", "additionalProperties": false, "required": [ "object", "id", "company_id", "accounting_period_id", "version_number", "version_name", "version_notes", "saved_at", "saved_by_user_id", "is_current", "is_active", "is_audited", "directors_report_signed_date", "balance_sheet_signed_date", "created_at", "updated_at" ], "properties": { "object": { "type": "string", "const": "business_statutory_accounts_version" }, "id": { "type": "string", "format": "uuid" }, "company_id": { "type": "string", "format": "uuid" }, "accounting_period_id": { "type": "string", "format": "uuid" }, "version_number": { "type": "integer", "minimum": 0 }, "version_name": { "type": [ "string", "null" ] }, "version_notes": { "type": [ "string", "null" ] }, "saved_at": { "type": [ "string", "null" ], "format": "date-time" }, "saved_by_user_id": { "type": [ "string", "null" ], "format": "uuid" }, "is_current": { "type": "boolean" }, "is_active": { "type": "boolean" }, "is_audited": { "type": "boolean" }, "directors_report_signed_date": { "type": [ "string", "null" ], "format": "date" }, "balance_sheet_signed_date": { "type": [ "string", "null" ], "format": "date" }, "created_at": { "type": [ "string", "null" ], "format": "date-time" }, "updated_at": { "type": [ "string", "null" ], "format": "date-time" } } }, "BusinessDirector": { "type": "object", "additionalProperties": false, "required": [ "object", "id", "company_id", "name", "email", "phone", "loan_account_id", "appointed_date", "resigned_date", "is_current", "created_at", "updated_at" ], "properties": { "object": { "type": "string", "const": "business_director" }, "id": { "type": "string", "format": "uuid" }, "company_id": { "type": "string", "format": "uuid" }, "name": { "type": [ "string", "null" ] }, "email": { "type": [ "string", "null" ], "format": "email" }, "phone": { "type": [ "string", "null" ] }, "loan_account_id": { "type": [ "string", "null" ], "format": "uuid" }, "appointed_date": { "type": [ "string", "null" ], "format": "date" }, "resigned_date": { "type": [ "string", "null" ], "format": "date" }, "is_current": { "type": "boolean" }, "created_at": { "type": [ "string", "null" ], "format": "date-time" }, "updated_at": { "type": [ "string", "null" ], "format": "date-time" } } }, "BusinessShareholder": { "type": "object", "additionalProperties": false, "required": [ "object", "id", "company_id", "legal_name", "member_type", "address_line1", "address_line2", "address_line3", "address_line4", "postcode", "country", "email", "notes", "is_active", "inactive_at", "created_by_user_id", "created_at", "updated_at" ], "properties": { "object": { "type": "string", "const": "business_shareholder" }, "id": { "type": "string", "format": "uuid" }, "company_id": { "type": "string", "format": "uuid" }, "legal_name": { "type": [ "string", "null" ] }, "member_type": { "type": "string", "enum": [ "individual", "entity" ] }, "address_line1": { "type": [ "string", "null" ] }, "address_line2": { "type": [ "string", "null" ] }, "address_line3": { "type": [ "string", "null" ] }, "address_line4": { "type": [ "string", "null" ] }, "postcode": { "type": [ "string", "null" ] }, "country": { "type": [ "string", "null" ] }, "email": { "type": [ "string", "null" ], "format": "email" }, "notes": { "type": [ "string", "null" ] }, "is_active": { "type": "boolean" }, "inactive_at": { "type": [ "string", "null" ], "format": "date-time" }, "created_by_user_id": { "type": [ "string", "null" ], "format": "uuid" }, "created_at": { "type": [ "string", "null" ], "format": "date-time" }, "updated_at": { "type": [ "string", "null" ], "format": "date-time" } } }, "V1BusinessStatutoryAccountsVersionListMeta": { "type": "object", "additionalProperties": false, "required": [ "api_version", "mode", "resource", "request_id", "pagination" ], "properties": { "api_version": { "type": "string", "enum": [ "v1-2026-07" ] }, "mode": { "type": "string", "enum": [ "list" ] }, "resource": { "type": "string", "enum": [ "business_statutory_accounts_version" ] }, "request_id": { "type": "string" }, "pagination": { "$ref": "#/components/schemas/V1PaginationMeta" } } }, "V1BusinessStatutoryAccountsVersionDetailMeta": { "type": "object", "additionalProperties": false, "required": [ "api_version", "mode", "resource", "request_id" ], "properties": { "api_version": { "type": "string", "enum": [ "v1-2026-07" ] }, "mode": { "type": "string", "enum": [ "detail" ] }, "resource": { "type": "string", "enum": [ "business_statutory_accounts_version" ] }, "request_id": { "type": "string" } } }, "V1BusinessStatutoryAccountsVersionListResponse": { "type": "object", "additionalProperties": false, "required": [ "data", "meta" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/BusinessStatutoryAccountsVersion" } }, "meta": { "$ref": "#/components/schemas/V1BusinessStatutoryAccountsVersionListMeta" } } }, "V1BusinessStatutoryAccountsVersionDetailResponse": { "type": "object", "additionalProperties": false, "required": [ "data", "meta" ], "properties": { "data": { "$ref": "#/components/schemas/BusinessStatutoryAccountsVersion" }, "meta": { "$ref": "#/components/schemas/V1BusinessStatutoryAccountsVersionDetailMeta" } } }, "V1BusinessDirectorListMeta": { "type": "object", "additionalProperties": false, "required": [ "api_version", "mode", "resource", "request_id", "pagination" ], "properties": { "api_version": { "type": "string", "enum": [ "v1-2026-07" ] }, "mode": { "type": "string", "enum": [ "list" ] }, "resource": { "type": "string", "enum": [ "business_director" ] }, "request_id": { "type": "string" }, "pagination": { "$ref": "#/components/schemas/V1PaginationMeta" } } }, "V1BusinessDirectorDetailMeta": { "type": "object", "additionalProperties": false, "required": [ "api_version", "mode", "resource", "request_id" ], "properties": { "api_version": { "type": "string", "enum": [ "v1-2026-07" ] }, "mode": { "type": "string", "enum": [ "detail" ] }, "resource": { "type": "string", "enum": [ "business_director" ] }, "request_id": { "type": "string" } } }, "V1BusinessDirectorListResponse": { "type": "object", "additionalProperties": false, "required": [ "data", "meta" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/BusinessDirector" } }, "meta": { "$ref": "#/components/schemas/V1BusinessDirectorListMeta" } } }, "V1BusinessDirectorDetailResponse": { "type": "object", "additionalProperties": false, "required": [ "data", "meta" ], "properties": { "data": { "$ref": "#/components/schemas/BusinessDirector" }, "meta": { "$ref": "#/components/schemas/V1BusinessDirectorDetailMeta" } } }, "V1BusinessShareholderListMeta": { "type": "object", "additionalProperties": false, "required": [ "api_version", "mode", "resource", "request_id", "pagination" ], "properties": { "api_version": { "type": "string", "enum": [ "v1-2026-07" ] }, "mode": { "type": "string", "enum": [ "list" ] }, "resource": { "type": "string", "enum": [ "business_shareholder" ] }, "request_id": { "type": "string" }, "pagination": { "$ref": "#/components/schemas/V1PaginationMeta" } } }, "V1BusinessShareholderDetailMeta": { "type": "object", "additionalProperties": false, "required": [ "api_version", "mode", "resource", "request_id" ], "properties": { "api_version": { "type": "string", "enum": [ "v1-2026-07" ] }, "mode": { "type": "string", "enum": [ "detail" ] }, "resource": { "type": "string", "enum": [ "business_shareholder" ] }, "request_id": { "type": "string" } } }, "V1BusinessShareholderListResponse": { "type": "object", "additionalProperties": false, "required": [ "data", "meta" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/BusinessShareholder" } }, "meta": { "$ref": "#/components/schemas/V1BusinessShareholderListMeta" } } }, "V1BusinessShareholderDetailResponse": { "type": "object", "additionalProperties": false, "required": [ "data", "meta" ], "properties": { "data": { "$ref": "#/components/schemas/BusinessShareholder" }, "meta": { "$ref": "#/components/schemas/V1BusinessShareholderDetailMeta" } } }, "BusinessCompaniesHouseChangeEvent": { "type": "object", "additionalProperties": false, "required": [ "object", "id", "company_id", "change_type", "form_code", "form_name", "status", "effective_date", "payload", "validation_warnings", "has_validation_warnings", "validation_warning_count", "filed_at", "filed_reference", "filing_enabled", "manual_filing_note", "created_by_user_id", "created_at", "updated_at" ], "properties": { "object": { "type": "string", "const": "business_companies_house_change_event" }, "id": { "type": "string", "format": "uuid" }, "company_id": { "type": "string", "format": "uuid" }, "change_type": { "type": "string", "enum": [ "registered_office", "director_appointment", "director_resignation", "share_allotment", "psc_add", "psc_change", "psc_cease" ] }, "form_code": { "type": "string", "enum": [ "AD01", "AP01", "TM01", "SH01", "PSC01", "PSC04", "PSC07" ] }, "form_name": { "type": [ "string", "null" ] }, "status": { "type": "string", "enum": [ "draft", "reviewed", "manually_filed", "superseded" ] }, "effective_date": { "type": "string", "format": "date" }, "payload": { "type": "object", "additionalProperties": true }, "validation_warnings": { "type": "array", "items": { "type": "string" } }, "has_validation_warnings": { "type": "boolean" }, "validation_warning_count": { "type": "integer", "minimum": 0 }, "filed_at": { "type": [ "string", "null" ], "format": "date-time" }, "filed_reference": { "type": [ "string", "null" ] }, "filing_enabled": { "type": "boolean", "const": false }, "manual_filing_note": { "type": "string" }, "created_by_user_id": { "type": [ "string", "null" ], "format": "uuid" }, "created_at": { "type": [ "string", "null" ], "format": "date-time" }, "updated_at": { "type": [ "string", "null" ], "format": "date-time" } } }, "V1BusinessCompaniesHouseChangeEventListMeta": { "type": "object", "additionalProperties": false, "required": [ "api_version", "mode", "resource", "request_id", "pagination" ], "properties": { "api_version": { "type": "string", "enum": [ "v1-2026-07" ] }, "mode": { "type": "string", "enum": [ "list" ] }, "resource": { "type": "string", "enum": [ "business_companies_house_change_event" ] }, "request_id": { "type": "string" }, "pagination": { "$ref": "#/components/schemas/V1PaginationMeta" } } }, "V1BusinessCompaniesHouseChangeEventDetailMeta": { "type": "object", "additionalProperties": false, "required": [ "api_version", "mode", "resource", "request_id" ], "properties": { "api_version": { "type": "string", "enum": [ "v1-2026-07" ] }, "mode": { "type": "string", "enum": [ "detail" ] }, "resource": { "type": "string", "enum": [ "business_companies_house_change_event" ] }, "request_id": { "type": "string" } } }, "V1BusinessCompaniesHouseChangeEventListResponse": { "type": "object", "additionalProperties": false, "required": [ "data", "meta" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/BusinessCompaniesHouseChangeEvent" } }, "meta": { "$ref": "#/components/schemas/V1BusinessCompaniesHouseChangeEventListMeta" } } }, "V1BusinessCompaniesHouseChangeEventDetailResponse": { "type": "object", "additionalProperties": false, "required": [ "data", "meta" ], "properties": { "data": { "$ref": "#/components/schemas/BusinessCompaniesHouseChangeEvent" }, "meta": { "$ref": "#/components/schemas/V1BusinessCompaniesHouseChangeEventDetailMeta" } } }, "BusinessCompanyPscRecord": { "type": "object", "additionalProperties": false, "required": [ "object", "id", "company_id", "psc_type", "name", "nature_of_control", "ownership_percent", "notified_on", "ceased_on", "is_active", "identity_verified", "personal_code_status", "source", "notes", "created_by_user_id", "created_at", "updated_at" ], "properties": { "object": { "type": "string", "const": "business_company_psc_record" }, "id": { "type": "string", "format": "uuid" }, "company_id": { "type": "string", "format": "uuid" }, "psc_type": { "type": [ "string", "null" ], "enum": [ "individual", "corporate", "other", null ] }, "name": { "type": [ "string", "null" ] }, "nature_of_control": { "type": "array", "items": { "type": "string" } }, "ownership_percent": { "type": [ "number", "null" ], "minimum": 0, "maximum": 100 }, "notified_on": { "type": [ "string", "null" ], "format": "date" }, "ceased_on": { "type": [ "string", "null" ], "format": "date" }, "is_active": { "type": "boolean" }, "identity_verified": { "type": "boolean" }, "personal_code_status": { "type": [ "string", "null" ], "enum": [ "not_recorded", "checked", "not_required", null ] }, "source": { "type": [ "string", "null" ], "enum": [ "manual", "shareholding_review", "companies_house", null ] }, "notes": { "type": [ "string", "null" ] }, "created_by_user_id": { "type": [ "string", "null" ], "format": "uuid" }, "created_at": { "type": [ "string", "null" ], "format": "date-time" }, "updated_at": { "type": [ "string", "null" ], "format": "date-time" } } }, "V1BusinessPscRegisterListMeta": { "type": "object", "additionalProperties": false, "required": [ "api_version", "mode", "resource", "request_id", "pagination" ], "properties": { "api_version": { "type": "string", "enum": [ "v1-2026-07" ] }, "mode": { "type": "string", "enum": [ "list" ] }, "resource": { "type": "string", "enum": [ "business_company_psc_record" ] }, "request_id": { "type": "string" }, "pagination": { "$ref": "#/components/schemas/V1PaginationMeta" } } }, "V1BusinessPscRegisterDetailMeta": { "type": "object", "additionalProperties": false, "required": [ "api_version", "mode", "resource", "request_id" ], "properties": { "api_version": { "type": "string", "enum": [ "v1-2026-07" ] }, "mode": { "type": "string", "enum": [ "detail" ] }, "resource": { "type": "string", "enum": [ "business_company_psc_record" ] }, "request_id": { "type": "string" } } }, "V1BusinessPscRegisterListResponse": { "type": "object", "additionalProperties": false, "required": [ "data", "meta" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/BusinessCompanyPscRecord" } }, "meta": { "$ref": "#/components/schemas/V1BusinessPscRegisterListMeta" } } }, "V1BusinessPscRegisterDetailResponse": { "type": "object", "additionalProperties": false, "required": [ "data", "meta" ], "properties": { "data": { "$ref": "#/components/schemas/BusinessCompanyPscRecord" }, "meta": { "$ref": "#/components/schemas/V1BusinessPscRegisterDetailMeta" } } }, "BusinessCompaniesHouseFilingLatestPoll": { "type": "object", "additionalProperties": false, "required": [ "http_status", "normalised_status", "polled_at", "raw_status" ], "properties": { "http_status": { "type": [ "integer", "null" ], "minimum": 100, "maximum": 599 }, "normalised_status": { "type": [ "string", "null" ] }, "polled_at": { "type": [ "string", "null" ], "format": "date-time" }, "raw_status": { "type": [ "string", "null" ] } } }, "BusinessCompaniesHouseFiling": { "type": "object", "additionalProperties": false, "required": [ "object", "id", "company_id", "accounting_period_id", "status", "environment", "filing_type", "filing_format", "submission_reference", "submitted_at", "acknowledged_at", "created_by_user_id", "has_rejection_reasons", "rejection_reason_count", "latest_poll", "upstream_status", "upstream_response_received_at", "created_at", "updated_at" ], "properties": { "object": { "type": "string", "const": "business_companies_house_filing" }, "id": { "type": "string", "format": "uuid" }, "company_id": { "type": "string", "format": "uuid" }, "accounting_period_id": { "type": "string", "format": "uuid" }, "status": { "type": [ "string", "null" ], "enum": [ "pending", "submitted", "acknowledged", "accepted", "rejected", null ] }, "environment": { "type": [ "string", "null" ], "enum": [ "test", "production", null ] }, "filing_type": { "type": [ "string", "null" ], "enum": [ "companies_house", "both", null ] }, "filing_format": { "type": [ "string", "null" ], "enum": [ "pdf", "ixbrl", "both", null ] }, "submission_reference": { "type": [ "string", "null" ] }, "submitted_at": { "type": [ "string", "null" ], "format": "date-time" }, "acknowledged_at": { "type": [ "string", "null" ], "format": "date-time" }, "created_by_user_id": { "type": [ "string", "null" ], "format": "uuid" }, "has_rejection_reasons": { "type": "boolean" }, "rejection_reason_count": { "type": "integer", "minimum": 0 }, "latest_poll": { "oneOf": [ { "$ref": "#/components/schemas/BusinessCompaniesHouseFilingLatestPoll" }, { "type": "null" } ] }, "upstream_status": { "type": [ "string", "null" ] }, "upstream_response_received_at": { "type": [ "string", "null" ], "format": "date-time" }, "created_at": { "type": [ "string", "null" ], "format": "date-time" }, "updated_at": { "type": [ "string", "null" ], "format": "date-time" } } }, "V1BusinessCompaniesHouseFilingListMeta": { "type": "object", "additionalProperties": false, "required": [ "api_version", "mode", "resource", "request_id", "pagination" ], "properties": { "api_version": { "type": "string", "enum": [ "v1-2026-07" ] }, "mode": { "type": "string", "enum": [ "list" ] }, "resource": { "type": "string", "enum": [ "business_companies_house_filing" ] }, "request_id": { "type": "string" }, "pagination": { "$ref": "#/components/schemas/V1PaginationMeta" } } }, "V1BusinessCompaniesHouseFilingDetailMeta": { "type": "object", "additionalProperties": false, "required": [ "api_version", "mode", "resource", "request_id" ], "properties": { "api_version": { "type": "string", "enum": [ "v1-2026-07" ] }, "mode": { "type": "string", "enum": [ "detail" ] }, "resource": { "type": "string", "enum": [ "business_companies_house_filing" ] }, "request_id": { "type": "string" } } }, "V1BusinessCompaniesHouseFilingListResponse": { "type": "object", "additionalProperties": false, "required": [ "data", "meta" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/BusinessCompaniesHouseFiling" } }, "meta": { "$ref": "#/components/schemas/V1BusinessCompaniesHouseFilingListMeta" } } }, "V1BusinessCompaniesHouseFilingDetailResponse": { "type": "object", "additionalProperties": false, "required": [ "data", "meta" ], "properties": { "data": { "$ref": "#/components/schemas/BusinessCompaniesHouseFiling" }, "meta": { "$ref": "#/components/schemas/V1BusinessCompaniesHouseFilingDetailMeta" } } }, "BusinessShareClass": { "type": "object", "additionalProperties": false, "required": [ "object", "id", "company_id", "name", "nominal_value", "authorised_shares", "rights_summary", "is_numbered", "next_share_number", "created_by_user_id", "created_at", "updated_at" ], "properties": { "object": { "type": "string", "const": "business_share_class" }, "id": { "type": "string", "format": "uuid" }, "company_id": { "type": "string", "format": "uuid" }, "name": { "type": [ "string", "null" ] }, "nominal_value": { "type": [ "number", "null" ] }, "authorised_shares": { "type": [ "integer", "null" ] }, "rights_summary": { "type": [ "string", "null" ] }, "is_numbered": { "type": "boolean" }, "next_share_number": { "type": [ "integer", "null" ] }, "created_by_user_id": { "type": [ "string", "null" ], "format": "uuid" }, "created_at": { "type": [ "string", "null" ], "format": "date-time" }, "updated_at": { "type": [ "string", "null" ], "format": "date-time" } } }, "V1BusinessShareClassListMeta": { "type": "object", "additionalProperties": false, "required": [ "api_version", "mode", "resource", "request_id", "pagination" ], "properties": { "api_version": { "type": "string", "enum": [ "v1-2026-07" ] }, "mode": { "type": "string", "enum": [ "list" ] }, "resource": { "type": "string", "enum": [ "business_share_class" ] }, "request_id": { "type": "string" }, "pagination": { "$ref": "#/components/schemas/V1PaginationMeta" } } }, "V1BusinessShareClassDetailMeta": { "type": "object", "additionalProperties": false, "required": [ "api_version", "mode", "resource", "request_id" ], "properties": { "api_version": { "type": "string", "enum": [ "v1-2026-07" ] }, "mode": { "type": "string", "enum": [ "detail" ] }, "resource": { "type": "string", "enum": [ "business_share_class" ] }, "request_id": { "type": "string" } } }, "V1BusinessShareClassListResponse": { "type": "object", "additionalProperties": false, "required": [ "data", "meta" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/BusinessShareClass" } }, "meta": { "$ref": "#/components/schemas/V1BusinessShareClassListMeta" } } }, "V1BusinessShareClassDetailResponse": { "type": "object", "additionalProperties": false, "required": [ "data", "meta" ], "properties": { "data": { "$ref": "#/components/schemas/BusinessShareClass" }, "meta": { "$ref": "#/components/schemas/V1BusinessShareClassDetailMeta" } } }, "BusinessShareIssue": { "type": "object", "additionalProperties": false, "required": [ "object", "id", "company_id", "share_class_id", "shareholder_id", "issue_date", "quantity", "issue_price_per_share", "amount_paid_per_share", "amount_unpaid_per_share", "reference", "share_number_start", "share_number_end", "consideration_account_id", "journal_transaction_id", "posted_to_ledger", "entry_kind", "voided", "voided_at", "void_reason", "created_by_user_id", "created_at", "updated_at" ], "properties": { "object": { "type": "string", "const": "business_share_issue" }, "entry_kind": { "type": "string", "enum": [ "allotment", "opening_position", "historical_allotment", "redesignation", "bonus_issue", "call", "forfeiture", "buyback_cancelled", "buyback_treasury", "treasury_holding", "redemption", "subdivision", "consolidation", "redenomination", "reduction", "treasury_sale", "treasury_cancellation" ], "description": "allotment: allotted and posted by FIQ. opening_position and historical_allotment: shares already in issue, recorded in the register only. redesignation: a class change; the class given up carries a negative quantity. The remaining kinds belong to a change recorded in FIQ (a bonus issue, a call, a forfeiture, a buy-back, a redemption, a split or consolidation, a redenomination, a reduction of capital, or a treasury share sale or cancellation); rows that take shares away carry a negative quantity, so adding every unvoided entry gives the holding." }, "voided": { "type": "boolean", "description": "True when the entry has been voided and is no longer part of the register." }, "voided_at": { "type": [ "string", "null" ], "format": "date-time" }, "void_reason": { "type": [ "string", "null" ] }, "id": { "type": "string", "format": "uuid" }, "company_id": { "type": "string", "format": "uuid" }, "share_class_id": { "type": "string", "format": "uuid" }, "shareholder_id": { "type": "string", "format": "uuid" }, "issue_date": { "type": [ "string", "null" ], "format": "date" }, "quantity": { "type": [ "integer", "null" ] }, "issue_price_per_share": { "type": [ "number", "null" ] }, "amount_paid_per_share": { "type": [ "number", "null" ] }, "amount_unpaid_per_share": { "type": [ "number", "null" ] }, "reference": { "type": [ "string", "null" ] }, "share_number_start": { "type": [ "integer", "null" ] }, "share_number_end": { "type": [ "integer", "null" ] }, "consideration_account_id": { "type": [ "string", "null" ], "format": "uuid" }, "journal_transaction_id": { "type": [ "string", "null" ], "format": "uuid" }, "posted_to_ledger": { "type": "boolean" }, "created_by_user_id": { "type": [ "string", "null" ], "format": "uuid" }, "created_at": { "type": [ "string", "null" ], "format": "date-time" }, "updated_at": { "type": [ "string", "null" ], "format": "date-time" } } }, "V1BusinessShareIssueListMeta": { "type": "object", "additionalProperties": false, "required": [ "api_version", "mode", "resource", "request_id", "pagination" ], "properties": { "api_version": { "type": "string", "enum": [ "v1-2026-07" ] }, "mode": { "type": "string", "enum": [ "list" ] }, "resource": { "type": "string", "enum": [ "business_share_issue" ] }, "request_id": { "type": "string" }, "pagination": { "$ref": "#/components/schemas/V1PaginationMeta" } } }, "V1BusinessShareIssueDetailMeta": { "type": "object", "additionalProperties": false, "required": [ "api_version", "mode", "resource", "request_id" ], "properties": { "api_version": { "type": "string", "enum": [ "v1-2026-07" ] }, "mode": { "type": "string", "enum": [ "detail" ] }, "resource": { "type": "string", "enum": [ "business_share_issue" ] }, "request_id": { "type": "string" } } }, "V1BusinessShareIssueListResponse": { "type": "object", "additionalProperties": false, "required": [ "data", "meta" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/BusinessShareIssue" } }, "meta": { "$ref": "#/components/schemas/V1BusinessShareIssueListMeta" } } }, "V1BusinessShareIssueDetailResponse": { "type": "object", "additionalProperties": false, "required": [ "data", "meta" ], "properties": { "data": { "$ref": "#/components/schemas/BusinessShareIssue" }, "meta": { "$ref": "#/components/schemas/V1BusinessShareIssueDetailMeta" } } }, "BusinessDividendDeclarationCreateRequest": { "type": "object", "additionalProperties": false, "required": [ "declaration_type", "declared_at", "record_date" ], "properties": { "declaration_type": { "type": "string", "enum": [ "interim", "final", "other" ] }, "declared_at": { "type": "string", "format": "date" }, "record_date": { "type": "string", "format": "date" }, "payment_date": { "type": [ "string", "null" ], "format": "date" }, "currency": { "type": "string", "pattern": "^[A-Z]{3}$", "default": "GBP" }, "declaration_reference": { "type": [ "string", "null" ], "maxLength": 120 }, "notes": { "type": [ "string", "null" ], "maxLength": 2000 } } }, "BusinessDividendDeclaration": { "type": "object", "additionalProperties": false, "required": [ "object", "id", "company_id", "declaration_reference", "declaration_type", "declared_at", "record_date", "payment_date", "status", "currency", "total_amount", "notes", "journal_transaction_id", "recurring_schedule_id", "recurring_run_id", "auto_declared", "supporting_paperwork_generated_at", "created_by_user_id", "approved_by_user_id", "approved_at", "cancelled_at", "created_at", "updated_at" ], "properties": { "object": { "type": "string", "const": "business_dividend_declaration" }, "id": { "type": "string", "format": "uuid" }, "company_id": { "type": "string", "format": "uuid" }, "declaration_reference": { "type": [ "string", "null" ] }, "declaration_type": { "type": "string", "enum": [ "interim", "final", "other" ] }, "declared_at": { "type": [ "string", "null" ], "format": "date" }, "record_date": { "type": [ "string", "null" ], "format": "date" }, "payment_date": { "type": [ "string", "null" ], "format": "date" }, "status": { "type": "string", "enum": [ "draft", "approved", "posted", "cancelled" ] }, "currency": { "type": [ "string", "null" ] }, "total_amount": { "type": [ "number", "null" ] }, "notes": { "type": [ "string", "null" ] }, "journal_transaction_id": { "type": [ "string", "null" ], "format": "uuid" }, "recurring_schedule_id": { "type": [ "string", "null" ], "format": "uuid" }, "recurring_run_id": { "type": [ "string", "null" ], "format": "uuid" }, "auto_declared": { "type": "boolean" }, "supporting_paperwork_generated_at": { "type": [ "string", "null" ], "format": "date-time" }, "created_by_user_id": { "type": [ "string", "null" ], "format": "uuid" }, "approved_by_user_id": { "type": [ "string", "null" ], "format": "uuid" }, "approved_at": { "type": [ "string", "null" ], "format": "date-time" }, "cancelled_at": { "type": [ "string", "null" ], "format": "date-time" }, "created_at": { "type": [ "string", "null" ], "format": "date-time" }, "updated_at": { "type": [ "string", "null" ], "format": "date-time" } } }, "V1BusinessDividendDeclarationListMeta": { "type": "object", "additionalProperties": false, "required": [ "api_version", "mode", "resource", "request_id", "pagination" ], "properties": { "api_version": { "type": "string", "enum": [ "v1-2026-07" ] }, "mode": { "type": "string", "enum": [ "list" ] }, "resource": { "type": "string", "enum": [ "business_dividend_declaration" ] }, "request_id": { "type": "string" }, "pagination": { "$ref": "#/components/schemas/V1PaginationMeta" } } }, "V1BusinessDividendDeclarationDetailMeta": { "type": "object", "additionalProperties": false, "required": [ "api_version", "mode", "resource", "request_id" ], "properties": { "api_version": { "type": "string", "enum": [ "v1-2026-07" ] }, "mode": { "type": "string", "enum": [ "detail" ] }, "resource": { "type": "string", "enum": [ "business_dividend_declaration" ] }, "request_id": { "type": "string" } } }, "V1BusinessDividendDeclarationListResponse": { "type": "object", "additionalProperties": false, "required": [ "data", "meta" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/BusinessDividendDeclaration" } }, "meta": { "$ref": "#/components/schemas/V1BusinessDividendDeclarationListMeta" } } }, "V1BusinessDividendDeclarationDetailResponse": { "type": "object", "additionalProperties": false, "required": [ "data", "meta" ], "properties": { "data": { "$ref": "#/components/schemas/BusinessDividendDeclaration" }, "meta": { "$ref": "#/components/schemas/V1BusinessDividendDeclarationDetailMeta" } } }, "V1BusinessDividendPaperworkPreviewResponse": { "type": "object", "additionalProperties": false, "required": [ "data", "meta" ], "properties": { "data": { "type": "object", "additionalProperties": false, "required": [ "object", "declaration", "board_minutes", "vouchers" ], "properties": { "object": { "type": "string", "const": "business_dividend_paperwork_preview" }, "declaration": { "$ref": "#/components/schemas/BusinessDividendDeclaration" }, "board_minutes": { "type": "object", "additionalProperties": true }, "vouchers": { "type": "object", "additionalProperties": true } } }, "meta": { "type": "object", "additionalProperties": true } } }, "BusinessDividendDeclarationLinesCreateRequest": { "type": "object", "additionalProperties": false, "required": [ "lines" ], "properties": { "lines": { "type": "array", "minItems": 1, "maxItems": 50, "items": { "type": "object", "additionalProperties": false, "required": [ "share_class_id", "dividend_per_share", "shares_on_record_date" ], "properties": { "share_class_id": { "type": "string", "format": "uuid" }, "dividend_per_share": { "type": "number", "exclusiveMinimum": 0 }, "shares_on_record_date": { "type": "integer", "minimum": 1 } } } } } }, "BusinessDividendDeclarationLine": { "type": "object", "additionalProperties": false, "required": [ "object", "id", "company_id", "declaration_id", "share_class_id", "dividend_per_share", "shares_on_record_date", "gross_amount", "is_archived", "archived_at", "archive_reason", "created_at", "updated_at" ], "properties": { "object": { "type": "string", "const": "business_dividend_declaration_line" }, "id": { "type": "string", "format": "uuid" }, "company_id": { "type": "string", "format": "uuid" }, "declaration_id": { "type": "string", "format": "uuid" }, "share_class_id": { "type": "string", "format": "uuid" }, "dividend_per_share": { "type": [ "number", "null" ] }, "shares_on_record_date": { "type": [ "integer", "null" ] }, "gross_amount": { "type": [ "number", "null" ] }, "is_archived": { "type": "boolean" }, "archived_at": { "type": [ "string", "null" ], "format": "date-time" }, "archive_reason": { "type": [ "string", "null" ] }, "created_at": { "type": [ "string", "null" ], "format": "date-time" }, "updated_at": { "type": [ "string", "null" ], "format": "date-time" } } }, "V1BusinessDividendDeclarationLineListMeta": { "type": "object", "additionalProperties": false, "required": [ "api_version", "mode", "resource", "request_id", "pagination" ], "properties": { "api_version": { "type": "string", "enum": [ "v1-2026-07" ] }, "mode": { "type": "string", "enum": [ "list" ] }, "resource": { "type": "string", "enum": [ "business_dividend_declaration_line" ] }, "request_id": { "type": "string" }, "pagination": { "$ref": "#/components/schemas/V1PaginationMeta" } } }, "V1BusinessDividendDeclarationLineListResponse": { "type": "object", "additionalProperties": false, "required": [ "data", "meta" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/BusinessDividendDeclarationLine" } }, "meta": { "$ref": "#/components/schemas/V1BusinessDividendDeclarationLineListMeta" } } }, "V1BusinessDividendDeclarationLineDetailMeta": { "type": "object", "additionalProperties": false, "required": [ "api_version", "mode", "resource", "request_id" ], "properties": { "api_version": { "type": "string", "enum": [ "v1-2026-07" ] }, "mode": { "type": "string", "enum": [ "detail" ] }, "resource": { "type": "string", "enum": [ "business_dividend_declaration_line" ] }, "request_id": { "type": "string" } } }, "V1BusinessDividendDeclarationLineDetailResponse": { "type": "object", "additionalProperties": false, "required": [ "data", "meta" ], "properties": { "data": { "$ref": "#/components/schemas/BusinessDividendDeclarationLine" }, "meta": { "$ref": "#/components/schemas/V1BusinessDividendDeclarationLineDetailMeta" } } }, "BusinessDividendAllocation": { "type": "object", "additionalProperties": false, "required": [ "object", "id", "company_id", "declaration_id", "declaration_line_id", "shareholder_id", "share_class_id", "shares_held", "allocation_ratio", "gross_amount", "is_forecast", "is_archived", "archived_at", "archive_reason", "created_at", "updated_at" ], "properties": { "object": { "type": "string", "const": "business_dividend_allocation" }, "id": { "type": "string", "format": "uuid" }, "company_id": { "type": "string", "format": "uuid" }, "declaration_id": { "type": "string", "format": "uuid" }, "declaration_line_id": { "type": "string", "format": "uuid" }, "shareholder_id": { "type": "string", "format": "uuid" }, "share_class_id": { "type": "string", "format": "uuid" }, "shares_held": { "type": [ "integer", "null" ] }, "allocation_ratio": { "type": [ "number", "null" ] }, "gross_amount": { "type": [ "number", "null" ] }, "is_forecast": { "type": "boolean" }, "is_archived": { "type": "boolean" }, "archived_at": { "type": [ "string", "null" ], "format": "date-time" }, "archive_reason": { "type": [ "string", "null" ] }, "created_at": { "type": [ "string", "null" ], "format": "date-time" }, "updated_at": { "type": [ "string", "null" ], "format": "date-time" } } }, "V1BusinessDividendAllocationListMeta": { "type": "object", "additionalProperties": false, "required": [ "api_version", "mode", "resource", "request_id", "pagination" ], "properties": { "api_version": { "type": "string", "enum": [ "v1-2026-07" ] }, "mode": { "type": "string", "enum": [ "list" ] }, "resource": { "type": "string", "enum": [ "business_dividend_allocation" ] }, "request_id": { "type": "string" }, "pagination": { "$ref": "#/components/schemas/V1PaginationMeta" } } }, "V1BusinessDividendAllocationListResponse": { "type": "object", "additionalProperties": false, "required": [ "data", "meta" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/BusinessDividendAllocation" } }, "meta": { "$ref": "#/components/schemas/V1BusinessDividendAllocationListMeta" } } }, "V1BusinessDividendAllocationDetailMeta": { "type": "object", "additionalProperties": false, "required": [ "api_version", "mode", "resource", "request_id" ], "properties": { "api_version": { "type": "string", "enum": [ "v1-2026-07" ] }, "mode": { "type": "string", "enum": [ "detail" ] }, "resource": { "type": "string", "enum": [ "business_dividend_allocation" ] }, "request_id": { "type": "string" } } }, "V1BusinessDividendAllocationDetailResponse": { "type": "object", "additionalProperties": false, "required": [ "data", "meta" ], "properties": { "data": { "$ref": "#/components/schemas/BusinessDividendAllocation" }, "meta": { "$ref": "#/components/schemas/V1BusinessDividendAllocationDetailMeta" } } }, "BusinessFixedAssetClass": { "type": "object", "additionalProperties": false, "required": [ "object", "id", "company_id", "name" ], "properties": { "object": { "type": "string", "const": "business_fixed_asset_class" }, "id": { "type": "string", "format": "uuid" }, "company_id": { "type": "string", "format": "uuid" }, "name": { "type": "string", "nullable": true }, "asset_type": { "type": "string", "nullable": true }, "coa_category_id": { "type": "string", "format": "uuid", "nullable": true }, "code_prefix": { "type": "string", "nullable": true }, "asset_code": { "type": "string", "nullable": true }, "accumulated_depreciation_code": { "type": "string", "nullable": true }, "depreciation_expense_code": { "type": "string", "nullable": true }, "description": { "type": "string", "nullable": true }, "default_depreciation_method": { "type": "string", "nullable": true }, "default_useful_life_months": { "type": "number", "nullable": true }, "default_residual_value": { "type": "number", "nullable": true }, "is_active": { "type": "boolean", "nullable": true }, "created_at": { "type": "string", "format": "date-time", "nullable": true }, "updated_at": { "type": "string", "format": "date-time", "nullable": true }, "asset_account_id": { "type": "string", "format": "uuid", "nullable": true }, "accumulated_depreciation_account_id": { "type": "string", "format": "uuid", "nullable": true }, "depreciation_expense_account_id": { "type": "string", "format": "uuid", "nullable": true } } }, "BusinessFixedAssetDepreciationSchedule": { "type": "object", "additionalProperties": false, "required": [ "object", "id", "fixed_asset_id", "period_date" ], "properties": { "object": { "type": "string", "const": "business_fixed_asset_depreciation_schedule" }, "id": { "type": "string", "format": "uuid", "nullable": true }, "fixed_asset_id": { "type": "string", "format": "uuid", "nullable": true }, "period_date": { "type": "string", "format": "date", "nullable": true }, "depreciation_amount": { "type": "number", "nullable": true }, "accumulated_depreciation": { "type": "number", "nullable": true }, "net_book_value": { "type": "number", "nullable": true }, "is_posted": { "type": "boolean", "nullable": true }, "journal_transaction_id": { "type": "string", "format": "uuid", "nullable": true }, "created_at": { "type": "string", "format": "date-time", "nullable": true } } }, "BusinessFixedAsset": { "type": "object", "additionalProperties": false, "required": [ "object", "id", "fixed_asset_id", "company_id", "asset_number", "status" ], "properties": { "object": { "type": "string", "const": "business_fixed_asset" }, "id": { "type": "string", "format": "uuid" }, "fixed_asset_id": { "type": "string", "format": "uuid" }, "company_id": { "type": "string", "format": "uuid" }, "asset_class_id": { "type": "string", "format": "uuid", "nullable": true }, "asset_class": { "anyOf": [ { "$ref": "#/components/schemas/BusinessFixedAssetClass" }, { "type": "null" } ] }, "asset_number": { "type": "string", "nullable": true }, "description": { "type": "string", "nullable": true }, "supplier_id": { "type": "string", "format": "uuid", "nullable": true }, "location": { "type": "string", "nullable": true }, "acquisition_date": { "type": "string", "format": "date", "nullable": true }, "acquisition_cost": { "type": "number", "nullable": true }, "residual_value": { "type": "number", "nullable": true }, "useful_life_months": { "type": "number", "nullable": true }, "depreciation_method": { "type": "string", "nullable": true }, "disposal_date": { "type": "string", "format": "date", "nullable": true }, "disposal_proceeds": { "type": "number", "nullable": true }, "disposal_gain_loss": { "type": "number", "nullable": true }, "is_disposed": { "type": "boolean", "nullable": true }, "status": { "type": "string", "nullable": true }, "notes": { "type": "string", "nullable": true }, "created_by_user_id": { "type": "string", "format": "uuid", "nullable": true }, "cost_center_id": { "type": "string", "format": "uuid", "nullable": true }, "fund_id": { "type": "string", "format": "uuid", "nullable": true }, "project_id": { "type": "string", "format": "uuid", "nullable": true }, "serial_number": { "type": "string", "nullable": true }, "current_accumulated_depreciation": { "type": "number", "nullable": true }, "current_net_book_value": { "type": "number", "nullable": true }, "latest_depreciation_schedule": { "anyOf": [ { "$ref": "#/components/schemas/BusinessFixedAssetDepreciationSchedule" }, { "type": "null" } ] }, "created_at": { "type": "string", "format": "date-time", "nullable": true }, "updated_at": { "type": "string", "format": "date-time", "nullable": true } }, "description": "Fixed asset register state with the latest saved depreciation schedule. It does not calculate or post depreciation on the fly." }, "V1BusinessFixedAssetListMeta": { "type": "object", "additionalProperties": false, "properties": { "api_version": { "type": "string" }, "mode": { "type": "string", "const": "list" }, "pagination": { "$ref": "#/components/schemas/V1Pagination" }, "request_id": { "type": "string" }, "resource": { "type": "string", "const": "business_fixed_asset" } } }, "V1BusinessFixedAssetDetailMeta": { "type": "object", "additionalProperties": false, "properties": { "api_version": { "type": "string" }, "mode": { "type": "string", "const": "detail" }, "request_id": { "type": "string" }, "resource": { "type": "string", "const": "business_fixed_asset" } } }, "BusinessFixedAssetListResponse": { "type": "object", "additionalProperties": false, "required": [ "data", "meta" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/BusinessFixedAsset" } }, "meta": { "$ref": "#/components/schemas/V1BusinessFixedAssetListMeta" } } }, "BusinessFixedAssetDetailResponse": { "type": "object", "additionalProperties": false, "required": [ "data", "meta" ], "properties": { "data": { "$ref": "#/components/schemas/BusinessFixedAsset" }, "meta": { "$ref": "#/components/schemas/V1BusinessFixedAssetDetailMeta" } } }, "BusinessPaymentLinkInvoice": { "type": "object", "additionalProperties": false, "required": [ "object", "id" ], "properties": { "object": { "type": "string", "const": "business_payment_link_invoice" }, "id": { "type": "string", "format": "uuid" }, "invoice_number": { "type": [ "string", "null" ] }, "customer_id": { "type": [ "string", "null" ], "format": "uuid" }, "status": { "type": [ "string", "null" ] }, "payment_status": { "type": [ "string", "null" ] }, "currency": { "type": [ "string", "null" ] }, "total_amount": { "type": [ "number", "null" ] }, "outstanding_balance": { "type": [ "number", "null" ] }, "due_date": { "type": [ "string", "null" ], "format": "date" } } }, "BusinessPaymentLink": { "type": "object", "additionalProperties": false, "required": [ "object", "id", "company_id", "invoice_id", "link_code", "payment_path", "is_active", "is_expired", "is_usable" ], "properties": { "object": { "type": "string", "const": "business_payment_link" }, "id": { "type": "string", "format": "uuid" }, "company_id": { "type": "string", "format": "uuid" }, "invoice_id": { "type": "string", "format": "uuid" }, "invoice": { "anyOf": [ { "$ref": "#/components/schemas/BusinessPaymentLinkInvoice" }, { "type": "null" } ] }, "link_code": { "type": [ "string", "null" ] }, "payment_path": { "type": [ "string", "null" ] }, "expires_at": { "type": [ "string", "null" ], "format": "date-time" }, "is_active": { "type": "boolean" }, "is_expired": { "type": "boolean" }, "is_usable": { "type": "boolean" }, "view_count": { "type": "number" }, "last_viewed_at": { "type": [ "string", "null" ], "format": "date-time" }, "require_email_verification": { "type": "boolean" }, "created_at": { "type": [ "string", "null" ], "format": "date-time" } } }, "V1BusinessPaymentLinkListMeta": { "type": "object", "additionalProperties": false, "properties": { "api_version": { "type": "string" }, "mode": { "type": "string", "const": "list" }, "pagination": { "$ref": "#/components/schemas/V1Pagination" }, "request_id": { "type": "string" }, "resource": { "type": "string", "const": "business_payment_link" } } }, "V1BusinessPaymentLinkDetailMeta": { "type": "object", "additionalProperties": false, "properties": { "api_version": { "type": "string" }, "mode": { "type": "string", "const": "detail" }, "request_id": { "type": "string" }, "resource": { "type": "string", "const": "business_payment_link" } } }, "BusinessPaymentLinkListResponse": { "type": "object", "additionalProperties": false, "required": [ "data", "meta" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/BusinessPaymentLink" } }, "meta": { "$ref": "#/components/schemas/V1BusinessPaymentLinkListMeta" } } }, "BusinessPaymentLinkDetailResponse": { "type": "object", "additionalProperties": false, "required": [ "data", "meta" ], "properties": { "data": { "$ref": "#/components/schemas/BusinessPaymentLink" }, "meta": { "$ref": "#/components/schemas/V1BusinessPaymentLinkDetailMeta" } } }, "BusinessCustomerPaymentCustomer": { "type": "object", "additionalProperties": false, "required": [ "object", "id" ], "properties": { "object": { "type": "string", "const": "business_customer_payment_customer" }, "id": { "type": "string", "format": "uuid" }, "name": { "type": [ "string", "null" ] } } }, "BusinessCustomerPaymentInvoice": { "type": "object", "additionalProperties": false, "required": [ "object", "id", "company_id" ], "properties": { "object": { "type": "string", "const": "business_customer_payment_invoice" }, "id": { "type": "string", "format": "uuid" }, "company_id": { "type": [ "string", "null" ], "format": "uuid" }, "invoice_number": { "type": [ "string", "null" ] }, "customer_id": { "type": [ "string", "null" ], "format": "uuid" }, "customer": { "anyOf": [ { "$ref": "#/components/schemas/BusinessCustomerPaymentCustomer" }, { "type": "null" } ] }, "status": { "type": [ "string", "null" ] }, "payment_status": { "type": [ "string", "null" ] }, "currency": { "type": [ "string", "null" ] }, "total_amount": { "type": [ "number", "null" ] }, "outstanding_balance": { "type": [ "number", "null" ] }, "due_date": { "type": [ "string", "null" ], "format": "date" } } }, "BusinessCustomerPaymentBankAccount": { "type": "object", "additionalProperties": false, "required": [ "object", "id" ], "properties": { "object": { "type": "string", "const": "business_customer_payment_bank_account" }, "id": { "type": "string", "format": "uuid" }, "account_name": { "type": [ "string", "null" ] }, "bank_name": { "type": [ "string", "null" ] } } }, "BusinessCustomerPaymentBankTransaction": { "type": "object", "additionalProperties": false, "required": [ "object", "id" ], "properties": { "object": { "type": "string", "const": "business_customer_payment_bank_transaction" }, "id": { "type": "string", "format": "uuid" }, "transaction_date": { "type": [ "string", "null" ], "format": "date" }, "description": { "type": [ "string", "null" ] }, "gross_amount": { "type": [ "number", "null" ] }, "currency": { "type": [ "string", "null" ] }, "reference": { "type": [ "string", "null" ] }, "reconciliation_status": { "type": [ "string", "null" ] }, "posting_status": { "type": [ "string", "null" ] } } }, "BusinessCustomerPaymentJournalTransaction": { "type": "object", "additionalProperties": false, "required": [ "object", "id" ], "properties": { "object": { "type": "string", "const": "business_customer_payment_journal_transaction" }, "id": { "type": "string", "format": "uuid" }, "transaction_date": { "type": [ "string", "null" ], "format": "date" }, "reference": { "type": [ "string", "null" ] }, "source_type": { "type": [ "string", "null" ] }, "status": { "type": [ "string", "null" ] } } }, "BusinessCustomerPayment": { "type": "object", "additionalProperties": false, "required": [ "object", "id", "invoice_id", "amount", "payment_date", "is_archived" ], "properties": { "object": { "type": "string", "const": "business_customer_payment" }, "id": { "type": "string", "format": "uuid" }, "company_id": { "type": [ "string", "null" ], "format": "uuid" }, "invoice_id": { "type": "string", "format": "uuid" }, "invoice": { "anyOf": [ { "$ref": "#/components/schemas/BusinessCustomerPaymentInvoice" }, { "type": "null" } ] }, "amount": { "type": [ "number", "null" ] }, "payment_date": { "type": [ "string", "null" ], "format": "date" }, "reference": { "type": [ "string", "null" ] }, "bank_account_id": { "type": [ "string", "null" ], "format": "uuid" }, "bank_account": { "anyOf": [ { "$ref": "#/components/schemas/BusinessCustomerPaymentBankAccount" }, { "type": "null" } ] }, "bank_transaction_id": { "type": [ "string", "null" ], "format": "uuid" }, "bank_transaction": { "anyOf": [ { "$ref": "#/components/schemas/BusinessCustomerPaymentBankTransaction" }, { "type": "null" } ] }, "journal_transaction_id": { "type": [ "string", "null" ], "format": "uuid" }, "journal_transaction": { "anyOf": [ { "$ref": "#/components/schemas/BusinessCustomerPaymentJournalTransaction" }, { "type": "null" } ] }, "original_currency": { "type": [ "string", "null" ] }, "original_amount": { "type": [ "number", "null" ] }, "exchange_rate": { "type": [ "number", "null" ] }, "gbp_amount": { "type": [ "number", "null" ] }, "is_archived": { "type": "boolean" }, "archived_at": { "type": [ "string", "null" ], "format": "date-time" }, "archive_reason": { "type": [ "string", "null" ] }, "created_at": { "type": [ "string", "null" ], "format": "date-time" } } }, "V1BusinessCustomerPaymentListMeta": { "type": "object", "additionalProperties": false, "properties": { "api_version": { "type": "string" }, "mode": { "type": "string", "const": "list" }, "pagination": { "$ref": "#/components/schemas/V1Pagination" }, "request_id": { "type": "string" }, "resource": { "type": "string", "const": "business_customer_payment" } } }, "V1BusinessCustomerPaymentDetailMeta": { "type": "object", "additionalProperties": false, "properties": { "api_version": { "type": "string" }, "mode": { "type": "string", "const": "detail" }, "request_id": { "type": "string" }, "resource": { "type": "string", "const": "business_customer_payment" } } }, "BusinessCustomerPaymentListResponse": { "type": "object", "additionalProperties": false, "required": [ "data", "meta" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/BusinessCustomerPayment" } }, "meta": { "$ref": "#/components/schemas/V1BusinessCustomerPaymentListMeta" } } }, "BusinessCustomerPaymentDetailResponse": { "type": "object", "additionalProperties": false, "required": [ "data", "meta" ], "properties": { "data": { "$ref": "#/components/schemas/BusinessCustomerPayment" }, "meta": { "$ref": "#/components/schemas/V1BusinessCustomerPaymentDetailMeta" } } }, "BusinessSupplierPaymentSupplier": { "type": "object", "additionalProperties": false, "required": [ "object", "id" ], "properties": { "object": { "type": "string", "const": "business_supplier_payment_supplier" }, "id": { "type": "string", "format": "uuid" }, "name": { "type": [ "string", "null" ] } } }, "BusinessSupplierPaymentPurchaseInvoice": { "type": "object", "additionalProperties": false, "required": [ "object", "id", "company_id" ], "properties": { "object": { "type": "string", "const": "business_supplier_payment_purchase_invoice" }, "id": { "type": "string", "format": "uuid" }, "company_id": { "type": [ "string", "null" ], "format": "uuid" }, "supplier_invoice_number": { "type": [ "string", "null" ] }, "internal_reference": { "type": [ "string", "null" ] }, "supplier_id": { "type": [ "string", "null" ], "format": "uuid" }, "supplier": { "anyOf": [ { "$ref": "#/components/schemas/BusinessSupplierPaymentSupplier" }, { "type": "null" } ] }, "invoice_date": { "type": [ "string", "null" ], "format": "date" }, "due_date": { "type": [ "string", "null" ], "format": "date" }, "status": { "type": [ "string", "null" ] }, "payment_status": { "type": [ "string", "null" ] }, "currency": { "type": [ "string", "null" ] }, "total_amount": { "type": [ "number", "null" ] } } }, "BusinessSupplierPaymentBankAccount": { "type": "object", "additionalProperties": false, "required": [ "object", "id" ], "properties": { "object": { "type": "string", "const": "business_supplier_payment_bank_account" }, "id": { "type": "string", "format": "uuid" }, "account_name": { "type": [ "string", "null" ] }, "bank_name": { "type": [ "string", "null" ] } } }, "BusinessSupplierPaymentBankTransaction": { "type": "object", "additionalProperties": false, "required": [ "object", "id" ], "properties": { "object": { "type": "string", "const": "business_supplier_payment_bank_transaction" }, "id": { "type": "string", "format": "uuid" }, "transaction_date": { "type": [ "string", "null" ], "format": "date" }, "description": { "type": [ "string", "null" ] }, "gross_amount": { "type": [ "number", "null" ] }, "currency": { "type": [ "string", "null" ] }, "reference": { "type": [ "string", "null" ] }, "reconciliation_status": { "type": [ "string", "null" ] }, "posting_status": { "type": [ "string", "null" ] } } }, "BusinessSupplierPaymentJournalTransaction": { "type": "object", "additionalProperties": false, "required": [ "object", "id" ], "properties": { "object": { "type": "string", "const": "business_supplier_payment_journal_transaction" }, "id": { "type": "string", "format": "uuid" }, "transaction_date": { "type": [ "string", "null" ], "format": "date" }, "reference": { "type": [ "string", "null" ] }, "source_type": { "type": [ "string", "null" ] }, "status": { "type": [ "string", "null" ] } } }, "BusinessSupplierPayment": { "type": "object", "additionalProperties": false, "required": [ "object", "id", "purchase_invoice_id", "amount", "payment_date", "is_archived" ], "properties": { "object": { "type": "string", "const": "business_supplier_payment" }, "id": { "type": "string", "format": "uuid" }, "company_id": { "type": [ "string", "null" ], "format": "uuid" }, "purchase_invoice_id": { "type": "string", "format": "uuid" }, "purchase_invoice": { "anyOf": [ { "$ref": "#/components/schemas/BusinessSupplierPaymentPurchaseInvoice" }, { "type": "null" } ] }, "amount": { "type": [ "number", "null" ] }, "payment_date": { "type": [ "string", "null" ], "format": "date" }, "payment_method": { "type": [ "string", "null" ] }, "reference": { "type": [ "string", "null" ] }, "status": { "type": [ "string", "null" ] }, "bank_account_id": { "type": [ "string", "null" ], "format": "uuid" }, "bank_account": { "anyOf": [ { "$ref": "#/components/schemas/BusinessSupplierPaymentBankAccount" }, { "type": "null" } ] }, "bank_transaction_id": { "type": [ "string", "null" ], "format": "uuid" }, "bank_transaction": { "anyOf": [ { "$ref": "#/components/schemas/BusinessSupplierPaymentBankTransaction" }, { "type": "null" } ] }, "journal_transaction_id": { "type": [ "string", "null" ], "format": "uuid" }, "journal_transaction": { "anyOf": [ { "$ref": "#/components/schemas/BusinessSupplierPaymentJournalTransaction" }, { "type": "null" } ] }, "payment_batch_id": { "type": [ "string", "null" ], "format": "uuid" }, "original_currency": { "type": [ "string", "null" ] }, "original_amount": { "type": [ "number", "null" ] }, "exchange_rate": { "type": [ "number", "null" ] }, "gbp_amount": { "type": [ "number", "null" ] }, "is_archived": { "type": "boolean" }, "archived_at": { "type": [ "string", "null" ], "format": "date-time" }, "archive_reason": { "type": [ "string", "null" ] }, "created_at": { "type": [ "string", "null" ], "format": "date-time" } } }, "V1BusinessSupplierPaymentListMeta": { "type": "object", "additionalProperties": false, "properties": { "api_version": { "type": "string" }, "mode": { "type": "string", "const": "list" }, "pagination": { "$ref": "#/components/schemas/V1Pagination" }, "request_id": { "type": "string" }, "resource": { "type": "string", "const": "business_supplier_payment" } } }, "V1BusinessSupplierPaymentDetailMeta": { "type": "object", "additionalProperties": false, "properties": { "api_version": { "type": "string" }, "mode": { "type": "string", "const": "detail" }, "request_id": { "type": "string" }, "resource": { "type": "string", "const": "business_supplier_payment" } } }, "BusinessSupplierPaymentListResponse": { "type": "object", "additionalProperties": false, "required": [ "data", "meta" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/BusinessSupplierPayment" } }, "meta": { "$ref": "#/components/schemas/V1BusinessSupplierPaymentListMeta" } } }, "BusinessSupplierPaymentDetailResponse": { "type": "object", "additionalProperties": false, "required": [ "data", "meta" ], "properties": { "data": { "$ref": "#/components/schemas/BusinessSupplierPayment" }, "meta": { "$ref": "#/components/schemas/V1BusinessSupplierPaymentDetailMeta" } } }, "BusinessPayrollPayItem": { "type": "object", "additionalProperties": false, "required": [ "object", "id", "name" ], "properties": { "object": { "type": "string", "const": "business_payroll_pay_item" }, "id": { "type": "string", "format": "uuid" }, "company_id": { "type": [ "string", "null" ], "format": "uuid" }, "code": { "type": [ "string", "null" ] }, "name": { "type": [ "string", "null" ] }, "description": { "type": [ "string", "null" ] }, "calculation_method": { "type": [ "string", "null" ] }, "default_amount": { "type": [ "number", "null" ] }, "taxable": { "type": [ "boolean", "null" ] }, "niable": { "type": [ "boolean", "null" ] }, "pensionable": { "type": [ "boolean", "null" ] }, "is_active": { "type": [ "boolean", "null" ] }, "created_at": { "type": [ "string", "null" ], "format": "date-time" }, "updated_at": { "type": [ "string", "null" ], "format": "date-time" } } }, "V1BusinessPayrollPayItemListMeta": { "type": "object", "additionalProperties": false, "properties": { "api_version": { "type": "string" }, "mode": { "type": "string", "const": "list" }, "pagination": { "$ref": "#/components/schemas/V1Pagination" }, "request_id": { "type": "string" }, "resource": { "type": "string", "const": "business_payroll_pay_item" } } }, "V1BusinessPayrollPayItemDetailMeta": { "type": "object", "additionalProperties": false, "properties": { "api_version": { "type": "string" }, "mode": { "type": "string", "const": "detail" }, "request_id": { "type": "string" }, "resource": { "type": "string", "const": "business_payroll_pay_item" } } }, "BusinessPayrollPayItemListResponse": { "type": "object", "additionalProperties": false, "required": [ "data", "meta" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/BusinessPayrollPayItem" } }, "meta": { "$ref": "#/components/schemas/V1BusinessPayrollPayItemListMeta" } } }, "BusinessPayrollPayItemDetailResponse": { "type": "object", "additionalProperties": false, "required": [ "data", "meta" ], "properties": { "data": { "$ref": "#/components/schemas/BusinessPayrollPayItem" }, "meta": { "$ref": "#/components/schemas/V1BusinessPayrollPayItemDetailMeta" } } }, "BusinessPayrollDeductionItem": { "type": "object", "additionalProperties": false, "required": [ "object", "id", "name" ], "properties": { "object": { "type": "string", "const": "business_payroll_deduction_item" }, "id": { "type": "string", "format": "uuid" }, "company_id": { "type": [ "string", "null" ], "format": "uuid" }, "code": { "type": [ "string", "null" ] }, "name": { "type": [ "string", "null" ] }, "description": { "type": [ "string", "null" ] }, "deduction_type": { "type": [ "string", "null" ] }, "calculation_method": { "type": [ "string", "null" ] }, "default_amount": { "type": [ "number", "null" ] }, "is_active": { "type": [ "boolean", "null" ] }, "created_at": { "type": [ "string", "null" ], "format": "date-time" }, "updated_at": { "type": [ "string", "null" ], "format": "date-time" } } }, "V1BusinessPayrollDeductionItemListMeta": { "type": "object", "additionalProperties": false, "properties": { "api_version": { "type": "string" }, "mode": { "type": "string", "const": "list" }, "pagination": { "$ref": "#/components/schemas/V1Pagination" }, "request_id": { "type": "string" }, "resource": { "type": "string", "const": "business_payroll_deduction_item" } } }, "V1BusinessPayrollDeductionItemDetailMeta": { "type": "object", "additionalProperties": false, "properties": { "api_version": { "type": "string" }, "mode": { "type": "string", "const": "detail" }, "request_id": { "type": "string" }, "resource": { "type": "string", "const": "business_payroll_deduction_item" } } }, "BusinessPayrollDeductionItemListResponse": { "type": "object", "additionalProperties": false, "required": [ "data", "meta" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/BusinessPayrollDeductionItem" } }, "meta": { "$ref": "#/components/schemas/V1BusinessPayrollDeductionItemListMeta" } } }, "BusinessPayrollDeductionItemDetailResponse": { "type": "object", "additionalProperties": false, "required": [ "data", "meta" ], "properties": { "data": { "$ref": "#/components/schemas/BusinessPayrollDeductionItem" }, "meta": { "$ref": "#/components/schemas/V1BusinessPayrollDeductionItemDetailMeta" } } }, "BusinessPayrollPensionScheme": { "type": "object", "additionalProperties": false, "required": [ "object", "id", "company_id", "provider", "scheme_name", "employer_reference", "submission_method", "status", "relief_method", "contribution_basis", "employee_rate", "employer_rate", "employee_fixed_amount", "employer_fixed_amount", "enforce_ae_minimum", "created_at", "updated_at" ], "properties": { "object": { "type": "string", "const": "business_payroll_pension_scheme" }, "id": { "type": "string", "format": "uuid" }, "company_id": { "type": "string", "format": "uuid" }, "provider": { "type": "string", "enum": [ "nest" ] }, "scheme_name": { "type": "string" }, "employer_reference": { "type": [ "string", "null" ] }, "submission_method": { "type": "string", "enum": [ "api", "sftp", "file_upload" ] }, "status": { "type": "string", "enum": [ "active", "inactive" ] }, "relief_method": { "type": "string", "enum": [ "relief_at_source", "net_pay", "salary_sacrifice" ] }, "contribution_basis": { "type": "string", "enum": [ "qualifying_earnings", "basic_pay", "total_pay", "tier1", "tier2", "tier3" ] }, "employee_rate": { "type": [ "number", "null" ] }, "employer_rate": { "type": [ "number", "null" ] }, "employee_fixed_amount": { "type": [ "number", "null" ] }, "employer_fixed_amount": { "type": [ "number", "null" ] }, "enforce_ae_minimum": { "type": [ "boolean", "null" ] }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" } } }, "V1BusinessPayrollPensionSchemeListMeta": { "type": "object", "additionalProperties": false, "required": [ "api_version", "mode", "pagination", "request_id", "resource" ], "properties": { "api_version": { "type": "string", "const": "v1" }, "mode": { "type": "string", "const": "list" }, "pagination": { "$ref": "#/components/schemas/V1Pagination" }, "request_id": { "type": "string" }, "resource": { "type": "string", "const": "business_payroll_pension_scheme" } } }, "V1BusinessPayrollPensionSchemeDetailMeta": { "type": "object", "additionalProperties": false, "required": [ "api_version", "mode", "request_id", "resource" ], "properties": { "api_version": { "type": "string", "const": "v1" }, "mode": { "type": "string", "const": "detail" }, "request_id": { "type": "string" }, "resource": { "type": "string", "const": "business_payroll_pension_scheme" } } }, "BusinessPayrollPensionSchemeListResponse": { "type": "object", "additionalProperties": false, "required": [ "data", "meta" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/BusinessPayrollPensionScheme" } }, "meta": { "$ref": "#/components/schemas/V1BusinessPayrollPensionSchemeListMeta" } } }, "BusinessPayrollPensionSchemeDetailResponse": { "type": "object", "additionalProperties": false, "required": [ "data", "meta" ], "properties": { "data": { "$ref": "#/components/schemas/BusinessPayrollPensionScheme" }, "meta": { "$ref": "#/components/schemas/V1BusinessPayrollPensionSchemeDetailMeta" } } }, "V1BusinessPayrollSubmissionRequestCreate": { "type": "object", "additionalProperties": false, "required": ["submission_channel", "submission_type", "submission_environment"], "properties": { "submission_channel": {"type": "string", "enum": ["hmrc_rti", "nest"]}, "submission_type": {"type": "string", "enum": ["fps", "contribution_schedule"]}, "submission_environment": {"type": "string", "enum": ["sandbox", "production"]} } }, "V1BusinessPayrollEpsSubmissionRequestCreate": { "type": "object", "additionalProperties": false, "required": ["submission_environment"], "properties": { "submission_environment": {"type": "string", "enum": ["sandbox", "production"]} } }, "BusinessPayrollSubmissionRequest": { "type": "object", "additionalProperties": false, "required": ["object", "id", "payroll_run_id", "submission_id", "submission_channel", "submission_type", "submission_environment", "status", "approval_url", "created_at", "expires_at", "completed_at", "failure_code", "provider_reference", "updated_at"], "properties": { "object": {"type": "string", "const": "business_payroll_submission_request"}, "id": {"type": "string", "format": "uuid"}, "payroll_run_id": {"type": "string", "format": "uuid"}, "submission_id": {"type": ["string", "null"], "format": "uuid"}, "submission_channel": {"type": "string", "enum": ["hmrc_rti", "nest"]}, "submission_type": {"type": "string", "enum": ["fps", "contribution_schedule"]}, "submission_environment": {"type": "string", "enum": ["sandbox", "production"]}, "status": {"type": "string", "enum": ["pending", "consumed", "submitted", "failed", "expired"]}, "approval_url": {"type": ["string", "null"], "format": "uri"}, "created_at": {"type": "string", "format": "date-time"}, "expires_at": {"type": "string", "format": "date-time"}, "completed_at": {"type": ["string", "null"], "format": "date-time"}, "failure_code": {"type": ["string", "null"]}, "provider_reference": {"type": ["string", "null"]}, "updated_at": {"type": "string", "format": "date-time"} } }, "V1BusinessPayrollSubmissionRequestResponse": { "type": "object", "additionalProperties": false, "required": ["data", "meta"], "properties": { "data": {"$ref": "#/components/schemas/BusinessPayrollSubmissionRequest"}, "meta": {"$ref": "#/components/schemas/V1Meta"} } }, "BusinessPayrollSubmission": { "type": "object", "additionalProperties": false, "required": [ "object", "id", "company_id", "payroll_run_id", "submission_channel", "submission_type", "submission_environment", "status", "correlation_id", "external_reference", "submitted_at", "responded_at", "error_code", "error_message", "attempt_count", "last_attempt_at", "next_retry_at", "created_at", "updated_at" ], "properties": { "object": { "type": "string", "const": "business_payroll_submission" }, "id": { "type": "string", "format": "uuid" }, "company_id": { "type": "string", "format": "uuid" }, "payroll_run_id": { "type": [ "string", "null" ], "format": "uuid" }, "submission_channel": { "type": "string", "enum": [ "hmrc_rti", "nest" ] }, "submission_type": { "type": "string" }, "submission_environment": { "type": "string", "enum": [ "sandbox", "production" ] }, "status": { "type": "string", "enum": [ "queued", "submitted", "accepted", "rejected", "retrying", "cancelled" ] }, "correlation_id": { "type": [ "string", "null" ] }, "external_reference": { "type": [ "string", "null" ] }, "submitted_at": { "type": [ "string", "null" ], "format": "date-time" }, "responded_at": { "type": [ "string", "null" ], "format": "date-time" }, "error_code": { "type": [ "string", "null" ] }, "error_message": { "type": [ "string", "null" ] }, "attempt_count": { "type": [ "number", "null" ] }, "last_attempt_at": { "type": [ "string", "null" ], "format": "date-time" }, "next_retry_at": { "type": [ "string", "null" ], "format": "date-time" }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" } } }, "V1BusinessPayrollSubmissionListMeta": { "type": "object", "additionalProperties": false, "required": [ "api_version", "mode", "pagination", "request_id", "resource" ], "properties": { "api_version": { "type": "string", "const": "v1" }, "mode": { "type": "string", "const": "list" }, "pagination": { "$ref": "#/components/schemas/V1Pagination" }, "request_id": { "type": "string" }, "resource": { "type": "string", "const": "business_payroll_submission" } } }, "V1BusinessPayrollSubmissionDetailMeta": { "type": "object", "additionalProperties": false, "required": [ "api_version", "mode", "request_id", "resource" ], "properties": { "api_version": { "type": "string", "const": "v1" }, "mode": { "type": "string", "const": "detail" }, "request_id": { "type": "string" }, "resource": { "type": "string", "const": "business_payroll_submission" } } }, "BusinessPayrollSubmissionListResponse": { "type": "object", "additionalProperties": false, "required": [ "data", "meta" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/BusinessPayrollSubmission" } }, "meta": { "$ref": "#/components/schemas/V1BusinessPayrollSubmissionListMeta" } } }, "BusinessPayrollSubmissionDetailResponse": { "type": "object", "additionalProperties": false, "required": [ "data", "meta" ], "properties": { "data": { "$ref": "#/components/schemas/BusinessPayrollSubmission" }, "meta": { "$ref": "#/components/schemas/V1BusinessPayrollSubmissionDetailMeta" } } }, "BusinessP11DBenefit": { "type": "object", "additionalProperties": false, "required": [ "object", "id", "company_id", "employee_id", "tax_year", "benefit_type", "description", "cash_equivalent", "amount_made_good", "taxable_value", "class_1a_nic", "status", "created_at", "updated_at" ], "properties": { "object": { "type": "string", "const": "business_p11d_benefit" }, "id": { "type": "string", "format": "uuid" }, "company_id": { "type": "string", "format": "uuid" }, "employee_id": { "type": "string", "format": "uuid" }, "tax_year": { "type": "string", "pattern": "^\\d{4}/\\d{2}$" }, "benefit_type": { "type": "string" }, "description": { "type": [ "string", "null" ] }, "cash_equivalent": { "type": "number" }, "amount_made_good": { "type": "number" }, "taxable_value": { "type": "number" }, "class_1a_nic": { "type": "number" }, "status": { "type": "string", "enum": [ "draft", "reviewed", "excluded" ] }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" } } }, "V1BusinessP11DBenefitListMeta": { "type": "object", "additionalProperties": false, "required": [ "api_version", "mode", "pagination", "request_id", "resource" ], "properties": { "api_version": { "type": "string", "const": "v1" }, "mode": { "type": "string", "const": "list" }, "pagination": { "$ref": "#/components/schemas/V1Pagination" }, "request_id": { "type": "string" }, "resource": { "type": "string", "const": "business_p11d_benefit" } } }, "V1BusinessP11DBenefitDetailMeta": { "type": "object", "additionalProperties": false, "required": [ "api_version", "mode", "request_id", "resource" ], "properties": { "api_version": { "type": "string", "const": "v1" }, "mode": { "type": "string", "const": "detail" }, "request_id": { "type": "string" }, "resource": { "type": "string", "const": "business_p11d_benefit" } } }, "BusinessP11DBenefitListResponse": { "type": "object", "additionalProperties": false, "required": [ "data", "meta" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/BusinessP11DBenefit" } }, "meta": { "$ref": "#/components/schemas/V1BusinessP11DBenefitListMeta" } } }, "BusinessP11DBenefitDetailResponse": { "type": "object", "additionalProperties": false, "required": [ "data", "meta" ], "properties": { "data": { "$ref": "#/components/schemas/BusinessP11DBenefit" }, "meta": { "$ref": "#/components/schemas/V1BusinessP11DBenefitDetailMeta" } } }, "BusinessCISSubcontractor": { "type": "object", "additionalProperties": false, "required": [ "object", "id", "company_id", "supplier_id", "verification_status", "verified_at", "created_at", "updated_at" ], "properties": { "object": { "type": "string", "const": "business_cis_subcontractor" }, "id": { "type": "string", "format": "uuid" }, "company_id": { "type": "string", "format": "uuid" }, "supplier_id": { "type": "string", "format": "uuid" }, "verification_status": { "type": "string", "enum": [ "gross", "registered", "unregistered" ] }, "verified_at": { "type": [ "string", "null" ], "format": "date-time" }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" } } }, "V1BusinessCISSubcontractorListMeta": { "type": "object", "additionalProperties": false, "required": [ "api_version", "mode", "pagination", "request_id", "resource" ], "properties": { "api_version": { "type": "string", "const": "v1" }, "mode": { "type": "string", "const": "list" }, "pagination": { "$ref": "#/components/schemas/V1Pagination" }, "request_id": { "type": "string" }, "resource": { "type": "string", "const": "business_cis_subcontractor" } } }, "V1BusinessCISSubcontractorDetailMeta": { "type": "object", "additionalProperties": false, "required": [ "api_version", "mode", "request_id", "resource" ], "properties": { "api_version": { "type": "string", "const": "v1" }, "mode": { "type": "string", "const": "detail" }, "request_id": { "type": "string" }, "resource": { "type": "string", "const": "business_cis_subcontractor" } } }, "BusinessCISSubcontractorListResponse": { "type": "object", "additionalProperties": false, "required": [ "data", "meta" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/BusinessCISSubcontractor" } }, "meta": { "$ref": "#/components/schemas/V1BusinessCISSubcontractorListMeta" } } }, "BusinessCISSubcontractorDetailResponse": { "type": "object", "additionalProperties": false, "required": [ "data", "meta" ], "properties": { "data": { "$ref": "#/components/schemas/BusinessCISSubcontractor" }, "meta": { "$ref": "#/components/schemas/V1BusinessCISSubcontractorDetailMeta" } } }, "BusinessCISDeduction": { "type": "object", "additionalProperties": false, "required": [ "object", "id", "company_id", "subcontractor_id", "supplier_id", "tax_month", "payment_date", "gross_amount", "materials_amount", "vat_amount", "deduction_rate", "deduction_amount", "net_payment", "status", "created_at", "updated_at" ], "properties": { "object": { "type": "string", "const": "business_cis_deduction" }, "id": { "type": "string", "format": "uuid" }, "company_id": { "type": "string", "format": "uuid" }, "subcontractor_id": { "type": "string", "format": "uuid" }, "supplier_id": { "type": "string", "format": "uuid" }, "tax_month": { "type": "string", "pattern": "^\\d{4}-(0[1-9]|1[0-2])$" }, "payment_date": { "type": "string", "format": "date" }, "gross_amount": { "type": "number" }, "materials_amount": { "type": "number" }, "vat_amount": { "type": "number" }, "deduction_rate": { "type": "number", "enum": [ 0, 20, 30 ] }, "deduction_amount": { "type": "number" }, "net_payment": { "type": "number" }, "status": { "type": "string", "enum": [ "draft", "reviewed", "submitted" ] }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" } } }, "V1BusinessCISDeductionListMeta": { "type": "object", "additionalProperties": false, "required": [ "api_version", "mode", "pagination", "request_id", "resource" ], "properties": { "api_version": { "type": "string", "const": "v1" }, "mode": { "type": "string", "const": "list" }, "pagination": { "$ref": "#/components/schemas/V1Pagination" }, "request_id": { "type": "string" }, "resource": { "type": "string", "const": "business_cis_deduction" } } }, "V1BusinessCISDeductionDetailMeta": { "type": "object", "additionalProperties": false, "required": [ "api_version", "mode", "request_id", "resource" ], "properties": { "api_version": { "type": "string", "const": "v1" }, "mode": { "type": "string", "const": "detail" }, "request_id": { "type": "string" }, "resource": { "type": "string", "const": "business_cis_deduction" } } }, "BusinessCISDeductionListResponse": { "type": "object", "additionalProperties": false, "required": [ "data", "meta" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/BusinessCISDeduction" } }, "meta": { "$ref": "#/components/schemas/V1BusinessCISDeductionListMeta" } } }, "BusinessCISDeductionDetailResponse": { "type": "object", "additionalProperties": false, "required": [ "data", "meta" ], "properties": { "data": { "$ref": "#/components/schemas/BusinessCISDeduction" }, "meta": { "$ref": "#/components/schemas/V1BusinessCISDeductionDetailMeta" } } }, "BusinessPayrollEmployee": { "type": "object", "additionalProperties": false, "required": [ "object", "id", "display_name" ], "properties": { "object": { "type": "string", "const": "business_payroll_employee" }, "id": { "type": "string", "format": "uuid" }, "company_id": { "type": [ "string", "null" ], "format": "uuid" }, "employee_code": { "type": [ "string", "null" ] }, "display_name": { "type": [ "string", "null" ] }, "employment_status": { "type": [ "string", "null" ] }, "pay_frequency": { "type": [ "string", "null" ] }, "start_date": { "type": [ "string", "null" ], "format": "date" }, "leave_date": { "type": [ "string", "null" ], "format": "date" }, "created_at": { "type": [ "string", "null" ], "format": "date-time" }, "updated_at": { "type": [ "string", "null" ], "format": "date-time" } } }, "V1BusinessPayrollEmployeeListMeta": { "type": "object", "additionalProperties": false, "properties": { "api_version": { "type": "string" }, "mode": { "type": "string", "const": "list" }, "pagination": { "$ref": "#/components/schemas/V1Pagination" }, "request_id": { "type": "string" }, "resource": { "type": "string", "const": "business_payroll_employee" } } }, "V1BusinessPayrollEmployeeDetailMeta": { "type": "object", "additionalProperties": false, "properties": { "api_version": { "type": "string" }, "mode": { "type": "string", "const": "detail" }, "request_id": { "type": "string" }, "resource": { "type": "string", "const": "business_payroll_employee" } } }, "BusinessPayrollEmployeeListResponse": { "type": "object", "additionalProperties": false, "required": [ "data", "meta" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/BusinessPayrollEmployee" } }, "meta": { "$ref": "#/components/schemas/V1BusinessPayrollEmployeeListMeta" } } }, "BusinessPayrollEmployeeDetailResponse": { "type": "object", "additionalProperties": false, "required": [ "data", "meta" ], "properties": { "data": { "$ref": "#/components/schemas/BusinessPayrollEmployee" }, "meta": { "$ref": "#/components/schemas/V1BusinessPayrollEmployeeDetailMeta" } } }, "BusinessPayrollRunTotals": { "type": "object", "additionalProperties": false, "properties": { "employee_count": { "type": [ "number", "null" ] }, "employer_ni": { "type": [ "number", "null" ] }, "employer_pension": { "type": [ "number", "null" ] }, "employment_allowance": { "type": [ "number", "null" ] }, "gross_wages": { "type": [ "number", "null" ] }, "net_wages": { "type": [ "number", "null" ] }, "ni_deducted": { "type": [ "number", "null" ] }, "paye_creditor": { "type": [ "number", "null" ] }, "paye_deducted": { "type": [ "number", "null" ] }, "pension_creditor": { "type": [ "number", "null" ] }, "pension_deducted": { "type": [ "number", "null" ] }, "student_loan_deducted": { "type": [ "number", "null" ] }, "total_credits": { "type": [ "number", "null" ] }, "total_debits": { "type": [ "number", "null" ] } } }, "BusinessPayrollRun": { "type": "object", "additionalProperties": false, "required": [ "object", "id", "status", "totals" ], "properties": { "object": { "type": "string", "const": "business_payroll_run" }, "id": { "type": "string", "format": "uuid" }, "company_id": { "type": [ "string", "null" ], "format": "uuid" }, "run_reference": { "type": [ "string", "null" ] }, "run_number": { "type": [ "number", "null" ] }, "period_start": { "type": [ "string", "null" ], "format": "date" }, "period_end": { "type": [ "string", "null" ], "format": "date" }, "pay_date": { "type": [ "string", "null" ], "format": "date" }, "status": { "type": [ "string", "null" ] }, "correction_of_run_id": { "type": [ "string", "null" ], "format": "uuid" }, "journal_transaction_id": { "type": [ "string", "null" ], "format": "uuid" }, "rti_submission_status": { "type": [ "string", "null" ] }, "pension_submission_status": { "type": [ "string", "null" ] }, "totals": { "$ref": "#/components/schemas/BusinessPayrollRunTotals" }, "approved_at": { "type": [ "string", "null" ], "format": "date-time" }, "finalised_at": { "type": [ "string", "null" ], "format": "date-time" }, "created_at": { "type": [ "string", "null" ], "format": "date-time" }, "updated_at": { "type": [ "string", "null" ], "format": "date-time" } } }, "V1BusinessPayrollRunListMeta": { "type": "object", "additionalProperties": false, "properties": { "api_version": { "type": "string" }, "mode": { "type": "string", "const": "list" }, "pagination": { "$ref": "#/components/schemas/V1Pagination" }, "request_id": { "type": "string" }, "resource": { "type": "string", "const": "business_payroll_run" } } }, "V1BusinessPayrollRunDetailMeta": { "type": "object", "additionalProperties": false, "properties": { "api_version": { "type": "string" }, "mode": { "type": "string", "const": "detail" }, "request_id": { "type": "string" }, "resource": { "type": "string", "const": "business_payroll_run" } } }, "BusinessPayrollRunListResponse": { "type": "object", "additionalProperties": false, "required": [ "data", "meta" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/BusinessPayrollRun" } }, "meta": { "$ref": "#/components/schemas/V1BusinessPayrollRunListMeta" } } }, "BusinessPayrollRunDetailResponse": { "type": "object", "additionalProperties": false, "required": [ "data", "meta" ], "properties": { "data": { "$ref": "#/components/schemas/BusinessPayrollRun" }, "meta": { "$ref": "#/components/schemas/V1BusinessPayrollRunDetailMeta" } } }, "BusinessPayrollPayableRun": { "type": "object", "additionalProperties": false, "required": [ "object", "id", "company_id" ], "properties": { "object": { "type": "string", "const": "business_payroll_payable_run" }, "id": { "type": "string", "format": "uuid" }, "company_id": { "type": [ "string", "null" ], "format": "uuid" }, "run_reference": { "type": [ "string", "null" ] }, "run_number": { "type": [ "number", "null" ] }, "period_start": { "type": [ "string", "null" ], "format": "date" }, "period_end": { "type": [ "string", "null" ], "format": "date" }, "pay_date": { "type": [ "string", "null" ], "format": "date" }, "status": { "type": [ "string", "null" ] }, "rti_submission_status": { "type": [ "string", "null" ] }, "pension_submission_status": { "type": [ "string", "null" ] }, "journal_transaction_id": { "type": [ "string", "null" ], "format": "uuid" } } }, "BusinessPayrollPayableEmployee": { "type": "object", "additionalProperties": false, "required": [ "object", "id" ], "properties": { "object": { "type": "string", "const": "business_payroll_payable_employee" }, "id": { "type": "string", "format": "uuid" }, "employee_code": { "type": [ "string", "null" ] }, "display_name": { "type": [ "string", "null" ] }, "employment_status": { "type": [ "string", "null" ] } } }, "BusinessPayrollPayable": { "type": "object", "additionalProperties": false, "required": [ "object", "id", "payroll_run_id", "payable_type", "amount", "status", "is_archived" ], "properties": { "object": { "type": "string", "const": "business_payroll_payable" }, "id": { "type": "string", "format": "uuid" }, "company_id": { "type": [ "string", "null" ], "format": "uuid" }, "payroll_run_id": { "type": "string", "format": "uuid" }, "payroll_run": { "anyOf": [ { "$ref": "#/components/schemas/BusinessPayrollPayableRun" }, { "type": "null" } ] }, "payable_type": { "type": [ "string", "null" ] }, "employee_id": { "type": [ "string", "null" ], "format": "uuid" }, "employee": { "anyOf": [ { "$ref": "#/components/schemas/BusinessPayrollPayableEmployee" }, { "type": "null" } ] }, "payee_name": { "type": [ "string", "null" ] }, "amount": { "type": [ "number", "null" ] }, "due_date": { "type": [ "string", "null" ], "format": "date" }, "control_account_id": { "type": [ "string", "null" ], "format": "uuid" }, "reference": { "type": [ "string", "null" ] }, "status": { "type": [ "string", "null" ] }, "paid_at": { "type": [ "string", "null" ], "format": "date-time" }, "paid_amount": { "type": [ "number", "null" ] }, "payment_method": { "type": [ "string", "null" ] }, "payment_bank_account_id": { "type": [ "string", "null" ], "format": "uuid" }, "payment_journal_transaction_id": { "type": [ "string", "null" ], "format": "uuid" }, "reversed_payment_journal_transaction_id": { "type": [ "string", "null" ], "format": "uuid" }, "payment_reversal_journal_transaction_id": { "type": [ "string", "null" ], "format": "uuid" }, "payment_reversed_at": { "type": [ "string", "null" ], "format": "date-time" }, "payment_reversal_reason": { "type": [ "string", "null" ] }, "is_archived": { "type": "boolean" }, "archived_at": { "type": [ "string", "null" ], "format": "date-time" }, "archive_reason": { "type": [ "string", "null" ] }, "created_at": { "type": [ "string", "null" ], "format": "date-time" }, "updated_at": { "type": [ "string", "null" ], "format": "date-time" } } }, "V1BusinessPayrollPayableListMeta": { "type": "object", "additionalProperties": false, "properties": { "api_version": { "type": "string" }, "mode": { "type": "string", "const": "list" }, "pagination": { "$ref": "#/components/schemas/V1Pagination" }, "request_id": { "type": "string" }, "resource": { "type": "string", "const": "business_payroll_payable" } } }, "V1BusinessPayrollPayableDetailMeta": { "type": "object", "additionalProperties": false, "properties": { "api_version": { "type": "string" }, "mode": { "type": "string", "const": "detail" }, "request_id": { "type": "string" }, "resource": { "type": "string", "const": "business_payroll_payable" } } }, "BusinessPayrollPayableListResponse": { "type": "object", "additionalProperties": false, "required": [ "data", "meta" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/BusinessPayrollPayable" } }, "meta": { "$ref": "#/components/schemas/V1BusinessPayrollPayableListMeta" } } }, "BusinessPayrollPayableDetailResponse": { "type": "object", "additionalProperties": false, "required": [ "data", "meta" ], "properties": { "data": { "$ref": "#/components/schemas/BusinessPayrollPayable" }, "meta": { "$ref": "#/components/schemas/V1BusinessPayrollPayableDetailMeta" } } }, "PersonalFinancialSummaryAccountCategory": { "type": "object", "additionalProperties": false, "required": [ "account_category", "available_balance_total", "balance_total", "count" ], "properties": { "account_category": { "type": "string" }, "available_balance_total": { "type": "number" }, "balance_total": { "type": "number" }, "count": { "type": "integer", "minimum": 0 } } }, "PersonalFinancialSummaryAccounts": { "type": "object", "additionalProperties": false, "required": [ "active_count", "available_balance_total", "balance_total", "by_category", "count" ], "properties": { "active_count": { "type": "integer", "minimum": 0 }, "available_balance_total": { "type": "number" }, "balance_total": { "type": "number" }, "by_category": { "type": "array", "items": { "$ref": "#/components/schemas/PersonalFinancialSummaryAccountCategory" } }, "count": { "type": "integer", "minimum": 0 } } }, "PersonalFinancialSummaryAssetType": { "type": "object", "additionalProperties": false, "required": [ "asset_type", "count", "value_total" ], "properties": { "asset_type": { "type": "string" }, "count": { "type": "integer", "minimum": 0 }, "value_total": { "type": "number" } } }, "PersonalFinancialSummaryAssets": { "type": "object", "additionalProperties": false, "required": [ "active_count", "by_type", "count", "value_total" ], "properties": { "active_count": { "type": "integer", "minimum": 0 }, "by_type": { "type": "array", "items": { "$ref": "#/components/schemas/PersonalFinancialSummaryAssetType" } }, "count": { "type": "integer", "minimum": 0 }, "value_total": { "type": "number" } } }, "PersonalFinancialSummaryLiabilityType": { "type": "object", "additionalProperties": false, "required": [ "balance_total", "count", "liability_type", "minimum_payment_total" ], "properties": { "balance_total": { "type": "number" }, "count": { "type": "integer", "minimum": 0 }, "liability_type": { "type": "string" }, "minimum_payment_total": { "type": "number" } } }, "PersonalFinancialSummaryLiabilities": { "type": "object", "additionalProperties": false, "required": [ "active_count", "balance_total", "by_type", "count", "minimum_payment_total" ], "properties": { "active_count": { "type": "integer", "minimum": 0 }, "balance_total": { "type": "number" }, "by_type": { "type": "array", "items": { "$ref": "#/components/schemas/PersonalFinancialSummaryLiabilityType" } }, "count": { "type": "integer", "minimum": 0 }, "minimum_payment_total": { "type": "number" } } }, "PersonalFinancialSummaryBudgetType": { "type": "object", "additionalProperties": false, "required": [ "budget_type", "budgeted_total", "count", "remaining_total", "spent_total" ], "properties": { "budget_type": { "type": "string" }, "budgeted_total": { "type": "number" }, "count": { "type": "integer", "minimum": 0 }, "remaining_total": { "type": "number" }, "spent_total": { "type": "number" } } }, "PersonalFinancialSummaryBudgets": { "type": "object", "additionalProperties": false, "required": [ "active_count", "budgeted_total", "by_type", "count", "over_budget_count", "remaining_total", "spent_total" ], "properties": { "active_count": { "type": "integer", "minimum": 0 }, "budgeted_total": { "type": "number" }, "by_type": { "type": "array", "items": { "$ref": "#/components/schemas/PersonalFinancialSummaryBudgetType" } }, "count": { "type": "integer", "minimum": 0 }, "over_budget_count": { "type": "integer", "minimum": 0 }, "remaining_total": { "type": "number" }, "spent_total": { "type": "number" } } }, "PersonalFinancialSummaryGoalType": { "type": "object", "additionalProperties": false, "required": [ "count", "current_total", "goal_type", "remaining_total", "target_total" ], "properties": { "count": { "type": "integer", "minimum": 0 }, "current_total": { "type": "number" }, "goal_type": { "type": "string" }, "remaining_total": { "type": "number" }, "target_total": { "type": "number" } } }, "PersonalFinancialSummaryGoals": { "type": "object", "additionalProperties": false, "required": [ "achieved_count", "active_count", "by_type", "count", "current_total", "remaining_total", "target_total" ], "properties": { "achieved_count": { "type": "integer", "minimum": 0 }, "active_count": { "type": "integer", "minimum": 0 }, "by_type": { "type": "array", "items": { "$ref": "#/components/schemas/PersonalFinancialSummaryGoalType" } }, "count": { "type": "integer", "minimum": 0 }, "current_total": { "type": "number" }, "remaining_total": { "type": "number" }, "target_total": { "type": "number" } } }, "PersonalFinancialSummaryCounts": { "type": "object", "additionalProperties": false, "required": [ "accounts", "active_accounts", "active_assets", "active_budgets", "active_goals", "active_liabilities", "achieved_goals", "assets", "budgets", "goals", "liabilities", "over_budget_budgets" ], "properties": { "accounts": { "type": "integer", "minimum": 0 }, "active_accounts": { "type": "integer", "minimum": 0 }, "active_assets": { "type": "integer", "minimum": 0 }, "active_budgets": { "type": "integer", "minimum": 0 }, "active_goals": { "type": "integer", "minimum": 0 }, "active_liabilities": { "type": "integer", "minimum": 0 }, "achieved_goals": { "type": "integer", "minimum": 0 }, "assets": { "type": "integer", "minimum": 0 }, "budgets": { "type": "integer", "minimum": 0 }, "goals": { "type": "integer", "minimum": 0 }, "liabilities": { "type": "integer", "minimum": 0 }, "over_budget_budgets": { "type": "integer", "minimum": 0 } } }, "PersonalFinancialSummaryTotals": { "type": "object", "additionalProperties": false, "required": [ "account_balance", "asset_value", "available_balance", "budget_remaining", "budget_spent", "budgeted_amount", "goal_current_amount", "goal_remaining_amount", "goal_target_amount", "liability_balance", "monthly_minimum_debt_payment", "net_worth" ], "properties": { "account_balance": { "type": "number" }, "asset_value": { "type": "number" }, "available_balance": { "type": "number" }, "budget_remaining": { "type": "number" }, "budget_spent": { "type": "number" }, "budgeted_amount": { "type": "number" }, "goal_current_amount": { "type": "number" }, "goal_remaining_amount": { "type": "number" }, "goal_target_amount": { "type": "number" }, "liability_balance": { "type": "number" }, "monthly_minimum_debt_payment": { "type": "number" }, "net_worth": { "type": "number" } } }, "PersonalFinancialSummary": { "type": "object", "additionalProperties": false, "required": [ "accounts", "api_version", "assets", "budgets", "counts", "currency", "generated_at", "goals", "liabilities", "freshness", "object", "report_type", "totals", "user_id" ], "properties": { "accounts": { "$ref": "#/components/schemas/PersonalFinancialSummaryAccounts" }, "api_version": { "type": "string", "const": "v1-2026-07" }, "assets": { "$ref": "#/components/schemas/PersonalFinancialSummaryAssets" }, "budgets": { "$ref": "#/components/schemas/PersonalFinancialSummaryBudgets" }, "counts": { "$ref": "#/components/schemas/PersonalFinancialSummaryCounts" }, "currency": { "type": "string", "minLength": 3, "maxLength": 5 }, "generated_at": { "type": "string", "format": "date-time" }, "goals": { "$ref": "#/components/schemas/PersonalFinancialSummaryGoals" }, "freshness": { "$ref": "#/components/schemas/PersonalFinancialSummaryFreshness" }, "liabilities": { "$ref": "#/components/schemas/PersonalFinancialSummaryLiabilities" }, "object": { "type": "string", "const": "personal_financial_summary" }, "report_type": { "type": "string", "const": "summary" }, "totals": { "$ref": "#/components/schemas/PersonalFinancialSummaryTotals" }, "user_id": { "type": "string", "format": "uuid" } } }, "PersonalFinancialSummaryFreshness": { "type": "object", "additionalProperties": false, "required": [ "latest_record_updated_at" ,"latest_transaction_date" ,"transaction_scope_included" ], "properties": { "latest_record_updated_at": { "type": [ "string", "null" ], "format": "date-time" }, "latest_transaction_date": { "type": [ "string", "null" ], "format": "date" }, "transaction_scope_included": { "type": "boolean" } } }, "PersonalFinancialSummaryMeta": { "type": "object", "additionalProperties": false, "required": [ "api_version", "mode", "request_id", "resource", "scopes" ], "properties": { "api_version": { "type": "string", "const": "v1-2026-07" }, "mode": { "type": "string", "const": "summary" }, "request_id": { "type": "string", "minLength": 1, "maxLength": 128 }, "resource": { "type": "string", "const": "personal_financial_summary" }, "scopes": { "type": "array", "minItems": 5, "maxItems": 5, "items": { "type": "string", "enum": [ "personal.accounts.read", "personal.assets.read", "personal.liabilities.read", "personal.budgets.read", "personal.goals.read" ] } } } }, "PersonalFinancialSummaryResponse": { "type": "object", "required": [ "data", "meta" ], "properties": { "data": { "$ref": "#/components/schemas/PersonalFinancialSummary" }, "meta": { "$ref": "#/components/schemas/PersonalFinancialSummaryMeta" } } }, "PersonalNetWorthTotals": { "type": "object", "additionalProperties": false, "required": [ "account_balance", "asset_value", "available_balance", "debt_to_asset_percent", "gross_assets", "liability_balance", "monthly_minimum_debt_payment", "net_worth" ], "properties": { "account_balance": { "type": "number" }, "asset_value": { "type": "number" }, "available_balance": { "type": "number" }, "debt_to_asset_percent": { "type": "number" }, "gross_assets": { "type": "number" }, "liability_balance": { "type": "number" }, "monthly_minimum_debt_payment": { "type": "number" }, "net_worth": { "type": "number" } } }, "PersonalNetWorthAccountCategory": { "type": "object", "additionalProperties": false, "required": [ "account_category", "available_balance_total", "balance_total", "count" ], "properties": { "account_category": { "type": "string" }, "available_balance_total": { "type": "number" }, "balance_total": { "type": "number" }, "count": { "type": "integer", "minimum": 0 } } }, "PersonalNetWorthAccounts": { "type": "object", "additionalProperties": false, "required": [ "active_count", "available_balance_total", "balance_total", "by_category", "count" ], "properties": { "active_count": { "type": "integer", "minimum": 0 }, "available_balance_total": { "type": "number" }, "balance_total": { "type": "number" }, "by_category": { "type": "array", "items": { "$ref": "#/components/schemas/PersonalNetWorthAccountCategory" } }, "count": { "type": "integer", "minimum": 0 } } }, "PersonalNetWorthAssetType": { "type": "object", "additionalProperties": false, "required": [ "asset_type", "count", "value_total" ], "properties": { "asset_type": { "type": "string" }, "count": { "type": "integer", "minimum": 0 }, "value_total": { "type": "number" } } }, "PersonalNetWorthAssets": { "type": "object", "additionalProperties": false, "required": [ "active_count", "by_type", "count", "value_total" ], "properties": { "active_count": { "type": "integer", "minimum": 0 }, "by_type": { "type": "array", "items": { "$ref": "#/components/schemas/PersonalNetWorthAssetType" } }, "count": { "type": "integer", "minimum": 0 }, "value_total": { "type": "number" } } }, "PersonalNetWorthLiabilityType": { "type": "object", "additionalProperties": false, "required": [ "balance_total", "count", "liability_type", "minimum_payment_total" ], "properties": { "balance_total": { "type": "number" }, "count": { "type": "integer", "minimum": 0 }, "liability_type": { "type": "string" }, "minimum_payment_total": { "type": "number" } } }, "PersonalNetWorthLiabilities": { "type": "object", "additionalProperties": false, "required": [ "active_count", "balance_total", "by_type", "count", "minimum_payment_total" ], "properties": { "active_count": { "type": "integer", "minimum": 0 }, "balance_total": { "type": "number" }, "by_type": { "type": "array", "items": { "$ref": "#/components/schemas/PersonalNetWorthLiabilityType" } }, "count": { "type": "integer", "minimum": 0 }, "minimum_payment_total": { "type": "number" } } }, "PersonalNetWorthReport": { "type": "object", "additionalProperties": false, "required": [ "accounts", "api_version", "assets", "currency", "generated_at", "freshness", "liabilities", "object", "report_type", "totals", "user_id" ], "properties": { "accounts": { "$ref": "#/components/schemas/PersonalNetWorthAccounts" }, "api_version": { "type": "string", "const": "v1-2026-07" }, "assets": { "$ref": "#/components/schemas/PersonalNetWorthAssets" }, "currency": { "type": "string", "minLength": 3, "maxLength": 5 }, "generated_at": { "type": "string", "format": "date-time" }, "freshness": { "$ref": "#/components/schemas/PersonalNetWorthFreshness" }, "liabilities": { "$ref": "#/components/schemas/PersonalNetWorthLiabilities" }, "object": { "type": "string", "const": "personal_net_worth_report" }, "report_type": { "type": "string", "const": "net_worth" }, "totals": { "$ref": "#/components/schemas/PersonalNetWorthTotals" }, "user_id": { "type": "string", "format": "uuid" } } }, "PersonalNetWorthFreshness": { "type": "object", "additionalProperties": false, "required": [ "latest_record_updated_at" ], "properties": { "latest_record_updated_at": { "type": [ "string", "null" ], "format": "date-time" } } }, "PersonalNetWorthReportMeta": { "type": "object", "additionalProperties": false, "required": [ "api_version", "mode", "request_id", "resource", "scopes" ], "properties": { "api_version": { "type": "string", "const": "v1-2026-07" }, "mode": { "type": "string", "const": "report" }, "request_id": { "type": "string", "minLength": 1, "maxLength": 128 }, "resource": { "type": "string", "const": "personal_net_worth_report" }, "scopes": { "type": "array", "items": { "type": "string", "enum": [ "personal.accounts.read", "personal.assets.read", "personal.liabilities.read" ] }, "minItems": 3, "maxItems": 3 } } }, "PersonalNetWorthReportResponse": { "type": "object", "required": [ "data", "meta" ], "properties": { "data": { "$ref": "#/components/schemas/PersonalNetWorthReport" }, "meta": { "$ref": "#/components/schemas/PersonalNetWorthReportMeta" } } }, "PersonalCashFlowPeriod": { "type": "object", "additionalProperties": false, "required": [ "from_date", "to_date" ], "properties": { "from_date": { "type": "string", "format": "date" }, "to_date": { "type": "string", "format": "date" } } }, "PersonalCashFlowTotals": { "type": "object", "additionalProperties": false, "required": [ "expense_transaction_count", "expense_total", "income_total", "income_transaction_count", "net_cash_flow", "transaction_count" ], "properties": { "expense_transaction_count": { "type": "integer", "minimum": 0 }, "expense_total": { "type": "number" }, "income_total": { "type": "number" }, "income_transaction_count": { "type": "integer", "minimum": 0 }, "net_cash_flow": { "type": "number" }, "transaction_count": { "type": "integer", "minimum": 0 } } }, "PersonalCashFlowMonth": { "type": "object", "additionalProperties": false, "required": [ "expense_total", "income_total", "month", "net_cash_flow", "transaction_count" ], "properties": { "expense_total": { "type": "number" }, "income_total": { "type": "number" }, "month": { "type": "string", "pattern": "^\\d{4}-\\d{2}$" }, "net_cash_flow": { "type": "number" }, "transaction_count": { "type": "integer", "minimum": 0 } } }, "PersonalCashFlowCategory": { "type": "object", "additionalProperties": false, "required": [ "category_id", "category_name", "category_type", "expense_total", "income_total", "net_cash_flow", "transaction_count" ], "properties": { "category_id": { "type": [ "string", "null" ], "format": "uuid" }, "category_name": { "type": "string" }, "category_type": { "type": [ "string", "null" ] }, "expense_total": { "type": "number" }, "income_total": { "type": "number" }, "net_cash_flow": { "type": "number" }, "transaction_count": { "type": "integer", "minimum": 0 } } }, "PersonalCashFlowAccount": { "type": "object", "additionalProperties": false, "required": [ "account_id", "expense_total", "income_total", "net_cash_flow", "transaction_count" ], "properties": { "account_id": { "type": [ "string", "null" ], "format": "uuid" }, "expense_total": { "type": "number" }, "income_total": { "type": "number" }, "net_cash_flow": { "type": "number" }, "transaction_count": { "type": "integer", "minimum": 0 } } }, "PersonalCashFlowReport": { "type": "object", "additionalProperties": false, "required": [ "accounts", "api_version", "categories", "currency", "generated_at", "months", "object", "period", "report_type", "scope", "totals", "user_id" ], "properties": { "accounts": { "type": "array", "items": { "$ref": "#/components/schemas/PersonalCashFlowAccount" } }, "api_version": { "type": "string", "const": "v1-2026-07" }, "categories": { "type": "array", "items": { "$ref": "#/components/schemas/PersonalCashFlowCategory" } }, "currency": { "type": "string", "minLength": 3, "maxLength": 5 }, "generated_at": { "type": "string", "format": "date-time" }, "months": { "type": "array", "items": { "$ref": "#/components/schemas/PersonalCashFlowMonth" } }, "object": { "type": "string", "const": "personal_cash_flow_report" }, "period": { "$ref": "#/components/schemas/PersonalCashFlowPeriod" }, "report_type": { "type": "string", "const": "cash_flow" }, "scope": { "type": "string", "const": "transaction_backed" }, "totals": { "$ref": "#/components/schemas/PersonalCashFlowTotals" }, "user_id": { "type": "string", "format": "uuid" } } }, "PersonalCashFlowReportMeta": { "type": "object", "additionalProperties": false, "required": [ "api_version", "filters", "mode", "request_id", "resource", "scope" ], "properties": { "api_version": { "type": "string", "const": "v1-2026-07" }, "filters": { "type": "object", "additionalProperties": false, "required": [ "account_id", "category_id", "from_date", "to_date", "uncategorised" ], "properties": { "account_id": { "type": [ "string", "null" ], "format": "uuid" }, "category_id": { "type": [ "string", "null" ], "format": "uuid" }, "from_date": { "type": "string", "format": "date" }, "to_date": { "type": "string", "format": "date" }, "uncategorised": { "type": "boolean" } } }, "mode": { "type": "string", "const": "report" }, "request_id": { "type": "string", "minLength": 1, "maxLength": 128 }, "resource": { "type": "string", "const": "personal_cash_flow_report" }, "scope": { "type": "string", "const": "personal.transactions.read" } } }, "PersonalCashFlowReportResponse": { "type": "object", "required": [ "data", "meta" ], "properties": { "data": { "$ref": "#/components/schemas/PersonalCashFlowReport" }, "meta": { "$ref": "#/components/schemas/PersonalCashFlowReportMeta" } } }, "PersonalBudgetPerformancePeriod": { "type": "object", "additionalProperties": false, "required": [ "from_date", "to_date" ], "properties": { "from_date": { "type": "string", "format": "date" }, "to_date": { "type": "string", "format": "date" } } }, "PersonalBudgetPerformanceTotals": { "type": "object", "additionalProperties": false, "required": [ "budget_count", "budgeted_total", "over_budget_count", "remaining_total", "spent_total", "utilisation_percent" ], "properties": { "budget_count": { "type": "integer", "minimum": 0 }, "budgeted_total": { "type": "number" }, "over_budget_count": { "type": "integer", "minimum": 0 }, "remaining_total": { "type": "number" }, "spent_total": { "type": "number" }, "utilisation_percent": { "type": "number" } } }, "PersonalBudgetPerformanceBudgetType": { "type": "object", "additionalProperties": false, "required": [ "budget_type", "budget_count", "budgeted_total", "over_budget_count", "remaining_total", "spent_total", "utilisation_percent" ], "properties": { "budget_type": { "type": "string" }, "budget_count": { "type": "integer", "minimum": 0 }, "budgeted_total": { "type": "number" }, "over_budget_count": { "type": "integer", "minimum": 0 }, "remaining_total": { "type": "number" }, "spent_total": { "type": "number" }, "utilisation_percent": { "type": "number" } } }, "PersonalBudgetPerformanceCategory": { "type": "object", "additionalProperties": false, "required": [ "budget_type", "category_id", "category_name", "budget_count", "budgeted_total", "over_budget_count", "remaining_total", "spent_total", "utilisation_percent" ], "properties": { "budget_type": { "type": [ "string", "null" ] }, "category_id": { "type": [ "string", "null" ], "format": "uuid" }, "category_name": { "type": "string" }, "budget_count": { "type": "integer", "minimum": 0 }, "budgeted_total": { "type": "number" }, "over_budget_count": { "type": "integer", "minimum": 0 }, "remaining_total": { "type": "number" }, "spent_total": { "type": "number" }, "utilisation_percent": { "type": "number" } } }, "PersonalBudgetPerformanceMonth": { "type": "object", "additionalProperties": false, "required": [ "budget_month", "budget_count", "budgeted_total", "over_budget_count", "remaining_total", "spent_total", "utilisation_percent" ], "properties": { "budget_month": { "type": "string", "format": "date" }, "budget_count": { "type": "integer", "minimum": 0 }, "budgeted_total": { "type": "number" }, "over_budget_count": { "type": "integer", "minimum": 0 }, "remaining_total": { "type": "number" }, "spent_total": { "type": "number" }, "utilisation_percent": { "type": "number" } } }, "PersonalBudgetPerformanceBudget": { "type": "object", "additionalProperties": false, "required": [ "budget_amount", "budget_month", "budget_type", "category_id", "category_name", "id", "is_active", "object", "period_type", "remaining_amount", "spent_amount", "utilisation_percent" ], "properties": { "object": { "type": "string", "const": "personal_budget_performance_budget" }, "id": { "type": [ "string", "null" ], "format": "uuid" }, "category_id": { "type": [ "string", "null" ], "format": "uuid" }, "category_name": { "type": "string" }, "budget_type": { "type": "string" }, "period_type": { "type": [ "string", "null" ] }, "budget_month": { "type": "string", "format": "date" }, "budget_amount": { "type": "number" }, "spent_amount": { "type": "number" }, "remaining_amount": { "type": "number" }, "utilisation_percent": { "type": "number" }, "is_active": { "type": "boolean" } } }, "PersonalBudgetPerformanceReport": { "type": "object", "additionalProperties": false, "required": [ "api_version", "budget_types", "budgets", "categories", "currency", "generated_at", "object", "period", "periods", "report_type", "totals", "user_id" ], "properties": { "api_version": { "type": "string", "const": "v1-2026-07" }, "budget_types": { "type": "array", "items": { "$ref": "#/components/schemas/PersonalBudgetPerformanceBudgetType" } }, "budgets": { "type": "array", "items": { "$ref": "#/components/schemas/PersonalBudgetPerformanceBudget" } }, "categories": { "type": "array", "items": { "$ref": "#/components/schemas/PersonalBudgetPerformanceCategory" } }, "currency": { "type": "string", "minLength": 3, "maxLength": 5 }, "generated_at": { "type": "string", "format": "date-time" }, "object": { "type": "string", "const": "personal_budget_performance_report" }, "period": { "$ref": "#/components/schemas/PersonalBudgetPerformancePeriod" }, "periods": { "type": "array", "items": { "$ref": "#/components/schemas/PersonalBudgetPerformanceMonth" } }, "report_type": { "type": "string", "const": "budget_performance" }, "totals": { "$ref": "#/components/schemas/PersonalBudgetPerformanceTotals" }, "user_id": { "type": "string", "format": "uuid" } } }, "PersonalBudgetPerformanceReportMeta": { "type": "object", "additionalProperties": false, "required": [ "api_version", "filters", "mode", "request_id", "resource", "scope" ], "properties": { "api_version": { "type": "string", "const": "v1-2026-07" }, "filters": { "type": "object", "additionalProperties": false, "required": [ "budget_type", "category_id", "from_date", "is_active", "period_type", "to_date" ], "properties": { "budget_type": { "type": [ "string", "null" ] }, "category_id": { "type": [ "string", "null" ], "format": "uuid" }, "from_date": { "type": "string", "format": "date" }, "is_active": { "type": [ "boolean", "null" ] }, "period_type": { "type": [ "string", "null" ] }, "to_date": { "type": "string", "format": "date" } } }, "mode": { "type": "string", "const": "report" }, "request_id": { "type": "string", "minLength": 1, "maxLength": 128 }, "resource": { "type": "string", "const": "personal_budget_performance_report" }, "scope": { "type": "string", "const": "personal.budgets.read" } } }, "PersonalBudgetPerformanceReportResponse": { "type": "object", "required": [ "data", "meta" ], "properties": { "data": { "$ref": "#/components/schemas/PersonalBudgetPerformanceReport" }, "meta": { "$ref": "#/components/schemas/PersonalBudgetPerformanceReportMeta" } } }, "PersonalGoalProgressTotals": { "type": "object", "additionalProperties": false, "required": [ "achieved_goal_count", "active_goal_count", "completion_percent", "current_total", "goal_count", "remaining_total", "target_total" ], "properties": { "achieved_goal_count": { "type": "integer", "minimum": 0 }, "active_goal_count": { "type": "integer", "minimum": 0 }, "completion_percent": { "type": "number" }, "current_total": { "type": "number" }, "goal_count": { "type": "integer", "minimum": 0 }, "remaining_total": { "type": "number" }, "target_total": { "type": "number" } } }, "PersonalGoalProgressGoalType": { "type": "object", "additionalProperties": false, "required": [ "goal_type", "achieved_goal_count", "active_goal_count", "completion_percent", "current_total", "goal_count", "remaining_total", "target_total" ], "properties": { "goal_type": { "type": "string" }, "achieved_goal_count": { "type": "integer", "minimum": 0 }, "active_goal_count": { "type": "integer", "minimum": 0 }, "completion_percent": { "type": "number" }, "current_total": { "type": "number" }, "goal_count": { "type": "integer", "minimum": 0 }, "remaining_total": { "type": "number" }, "target_total": { "type": "number" } } }, "PersonalGoalProgressCategory": { "type": "object", "additionalProperties": false, "required": [ "category_id", "achieved_goal_count", "active_goal_count", "completion_percent", "current_total", "goal_count", "remaining_total", "target_total" ], "properties": { "category_id": { "type": [ "string", "null" ], "format": "uuid" }, "achieved_goal_count": { "type": "integer", "minimum": 0 }, "active_goal_count": { "type": "integer", "minimum": 0 }, "completion_percent": { "type": "number" }, "current_total": { "type": "number" }, "goal_count": { "type": "integer", "minimum": 0 }, "remaining_total": { "type": "number" }, "target_total": { "type": "number" } } }, "PersonalGoalProgressGoal": { "type": "object", "additionalProperties": false, "required": [ "category_id", "completion_percent", "contribution_amount", "contribution_frequency", "contribution_percent", "current_amount", "goal_type", "id", "is_achieved", "is_shared", "linked_account_id", "name", "object", "priority", "remaining_amount", "target_amount", "target_date" ], "properties": { "object": { "type": "string", "const": "personal_goal_progress_goal" }, "id": { "type": [ "string", "null" ], "format": "uuid" }, "name": { "type": [ "string", "null" ] }, "goal_type": { "type": "string" }, "category_id": { "type": [ "string", "null" ], "format": "uuid" }, "linked_account_id": { "type": [ "string", "null" ], "format": "uuid" }, "target_amount": { "type": "number" }, "current_amount": { "type": "number" }, "remaining_amount": { "type": "number" }, "completion_percent": { "type": "number" }, "target_date": { "type": [ "string", "null" ], "format": "date" }, "priority": { "type": [ "number", "null" ] }, "is_achieved": { "type": "boolean" }, "is_shared": { "type": "boolean" }, "contribution_amount": { "type": [ "number", "null" ] }, "contribution_percent": { "type": [ "number", "null" ] }, "contribution_frequency": { "type": [ "string", "null" ] } } }, "PersonalGoalProgressReport": { "type": "object", "additionalProperties": false, "required": [ "api_version", "categories", "currency", "generated_at", "goal_types", "goals", "object", "report_type", "totals", "user_id" ], "properties": { "api_version": { "type": "string", "const": "v1-2026-07" }, "categories": { "type": "array", "items": { "$ref": "#/components/schemas/PersonalGoalProgressCategory" } }, "currency": { "type": "string", "minLength": 3, "maxLength": 5 }, "generated_at": { "type": "string", "format": "date-time" }, "goal_types": { "type": "array", "items": { "$ref": "#/components/schemas/PersonalGoalProgressGoalType" } }, "goals": { "type": "array", "items": { "$ref": "#/components/schemas/PersonalGoalProgressGoal" } }, "object": { "type": "string", "const": "personal_goal_progress_report" }, "report_type": { "type": "string", "const": "goal_progress" }, "totals": { "$ref": "#/components/schemas/PersonalGoalProgressTotals" }, "user_id": { "type": "string", "format": "uuid" } } }, "PersonalGoalProgressReportMeta": { "type": "object", "additionalProperties": false, "required": [ "api_version", "filters", "mode", "request_id", "resource", "scope" ], "properties": { "api_version": { "type": "string", "const": "v1-2026-07" }, "filters": { "type": "object", "additionalProperties": false, "required": [ "category_id", "from_target_date", "goal_type", "is_achieved", "is_shared", "linked_account_id", "search", "to_target_date" ], "properties": { "category_id": { "type": [ "string", "null" ], "format": "uuid" }, "from_target_date": { "type": [ "string", "null" ], "format": "date" }, "goal_type": { "type": [ "string", "null" ] }, "is_achieved": { "type": [ "boolean", "null" ] }, "is_shared": { "type": [ "boolean", "null" ] }, "linked_account_id": { "type": [ "string", "null" ], "format": "uuid" }, "search": { "type": [ "string", "null" ] }, "to_target_date": { "type": [ "string", "null" ], "format": "date" } } }, "mode": { "type": "string", "const": "report" }, "request_id": { "type": "string", "minLength": 1, "maxLength": 128 }, "resource": { "type": "string", "const": "personal_goal_progress_report" }, "scope": { "type": "string", "const": "personal.goals.read" } } }, "PersonalGoalProgressReportResponse": { "type": "object", "required": [ "data", "meta" ], "properties": { "data": { "$ref": "#/components/schemas/PersonalGoalProgressReport" }, "meta": { "$ref": "#/components/schemas/PersonalGoalProgressReportMeta" } } }, "PersonalCategorizationRuleCreateRequest": { "type": "object", "additionalProperties": false, "required": [ "merchant_pattern", "category_id" ], "properties": { "category_id": { "type": "string", "format": "uuid", "description": "Personal category owned by the bearer-token user." }, "is_active": { "type": "boolean", "default": true }, "match_type": { "type": "string", "enum": [ "contains", "starts_with", "equals" ], "default": "contains" }, "merchant_pattern": { "type": "string", "minLength": 1, "maxLength": 160, "description": "Merchant or keyword pattern to match. Control characters are rejected." }, "pattern_type": { "type": "string", "enum": [ "merchant", "keyword" ], "default": "merchant" } } }, "PersonalCategorizationRuleUpdateRequest": { "type": "object", "additionalProperties": false, "minProperties": 1, "properties": { "category_id": { "type": "string", "format": "uuid", "description": "Personal category owned by the bearer-token user." }, "is_active": { "type": "boolean", "default": true }, "match_type": { "type": "string", "enum": [ "contains", "starts_with", "equals" ], "default": "contains" }, "merchant_pattern": { "type": "string", "minLength": 1, "maxLength": 160, "description": "Merchant or keyword pattern to match. Control characters are rejected." }, "pattern_type": { "type": "string", "enum": [ "merchant", "keyword" ], "default": "merchant" } } }, "PersonalCategorizationRuleMeta": { "type": "object", "additionalProperties": false, "required": [ "api_version", "mode", "request_id", "resource", "scopes" ], "properties": { "api_version": { "type": "string", "const": "v1-2026-07" }, "mode": { "type": "string", "const": "detail" }, "request_id": { "type": "string", "minLength": 1, "maxLength": 128 }, "resource": { "type": "string", "const": "personal_categorization_rule" }, "scopes": { "type": "array", "items": { "type": "string", "enum": [ "personal.transactions.read", "personal.categories.read" ] }, "minItems": 2, "maxItems": 2 } } }, "PersonalCategorizationRuleCreateMeta": { "type": "object", "additionalProperties": false, "required": [ "api_version", "mode", "request_id", "resource", "scopes" ], "properties": { "api_version": { "type": "string", "const": "v1-2026-07" }, "mode": { "type": "string", "const": "created" }, "request_id": { "type": "string", "minLength": 1, "maxLength": 128 }, "resource": { "type": "string", "const": "personal_categorization_rule" }, "scopes": { "type": "array", "items": { "type": "string", "enum": [ "personal.transactions.write", "personal.categories.read" ] }, "minItems": 2, "maxItems": 2 } } }, "PersonalCategorizationRuleUpdateMeta": { "type": "object", "additionalProperties": false, "required": [ "api_version", "mode", "request_id", "resource", "scopes" ], "properties": { "api_version": { "type": "string", "const": "v1-2026-07" }, "mode": { "type": "string", "const": "updated" }, "request_id": { "type": "string", "minLength": 1, "maxLength": 128 }, "resource": { "type": "string", "const": "personal_categorization_rule" }, "scopes": { "type": "array", "items": { "type": "string", "enum": [ "personal.transactions.write", "personal.categories.read" ] }, "minItems": 2, "maxItems": 2 } } }, "PersonalCategorizationRuleResponse": { "type": "object", "additionalProperties": false, "required": [ "data", "meta" ], "properties": { "data": { "$ref": "#/components/schemas/PersonalCategorizationRule" }, "meta": { "$ref": "#/components/schemas/PersonalCategorizationRuleMeta" } } }, "PersonalCategorizationRuleCreateResponse": { "type": "object", "additionalProperties": false, "required": [ "data", "meta" ], "properties": { "data": { "$ref": "#/components/schemas/PersonalCategorizationRule" }, "meta": { "$ref": "#/components/schemas/PersonalCategorizationRuleCreateMeta" } } }, "PersonalCategorizationRuleUpdateResponse": { "type": "object", "additionalProperties": false, "required": [ "data", "meta" ], "properties": { "data": { "$ref": "#/components/schemas/PersonalCategorizationRule" }, "meta": { "$ref": "#/components/schemas/PersonalCategorizationRuleUpdateMeta" } } }, "BusinessGiftAidDonorUpdateRequest": { "type": "object", "additionalProperties": false, "properties": { "title": { "type": [ "string", "null" ], "maxLength": 50 }, "first_name": { "type": "string", "minLength": 1, "maxLength": 100 }, "last_name": { "type": "string", "minLength": 1, "maxLength": 100 }, "address_line_1": { "type": "string", "minLength": 1, "maxLength": 200 }, "address_line_2": { "type": [ "string", "null" ], "maxLength": 200 }, "city": { "type": "string", "minLength": 1, "maxLength": 100 }, "county": { "type": [ "string", "null" ], "maxLength": 100 }, "postcode": { "type": "string", "minLength": 1, "maxLength": 20 }, "country": { "type": [ "string", "null" ], "maxLength": 100, "default": "United Kingdom" }, "email": { "type": [ "string", "null" ], "format": "email", "maxLength": 320 }, "telephone": { "type": [ "string", "null" ], "maxLength": 50 }, "external_id": { "type": [ "string", "null" ], "maxLength": 100 }, "notes": { "type": [ "string", "null" ], "maxLength": 2000 }, "is_active": { "type": "boolean", "default": true } }, "minProperties": 1, "description": "Safe Gift Aid donor profile fields that can be updated. Declaration, donation, claim and filing fields are intentionally excluded." }, "BusinessGiftAidDonorUpdateMeta": { "type": "object", "required": [ "api_version", "mode", "request_id", "resource" ], "properties": { "api_version": { "type": "string", "const": "v1-2026-07" }, "mode": { "type": "string", "const": "updated" }, "request_id": { "type": "string", "minLength": 1, "maxLength": 128 }, "resource": { "type": "string", "const": "business_gift_aid_donor" }, "scope": { "type": "string", "const": "business.gift_aid_donors.update" } } }, "BusinessGiftAidDonorUpdateResponse": { "type": "object", "required": [ "data", "meta" ], "properties": { "data": { "$ref": "#/components/schemas/BusinessGiftAidDonor" }, "meta": { "$ref": "#/components/schemas/BusinessGiftAidDonorUpdateMeta" } } }, "BusinessCostCenterBudgetTargetMeta": { "type": "object", "required": [ "api_version", "mode", "request_id", "resource" ], "properties": { "api_version": { "type": "string", "const": "v1-2026-07" }, "mode": { "type": "string", "const": "detail" }, "request_id": { "type": "string", "minLength": 1, "maxLength": 128 }, "resource": { "type": "string", "const": "business_cost_center_budget_target" } } }, "BusinessCostCenterBudgetTargetResponse": { "type": "object", "required": [ "data", "meta" ], "properties": { "data": { "$ref": "#/components/schemas/BusinessCostCenterBudgetTarget" }, "meta": { "$ref": "#/components/schemas/BusinessCostCenterBudgetTargetMeta" } } }, "QuoteSendApprovalRequest": { "type": "object", "additionalProperties": false, "properties": { "reason": { "type": "string", "maxLength": 1000 }, "requested_by_name": { "type": "string", "maxLength": 200 }, "requested_by_email": { "type": "string", "format": "email", "maxLength": 320 } } }, "V1QuoteApprovalRequestResponse": { "type": "object", "required": [ "data", "meta" ], "properties": { "data": { "$ref": "#/components/schemas/QuoteApprovalRequest" }, "meta": { "$ref": "#/components/schemas/V1ApprovalRequestMeta" } } }, "QuoteApprovalRequest": { "type": "object", "required": [ "id", "object", "status", "resource_type", "resource_id", "requested_action", "policy" ], "properties": { "id": { "type": "string", "format": "uuid" }, "object": { "type": "string", "const": "approval_request" }, "status": { "type": "string", "enum": [ "pending" ] }, "resource_type": { "type": "string", "const": "quote" }, "resource_id": { "type": "string", "format": "uuid" }, "requested_action": { "type": "string", "const": "send_quote" }, "current_step_id": { "type": [ "string", "null" ], "format": "uuid" }, "current_step_order": { "type": [ "integer", "null" ] }, "policy": { "type": "object", "required": [ "decision", "reason" ], "properties": { "decision": { "type": "string", "const": "approval_required" }, "reason": { "type": "string" } } } } }, "PurchaseInvoiceApprovalRequest": { "type": "object", "additionalProperties": false, "properties": { "reason": { "type": "string", "maxLength": 1000 }, "requested_by_name": { "type": "string", "maxLength": 200 }, "requested_by_email": { "type": "string", "format": "email", "maxLength": 320 } } }, "V1PurchaseInvoiceApprovalRequestResponse": { "type": "object", "required": [ "data", "meta" ], "properties": { "data": { "$ref": "#/components/schemas/PurchaseInvoiceApprovalRequestRecord" }, "meta": { "$ref": "#/components/schemas/V1ApprovalRequestMeta" } } }, "PurchaseInvoiceApprovalRequestRecord": { "type": "object", "required": [ "id", "object", "status", "resource_type", "resource_id", "requested_action", "policy" ], "properties": { "id": { "type": "string", "format": "uuid" }, "object": { "type": "string", "const": "approval_request" }, "status": { "type": "string", "enum": [ "pending" ] }, "resource_type": { "type": "string", "const": "purchase_invoice" }, "resource_id": { "type": "string", "format": "uuid" }, "requested_action": { "type": "string", "const": "approve_purchase_invoice" }, "current_step_id": { "type": [ "string", "null" ], "format": "uuid" }, "current_step_order": { "type": [ "integer", "null" ] }, "policy": { "type": "object", "required": [ "decision", "reason" ], "properties": { "decision": { "type": "string", "const": "approval_required" }, "reason": { "type": "string" } } } } }, "ExpenseClaimApprovalRequest": { "type": "object", "additionalProperties": false, "properties": { "reason": { "type": "string", "maxLength": 1000 }, "requested_by_name": { "type": "string", "maxLength": 200 }, "requested_by_email": { "type": "string", "format": "email", "maxLength": 320 } } }, "V1ExpenseClaimApprovalRequestResponse": { "type": "object", "required": [ "data", "meta" ], "properties": { "data": { "$ref": "#/components/schemas/ExpenseClaimApprovalRequestRecord" }, "meta": { "$ref": "#/components/schemas/V1ApprovalRequestMeta" } } }, "ExpenseClaimApprovalRequestRecord": { "type": "object", "required": [ "id", "object", "status", "resource_type", "resource_id", "requested_action", "policy" ], "properties": { "id": { "type": "string", "format": "uuid" }, "object": { "type": "string", "const": "approval_request" }, "status": { "type": "string", "enum": [ "pending" ] }, "resource_type": { "type": "string", "const": "expense_claim" }, "resource_id": { "type": "string", "format": "uuid" }, "requested_action": { "type": "string", "const": "approve_expense_claim" }, "current_step_id": { "type": [ "string", "null" ], "format": "uuid" }, "current_step_order": { "type": [ "integer", "null" ] }, "policy": { "type": "object", "required": [ "decision", "reason" ], "properties": { "decision": { "type": "string", "const": "approval_required" }, "reason": { "type": "string" } } } } }, "PurchaseOrderApprovalRequest": { "type": "object", "additionalProperties": false, "properties": { "reason": { "type": "string", "maxLength": 1000 }, "requested_by_name": { "type": "string", "maxLength": 200 }, "requested_by_email": { "type": "string", "format": "email", "maxLength": 320 } } }, "V1PurchaseOrderApprovalRequestResponse": { "type": "object", "required": [ "data", "meta" ], "properties": { "data": { "$ref": "#/components/schemas/PurchaseOrderApprovalRequestRecord" }, "meta": { "$ref": "#/components/schemas/V1ApprovalRequestMeta" } } }, "PurchaseOrderApprovalRequestRecord": { "type": "object", "required": [ "id", "object", "status", "resource_type", "resource_id", "requested_action", "policy" ], "properties": { "id": { "type": "string", "format": "uuid" }, "object": { "type": "string", "const": "approval_request" }, "status": { "type": "string", "enum": [ "pending" ] }, "resource_type": { "type": "string", "const": "purchase_order" }, "resource_id": { "type": "string", "format": "uuid" }, "requested_action": { "type": "string", "const": "approve_purchase_order" }, "current_step_id": { "type": [ "string", "null" ], "format": "uuid" }, "current_step_order": { "type": [ "integer", "null" ] }, "policy": { "type": "object", "required": [ "decision", "reason" ], "properties": { "decision": { "type": "string", "const": "approval_required" }, "reason": { "type": "string" } } } } }, "BusinessSupplierPaymentRunCreateRequest": { "type": "object", "additionalProperties": false, "required": [ "purchase_invoice_ids" ], "properties": { "purchase_invoice_ids": { "type": "array", "minItems": 1, "maxItems": 100, "uniqueItems": true, "items": { "type": "string", "format": "uuid" } }, "scheduled_payment_date": { "type": [ "string", "null" ], "format": "date" }, "notes": { "type": [ "string", "null" ], "maxLength": 1000 } } }, "V1BusinessSupplierPaymentRunCreateMeta": { "type": "object", "additionalProperties": false, "properties": { "api_version": { "type": "string" }, "mode": { "type": "string", "const": "created" }, "request_id": { "type": "string" }, "resource": { "type": "string", "const": "business_supplier_payment_run" } } }, "V1BusinessSupplierPaymentRunCreateResponse": { "type": "object", "additionalProperties": false, "required": [ "data", "meta" ], "properties": { "data": { "$ref": "#/components/schemas/BusinessSupplierPaymentRun" }, "meta": { "$ref": "#/components/schemas/V1BusinessSupplierPaymentRunCreateMeta" } } }, "SupplierPaymentRunApprovalRequest": { "type": "object", "additionalProperties": false, "properties": { "reason": { "type": "string", "maxLength": 1000 }, "requested_by_name": { "type": "string", "maxLength": 200 }, "requested_by_email": { "type": "string", "format": "email", "maxLength": 320 } } }, "SupplierPaymentRunApprovalRequestRecord": { "type": "object", "required": [ "id", "object", "status", "resource_type", "resource_id", "requested_action", "policy" ], "properties": { "id": { "type": "string", "format": "uuid" }, "object": { "type": "string", "const": "approval_request" }, "status": { "type": "string", "enum": [ "pending" ] }, "resource_type": { "type": "string", "const": "supplier_payment_run" }, "resource_id": { "type": "string", "format": "uuid" }, "requested_action": { "type": "string", "const": "approve_supplier_payment_run" }, "current_step_id": { "type": [ "string", "null" ], "format": "uuid" }, "current_step_order": { "type": [ "integer", "null" ] }, "policy": { "type": "object", "required": [ "decision", "reason" ], "properties": { "decision": { "type": "string", "const": "approval_required" }, "reason": { "type": "string" } } } } }, "V1SupplierPaymentRunApprovalRequestResponse": { "type": "object", "required": [ "data", "meta" ], "properties": { "data": { "$ref": "#/components/schemas/SupplierPaymentRunApprovalRequestRecord" }, "meta": { "$ref": "#/components/schemas/V1ApprovalRequestMeta" } } }, "BusinessApprovalRequestInfoRequest": { "type": "object", "additionalProperties": false, "required": [ "message" ], "properties": { "message": { "type": "string", "minLength": 1, "maxLength": 1000, "description": "Required message explaining what information is needed before approval can continue." } } }, "V1BusinessApprovalRequestInfoResponse": { "type": "object", "required": [ "data", "meta" ], "properties": { "data": { "$ref": "#/components/schemas/BusinessApprovalRequest" }, "meta": { "$ref": "#/components/schemas/V1BusinessApprovalRequestInfoMeta" } } }, "V1BusinessApprovalRequestInfoMeta": { "type": "object", "required": [ "api_version", "mode", "request_id", "resource", "scope" ], "properties": { "api_version": { "type": "string", "const": "v1-2026-07" }, "mode": { "type": "string", "const": "info_requested" }, "request_id": { "type": "string", "minLength": 1, "maxLength": 128 }, "resource": { "type": "string", "const": "approval_request" }, "scope": { "type": "string", "const": "business.approval_requests.request_info" } } }, "BusinessCustomerPaymentRecordRequest": { "type": "object", "additionalProperties": false, "required": [ "invoice_id", "stripe_payment_intent" ], "properties": { "invoice_id": { "type": "string", "format": "uuid", "description": "Ledger-posted sales invoice id to record the completed payment against." }, "stripe_payment_intent": { "type": "string", "minLength": 1, "maxLength": 255, "description": "Stripe PaymentIntent id. Financial IQ fetches gross amount and fee from Stripe; caller-supplied amounts are rejected." }, "provider": { "type": "string", "enum": [ "stripe" ], "default": "stripe", "description": "Payment provider. Only stripe is supported for v1 recording." }, "stripe_account": { "type": "string", "maxLength": 255, "description": "Optional connected Stripe account id when the PaymentIntent lives on a Stripe Connect account." }, "payment_date": { "type": "string", "format": "date", "description": "Optional payment date. Defaults inside the payment engine when omitted." }, "reference": { "type": "string", "maxLength": 100, "description": "Optional payment reference. If omitted Financial IQ derives one from the Stripe charge or PaymentIntent." }, "notes": { "type": "string", "maxLength": 500, "description": "Optional internal note stored on the payment evidence row. Notes are not returned by the public response." } } }, "V1BusinessCustomerPaymentCreateMeta": { "type": "object", "additionalProperties": false, "required": [ "api_version", "mode", "request_id", "resource", "scope" ], "properties": { "api_version": { "type": "string", "const": "v1-2026-07" }, "mode": { "type": "string", "const": "created" }, "request_id": { "type": "string", "minLength": 1, "maxLength": 128 }, "resource": { "type": "string", "const": "business_customer_payment" }, "scope": { "type": "string", "const": "business.customer_payments.record" } } }, "BusinessCustomerPaymentCreateResponse": { "type": "object", "additionalProperties": false, "required": [ "data", "meta" ], "properties": { "data": { "$ref": "#/components/schemas/BusinessCustomerPayment" }, "meta": { "$ref": "#/components/schemas/V1BusinessCustomerPaymentCreateMeta" } } }, "BusinessPaymentLinkCreateRequest": { "type": "object", "additionalProperties": false, "required": [ "invoice_id" ], "properties": { "invoice_id": { "type": "string", "format": "uuid", "description": "Invoice id to create or reuse a payment link for." }, "expiry_days": { "type": "integer", "minimum": 1, "maximum": 365, "description": "Optional expiry in days for a newly created link. Defaults to invoice payment settings, then 30 days." }, "require_email_verification": { "type": "boolean", "default": false, "description": "Whether the public payment page should require email verification before payment." } } }, "V1BusinessPaymentLinkCreateMeta": { "type": "object", "additionalProperties": false, "required": [ "api_version", "mode", "request_id", "resource", "scope" ], "properties": { "api_version": { "type": "string", "const": "v1-2026-07" }, "mode": { "type": "string", "enum": [ "created", "reused" ] }, "request_id": { "type": "string", "minLength": 1, "maxLength": 128 }, "resource": { "type": "string", "const": "business_payment_link" }, "scope": { "type": "string", "const": "business.payment_links.create" } } }, "BusinessPaymentLinkCreateResponse": { "type": "object", "additionalProperties": false, "required": [ "data", "meta" ], "properties": { "data": { "$ref": "#/components/schemas/BusinessPaymentLink" }, "meta": { "$ref": "#/components/schemas/V1BusinessPaymentLinkCreateMeta" } } }, "BusinessBalanceSheetReconciliationSummary": { "type": "object", "additionalProperties": false, "required": [ "object", "id", "company_id", "reconciliation_period_id", "accounting_period_id", "account_code", "account_name", "workbook_type", "status" ], "properties": { "object": { "type": "string", "const": "business_balance_sheet_reconciliation" }, "id": { "type": "string", "format": "uuid" }, "company_id": { "type": "string", "format": "uuid" }, "reconciliation_period_id": { "type": "string", "format": "uuid" }, "accounting_period_id": { "type": "string", "format": "uuid" }, "period_start_date": { "type": [ "string", "null" ], "format": "date" }, "period_end_date": { "type": [ "string", "null" ], "format": "date" }, "period_status": { "type": [ "string", "null" ] }, "chart_of_accounts_id": { "type": [ "string", "null" ], "format": "uuid" }, "bank_account_id": { "type": [ "string", "null" ], "format": "uuid" }, "account_code": { "type": [ "string", "null" ] }, "account_name": { "type": [ "string", "null" ] }, "workbook_type": { "type": [ "string", "null" ] }, "status": { "type": [ "string", "null" ] }, "gl_balance": { "type": [ "number", "null" ] }, "source_kind": { "type": [ "string", "null" ] }, "source_balance": { "type": [ "number", "null" ] }, "source_note": { "type": [ "string", "null" ] }, "adjusted_source_balance": { "type": [ "number", "null" ] }, "difference": { "type": [ "number", "null" ] }, "is_material": { "type": "boolean" }, "open_item_count": { "type": [ "number", "null" ] }, "preparer_user_id": { "type": [ "string", "null" ], "format": "uuid" }, "reviewer_user_id": { "type": [ "string", "null" ], "format": "uuid" }, "due_date": { "type": [ "string", "null" ], "format": "date" }, "updated_at": { "type": [ "string", "null" ], "format": "date-time" }, "account_type": { "type": [ "string", "null" ] }, "financial_statement": { "type": [ "string", "null" ] }, "last_reconciled_date": { "type": [ "string", "null" ], "format": "date" }, "linked_bank_account_name": { "type": [ "string", "null" ] } } }, "BusinessBalanceSheetReconciliationPeriod": { "type": "object", "additionalProperties": false, "properties": { "object": { "type": "string", "const": "business_balance_sheet_reconciliation_period" }, "id": { "type": "string", "format": "uuid" }, "company_id": { "type": "string", "format": "uuid" }, "accounting_period_id": { "type": [ "string", "null" ], "format": "uuid" }, "period_start_date": { "type": [ "string", "null" ], "format": "date" }, "period_end_date": { "type": [ "string", "null" ], "format": "date" }, "status": { "type": [ "string", "null" ] }, "materiality_threshold": { "type": [ "number", "null" ] }, "created_at": { "type": [ "string", "null" ], "format": "date-time" }, "updated_at": { "type": [ "string", "null" ], "format": "date-time" } } }, "BusinessBalanceSheetReconciliationLine": { "type": "object", "additionalProperties": false, "properties": { "object": { "type": "string", "const": "business_balance_sheet_reconciliation_line" }, "id": { "type": "string", "format": "uuid" }, "company_id": { "type": "string", "format": "uuid" }, "reconciliation_id": { "type": "string", "format": "uuid" }, "line_type": { "type": [ "string", "null" ] }, "line_category": { "type": [ "string", "null" ] }, "description": { "type": [ "string", "null" ] }, "reference": { "type": [ "string", "null" ] }, "amount": { "type": [ "number", "null" ] }, "line_date": { "type": [ "string", "null" ], "format": "date" }, "expected_clear_date": { "type": [ "string", "null" ], "format": "date" }, "cleared_at": { "type": [ "string", "null" ], "format": "date-time" }, "cleared_by_user_id": { "type": [ "string", "null" ], "format": "uuid" }, "is_open_item": { "type": "boolean" }, "source_line_id": { "type": [ "string", "null" ], "format": "uuid" }, "sort_order": { "type": [ "number", "null" ] }, "metadata": { "type": "object", "additionalProperties": true }, "created_by_user_id": { "type": [ "string", "null" ], "format": "uuid" }, "updated_by_user_id": { "type": [ "string", "null" ], "format": "uuid" }, "created_at": { "type": [ "string", "null" ], "format": "date-time" }, "updated_at": { "type": [ "string", "null" ], "format": "date-time" } } }, "BusinessBalanceSheetReconciliationAttachment": { "type": "object", "additionalProperties": false, "properties": { "object": { "type": "string", "const": "business_balance_sheet_reconciliation_attachment" }, "id": { "type": "string", "format": "uuid" }, "company_id": { "type": "string", "format": "uuid" }, "reconciliation_id": { "type": "string", "format": "uuid" }, "reconciliation_line_id": { "type": [ "string", "null" ], "format": "uuid" }, "document_id": { "type": [ "string", "null" ], "format": "uuid" }, "attachment_type": { "type": [ "string", "null" ] }, "is_primary": { "type": "boolean" }, "created_by_user_id": { "type": [ "string", "null" ], "format": "uuid" }, "created_at": { "type": [ "string", "null" ], "format": "date-time" } } }, "BusinessBalanceSheetReconciliationComment": { "type": "object", "additionalProperties": false, "properties": { "object": { "type": "string", "const": "business_balance_sheet_reconciliation_comment" }, "id": { "type": "string", "format": "uuid" }, "company_id": { "type": "string", "format": "uuid" }, "reconciliation_id": { "type": "string", "format": "uuid" }, "parent_comment_id": { "type": [ "string", "null" ], "format": "uuid" }, "commenter_user_id": { "type": [ "string", "null" ], "format": "uuid" }, "comment_text": { "type": [ "string", "null" ] }, "status": { "type": [ "string", "null" ] }, "resolved_by_user_id": { "type": [ "string", "null" ], "format": "uuid" }, "resolved_at": { "type": [ "string", "null" ], "format": "date-time" }, "created_at": { "type": [ "string", "null" ], "format": "date-time" }, "updated_at": { "type": [ "string", "null" ], "format": "date-time" } } }, "BusinessBalanceSheetReconciliationSignoff": { "type": "object", "additionalProperties": false, "properties": { "object": { "type": "string", "const": "business_balance_sheet_reconciliation_signoff" }, "id": { "type": "string", "format": "uuid" }, "company_id": { "type": "string", "format": "uuid" }, "reconciliation_id": { "type": "string", "format": "uuid" }, "signoff_role": { "type": [ "string", "null" ] }, "signed_by_user_id": { "type": [ "string", "null" ], "format": "uuid" }, "signed_at": { "type": [ "string", "null" ], "format": "date-time" }, "comment": { "type": [ "string", "null" ] }, "created_at": { "type": [ "string", "null" ], "format": "date-time" } } }, "BusinessBalanceSheetReconciliationEvent": { "type": "object", "additionalProperties": false, "properties": { "object": { "type": "string", "const": "business_balance_sheet_reconciliation_event" }, "id": { "type": "string", "format": "uuid" }, "company_id": { "type": "string", "format": "uuid" }, "reconciliation_id": { "type": [ "string", "null" ], "format": "uuid" }, "event_type": { "type": [ "string", "null" ] }, "actor_user_id": { "type": [ "string", "null" ], "format": "uuid" }, "old_values": { "type": "object", "additionalProperties": true }, "new_values": { "type": "object", "additionalProperties": true }, "metadata": { "type": "object", "additionalProperties": true }, "created_at": { "type": [ "string", "null" ], "format": "date-time" } } }, "BusinessBalanceSheetReconciliation": { "type": "object", "additionalProperties": false, "required": [ "object", "id", "company_id", "reconciliation_period_id", "lines", "attachments", "comments", "signoffs", "events" ], "properties": { "object": { "type": "string", "const": "business_balance_sheet_reconciliation" }, "id": { "type": "string", "format": "uuid" }, "company_id": { "type": "string", "format": "uuid" }, "reconciliation_period_id": { "type": "string", "format": "uuid" }, "accounting_period_id": { "type": "string", "format": "uuid" }, "period_start_date": { "type": [ "string", "null" ], "format": "date" }, "period_end_date": { "type": [ "string", "null" ], "format": "date" }, "period_status": { "type": [ "string", "null" ] }, "chart_of_accounts_id": { "type": [ "string", "null" ], "format": "uuid" }, "bank_account_id": { "type": [ "string", "null" ], "format": "uuid" }, "account_code": { "type": [ "string", "null" ] }, "account_name": { "type": [ "string", "null" ] }, "workbook_type": { "type": [ "string", "null" ] }, "status": { "type": [ "string", "null" ] }, "gl_balance": { "type": [ "number", "null" ] }, "source_kind": { "type": [ "string", "null" ] }, "source_balance": { "type": [ "number", "null" ] }, "source_note": { "type": [ "string", "null" ] }, "adjusted_source_balance": { "type": [ "number", "null" ] }, "difference": { "type": [ "number", "null" ] }, "is_material": { "type": "boolean" }, "open_item_count": { "type": [ "number", "null" ] }, "preparer_user_id": { "type": [ "string", "null" ], "format": "uuid" }, "reviewer_user_id": { "type": [ "string", "null" ], "format": "uuid" }, "due_date": { "type": [ "string", "null" ], "format": "date" }, "updated_at": { "type": [ "string", "null" ], "format": "date-time" }, "account_type": { "type": [ "string", "null" ] }, "financial_statement": { "type": [ "string", "null" ] }, "last_reconciled_date": { "type": [ "string", "null" ], "format": "date" }, "linked_bank_account_name": { "type": [ "string", "null" ] }, "approved_exception": { "type": "boolean" }, "exception_reason": { "type": [ "string", "null" ] }, "notes": { "type": [ "string", "null" ] }, "materiality_threshold": { "type": [ "number", "null" ] }, "prepared_by_user_id": { "type": [ "string", "null" ], "format": "uuid" }, "prepared_at": { "type": [ "string", "null" ], "format": "date-time" }, "reviewed_by_user_id": { "type": [ "string", "null" ], "format": "uuid" }, "reviewed_at": { "type": [ "string", "null" ], "format": "date-time" }, "approved_by_user_id": { "type": [ "string", "null" ], "format": "uuid" }, "approved_at": { "type": [ "string", "null" ], "format": "date-time" }, "locked_by_user_id": { "type": [ "string", "null" ], "format": "uuid" }, "locked_at": { "type": [ "string", "null" ], "format": "date-time" }, "carry_forward_count": { "type": [ "number", "null" ] }, "rollforward_from_reconciliation_id": { "type": [ "string", "null" ], "format": "uuid" }, "created_at": { "type": [ "string", "null" ], "format": "date-time" }, "period": { "anyOf": [ { "$ref": "#/components/schemas/BusinessBalanceSheetReconciliationPeriod" }, { "type": "null" } ] }, "lines": { "type": "array", "items": { "$ref": "#/components/schemas/BusinessBalanceSheetReconciliationLine" } }, "attachments": { "type": "array", "items": { "$ref": "#/components/schemas/BusinessBalanceSheetReconciliationAttachment" } }, "comments": { "type": "array", "items": { "$ref": "#/components/schemas/BusinessBalanceSheetReconciliationComment" } }, "signoffs": { "type": "array", "items": { "$ref": "#/components/schemas/BusinessBalanceSheetReconciliationSignoff" } }, "events": { "type": "array", "items": { "$ref": "#/components/schemas/BusinessBalanceSheetReconciliationEvent" } } } }, "V1BusinessBalanceSheetReconciliationListMeta": { "type": "object", "required": [ "api_version", "mode", "pagination", "request_id", "resource", "scope" ], "properties": { "api_version": { "type": "string", "const": "v1-2026-07" }, "mode": { "type": "string", "const": "list" }, "pagination": { "$ref": "#/components/schemas/V1PaginationMeta" }, "request_id": { "type": "string", "minLength": 1, "maxLength": 128 }, "resource": { "type": "string", "const": "business_balance_sheet_reconciliation" }, "scope": { "type": "string", "const": "business.balance_sheet_reconciliations.read" } } }, "V1BusinessBalanceSheetReconciliationMeta": { "type": "object", "required": [ "api_version", "mode", "request_id", "resource", "scope" ], "properties": { "api_version": { "type": "string", "const": "v1-2026-07" }, "mode": { "type": "string", "const": "detail" }, "request_id": { "type": "string", "minLength": 1, "maxLength": 128 }, "resource": { "type": "string", "const": "business_balance_sheet_reconciliation" }, "scope": { "type": "string", "const": "business.balance_sheet_reconciliations.read" } } }, "V1BusinessBalanceSheetReconciliationListResponse": { "type": "object", "required": [ "data", "meta" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/BusinessBalanceSheetReconciliationSummary" } }, "meta": { "$ref": "#/components/schemas/V1BusinessBalanceSheetReconciliationListMeta" } } }, "V1BusinessBalanceSheetReconciliationResponse": { "type": "object", "required": [ "data", "meta" ], "properties": { "data": { "$ref": "#/components/schemas/BusinessBalanceSheetReconciliation" }, "meta": { "$ref": "#/components/schemas/V1BusinessBalanceSheetReconciliationMeta" } } }, "BusinessFixedAssetCreateRequest": { "type": "object", "additionalProperties": false, "required": [ "asset_class_id", "description", "acquisition_date", "acquisition_cost" ], "properties": { "asset_class_id": { "type": "string", "format": "uuid" }, "asset_number": { "type": "string", "nullable": true, "maxLength": 100 }, "description": { "type": "string", "maxLength": 500 }, "supplier_id": { "type": "string", "format": "uuid", "nullable": true }, "location": { "type": "string", "nullable": true, "maxLength": 200 }, "acquisition_date": { "type": "string", "format": "date" }, "acquisition_cost": { "type": "number", "exclusiveMinimum": 0 }, "residual_value": { "type": "number", "minimum": 0, "default": 0 }, "useful_life_months": { "type": "integer", "minimum": 1, "maximum": 1200, "default": 36 }, "depreciation_method": { "type": "string", "enum": [ "straight_line", "reducing_balance", "none" ], "default": "straight_line" }, "notes": { "type": "string", "nullable": true, "maxLength": 2000 }, "cost_center_id": { "type": "string", "format": "uuid", "nullable": true }, "fund_id": { "type": "string", "format": "uuid", "nullable": true }, "project_id": { "type": "string", "format": "uuid", "nullable": true }, "opening_depreciation_period_date": { "type": "string", "format": "date", "nullable": true }, "opening_accumulated_depreciation": { "type": "number", "minimum": 0, "nullable": true }, "opening_net_book_value": { "type": "number", "minimum": 0, "nullable": true } }, "description": "Creates one fixed asset register record. Optional opening depreciation seeds the latest saved schedule; it does not post depreciation or journals." }, "BusinessFixedAssetCorrectionRequest": { "type": "object", "additionalProperties": false, "required": [ "reason" ], "minProperties": 2, "properties": { "asset_class_id": { "type": "string", "format": "uuid" }, "asset_number": { "type": "string", "maxLength": 100 }, "description": { "type": "string", "maxLength": 500 }, "acquisition_date": { "type": "string", "format": "date" }, "acquisition_cost": { "type": "number", "exclusiveMinimum": 0 }, "residual_value": { "type": "number", "minimum": 0 }, "useful_life_months": { "type": "integer", "minimum": 1, "maximum": 1200 }, "depreciation_method": { "type": "string", "enum": [ "straight_line", "reducing_balance", "none" ] }, "location": { "type": "string", "nullable": true, "maxLength": 200 }, "notes": { "type": "string", "nullable": true, "maxLength": 2000 }, "reason": { "type": "string", "maxLength": 500 } }, "description": "Corrects safe fixed asset register fields and requires a reason for the audit trail. It cannot dispose assets, post depreciation or move money." }, "V1BusinessFixedAssetCreateMeta": { "type": "object", "additionalProperties": false, "required": [ "api_version", "mode", "resource", "request_id", "scope" ], "properties": { "api_version": { "type": "string", "enum": [ "v1-2026-07" ] }, "mode": { "type": "string", "const": "created" }, "request_id": { "type": "string" }, "resource": { "type": "string", "const": "business_fixed_asset" }, "scope": { "type": "string", "const": "business.fixed_assets.create" } } }, "V1BusinessFixedAssetCorrectionMeta": { "type": "object", "additionalProperties": false, "required": [ "api_version", "mode", "resource", "request_id", "scope" ], "properties": { "api_version": { "type": "string", "enum": [ "v1-2026-07" ] }, "mode": { "type": "string", "const": "updated" }, "request_id": { "type": "string" }, "resource": { "type": "string", "const": "business_fixed_asset" }, "scope": { "type": "string", "const": "business.fixed_assets.correct" } } }, "BusinessFixedAssetCreateResponse": { "type": "object", "additionalProperties": false, "required": [ "data", "meta" ], "properties": { "data": { "$ref": "#/components/schemas/BusinessFixedAsset" }, "meta": { "$ref": "#/components/schemas/V1BusinessFixedAssetCreateMeta" } } }, "BusinessFixedAssetCorrectionResponse": { "type": "object", "additionalProperties": false, "required": [ "data", "meta" ], "properties": { "data": { "$ref": "#/components/schemas/BusinessFixedAsset" }, "meta": { "$ref": "#/components/schemas/V1BusinessFixedAssetCorrectionMeta" } } }, "BusinessFixedAssetDisposalRequest": { "type": "object", "additionalProperties": false, "required": [ "disposal_date", "disposal_proceeds", "proceeds_account_id", "reason" ], "properties": { "disposal_date": { "type": "string", "format": "date" }, "disposal_proceeds": { "type": "number", "minimum": 0 }, "proceeds_account_id": { "type": "string", "format": "uuid" }, "gain_account_code": { "type": "string", "maxLength": 20 }, "loss_account_code": { "type": "string", "maxLength": 20 }, "reason": { "type": "string", "maxLength": 500 } }, "description": "Disposes one fixed asset and posts the disposal journal through the fixed-asset lifecycle workflow. Requires a reason for the public API audit trail." }, "V1BusinessFixedAssetDisposalMeta": { "type": "object", "additionalProperties": false, "required": [ "api_version", "mode", "resource", "request_id", "scope", "journal_transaction_id", "reference", "disposal_proceeds", "accumulated_depreciation", "net_book_value", "gain_loss" ], "properties": { "api_version": { "type": "string", "enum": [ "v1-2026-07" ] }, "mode": { "type": "string", "const": "disposed" }, "request_id": { "type": "string" }, "resource": { "type": "string", "const": "business_fixed_asset" }, "scope": { "type": "string", "const": "business.fixed_assets.dispose" }, "journal_transaction_id": { "type": "string", "format": "uuid", "nullable": true }, "reference": { "type": "string", "nullable": true }, "disposal_proceeds": { "type": "number", "nullable": true }, "accumulated_depreciation": { "type": "number", "nullable": true }, "net_book_value": { "type": "number", "nullable": true }, "gain_loss": { "type": "number", "nullable": true } } }, "BusinessFixedAssetDisposalResponse": { "type": "object", "additionalProperties": false, "required": [ "data", "meta" ], "properties": { "data": { "$ref": "#/components/schemas/BusinessFixedAsset" }, "meta": { "$ref": "#/components/schemas/V1BusinessFixedAssetDisposalMeta" } } }, "BusinessFixedAssetDisposalReversalRequest": { "type": "object", "additionalProperties": false, "required": [ "reason" ], "properties": { "reason": { "type": "string", "maxLength": 500 } }, "description": "Reverses a fixed asset disposal and posts a reversing journal through the fixed-asset lifecycle workflow. Requires a reason for the audit trail." }, "V1BusinessFixedAssetDisposalReversalMeta": { "type": "object", "additionalProperties": false, "required": [ "api_version", "mode", "resource", "request_id", "scope", "journal_transaction_id", "original_journal_transaction_id", "reference", "asset_status", "already_reversed" ], "properties": { "api_version": { "type": "string", "enum": [ "v1-2026-07" ] }, "mode": { "type": "string", "const": "disposal_reversed" }, "request_id": { "type": "string" }, "resource": { "type": "string", "const": "business_fixed_asset" }, "scope": { "type": "string", "const": "business.fixed_assets.reverse_disposal" }, "journal_transaction_id": { "type": "string", "format": "uuid", "nullable": true }, "original_journal_transaction_id": { "type": "string", "format": "uuid", "nullable": true }, "reference": { "type": "string", "nullable": true }, "asset_status": { "type": "string", "nullable": true }, "already_reversed": { "type": "boolean" } } }, "BusinessFixedAssetDisposalReversalResponse": { "type": "object", "additionalProperties": false, "required": [ "data", "meta" ], "properties": { "data": { "$ref": "#/components/schemas/BusinessFixedAsset" }, "meta": { "$ref": "#/components/schemas/V1BusinessFixedAssetDisposalReversalMeta" } } }, "BusinessFixedAssetClassGeneratedAccount": { "type": "object", "additionalProperties": false, "required": [ "role", "id", "code", "name" ], "properties": { "role": { "type": "string", "enum": [ "asset_cost", "accumulated_depreciation", "depreciation_expense", "fair_value_movement" ] }, "id": { "type": "string", "format": "uuid", "nullable": true }, "code": { "type": "string", "nullable": true }, "name": { "type": "string", "nullable": true } } }, "BusinessFixedAssetClassCreateRequest": { "type": "object", "additionalProperties": false, "required": [ "name" ], "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 120 }, "code_prefix": { "type": "string", "minLength": 1, "maxLength": 20, "nullable": true, "description": "Optional asset number prefix. When omitted, FIQ derives one from the class name." }, "asset_type": { "type": "string", "enum": [ "tangible", "intangible", "investment" ], "default": "tangible" }, "default_depreciation_method": { "type": "string", "enum": [ "straight_line", "reducing_balance", "none" ], "default": "straight_line" }, "default_useful_life_months": { "type": "integer", "minimum": 0, "maximum": 1200, "description": "Use 0 only when default_depreciation_method is none." }, "default_residual_value": { "type": "number", "minimum": 0, "maximum": 100, "multipleOf": 0.01, "default": 0, "description": "Default residual value percentage used by the setup UI." }, "description": { "type": "string", "maxLength": 500, "nullable": true } } }, "BusinessFixedAssetClassArchiveRequest": { "type": "object", "additionalProperties": false, "required": [ "reason" ], "properties": { "reason": { "type": "string", "minLength": 1, "maxLength": 500 } } }, "V1BusinessFixedAssetClassListMeta": { "type": "object", "additionalProperties": false, "required": [ "api_version", "mode", "request_id", "resource", "pagination" ], "properties": { "api_version": { "type": "string" }, "mode": { "type": "string", "const": "list" }, "request_id": { "type": "string" }, "resource": { "type": "string", "const": "business_fixed_asset_class" }, "pagination": { "$ref": "#/components/schemas/V1PaginationMeta" } } }, "V1BusinessFixedAssetClassDetailMeta": { "type": "object", "additionalProperties": false, "required": [ "api_version", "mode", "request_id", "resource" ], "properties": { "api_version": { "type": "string" }, "mode": { "type": "string", "enum": [ "detail" ] }, "request_id": { "type": "string" }, "resource": { "type": "string", "const": "business_fixed_asset_class" } } }, "V1BusinessFixedAssetClassCreateMeta": { "type": "object", "additionalProperties": false, "required": [ "api_version", "mode", "request_id", "resource", "scope", "generated_accounts" ], "properties": { "api_version": { "type": "string" }, "mode": { "type": "string", "const": "created" }, "request_id": { "type": "string" }, "resource": { "type": "string", "const": "business_fixed_asset_class" }, "scope": { "type": "string", "const": "business.fixed_asset_classes.create" }, "generated_accounts": { "type": "array", "items": { "$ref": "#/components/schemas/BusinessFixedAssetClassGeneratedAccount" } } } }, "V1BusinessFixedAssetClassArchiveMeta": { "type": "object", "additionalProperties": false, "required": [ "api_version", "mode", "request_id", "resource", "scope", "already_archived", "archived_account_ids" ], "properties": { "api_version": { "type": "string" }, "mode": { "type": "string", "const": "archived" }, "request_id": { "type": "string" }, "resource": { "type": "string", "const": "business_fixed_asset_class" }, "scope": { "type": "string", "const": "business.fixed_asset_classes.archive" }, "already_archived": { "type": "boolean" }, "archived_account_ids": { "type": "array", "items": { "type": "string", "format": "uuid" } } } }, "BusinessFixedAssetClassListResponse": { "type": "object", "additionalProperties": false, "required": [ "data", "meta" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/BusinessFixedAssetClass" } }, "meta": { "$ref": "#/components/schemas/V1BusinessFixedAssetClassListMeta" } } }, "BusinessFixedAssetClassDetailResponse": { "type": "object", "additionalProperties": false, "required": [ "data", "meta" ], "properties": { "data": { "$ref": "#/components/schemas/BusinessFixedAssetClass" }, "meta": { "$ref": "#/components/schemas/V1BusinessFixedAssetClassDetailMeta" } } }, "BusinessFixedAssetClassCreateResponse": { "type": "object", "additionalProperties": false, "required": [ "data", "meta" ], "properties": { "data": { "$ref": "#/components/schemas/BusinessFixedAssetClass" }, "meta": { "$ref": "#/components/schemas/V1BusinessFixedAssetClassCreateMeta" } } }, "BusinessFixedAssetClassArchiveResponse": { "type": "object", "additionalProperties": false, "required": [ "data", "meta" ], "properties": { "data": { "$ref": "#/components/schemas/BusinessFixedAssetClass" }, "meta": { "$ref": "#/components/schemas/V1BusinessFixedAssetClassArchiveMeta" } } }, "PersonalAccessTokenResponse": { "type": "object", "required": [ "data", "meta" ], "properties": { "data": { "type": "object", "required": [ "object", "api_version", "consent_request_id", "token", "token_record", "authorised_user_id", "requested_client", "granted_scopes", "oauth", "safety_boundaries" ], "properties": { "object": { "type": "string", "const": "personal_access_token" }, "api_version": { "type": "string", "const": "v1-2026-07" }, "consent_request_id": { "type": "string", "format": "uuid" }, "token": { "type": "object", "required": [ "access_token", "token_type", "expires_at", "expires_in", "refresh_token", "refresh_token_expires_at", "refresh_expires_in" ], "properties": { "access_token": { "type": "string", "pattern": "^fiq_usr_[a-f0-9]{64}$" }, "token_type": { "type": "string", "const": "Bearer" }, "expires_at": { "type": "string", "format": "date-time" }, "expires_in": { "type": "integer", "minimum": 0 }, "refresh_token": { "type": "string", "pattern": "^fiq_rfr_[a-f0-9]{64}$" }, "refresh_token_expires_at": { "type": "string", "format": "date-time" }, "refresh_expires_in": { "type": "integer", "minimum": 0 } } }, "token_record": { "type": "object", "required": [ "id", "status", "token_last4", "refresh_token_last4" ], "properties": { "id": { "type": "string", "format": "uuid" }, "status": { "type": "string", "const": "active" }, "token_last4": { "type": "string", "minLength": 4, "maxLength": 4 }, "refresh_token_last4": { "type": "string", "pattern": "^[a-f0-9]{4}$" } } }, "authorised_user_id": { "type": "string", "format": "uuid" }, "requested_client": { "type": "object", "additionalProperties": true }, "granted_scopes": { "type": "array", "items": { "type": "string" } }, "oauth": { "type": "object", "required": [ "consent_granted", "token_issuing", "refresh_tokens", "approval_flow" ], "properties": { "consent_granted": { "type": "boolean", "const": true }, "token_issuing": { "type": "string", "const": "access_token_issued" }, "refresh_tokens": { "type": "string", "const": "rotating_refresh_token_issued" }, "approval_flow": { "type": "string", "const": "user_authorised_v1" } } }, "safety_boundaries": { "type": "array", "items": { "type": "string" } } } }, "meta": { "$ref": "#/components/schemas/V1Meta" } } }, "PersonalAccessTokenRefreshRequest": { "type": "object", "additionalProperties": false, "required": [ "refresh_token" ], "properties": { "refresh_token": { "type": "string", "pattern": "^fiq_rfr_[a-f0-9]{64}$" } } }, "PersonalAccessTokenRefreshResponse": { "type": "object", "additionalProperties": false, "required": [ "data", "meta" ], "properties": { "data": { "type": "object", "additionalProperties": false, "required": [ "object", "api_version", "token", "token_record", "authorised_user_id", "granted_scopes", "oauth", "safety_boundaries" ], "properties": { "object": { "type": "string", "const": "personal_access_token" }, "api_version": { "type": "string", "const": "v1-2026-07" }, "token": { "type": "object", "additionalProperties": false, "required": [ "access_token", "token_type", "expires_at", "expires_in", "refresh_token", "refresh_token_expires_at", "refresh_expires_in" ], "properties": { "access_token": { "type": "string", "pattern": "^fiq_usr_[a-f0-9]{64}$" }, "token_type": { "type": "string", "const": "Bearer" }, "expires_at": { "type": "string", "format": "date-time" }, "expires_in": { "type": "integer", "minimum": 0 }, "refresh_token": { "type": "string", "pattern": "^fiq_rfr_[a-f0-9]{64}$" }, "refresh_token_expires_at": { "type": "string", "format": "date-time" }, "refresh_expires_in": { "type": "integer", "minimum": 0 } } }, "token_record": { "type": "object", "additionalProperties": false, "required": [ "id", "status", "token_last4", "refresh_token_last4" ], "properties": { "id": { "type": "string", "format": "uuid" }, "status": { "type": "string", "const": "active" }, "token_last4": { "type": "string", "pattern": "^[a-f0-9]{4}$" }, "refresh_token_last4": { "type": "string", "pattern": "^[a-f0-9]{4}$" } } }, "authorised_user_id": { "type": "string", "format": "uuid" }, "granted_scopes": { "type": "array", "items": { "type": "string" } }, "oauth": { "type": "object", "additionalProperties": false, "required": [ "refresh_tokens", "token_issuing" ], "properties": { "refresh_tokens": { "type": "string", "const": "rotated" }, "token_issuing": { "type": "string", "const": "access_token_rotated" } } }, "safety_boundaries": { "type": "array", "items": { "type": "string" } } } }, "meta": { "type": "object", "additionalProperties": true, "required": [ "api_version", "request_id", "resource" ], "properties": { "api_version": { "type": "string", "const": "v1-2026-07" }, "request_id": { "type": "string" }, "resource": { "type": "string", "const": "personal_access_token_refresh" } } } } }, "PersonalAccessTokenRecord": { "type": "object", "additionalProperties": false, "required": [ "object", "id", "api_version", "consent_request_id", "status", "effective_status", "token_last4", "refresh_token_last4", "refresh_token_expires_at", "granted_scopes", "authorised_user_id", "created_at", "expires_at", "last_used_at", "revoked_at", "requested_client", "oauth", "safety_boundaries" ], "properties": { "object": { "type": "string", "const": "personal_access_token" }, "id": { "type": "string", "format": "uuid" }, "api_version": { "type": "string", "const": "v1-2026-07" }, "consent_request_id": { "type": "string", "format": "uuid" }, "status": { "type": "string", "enum": [ "active", "revoked", "expired" ] }, "effective_status": { "type": "string", "enum": [ "active", "revoked", "expired" ] }, "token_last4": { "type": "string", "pattern": "^[a-f0-9]{4}$" }, "refresh_token_last4": { "anyOf": [ { "type": "string", "pattern": "^[a-f0-9]{4}$" }, { "type": "null" } ] }, "refresh_token_expires_at": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ] }, "granted_scopes": { "type": "array", "items": { "type": "string" } }, "authorised_user_id": { "type": "string", "format": "uuid" }, "created_at": { "type": "string", "format": "date-time" }, "expires_at": { "type": "string", "format": "date-time" }, "last_used_at": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ] }, "revoked_at": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ] }, "requested_client": { "anyOf": [ { "type": "object", "additionalProperties": false, "required": [ "client_name", "purpose", "redirect_uri", "state_present" ], "properties": { "client_name": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "purpose": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "redirect_uri": { "anyOf": [ { "type": "string", "format": "uri" }, { "type": "null" } ] }, "state_present": { "type": "boolean" } } }, { "type": "null" } ] }, "oauth": { "type": "object", "additionalProperties": false, "required": [ "refresh_tokens", "revocation" ], "properties": { "refresh_tokens": { "type": "string", "enum": [ "not_issued", "rotating_refresh_token_issued" ] }, "revocation": { "type": "string", "enum": [ "user_self_service", "already_revoked" ] } } }, "safety_boundaries": { "type": "array", "items": { "type": "string" } } } }, "PersonalAccessTokenListResponse": { "type": "object", "additionalProperties": false, "required": [ "data", "meta" ], "properties": { "data": { "type": "object", "additionalProperties": false, "required": [ "object", "api_version", "items", "limit", "has_more", "safety_boundaries" ], "properties": { "object": { "type": "string", "const": "personal_access_token_list" }, "api_version": { "type": "string", "const": "v1-2026-07" }, "items": { "type": "array", "items": { "$ref": "#/components/schemas/PersonalAccessTokenRecord" } }, "limit": { "type": "integer", "const": 100 }, "has_more": { "type": "boolean", "const": false }, "safety_boundaries": { "type": "array", "items": { "type": "string" } } } }, "meta": { "type": "object", "additionalProperties": true, "required": [ "api_version", "request_id", "resource" ], "properties": { "api_version": { "type": "string", "const": "v1-2026-07" }, "request_id": { "type": "string" }, "resource": { "type": "string", "const": "personal_access_tokens" } } } } }, "PersonalAccessTokenLifecycleResponse": { "type": "object", "additionalProperties": false, "required": [ "data", "meta" ], "properties": { "data": { "allOf": [ { "$ref": "#/components/schemas/PersonalAccessTokenRecord" }, { "type": "object", "required": [ "revocation" ], "properties": { "revocation": { "type": "object", "additionalProperties": false, "required": [ "mode" ], "properties": { "mode": { "type": "string", "enum": [ "revoked", "already_revoked" ] } } } } } ] }, "meta": { "type": "object", "additionalProperties": true, "required": [ "api_version", "request_id", "resource" ], "properties": { "api_version": { "type": "string", "const": "v1-2026-07" }, "request_id": { "type": "string" }, "resource": { "type": "string", "const": "personal_access_token" } } } } }, "BusinessQuoteConversionRequest": { "type": "object", "additionalProperties": false, "properties": { "invoice_date": { "type": "string", "format": "date", "pattern": "^\\d{4}-\\d{2}-\\d{2}$", "description": "Optional invoice date. Defaults to the current date." }, "due_date": { "type": "string", "format": "date", "pattern": "^\\d{4}-\\d{2}-\\d{2}$", "description": "Optional due date. Must be on or after invoice_date when both are supplied." }, "payment_terms_days": { "type": "integer", "minimum": 0, "maximum": 3650, "description": "Optional payment terms in days. Used to calculate due_date when due_date is not supplied." } } }, "QuoteConversionEffects": { "type": "object", "additionalProperties": false, "required": [ "accounting_entries_posted", "invoice_status", "invoice_type", "external_send_performed", "money_movement_performed", "tax_filing_performed" ], "properties": { "accounting_entries_posted": { "type": "boolean", "const": true }, "invoice_status": { "type": "string", "const": "issued" }, "invoice_type": { "type": "string", "const": "issued" }, "external_send_performed": { "type": "boolean", "const": false }, "money_movement_performed": { "type": "boolean", "const": false }, "tax_filing_performed": { "type": "boolean", "const": false } } }, "QuoteConversionInvoice": { "type": "object", "additionalProperties": true, "required": [ "object", "id", "status", "posted_to_ledger" ], "properties": { "object": { "type": "string", "const": "invoice" }, "id": { "type": "string", "format": "uuid" }, "company_id": { "type": "string", "format": "uuid" }, "customer_id": { "type": "string", "format": "uuid" }, "invoice_number": { "type": "string" }, "invoice_date": { "type": "string", "format": "date" }, "due_date": { "type": [ "string", "null" ], "format": "date" }, "status": { "type": "string", "const": "issued" }, "currency": { "type": "string" }, "total_amount": { "type": "number" }, "posted_to_ledger": { "type": "boolean", "const": true }, "customers": { "$ref": "#/components/schemas/InvoiceCustomer" }, "invoice_line_items": { "type": "array", "items": { "$ref": "#/components/schemas/InvoiceLineItem" } } } }, "QuoteConversion": { "type": "object", "additionalProperties": false, "required": [ "object", "effects", "invoice", "quote" ], "properties": { "object": { "type": "string", "const": "quote_conversion" }, "effects": { "$ref": "#/components/schemas/QuoteConversionEffects" }, "invoice": { "$ref": "#/components/schemas/QuoteConversionInvoice" }, "quote": { "$ref": "#/components/schemas/Quote" } } }, "V1BusinessQuoteConversionMeta": { "type": "object", "required": [ "api_version", "mode", "request_id", "resource" ], "properties": { "api_version": { "type": "string", "const": "v1-2026-07" }, "mode": { "type": "string", "const": "converted" }, "request_id": { "type": "string", "minLength": 1, "maxLength": 128 }, "resource": { "type": "string", "const": "quote_conversion" } } }, "V1BusinessQuoteConversionResponse": { "type": "object", "required": [ "data", "meta" ], "properties": { "data": { "$ref": "#/components/schemas/QuoteConversion" }, "meta": { "$ref": "#/components/schemas/V1BusinessQuoteConversionMeta" } } }, "CreditNoteIssueEffects": { "type": "object", "additionalProperties": false, "required": [ "accounting_entries_posted", "credit_note_status", "external_send_performed", "money_movement_performed", "tax_filing_performed" ], "properties": { "accounting_entries_posted": { "type": "boolean", "const": true }, "credit_note_status": { "type": "string", "const": "issued" }, "external_send_performed": { "type": "boolean", "const": false }, "money_movement_performed": { "type": "boolean", "const": false }, "tax_filing_performed": { "type": "boolean", "const": false } } }, "CreditNoteIssue": { "type": "object", "additionalProperties": false, "required": [ "object", "effects", "credit_note", "journal_transaction_id" ], "properties": { "object": { "type": "string", "const": "credit_note_issue" }, "effects": { "$ref": "#/components/schemas/CreditNoteIssueEffects" }, "credit_note": { "$ref": "#/components/schemas/CreditNote" }, "journal_transaction_id": { "type": [ "string", "null" ], "format": "uuid" } } }, "V1BusinessCreditNoteIssueMeta": { "type": "object", "required": [ "api_version", "mode", "request_id", "resource" ], "properties": { "api_version": { "type": "string", "const": "v1-2026-07" }, "mode": { "type": "string", "const": "issued" }, "request_id": { "type": "string", "minLength": 1, "maxLength": 128 }, "resource": { "type": "string", "const": "credit_note_issue" } } }, "V1BusinessCreditNoteIssueResponse": { "type": "object", "required": [ "data", "meta" ], "properties": { "data": { "$ref": "#/components/schemas/CreditNoteIssue" }, "meta": { "$ref": "#/components/schemas/V1BusinessCreditNoteIssueMeta" } } }, "InvoiceIssueEffects": { "type": "object", "additionalProperties": false, "required": [ "accounting_entries_posted", "external_send_performed", "inventory_effects_processed", "invoice_status", "money_movement_performed", "payment_link_created", "tax_filing_performed", "vat_entries_recorded" ], "properties": { "accounting_entries_posted": { "type": "boolean", "const": true }, "external_send_performed": { "type": "boolean", "const": false }, "inventory_effects_processed": { "type": "boolean", "const": true }, "invoice_status": { "type": "string", "const": "issued" }, "money_movement_performed": { "type": "boolean", "const": false }, "payment_link_created": { "type": "boolean", "const": false }, "tax_filing_performed": { "type": "boolean", "const": false }, "vat_entries_recorded": { "type": "boolean" } } }, "InvoiceIssue": { "type": "object", "additionalProperties": false, "required": [ "object", "effects", "invoice", "journal_transaction_id" ], "properties": { "object": { "type": "string", "const": "invoice_issue" }, "effects": { "$ref": "#/components/schemas/InvoiceIssueEffects" }, "invoice": { "$ref": "#/components/schemas/Invoice" }, "journal_transaction_id": { "type": [ "string", "null" ], "format": "uuid" } } }, "V1BusinessInvoiceIssueMeta": { "type": "object", "required": [ "api_version", "mode", "request_id", "resource" ], "properties": { "api_version": { "type": "string", "const": "v1-2026-07" }, "mode": { "type": "string", "const": "issued" }, "request_id": { "type": "string", "minLength": 1, "maxLength": 128 }, "resource": { "type": "string", "const": "invoice_issue" } } }, "V1BusinessInvoiceIssueResponse": { "type": "object", "required": [ "data", "meta" ], "properties": { "data": { "$ref": "#/components/schemas/InvoiceIssue" }, "meta": { "$ref": "#/components/schemas/V1BusinessInvoiceIssueMeta" } } }, "BusinessInvoiceVoidRequest": { "type": "object", "additionalProperties": false, "required": [ "reason" ], "properties": { "reason": { "type": "string", "minLength": 5, "maxLength": 500, "description": "Human-readable audit reason for voiding the invoice." } } }, "InvoiceVoidEffects": { "type": "object", "additionalProperties": false, "required": [ "accounting_reversal_posted", "external_send_performed", "inventory_effects_reversed", "invoice_status", "money_movement_performed", "payment_refund_performed", "tax_filing_performed", "vat_entries_reversed" ], "properties": { "accounting_reversal_posted": { "type": "boolean" }, "external_send_performed": { "type": "boolean", "const": false }, "inventory_effects_reversed": { "type": "boolean" }, "invoice_status": { "type": "string", "const": "voided" }, "money_movement_performed": { "type": "boolean", "const": false }, "payment_refund_performed": { "type": "boolean", "const": false }, "tax_filing_performed": { "type": "boolean", "const": false }, "vat_entries_reversed": { "type": "boolean" } } }, "InvoiceVoid": { "type": "object", "additionalProperties": false, "required": [ "object", "effects", "invoice", "voiding_transaction_id" ], "properties": { "object": { "type": "string", "const": "invoice_void" }, "effects": { "$ref": "#/components/schemas/InvoiceVoidEffects" }, "invoice": { "$ref": "#/components/schemas/Invoice" }, "voiding_transaction_id": { "type": [ "string", "null" ], "format": "uuid" } } }, "V1BusinessInvoiceVoidMeta": { "type": "object", "required": [ "api_version", "mode", "request_id", "resource" ], "properties": { "api_version": { "type": "string", "const": "v1-2026-07" }, "mode": { "type": "string", "enum": [ "voided", "existing" ] }, "request_id": { "type": "string", "minLength": 1, "maxLength": 128 }, "resource": { "type": "string", "const": "invoice_void" } } }, "V1BusinessInvoiceVoidResponse": { "type": "object", "required": [ "data", "meta" ], "properties": { "data": { "$ref": "#/components/schemas/InvoiceVoid" }, "meta": { "$ref": "#/components/schemas/V1BusinessInvoiceVoidMeta" } } }, "BusinessPurchaseInvoiceVoidRequest": { "type": "object", "additionalProperties": false, "required": [ "reason" ], "properties": { "reason": { "type": "string", "minLength": 5, "maxLength": 500, "description": "Human-readable audit reason for voiding the supplier bill." } } }, "PurchaseInvoiceVoidEffects": { "type": "object", "additionalProperties": false, "required": [ "accounting_reversal_posted", "money_movement_performed", "payment_refund_performed", "purchase_invoice_status", "tax_filing_performed", "vat_entries_reversed" ], "properties": { "accounting_reversal_posted": { "type": "boolean" }, "money_movement_performed": { "type": "boolean", "const": false }, "payment_refund_performed": { "type": "boolean", "const": false }, "purchase_invoice_status": { "type": "string", "enum": [ "void", "cancelled" ] }, "tax_filing_performed": { "type": "boolean", "const": false }, "vat_entries_reversed": { "type": "boolean" } } }, "PurchaseInvoiceVoid": { "type": "object", "additionalProperties": false, "required": [ "object", "effects", "purchase_invoice", "reason", "voiding_transaction_id" ], "properties": { "object": { "type": "string", "const": "purchase_invoice_void" }, "effects": { "$ref": "#/components/schemas/PurchaseInvoiceVoidEffects" }, "purchase_invoice": { "$ref": "#/components/schemas/PurchaseInvoice" }, "reason": { "type": "string" }, "voiding_transaction_id": { "type": [ "string", "null" ], "format": "uuid" } } }, "V1BusinessPurchaseInvoiceVoidMeta": { "type": "object", "additionalProperties": false, "required": [ "api_version", "mode", "request_id", "resource" ], "properties": { "api_version": { "type": "string", "const": "v1-2026-07" }, "mode": { "type": "string", "enum": [ "voided", "existing" ] }, "request_id": { "type": "string", "minLength": 1, "maxLength": 128 }, "resource": { "type": "string", "const": "purchase_invoice_void" } } }, "V1BusinessPurchaseInvoiceVoidResponse": { "type": "object", "additionalProperties": false, "required": [ "data", "meta" ], "properties": { "data": { "$ref": "#/components/schemas/PurchaseInvoiceVoid" }, "meta": { "$ref": "#/components/schemas/V1BusinessPurchaseInvoiceVoidMeta" } } }, "BusinessExpenseClaimVoidRequest": { "type": "object", "additionalProperties": false, "required": [ "reason" ], "properties": { "reason": { "type": "string", "minLength": 5, "maxLength": 500, "description": "Human-readable audit reason for voiding the expense claim." } } }, "ExpenseClaimVoidEffects": { "type": "object", "additionalProperties": false, "required": [ "expense_claim_status", "journal_transaction_voided", "linked_purchase_invoice_voided", "money_movement_performed", "payment_refund_performed", "tax_filing_performed" ], "properties": { "expense_claim_status": { "type": "string", "enum": [ "void" ] }, "journal_transaction_voided": { "type": "boolean" }, "linked_purchase_invoice_voided": { "type": "boolean" }, "money_movement_performed": { "type": "boolean", "const": false }, "payment_refund_performed": { "type": "boolean", "const": false }, "tax_filing_performed": { "type": "boolean", "const": false } } }, "ExpenseClaimVoid": { "type": "object", "additionalProperties": false, "required": [ "object", "effects", "expense_claim", "journal_transaction_id", "linked_purchase_invoice_id", "reason" ], "properties": { "object": { "type": "string", "const": "expense_claim_void" }, "effects": { "$ref": "#/components/schemas/ExpenseClaimVoidEffects" }, "expense_claim": { "$ref": "#/components/schemas/ExpenseClaim" }, "journal_transaction_id": { "type": [ "string", "null" ], "format": "uuid" }, "linked_purchase_invoice_id": { "type": [ "string", "null" ], "format": "uuid" }, "reason": { "type": "string" } } }, "V1BusinessExpenseClaimVoidMeta": { "type": "object", "additionalProperties": false, "required": [ "api_version", "mode", "request_id", "resource" ], "properties": { "api_version": { "type": "string", "const": "v1-2026-07" }, "mode": { "type": "string", "enum": [ "voided", "existing" ] }, "request_id": { "type": "string", "minLength": 1, "maxLength": 128 }, "resource": { "type": "string", "const": "expense_claim_void" } } }, "V1BusinessExpenseClaimVoidResponse": { "type": "object", "additionalProperties": false, "required": [ "data", "meta" ], "properties": { "data": { "$ref": "#/components/schemas/ExpenseClaimVoid" }, "meta": { "$ref": "#/components/schemas/V1BusinessExpenseClaimVoidMeta" } } }, "BusinessCreditNoteCancelRequest": { "type": "object", "additionalProperties": false, "required": [ "reason" ], "properties": { "reason": { "type": "string", "minLength": 5, "maxLength": 500, "description": "Human-readable audit reason for cancelling the credit note." } } }, "CreditNoteCancelEffects": { "type": "object", "additionalProperties": false, "required": [ "credit_note_allocations_archived", "credit_note_status", "journal_transaction_voided", "money_movement_performed", "payment_refund_performed", "tax_filing_performed", "vat_transactions_archived" ], "properties": { "credit_note_allocations_archived": { "type": "boolean" }, "credit_note_status": { "type": "string", "const": "cancelled" }, "journal_transaction_voided": { "type": "boolean" }, "money_movement_performed": { "type": "boolean", "const": false }, "payment_refund_performed": { "type": "boolean", "const": false }, "tax_filing_performed": { "type": "boolean", "const": false }, "vat_transactions_archived": { "type": "boolean" } } }, "CreditNoteCancel": { "type": "object", "additionalProperties": false, "required": [ "object", "effects", "credit_note", "journal_transaction_id", "reason" ], "properties": { "object": { "type": "string", "const": "credit_note_cancel" }, "effects": { "$ref": "#/components/schemas/CreditNoteCancelEffects" }, "credit_note": { "$ref": "#/components/schemas/CreditNote" }, "journal_transaction_id": { "type": [ "string", "null" ], "format": "uuid" }, "reason": { "type": "string" } } }, "V1BusinessCreditNoteCancelMeta": { "type": "object", "additionalProperties": false, "required": [ "api_version", "mode", "request_id", "resource" ], "properties": { "api_version": { "type": "string", "const": "v1-2026-07" }, "mode": { "type": "string", "enum": [ "cancelled", "existing" ] }, "request_id": { "type": "string", "minLength": 1, "maxLength": 128 }, "resource": { "type": "string", "const": "credit_note_cancel" } } }, "V1BusinessCreditNoteCancelResponse": { "type": "object", "additionalProperties": false, "required": [ "data", "meta" ], "properties": { "data": { "$ref": "#/components/schemas/CreditNoteCancel" }, "meta": { "$ref": "#/components/schemas/V1BusinessCreditNoteCancelMeta" } } }, "V1BusinessGiftAidSubmissionRequestCreate": { "type": "object", "additionalProperties": false, "required": ["submission_type"], "properties": { "submission_type": {"type": "string", "enum": ["test", "production"], "default": "test"} } }, "BusinessGiftAidSubmissionRequest": { "type": "object", "additionalProperties": false, "required": ["object", "id", "claim_batch_id", "status", "approval_url", "submission_type", "created_at", "expires_at", "completed_at", "failure_code", "provider_reference", "updated_at"], "properties": { "object": {"type": "string", "const": "business_gift_aid_submission_request"}, "id": {"type": "string", "format": "uuid"}, "claim_batch_id": {"type": "string", "format": "uuid"}, "status": {"type": "string", "enum": ["pending", "consumed", "submitted", "failed", "expired"]}, "approval_url": {"type": ["string", "null"], "format": "uri"}, "submission_type": {"type": "string", "enum": ["test", "production"]}, "created_at": {"type": "string", "format": "date-time"}, "expires_at": {"type": "string", "format": "date-time"}, "completed_at": {"type": ["string", "null"], "format": "date-time"}, "failure_code": {"type": ["string", "null"]}, "provider_reference": {"type": ["string", "null"]}, "updated_at": {"type": "string", "format": "date-time"} } }, "V1BusinessGiftAidSubmissionRequestResponse": { "type": "object", "additionalProperties": false, "required": ["data", "meta"], "properties": { "data": {"$ref": "#/components/schemas/BusinessGiftAidSubmissionRequest"}, "meta": {"$ref": "#/components/schemas/V1Meta"} } }, "BusinessGiftAidClaimBatchCreateRequest": { "type": "object", "additionalProperties": false, "required": [ "batch_reference", "claim_type", "period_start", "period_end" ], "properties": { "batch_reference": { "type": "string", "minLength": 1, "maxLength": 200, "description": "Human-readable draft claim batch reference." }, "claim_type": { "type": "string", "enum": [ "gift_aid", "gasds", "combined" ], "description": "Type of draft claim batch to create." }, "period_start": { "type": "string", "format": "date", "description": "First date covered by the draft claim batch." }, "period_end": { "type": "string", "format": "date", "description": "Last date covered by the draft claim batch. Must be on or after period_start." }, "status": { "type": "string", "enum": [ "draft" ], "default": "draft", "description": "Optional. Only draft is accepted; this route cannot mark a batch ready or submitted." } } }, "V1BusinessGiftAidClaimBatchCreateMeta": { "type": "object", "required": [ "api_version", "mode", "request_id", "resource" ], "properties": { "api_version": { "type": "string", "const": "v1-2026-07" }, "mode": { "type": "string", "const": "created" }, "request_id": { "type": "string", "minLength": 1, "maxLength": 128 }, "resource": { "type": "string", "const": "business_gift_aid_claim_batch" } } }, "BusinessGiftAidClaimBatchCreateResponse": { "type": "object", "additionalProperties": false, "required": [ "data", "meta" ], "properties": { "data": { "$ref": "#/components/schemas/BusinessGiftAidClaimBatch" }, "meta": { "$ref": "#/components/schemas/V1BusinessGiftAidClaimBatchCreateMeta" } } }, "BusinessCostCenterOptionListMeta": { "type": "object", "required": [ "api_version", "cost_center_level_id", "mode", "pagination", "request_id", "resource" ], "properties": { "api_version": { "type": "string", "const": "v1-2026-07" }, "cost_center_level_id": { "type": "string", "format": "uuid" }, "mode": { "type": "string", "const": "list" }, "pagination": { "$ref": "#/components/schemas/V1PaginationMeta" }, "request_id": { "type": "string", "minLength": 1, "maxLength": 128 }, "resource": { "type": "string", "const": "business_cost_center_option" } } }, "BusinessCostCenterOptionListResponse": { "type": "object", "required": [ "data", "meta" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/BusinessCostCenterOption" } }, "meta": { "$ref": "#/components/schemas/BusinessCostCenterOptionListMeta" } } }, "PersonalBusinessShareholderUpdateRequest": { "type": "object", "additionalProperties": false, "required": [ "weight_override" ], "properties": { "weight_override": { "type": [ "number", "null" ], "exclusiveMinimum": 0, "maximum": 1 } } } } } }