{"openapi":"3.0.0","info":{"version":"1.0.0","title":"Tax Manager API","description":"Multi-platform accounting data parser and tax calculator. Supports FreeAgent exports (Xero and others coming soon) with Polar license validation."},"servers":[{"url":"https://tax-manager-api.yourdomain.com","description":"Production server"}],"components":{"schemas":{},"parameters":{}},"paths":{"/":{"get":{"tags":["Info"],"responses":{"200":{"description":"API information","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string"},"documentation":{"type":"string"}},"required":["message","documentation"]}}}}}}},"/parse":{"post":{"tags":["Data Import"],"security":[{"bearerAuth":[]}],"requestBody":{"required":true,"content":{"text/plain":{"schema":{"type":"string"}},"application/json":{"schema":{"type":"object","properties":{"filePath":{"type":"string"},"csvData":{"type":"string"}}}}}},"responses":{"200":{"description":"Data parsed successfully (CSV or Excel)","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string"},"accountingYear":{"type":"string"},"provider":{"type":"string"},"source":{"type":"string","enum":["csv","excel"]},"categoriesCount":{"type":"number"},"summary":{"nullable":true}},"required":["message","accountingYear","provider","source"]}}}},"400":{"description":"Bad request","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"}},"required":["error"]}}}}}}},"/categories":{"get":{"tags":["Categories"],"security":[{"bearerAuth":[]}],"responses":{"200":{"description":"All categories with totals","content":{"application/json":{"schema":{"type":"object","properties":{"provider":{"type":"string","enum":["freeagent","xero","quickbooks","unknown"]},"accountingYear":{"type":"string"},"categories":{"type":"array","items":{"type":"object","properties":{"code":{"type":"string"},"name":{"type":"string"},"transactionCount":{"type":"number"},"total":{"type":"object","properties":{"date":{"type":"string","example":"31 Jan 26"},"description":{"type":"string","example":"Invoice UNDP-AI-3"},"debit":{"type":"number","example":0},"credit":{"type":"number","example":7689.99},"isTotal":{"type":"boolean","example":false}},"required":["date","description","debit","credit","isTotal"]}},"required":["code","name","transactionCount"]}}},"required":["provider","accountingYear","categories"]}}}},"400":{"description":"No data loaded","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"}},"required":["error"]}}}}}}},"/sales":{"get":{"tags":["Transactions"],"security":[{"bearerAuth":[]}],"responses":{"200":{"description":"Sales transactions","content":{"application/json":{"schema":{"type":"object","properties":{"provider":{"type":"string","enum":["freeagent","xero","quickbooks","unknown"]},"sales":{"type":"array","items":{"type":"object","properties":{"code":{"type":"string","example":"001"},"name":{"type":"string","example":"Sales"},"transactions":{"type":"array","items":{"type":"object","properties":{"date":{"type":"string","example":"31 Jan 26"},"description":{"type":"string","example":"Invoice UNDP-AI-3"},"debit":{"type":"number","example":0},"credit":{"type":"number","example":7689.99},"isTotal":{"type":"boolean","example":false}},"required":["date","description","debit","credit","isTotal"]}},"total":{"type":"object","properties":{"date":{"type":"string","example":"31 Jan 26"},"description":{"type":"string","example":"Invoice UNDP-AI-3"},"debit":{"type":"number","example":0},"credit":{"type":"number","example":7689.99},"isTotal":{"type":"boolean","example":false}},"required":["date","description","debit","credit","isTotal"]}},"required":["code","name","transactions"]}}},"required":["provider","sales"]}}}},"400":{"description":"No data loaded","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"}},"required":["error"]}}}}}}},"/expenses":{"get":{"tags":["Transactions"],"security":[{"bearerAuth":[]}],"responses":{"200":{"description":"Expense transactions","content":{"application/json":{"schema":{"type":"object","properties":{"provider":{"type":"string","enum":["freeagent","xero","quickbooks","unknown"]},"expenses":{"type":"array","items":{"type":"object","properties":{"code":{"type":"string","example":"001"},"name":{"type":"string","example":"Sales"},"transactions":{"type":"array","items":{"type":"object","properties":{"date":{"type":"string","example":"31 Jan 26"},"description":{"type":"string","example":"Invoice UNDP-AI-3"},"debit":{"type":"number","example":0},"credit":{"type":"number","example":7689.99},"isTotal":{"type":"boolean","example":false}},"required":["date","description","debit","credit","isTotal"]}},"total":{"type":"object","properties":{"date":{"type":"string","example":"31 Jan 26"},"description":{"type":"string","example":"Invoice UNDP-AI-3"},"debit":{"type":"number","example":0},"credit":{"type":"number","example":7689.99},"isTotal":{"type":"boolean","example":false}},"required":["date","description","debit","credit","isTotal"]}},"required":["code","name","transactions"]}}},"required":["provider","expenses"]}}}},"400":{"description":"No data loaded","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"}},"required":["error"]}}}}}}},"/dividends":{"get":{"tags":["Transactions"],"security":[{"bearerAuth":[]}],"responses":{"200":{"description":"Dividend transactions","content":{"application/json":{"schema":{"type":"object","properties":{"provider":{"type":"string","enum":["freeagent","xero","quickbooks","unknown"]},"dividends":{"type":"array","items":{"type":"object","properties":{"code":{"type":"string","example":"001"},"name":{"type":"string","example":"Sales"},"transactions":{"type":"array","items":{"type":"object","properties":{"date":{"type":"string","example":"31 Jan 26"},"description":{"type":"string","example":"Invoice UNDP-AI-3"},"debit":{"type":"number","example":0},"credit":{"type":"number","example":7689.99},"isTotal":{"type":"boolean","example":false}},"required":["date","description","debit","credit","isTotal"]}},"total":{"type":"object","properties":{"date":{"type":"string","example":"31 Jan 26"},"description":{"type":"string","example":"Invoice UNDP-AI-3"},"debit":{"type":"number","example":0},"credit":{"type":"number","example":7689.99},"isTotal":{"type":"boolean","example":false}},"required":["date","description","debit","credit","isTotal"]}},"required":["code","name","transactions"]}}},"required":["provider","dividends"]}}}},"400":{"description":"No data loaded","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"}},"required":["error"]}}}}}}},"/summary":{"get":{"tags":["Summary"],"security":[{"bearerAuth":[]}],"responses":{"200":{"description":"Financial summary","content":{"application/json":{"schema":{"type":"object","properties":{"provider":{"type":"string","enum":["freeagent","xero","quickbooks","unknown"]},"accountingYear":{"type":"string"},"totalCategories":{"type":"number"},"totals":{"type":"object","additionalProperties":{"type":"object","properties":{"date":{"type":"string","example":"31 Jan 26"},"description":{"type":"string","example":"Invoice UNDP-AI-3"},"debit":{"type":"number","example":0},"credit":{"type":"number","example":7689.99},"isTotal":{"type":"boolean","example":false}},"required":["date","description","debit","credit","isTotal"]}}},"required":["provider","accountingYear","totalCategories","totals"]}}}},"400":{"description":"No data loaded","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"}},"required":["error"]}}}}}}},"/invoices":{"get":{"tags":["Accounting Views"],"security":[{"bearerAuth":[]}],"responses":{"200":{"description":"Invoice list with status information","content":{"application/json":{"schema":{"type":"object","properties":{"provider":{"type":"string","enum":["freeagent","xero","quickbooks","unknown"]},"accountingYear":{"type":"string"},"invoices":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","example":"CDP-GLOBAL-001"},"date":{"type":"string","example":"31 Jan 26"},"dueDate":{"type":"string","example":"14 Feb 26"},"reference":{"type":"string","example":"Invoice CDP GLOBAL 001"},"contact":{"type":"string","example":"Prism Digital Limited"},"project":{"type":"string","example":"CDP Global"},"totalValue":{"type":"number","example":10800},"status":{"type":"object","properties":{"type":{"type":"string","enum":["open","overdue","paid"],"example":"open"},"message":{"type":"string","example":"Open - due in 16 days"},"date":{"type":"string","example":"31 Jan 26"}},"required":["type","message"]}},"required":["id","date","dueDate","reference","contact","totalValue","status"]}},"summary":{"type":"object","properties":{"totalInvoices":{"type":"number"},"totalValue":{"type":"number"},"open":{"type":"number"},"overdue":{"type":"number"},"paid":{"type":"number"}},"required":["totalInvoices","totalValue","open","overdue","paid"]}},"required":["provider","accountingYear","invoices","summary"]}}}},"400":{"description":"No data loaded","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"}},"required":["error"]}}}}}}},"/salary":{"get":{"tags":["Accounting Views"],"security":[{"bearerAuth":[]}],"responses":{"200":{"description":"Salary information with running balance","content":{"application/json":{"schema":{"type":"object","properties":{"user":{"type":"string","example":"Andrew Maguire"},"taxYear":{"type":"string","example":"2025/26"},"period":{"type":"object","properties":{"start":{"type":"string","example":"06 Apr 25"},"end":{"type":"string","example":"05 Apr 26"}},"required":["start","end"]},"broughtForward":{"type":"number","example":-10473},"transactions":{"type":"array","items":{"type":"object","properties":{"date":{"type":"string","example":"31 Jan 26"},"description":{"type":"string","example":"Bank Of Scotland Pers (Faster Payments Out)"},"type":{"type":"string","example":"Net Salary and Bonuses"},"owed":{"type":"number","example":11500},"paid":{"type":"number","example":1047.5},"balanceOwed":{"type":"number","example":-10473}},"required":["date","description","type","balanceOwed"]}},"currentBalance":{"type":"number","example":0},"provider":{"type":"string","enum":["freeagent","xero","quickbooks","unknown"]}},"required":["user","taxYear","period","broughtForward","transactions","currentBalance","provider"]}}}},"400":{"description":"No data loaded","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"}},"required":["error"]}}}}}}},"/expenses-list":{"get":{"tags":["Accounting Views"],"security":[{"bearerAuth":[]}],"responses":{"200":{"description":"Out-of-pocket expenses list","content":{"application/json":{"schema":{"type":"object","properties":{"user":{"type":"string","example":"Andrew Maguire"},"taxYear":{"type":"string","example":"2025/26"},"expenses":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","example":"EXP-001"},"date":{"type":"string","example":"15 Jan 26"},"description":{"type":"string","example":"Office supplies"},"category":{"type":"string","example":"Office"},"amount":{"type":"number","example":45.99},"receipt":{"type":"boolean","example":true},"status":{"type":"string","enum":["pending","approved","reimbursed"],"example":"pending"}},"required":["id","date","description","category","amount","receipt","status"]}},"total":{"type":"number","example":0},"provider":{"type":"string","enum":["freeagent","xero","quickbooks","unknown"]}},"required":["user","taxYear","expenses","total","provider"]}}}},"400":{"description":"No data loaded","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"}},"required":["error"]}}}}}}},"/corporation-tax":{"get":{"tags":["Tax"],"security":[{"bearerAuth":[]}],"responses":{"200":{"description":"Corporation tax calculation with profit analysis and payment tracking","content":{"application/json":{"schema":{"type":"object","properties":{"taxYear":{"type":"string","example":"2025/26"},"accountingPeriod":{"type":"object","properties":{"start":{"type":"string","example":"01 May 25"},"end":{"type":"string","example":"30 Apr 26"}},"required":["start","end"]},"profit":{"type":"object","properties":{"sales":{"type":"number","example":55739.99},"otherIncome":{"type":"number","example":5443.9},"totalIncome":{"type":"number","example":61183.89},"expenses":{"type":"number","example":15234.56},"netProfit":{"type":"number","example":45949.33}},"required":["sales","otherIncome","totalIncome","expenses","netProfit"]},"taxCalculation":{"type":"object","properties":{"profitBeforeTax":{"type":"number","example":45949.33},"taxableProfit":{"type":"number","example":45949.33},"taxRate":{"type":"number","example":0.19},"taxDue":{"type":"number","example":8730.37},"effectiveRate":{"type":"number","example":0.19}},"required":["profitBeforeTax","taxableProfit","taxRate","taxDue","effectiveRate"]},"payments":{"type":"array","items":{"type":"object","properties":{"date":{"type":"string","example":"31 Jan 26"},"amount":{"type":"number","example":2500},"description":{"type":"string","example":"Corporation Tax Payment"},"taxYear":{"type":"string","example":"2024/25"}},"required":["date","amount","description","taxYear"]}},"balance":{"type":"object","properties":{"totalPaid":{"type":"number","example":2500},"totalDue":{"type":"number","example":8730.37},"outstanding":{"type":"number","example":6230.37},"overpaid":{"type":"number","example":0}},"required":["totalPaid","totalDue","outstanding","overpaid"]},"dueDate":{"type":"string","example":"01 Jan 27"},"status":{"type":"string","enum":["paid","partially-paid","outstanding","overpaid"],"example":"partially-paid"},"provider":{"type":"string","enum":["freeagent","xero","quickbooks","unknown"]}},"required":["taxYear","accountingPeriod","profit","taxCalculation","payments","balance","dueDate","status","provider"]}}}},"400":{"description":"No data loaded","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"}},"required":["error"]}}}}}}},"/personal-allowance":{"get":{"tags":["Tax"],"security":[{"bearerAuth":[]}],"responses":{"200":{"description":"Personal allowance and income tax calculation with band breakdown","content":{"application/json":{"schema":{"type":"object","properties":{"taxYear":{"type":"string","example":"2025/26"},"user":{"type":"string","example":"Andrew Maguire"},"allowances":{"type":"object","properties":{"personalAllowance":{"type":"number","example":12570},"dividendAllowance":{"type":"number","example":500},"personalAllowanceUsed":{"type":"number","example":12570},"personalAllowanceRemaining":{"type":"number","example":0}},"required":["personalAllowance","dividendAllowance","personalAllowanceUsed","personalAllowanceRemaining"]},"income":{"type":"object","properties":{"salary":{"type":"number","example":12570},"dividends":{"type":"number","example":30000},"otherIncome":{"type":"number","example":0},"totalIncome":{"type":"number","example":42570},"taxableIncome":{"type":"number","example":30000}},"required":["salary","dividends","otherIncome","totalIncome","taxableIncome"]},"incomeTax":{"type":"object","properties":{"bands":{"type":"array","items":{"type":"object","properties":{"name":{"type":"string","example":"Basic Rate"},"range":{"type":"string","example":"£12,571 - £50,270"},"rate":{"type":"number","example":0.2},"income":{"type":"number","example":25000},"tax":{"type":"number","example":5000}},"required":["name","range","rate","income","tax"]}},"totalIncomeTax":{"type":"number","example":0}},"required":["bands","totalIncomeTax"]},"dividendTax":{"type":"object","properties":{"taxableDividends":{"type":"number","example":29500},"bands":{"type":"array","items":{"type":"object","properties":{"name":{"type":"string","example":"Basic Rate"},"rate":{"type":"number","example":0.0875},"dividends":{"type":"number","example":15000},"tax":{"type":"number","example":1312.5}},"required":["name","rate","dividends","tax"]}},"totalDividendTax":{"type":"number","example":2581.25}},"required":["taxableDividends","bands","totalDividendTax"]},"summary":{"type":"object","properties":{"totalTaxDue":{"type":"number","example":2581.25},"effectiveRate":{"type":"number","example":0.0606},"takeHomePay":{"type":"number","example":39988.75}},"required":["totalTaxDue","effectiveRate","takeHomePay"]},"payments":{"type":"array","items":{"type":"object","properties":{"date":{"type":"string","example":"31 Jan 26"},"amount":{"type":"number","example":0},"description":{"type":"string"},"method":{"type":"string","enum":["PAYE","Self Assessment","Dividend Tax"]}},"required":["date","amount","description","method"]}},"balance":{"type":"object","properties":{"totalPaid":{"type":"number","example":1200},"totalDue":{"type":"number","example":2581.25},"outstanding":{"type":"number","example":1381.25}},"required":["totalPaid","totalDue","outstanding"]},"provider":{"type":"string","enum":["freeagent","xero","quickbooks","unknown"]}},"required":["taxYear","user","allowances","income","incomeTax","dividendTax","summary","payments","balance","provider"]}}}},"400":{"description":"No data loaded","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"}},"required":["error"]}}}}}}}}}