TaxWhizz.ai — UK Tax Intelligence Platform

API Reference

Base URL:https://api.taxwhizz.ai/api/v1

Authentication

All authenticated endpoints require a JWT Bearer token in the Authorization header. Obtain tokens via the /auth/login endpoint.

Authorization: Bearer eyJhbGciOiJIUzI1NiIs...

Access tokens expire after 15 minutes. Use the /auth/refresh endpoint with your refresh token to obtain a new access token. Refresh tokens are valid for 7 days.

Rate Limits

Tier	Rate Limit
Free	100/day
Starter	1,000/day
Professional	10,000/day
Business	50,000/day
Advisor	Unlimited

Status Codes

Code	Meaning	Description
200	OK	Request succeeded
201	Created	Resource created successfully
400	Bad Request	Invalid parameters or request body
401	Unauthorized	Missing or invalid authentication token
403	Forbidden	Insufficient permissions or tier access
404	Not Found	Requested resource does not exist
429	Too Many Requests	Rate limit exceeded for your tier
500	Internal Server Error	Unexpected server error

Endpoints

POST/auth/registerRegister new user

POST/auth/loginLogin and get tokens

POST/auth/refreshRefresh access token

GET/auth/meGet current user

Examples

Login & Get Tokens

POST/auth/login

// Request
POST /api/v1/auth/login
Content-Type: application/json

{
  "email": "user@example.com",
  "password": "your_password"
}

// Response 200
{
  "user": {
    "id": "uuid-here",
    "email": "user@example.com",
    "full_name": "John Smith",
    "subscription_tier": "professional"
  },
  "tokens": {
    "access_token": "eyJhbG...",
    "refresh_token": "eyJhbG...",
    "token_type": "bearer"
  }
}

Run Income Tax Calculation

POST/calculators/income-tax

// Request
POST /api/v1/calculators/income-tax
Authorization: Bearer YOUR_TOKEN
Content-Type: application/json

{
  "annual_income": 85000,
  "tax_year": "2025/26"
}

// Response 200
{
  "calculator_type": "income-tax",
  "tax_year": "2025/26",
  "results": {
    "gross_income": 85000,
    "personal_allowance": 12570,
    "taxable_income": 72430,
    "income_tax": 17432,
    "effective_rate": 20.51,
    "marginal_rate": 40,
    "bands": [
      { "band": "Basic Rate (20%)", "taxable": 37700, "tax": 7540 },
      { "band": "Higher Rate (40%)", "taxable": 34730, "tax": 13892 }
    ]
  }
}