HMRC & Tax

HMRC Status#

Check whether HMRC is connected and tokens are valid.

const status = await $fetch('https://taxmtd.uk/api/hmrc/status')
// Returns: { connected: boolean, nino: string | null, expiresAt: string | null }

Store NINO#

Save the user's National Insurance Number for HMRC submissions.

await $fetch('https://taxmtd.uk/api/hmrc/nino', {
  method: 'POST',
  body: { nino: 'QQ123456C' }
})

Initiate HMRC OAuth#

Redirects the user to HMRC Gov Gateway for authorisation.

// Server-side redirect to HMRC
const { url } = await $fetch('https://taxmtd.uk/api/hmrc/auth')
navigateTo(url, { external: true })

// After authorisation, HMRC redirects to /api/hmrc/callback
// Tokens are stored automatically

Get SA103 Data#

Retrieve the auto-generated Self-Employment supplement data.

const sa103 = await $fetch('https://taxmtd.uk/api/hmrc/sa103')
// Returns:
// {
//   turnover: 42000,
//   boxes: {
//     box16: 1200,   // Cost of goods
//     box17: 0,      // CIS
//     box18: 0,      // Staff
//     box19: 2400,   // Premises
//     box20: 150,    // Repairs
//     box21: 890,    // Admin
//     box22: 1200,   // Motor
//     box23: 450,    // Travel
//     box24: 300,    // Advertising
//     box25: 120,    // Interest
//     box26: 600,    // Accountancy
//     box27: 250,    // Other
//   },
//   totalExpenses: 7560,
//   netProfit: 34440
// }

National Insurance Annual Summary#

Fetches the HMRC-authoritative Class 1 NICable earnings and Class 2 contributions for the active entity's UTR and the requested tax year. Backs on to GET /national-insurance/sa/{utr}/annual-summary/{taxYear}.

Requires an HMRC-connected session and an entity with a UTR. The OAuth scope read:national-insurance is requested automatically at the connect step.

const ni = await $fetch('https://taxmtd.uk/api/hmrc/ni', {
  query: { entityId: 'entity-uuid', taxYear: '2025' } // taxYear optional
})
// Returns:
// {
//   entityId, entityName, utr,
//   taxYear: '2025-26',
//   class1NICableEarnings: 42000,
//   class2Due: 179.40,
//   maxNICsReached: false,
//   fetchedAt: '...',
//   notFound?: true        // HMRC has no record for this year yet
// }

P&L Report#

const pnl = await $fetch('https://taxmtd.uk/api/reports/pnl', {
  params: { periodId: 1 }
})
// Returns: { totalIncome, totalExpenses, netProfit, categories: {...} }

Disconnect HMRC#

await $fetch('https://taxmtd.uk/api/hmrc/disconnect', {
  method: 'POST'
})