Tax API Reference — GovData Docs

Tax Years

GET /v1/tax/years

List all available tax years.

curl -H "Authorization: Bearer YOUR_API_KEY" \
  https://api.govdata.dev/v1/tax/years

Response

{
  "data": [
    {
      "identifier": "2026-27",
      "start_date": "2026-04-06",
      "end_date": "2027-04-05",
      "active": true,
      "key_dates": {
        "self_assessment_deadline": "2028-01-31",
        "payment_on_account_first": "2027-01-31",
        "payment_on_account_second": "2027-07-31",
        "p60_deadline": "2027-05-31",
        "p11d_deadline": "2027-07-06"
      }
    }
  ],
  "meta": {
    "api_version": "v1",
    "licence": "Open Government Licence v3.0"
  },
  "pagination": { "total": 7, "page": 1, "per_page": 25, "total_pages": 1 }
}

GET /v1/tax/years/current

Returns the current active tax year.

GET /v1/tax/years/:identifier

Returns a specific tax year by identifier.

Parameter	Type	Description
`identifier`	string	Tax year in `YYYY-YY` format (e.g., `2025-26`)

Income Tax

GET /v1/tax/income/bands

Returns income tax bands for the current tax year. Append /:tax_year for a specific year.

curl -H "Authorization: Bearer YOUR_API_KEY" \
  https://api.govdata.dev/v1/tax/income/bands

Response

{
  "data": {
    "tax_year": "2025-26",
    "personal_allowance": 12570,
    "personal_allowance_taper_threshold": 100000,
    "regions": {
      "england_wales_ni": {
        "bands": [
          { "name": "basic_rate", "label": "Basic Rate", "rate": 0.20, "from": 12570, "to": 50270 },
          { "name": "higher_rate", "label": "Higher Rate", "rate": 0.40, "from": 50270, "to": 125140 },
          { "name": "additional_rate", "label": "Additional Rate", "rate": 0.45, "from": 125140, "to": null }
        ]
      },
      "scotland": {
        "bands": [
          { "name": "starter_rate", "rate": 0.19, "from": 12570, "to": 15325 },
          { "name": "basic_rate", "rate": 0.20, "from": 15325, "to": 43662 },
          { "name": "intermediate_rate", "rate": 0.21, "from": 43662, "to": 50270 },
          { "name": "higher_rate", "rate": 0.41, "from": 50270, "to": 125140 },
          { "name": "top_rate", "rate": 0.46, "from": 125140, "to": null }
        ]
      }
    }
  },
  "meta": {
    "api_version": "v1",
    "licence": "Open Government Licence v3.0",
    "source": "HMRC",
    "source_url": "https://www.gov.uk/income-tax-rates"
  }
}

POST /v1/tax/income/calculate

Calculate income tax for a given gross income.

Parameters

Parameter	Type	Required	Description
`gross_income`	integer	Yes	Annual gross income in pounds (e.g., 55000)
`region`	string	No	Default: `england_wales_ni`. Also: `scotland`
`tax_year`	string	No	Default: current year. Format: `YYYY-YY`
`marriage_allowance_recipient`	boolean	No	This person receives a transferred Marriage Allowance. Reduces tax by 20% of the transferred amount (£252 in 2025-26 and 2026-27). Only basic rate taxpayers are eligible (starter/basic/intermediate in Scotland) — a higher-rate income returns a `422 marriage_allowance_ineligible` error.
`marriage_allowance_transferor`	boolean	No	This person transfers Marriage Allowance to their partner, reducing their own `personal_allowance` by the transferable amount.
`blind_persons_allowance`	boolean	No	Adds Blind Person's Allowance to the `personal_allowance` (£3,250 in 2026-27, £3,130 in 2025-26). Additive, not tapered — applies at any income and composes with Marriage Allowance. UK-wide (same for rUK and Scotland). Spouse transfer of unused allowance is not supported.

See gov.uk/marriage-allowance and gov.uk/blind-persons-allowance for eligibility rules.

curl -X POST https://api.govdata.dev/v1/tax/income/calculate \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"gross_income": 55000, "region": "england_wales_ni"}'

Response

{
  "data": {
    "gross_income": 55000,
    "personal_allowance": 12570,
    "taxable_income": 42430,
    "tax_year": "2025-26",
    "region": "england_wales_ni",
    "breakdown": [
      { "band": "basic_rate", "rate": 0.20, "taxable_amount": 37700, "tax": 7540.00 },
      { "band": "higher_rate", "rate": 0.40, "taxable_amount": 4730, "tax": 1892.00 }
    ],
    "total_income_tax": 9432.00,
    "effective_rate": 0.1715
  },
  "meta": {
    "api_version": "v1",
    "licence": "Open Government Licence v3.0",
    "source": "HMRC"
  }
}

With Marriage Allowance

Passing marriage_allowance_recipient: true for a £30,000 basic-rate income adds a marriage_allowance object and reduces total_income_tax by the tax reduction:

{
  "data": {
    "gross_income": 30000,
    "personal_allowance": 12570,
    "taxable_income": 17430,
    "total_income_tax": 3234.00,
    "effective_rate": 0.1078,
    "marriage_allowance": {
      "eligible": true,
      "transferred_amount": 1260,
      "tax_reduction": 252.00
    }
  }
}

If the recipient's income falls into a higher tax band, the request returns a 422 with code marriage_allowance_ineligible. Use marriage_allowance_transferor: true instead to reduce the transferor's own personal_allowance by the transferable amount (£1,260 in 2025-26 and 2026-27).

With Blind Person's Allowance

Passing blind_persons_allowance: true adds the allowance (£3,250 in 2026-27) directly to personal_allowance before tax is calculated — for a £30,000 income, Personal Allowance rises to £15,820 and taxable income falls to £14,180:

{
  "data": {
    "gross_income": 30000,
    "personal_allowance": 15820,
    "taxable_income": 14180,
    "total_income_tax": 2836.00,
    "effective_rate": 0.0945
  }
}

Composes with marriage_allowance_recipient/marriage_allowance_transferor — Blind Person's Allowance is added after any Marriage Allowance transfer, and is never reduced by it. Spouse transfer of unused Blind Person's Allowance is not supported.

National Insurance

GET /v1/tax/national-insurance/thresholds

Returns National Insurance thresholds for the current tax year. Append /:tax_year for a specific year.

Response

{
  "data": {
    "tax_year": "2025-26",
    "employee": {
      "primary_threshold": { "annual": 12570, "weekly": 241.73 },
      "upper_earnings_limit": { "annual": 50270, "weekly": 967.12 }
    },
    "employer": {
      "secondary_threshold": { "annual": 5000 }
    },
    "self_employed": {
      "class_2_small_profits_threshold": { "annual": 6725 },
      "class_4_lower_profit_limit": { "annual": 12570 },
      "class_4_upper_profit_limit": { "annual": 50270 }
    }
  },
  "meta": {
    "api_version": "v1",
    "licence": "Open Government Licence v3.0",
    "source": "HMRC",
    "source_url": "https://www.gov.uk/national-insurance-rates-letters"
  }
}

GET /v1/tax/national-insurance/categories

Returns every current UK National Insurance category letter (A, B, C, H, J, M, V, Z, plus the Freeport and Investment Zone letters) with a description of who it applies to and the employee/employer contribution rates for that letter.

Response

{
  "data": {
    "tax_year": "2025-26",
    "categories": [
      {
        "letter": "A",
        "description": "All employees apart from those in groups B, C, H, J, M, V and Z in this table",
        "group": "standard",
        "employee": { "rate_main": 0.08, "rate_upper": 0.02 },
        "employer": { "rate": 0.15, "reduced_rate": false }
      },
      {
        "letter": "C",
        "description": "Employees over the State Pension age",
        "group": "state_pension_age",
        "employee": { "rate_main": null, "rate_upper": null },
        "employer": { "rate": 0.15, "reduced_rate": false }
      },
      {
        "letter": "H",
        "description": "Apprentices under 25",
        "group": "apprentice_under_25",
        "employee": { "rate_main": 0.08, "rate_upper": 0.02 },
        "employer": { "rate": 0.15, "reduced_rate": true }
      }
    ]
  },
  "meta": {
    "api_version": "v1",
    "licence": "Open Government Licence v3.0",
    "source": "HMRC",
    "source_url": "https://www.gov.uk/national-insurance-rates-letters"
  }
}

"rate_main" is the rate charged between the primary threshold and upper earnings limit; "rate_upper" is the rate above the upper earnings limit. Both are null for categories with no employee contribution (state pension age and the "X" no-NI marker). "reduced_rate" marks categories where the employer pays 0% up to that category's own upper secondary threshold.

POST /v1/tax/national-insurance/calculate

Calculate National Insurance contributions for employed or self-employed income.

Parameters

Parameter	Type	Required	Description
`annual_salary`	integer	Yes*	Annual salary in pounds (for employed type)
`annual_profit`	integer	Yes*	Annual profit in pounds (for self_employed type)
`type`	string	No	Default: `employed`. Also: `self_employed`
`tax_year`	string	No	Default: current year. Format: `YYYY-YY`
`director`	boolean	No	Use HMRC's directors' annual (cumulative) NI method — applies annual PT/UEL/ST thresholds. Only valid with `type: employed`; otherwise returns `422 director_not_applicable`. The response's `method` field reports which method was used (`standard` or `directors_annual`).

* Use annual_salary for employed, annual_profit for self-employed. See gov.uk/employee-directors for the directors' annual method.

curl -X POST https://api.govdata.dev/v1/tax/national-insurance/calculate \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"annual_salary": 55000, "type": "employed"}'

Directors' annual method

Passing director: true assesses NI using HMRC's default annual (cumulative) method for company directors — the same annual PT/UEL/ST thresholds, so the figures for a given annual_salary match the standard calculation. The response's method field confirms which method was applied:

{
  "data": {
    "annual_salary": 55000,
    "tax_year": "2026-27",
    "type": "employed",
    "method": "directors_annual",
    "employee": { "contributions": 3110.60, "breakdown": [ ... ] },
    "employer": { "contributions": 7500.00, "breakdown": [ ... ] }
  }
}

Only HMRC's annual method is implemented. The optional "alternative" (period-by-period) method reconciles to the same annual total at year end and is out of scope. director: true with type: self_employed returns a 422 with code director_not_applicable.

Take-Home Calculator

POST /v1/tax/take-home/calculate

Combined income tax and National Insurance calculation. Returns net pay breakdown with annual, monthly, and weekly figures.

Parameters

Parameter	Type	Required	Description
`gross_income`	integer	Yes	Annual gross income in pounds
`region`	string	No	Default: `england_wales_ni`
`tax_year`	string	No	Default: current year
`marriage_allowance_recipient`	boolean	No	Adds a `deductions.income_tax.marriage_allowance` object and reduces income tax by 20% of the transferred amount. Basic rate taxpayers only (starter/basic/intermediate in Scotland) — otherwise returns `422 marriage_allowance_ineligible`.
`marriage_allowance_transferor`	boolean	No	Reduces this person's own `personal_allowance` by the transferred amount.
`blind_persons_allowance`	boolean	No	Adds Blind Person's Allowance to `deductions.income_tax.personal_allowance` (£3,250 in 2026-27, £3,130 in 2025-26). Additive, not tapered, composes with Marriage Allowance.

curl -X POST https://api.govdata.dev/v1/tax/take-home/calculate \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"gross_income": 55000, "region": "england_wales_ni"}'

Response

{
  "data": {
    "gross_income": 55000,
    "region": "england_wales_ni",
    "tax_year": "2025-26",
    "deductions": {
      "income_tax": {
        "amount": 9432.00,
        "personal_allowance": 12570,
        "effective_rate": 0.1715,
        "breakdown": [
          { "band": "basic_rate", "rate": 0.20, "taxable_amount": 37700, "tax": 7540.00 },
          { "band": "higher_rate", "rate": 0.40, "taxable_amount": 4730, "tax": 1892.00 }
        ]
      },
      "national_insurance": {
        "employee": 3110.60,
        "breakdown": [
          { "from": 12570, "to": 50270, "rate": 0.08, "amount": 3016.00 },
          { "from": 50270, "to": 55000, "rate": 0.02, "amount": 94.60 }
        ]
      }
    },
    "net_annual": 42457.40,
    "net_monthly": 3538.12,
    "net_weekly": 816.49,
    "total_deductions": 12542.60,
    "marginal_rate": 0.42,
    "employer_costs": {
      "employer_ni": 7500.00,
      "total_cost_to_employer": 62500.00
    }
  },
  "meta": {
    "api_version": "v1",
    "licence": "Open Government Licence v3.0",
    "source": "HMRC"
  }
}

Tax Comparison

POST /v1/tax/compare

Compare take-home pay between two scenarios. Takes two sets of inputs and returns a side-by-side comparison with absolute and percentage differences.

Parameters

Parameter	Type	Required	Description
`scenario_a`	object	Yes	First scenario (gross_income required, plus optional region, student_loan_plans, pension_contribution_percent, pension_type)
`scenario_b`	object	Yes	Second scenario (same fields as scenario_a)
`tax_year`	string	No	Shared tax year for both scenarios. Default: current year

curl -X POST https://api.govdata.dev/v1/tax/compare \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"scenario_a":{"gross_income":50000,"region":"england_wales_ni"},"scenario_b":{"gross_income":60000,"region":"scotland"}}'

Response

{
  "data": {
    "scenario_a": {
      "gross_income": 50000,
      "region": "england_wales_ni",
      "tax_year": "2025-26",
      "net_annual": 38957.40,
      "total_deductions": 11042.60,
      "marginal_rate": 0.42,
      "..."
    },
    "scenario_b": {
      "gross_income": 60000,
      "region": "scotland",
      "tax_year": "2025-26",
      "net_annual": 45678.90,
      "total_deductions": 14321.10,
      "marginal_rate": 0.53,
      "..."
    },
    "differences": {
      "gross_income": { "absolute": 10000, "percentage": 20.0 },
      "net_annual": { "absolute": 6721.50, "percentage": 17.25 },
      "total_deductions": { "absolute": 3278.50, "percentage": 29.69 },
      "income_tax": { "absolute": 2432.00, "percentage": 32.36 },
      "national_insurance": { "absolute": 94.60, "percentage": 3.15 },
      "marginal_rate": { "absolute": 0.11, "percentage": 26.19 }
    }
  },
  "meta": {
    "api_version": "v1",
    "licence": "Open Government Licence v3.0",
    "source": "HMRC"
  }
}

VAT Return Calculation

POST /v1/tax/vat/return/calculate

Calculate a complete 9-box VAT return from a set of transactions. Supports standard accounting, flat rate scheme, partial exemption, domestic reverse charge, EC supplies/acquisitions, postponed VAT accounting, bad debt relief, and fuel scale charges.

Query Parameters

Parameter	Type	Required	Description
breakdown_detail	string	No	`full`, `summary` (default), or `none`. Controls transaction detail in the breakdown.

Request Body

Field	Type	Description
company	object	VAT registration, schemes, partial exemption config, fuel scale charges.
period	object	Return period `start_date` and `end_date` (ISO 8601). Max 12 months.
transactions	array	Up to 10,000 transactions with id, date, type, amounts, VAT rate, and supply type.

curl -X POST https://api.govdata.dev/v1/tax/vat/return/calculate \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "company": {
      "vat_registration_number": "123456789",
      "vat_schemes": [{"scheme": "standard", "effective_from": "2024-01-01", "effective_to": null}],
      "partially_exempt": false
    },
    "period": {"start_date": "2024-01-01", "end_date": "2024-03-31"},
    "transactions": [
      {"id": "S001", "date": "2024-01-15", "type": "sale", "net_amount": 10000, "vat_amount": 2000, "gross_amount": 12000, "vat_rate": "standard", "vat_rate_percentage": 20, "supply_type": "domestic", "is_capital_asset": false},
      {"id": "P001", "date": "2024-02-01", "type": "purchase", "net_amount": 3000, "vat_amount": 600, "gross_amount": 3600, "vat_rate": "standard", "vat_rate_percentage": 20, "supply_type": "domestic", "is_capital_asset": false}
    ]
  }'

Response (200 OK)

{
  "data": {
    "return_period": {
      "start_date": "2024-01-01",
      "end_date": "2024-03-31"
    },
    "boxes": {
      "box_1": { "value": 2000.00, "exact_value": 2000.00 },
      "box_2": { "value": 0.00, "exact_value": 0.00 },
      "box_3": { "value": 2000.00, "exact_value": 2000.00 },
      "box_4": { "value": 600.00, "exact_value": 600.00 },
      "box_5": { "value": 1400.00, "exact_value": 1400.00 },
      "box_6": { "value": 10000, "exact_value": 10000.00 },
      "box_7": { "value": 3000, "exact_value": 3000.00 },
      "box_8": { "value": 0, "exact_value": 0.00 },
      "box_9": { "value": 0, "exact_value": 0.00 }
    },
    "warnings": [],
    "scheme_summary": [
      { "scheme": "standard", "effective_from": "2024-01-01", "effective_to": "2024-03-31", "transaction_count": 2 }
    ],
    "rounding_summary": {
      "box_1_rounding": 0.0, "box_2_rounding": 0.0, "box_3_rounding": 0.0,
      "box_4_rounding": 0.0, "box_5_rounding": 0.0, "box_6_rounding": 0.0,
      "box_7_rounding": 0.0, "box_8_rounding": 0.0, "box_9_rounding": 0.0
    }
  },
  "meta": { "source": "HMRC", "source_url": "https://www.gov.uk/vat-returns" }
}

Box Descriptions

Box	Description
box_1	VAT due on sales and other outputs
box_2	VAT due on acquisitions from other EC member states
box_3	Total VAT due (Box 1 + Box 2)
box_4	VAT reclaimed on purchases and other inputs
box_5	Net VAT due or reclaimable (Box 3 - Box 4)
box_6	Total value of sales excluding VAT
box_7	Total value of purchases excluding VAT
box_8	Total value of EC supplies of goods
box_9	Total value of EC acquisitions of goods

Transaction Types

sale purchase credit_note_issued credit_note_received debit_note_issued debit_note_received bad_debt_relief journal

Supply Types

domestic domestic_reverse_charge ec_supply_goods ec_supply_services ec_acquisition_goods ec_acquisition_services export_outside_ec import_outside_ec import_postponed_vat outside_scope

VAT Schemes

standard flat_rate cash_accounting annual_accounting

Validation Errors (400)

{
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Request contains invalid data.",
    "documentation_url": "https://docs.govdata.dev/errors/VALIDATION_ERROR",
    "details": [
      { "field": "transactions[0]", "code": "AMOUNT_MISMATCH", "message": "Transaction S001: net_amount (100.0) + vat_amount (20.0) = 120.0, but gross_amount is 999.0." }
    ]
  }
}

Error codes: AMOUNT_MISMATCH, EXEMPT_WITH_VAT, DUPLICATE_TRANSACTION_ID, TRANSACTION_OUTSIDE_PERIOD, SCHEME_GAP, SCHEME_OVERLAP, FRS_MISSING_PERCENTAGE, BAD_DEBT_RELIEF_TOO_EARLY, BAD_DEBT_RELIEF_POSITIVE_VAT, BAD_DEBT_RELIEF_MISSING_ORIGINAL, DOMESTIC_REVERSE_CHARGE_SALE_WITH_VAT, CAPITAL_GOODS_MISSING_VALUE, PERIOD_TOO_LONG, INVALID_RATE_SUPPLY_COMBINATION, ANNUAL_ADJUSTMENT_WITHOUT_PARTIAL_EXEMPTION, PARTIAL_EXEMPTION_ATTRIBUTION_ON_OUTPUT, INVALID_SCHEME_OVERRIDE, RATE_PERCENTAGE_MISMATCH, SCHEME_OVERRIDE_DATE_MISMATCH, CREDIT_NOTE_POSITIVE_AMOUNTS, NEGATIVE_AMOUNT_ON_POSITIVE_TYPE, SUPPLY_TYPE_DIRECTION_MISMATCH, TRANSACTION_LIMIT_EXCEEDED, INVALID_CO2_BAND, TRANSACTION_NO_MATCHING_SCHEME.

Employer Cost Calculator

Calculate the total cost to an employer of hiring staff. Includes gross salary, employer National Insurance contributions, and workplace pension. Supports multiple employees at the same salary and an opt-in Employment Allowance.

Request body

Field	Type	Required	Description
`annual_salary`	number	Yes	Gross annual salary in GBP
`tax_year`	string	No	Tax year (e.g. "2025-26"). Defaults to current year.
`pension_rate`	number	No	Employer pension rate as decimal (e.g. 0.03 for 3%). Default: 0.03
`num_employees`	integer	No	Number of employees at this salary. Default: 1
`employment_allowance`	boolean	No	Self-attest eligibility and apply the tax year's allowance once against total employer secondary Class 1 NI, floored at zero. Default: false

curl -X POST -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"annual_salary": 45000, "pension_rate": 0.05, "num_employees": 3, "employment_allowance": true}' \
  "https://api.govdata.dev/v1/tax/employer-cost/calculate"

Example response

{
  "data": {
    "tax_year": "2025-26",
    "per_employee": {
      "annual_salary": 45000.0,
      "employer_ni": 2500.0,
      "employer_ni_breakdown": [{ "from": 5000, "to": 45000, "rate": 0.15, "amount": 6000.0 }],
      "employer_pension": 2250.0,
      "pension_rate": 0.05,
      "total_cost": 49750.0
    },
    "num_employees": 3,
    "employer_ni_before_allowance": 18000.0,
    "employment_allowance_applied": 10500.0,
    "total_annual_cost": 149250.0,
    "monthly_cost": 12437.5
  },
  "meta": {
    "api_version": "v1",
    "licence": "Open Government Licence v3.0"
  }
}

Eligibility is not inferred from these inputs. Set employment_allowance: true only after checking the employer is eligible. GOV.UK confirms that from April 2025 employers with more than £100,000 of Class 1 NI liability can apply; other exclusions still apply. See Employment Allowance eligibility.

VAT

GET /v1/tax/vat/rates

Returns the current UK VAT rates (standard, reduced, zero) and the flat rate scheme percentages by business type. Append /:tax_year for a specific year.

Response

{
  "data": {
    "rates": [
      { "name": "reduced", "label": "Reduced Rate", "rate": 0.05, "effective_date": "1994-04-01", "description": "Some goods and services, e.g. home energy and children's car seats" },
      { "name": "standard", "label": "Standard Rate", "rate": 0.20, "effective_date": "2011-01-04", "description": "Most goods and services" },
      { "name": "zero", "label": "Zero Rate", "rate": 0.0, "effective_date": "1973-04-01", "description": "Zero-rated goods and services, e.g. most food and children's clothes" }
    ],
    "flat_rate_schemes": [
      { "business_type": "Accountancy or book-keeping", "rate": 0.145 },
      { "business_type": "Advertising", "rate": 0.11 }
    ]
  },
  "meta": {
    "api_version": "v1",
    "licence": "Open Government Licence v3.0",
    "source": "HMRC",
    "source_url": "https://www.gov.uk/vat-rates"
  }
}

GET /v1/tax/vat/flat-rate-percentages

Returns VAT Flat Rate Scheme percentages by business category, including the 1% first-year discount for newly-registered businesses.

Response

{
  "data": {
    "effective_date": "2026-08-05",
    "source": "HMRC Notice 733",
    "categories": [
      { "code": "accountancy_or_book-keeping", "description": "Accountancy or book-keeping", "percentage": 14.5, "first_year_percentage": 13.5 },
      { "code": "advertising", "description": "Advertising", "percentage": 11.0, "first_year_percentage": 10.0 }
    ]
  },
  "meta": { "api_version": "v1", "licence": "Open Government Licence v3.0" }
}

POST /v1/tax/vat/calculate

Calculate VAT on an amount, either adding VAT to a net figure (exclusive) or extracting VAT from a gross figure (inclusive).

curl -X POST https://api.govdata.dev/v1/tax/vat/calculate \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"amount": 1000, "rate": "standard", "direction": "exclusive"}'

Response

{
  "data": {
    "net_amount": 1000.0,
    "vat_amount": 200.0,
    "total": 1200.0,
    "rate": 0.20,
    "rate_name": "standard",
    "rate_type": "standard",
    "direction": "exclusive"
  },
  "meta": {
    "api_version": "v1",
    "licence": "Open Government Licence v3.0",
    "source": "HMRC"
  }
}

Capital Gains Tax

GET /v1/tax/capital-gains/rates

Returns Capital Gains Tax rates by asset type and taxpayer band for the current tax year. Append /:tax_year for a specific year (2020-21 onwards).

Response

{
  "data": {
    "tax_year": "2026-27",
    "rates": [
      { "asset_type": "residential_property", "taxpayer_band": "basic", "rate": 0.18 },
      { "asset_type": "residential_property", "taxpayer_band": "higher", "rate": 0.24 },
      { "asset_type": "other_assets", "taxpayer_band": "basic", "rate": 0.18 },
      { "asset_type": "other_assets", "taxpayer_band": "higher", "rate": 0.24 },
      { "asset_type": "business_asset_disposal", "taxpayer_band": "basic", "rate": 0.18 },
      { "asset_type": "business_asset_disposal", "taxpayer_band": "higher", "rate": 0.18 }
    ]
  },
  "meta": {
    "api_version": "v1",
    "licence": "Open Government Licence v3.0",
    "source": "HMRC",
    "source_url": "https://www.gov.uk/capital-gains-tax/rates"
  }
}

GET /v1/tax/capital-gains/allowances

Returns the annual exempt amount and Business Asset Disposal Relief lifetime limit for the current tax year.

Response

{
  "data": {
    "tax_year": "2026-27",
    "allowances": [
      { "allowance_type": "annual_exempt_amount", "amount": 3000 },
      { "allowance_type": "business_asset_disposal_lifetime", "amount": 1000000 }
    ]
  },
  "meta": {
    "api_version": "v1",
    "licence": "Open Government Licence v3.0",
    "source": "HMRC",
    "source_url": "https://www.gov.uk/capital-gains-tax/rates"
  }
}

POST /v1/tax/capital-gains/calculate

Calculate Capital Gains Tax due, after deducting the annual exempt amount.

curl -X POST https://api.govdata.dev/v1/tax/capital-gains/calculate \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"gain": 50000, "asset_type": "other_assets", "taxpayer_band": "higher"}'

Response

{
  "data": {
    "gain": 50000,
    "annual_exempt_amount": 3000,
    "taxable_gain": 47000,
    "rate": 0.24,
    "tax": 11280.0,
    "tax_year": "2026-27",
    "asset_type": "other_assets",
    "taxpayer_band": "higher"
  },
  "meta": {
    "api_version": "v1",
    "licence": "Open Government Licence v3.0",
    "source": "HMRC"
  }
}

Dividend Tax

GET /v1/tax/dividends/rates

Returns dividend tax rates by taxpayer band and the dividend allowance for the current tax year. Append /:tax_year for a specific year (2020-21 onwards).

Response

{
  "data": {
    "tax_year": "2026-27",
    "dividend_allowance": 500,
    "rates": [
      { "band": "basic", "rate": 0.1075 },
      { "band": "higher", "rate": 0.3575 },
      { "band": "additional", "rate": 0.3935 }
    ]
  },
  "meta": {
    "api_version": "v1",
    "licence": "Open Government Licence v3.0",
    "source": "HMRC",
    "source_url": "https://www.gov.uk/tax-on-dividends"
  }
}

POST /v1/tax/dividends/calculate

Calculate dividend tax due, after deducting the dividend allowance.

curl -X POST https://api.govdata.dev/v1/tax/dividends/calculate \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"dividend_income": 10000, "taxpayer_band": "higher"}'

Response

{
  "data": {
    "dividend_income": 10000,
    "allowance": 500,
    "taxable_dividends": 9500,
    "rate": 0.3575,
    "tax": 3396.25,
    "tax_year": "2026-27",
    "taxpayer_band": "higher"
  },
  "meta": {
    "api_version": "v1",
    "licence": "Open Government Licence v3.0",
    "source": "HMRC"
  }
}

Student Loans

GET /v1/tax/student-loan/thresholds

Returns annual repayment thresholds and rates for every student loan plan type for the current tax year. Append /:tax_year for a specific year.

Response

{
  "data": {
    "tax_year": "2026-27",
    "thresholds": [
      { "plan_type": "plan_1", "annual_threshold": 26900, "rate": 0.09 },
      { "plan_type": "plan_2", "annual_threshold": 29385, "rate": 0.09 },
      { "plan_type": "plan_4", "annual_threshold": 33795, "rate": 0.09 },
      { "plan_type": "plan_5", "annual_threshold": 25000, "rate": 0.09 },
      { "plan_type": "postgraduate", "annual_threshold": 21000, "rate": 0.06 }
    ]
  },
  "meta": {
    "api_version": "v1",
    "licence": "Open Government Licence v3.0",
    "source": "HMRC / SLC",
    "source_url": "https://www.gov.uk/repaying-your-student-loan/what-you-pay"
  }
}

POST /v1/tax/student-loan/calculate

Calculate student loan repayments. Accepts one or more plan types at once — useful for borrowers repaying an undergraduate plan alongside a Postgraduate Loan simultaneously.

curl -X POST https://api.govdata.dev/v1/tax/student-loan/calculate \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"annual_income": 35000, "plan_types": ["plan_2"]}'

Response

{
  "data": {
    "annual_income": 35000,
    "tax_year": "2026-27",
    "repayments": [
      { "plan_type": "plan_2", "threshold": 29385, "rate": 0.09, "amount": 505.35 }
    ],
    "total_repayment": 505.35
  },
  "meta": {
    "api_version": "v1",
    "licence": "Open Government Licence v3.0",
    "source": "HMRC / SLC"
  }
}

Pension Allowances

GET /v1/tax/pension/allowances

Returns pension contribution allowances for the current tax year — the standard annual allowance, the Money Purchase Annual Allowance (MPAA), and the tapered annual allowance thresholds for high earners. Append /:tax_year for a specific year. Reference data only — there is no calculate endpoint.

Response

{
  "data": {
    "tax_year": "2026-27",
    "allowances": [
      { "allowance_type": "annual", "amount": 60000 },
      { "allowance_type": "mpaa", "amount": 10000 },
      { "allowance_type": "tapered_threshold_income", "amount": 200000 },
      { "allowance_type": "tapered_adjusted_income", "amount": 260000 },
      { "allowance_type": "minimum_tapered", "amount": 10000 }
    ]
  },
  "meta": {
    "api_version": "v1",
    "licence": "Open Government Licence v3.0",
    "source": "HMRC",
    "source_url": "https://www.gov.uk/tax-on-your-private-pension/annual-allowance"
  }
}

Corporation Tax

GET /v1/tax/corporation/rates

Returns Corporation Tax rates for the current tax year — the small profits rate, the main rate, and the marginal relief fraction used between them. Append /:tax_year for a specific year (2020-21 onwards).

Response

{
  "data": {
    "tax_year": "2026-27",
    "rates": [
      { "rate_type": "small_profits", "rate": 0.19, "upper_limit": 50000 },
      { "rate_type": "marginal_relief_fraction", "rate": 0.015, "lower_limit": 50000, "upper_limit": 250000 },
      { "rate_type": "main", "rate": 0.25, "lower_limit": 250000 }
    ]
  },
  "meta": {
    "api_version": "v1",
    "licence": "Open Government Licence v3.0",
    "source": "HMRC",
    "source_url": "https://www.gov.uk/corporation-tax-rates"
  }
}

POST /v1/tax/corporation/calculate

Calculate Corporation Tax due, automatically applying the small profits rate, main rate, or marginal relief depending on the profit band.

curl -X POST https://api.govdata.dev/v1/tax/corporation/calculate \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"profit": 100000}'

Response

{
  "data": {
    "profit": 100000,
    "tax_year": "2026-27",
    "rate_type": "marginal_relief",
    "tax": 22750.0,
    "effective_rate": 0.2275,
    "marginal_relief": 2250.0
  },
  "meta": {
    "api_version": "v1",
    "licence": "Open Government Licence v3.0",
    "source": "HMRC"
  }
}

Data Coverage

Source	HMRC / GOV.UK
Date range	Income Tax & National Insurance: 1990-91 to 2026-27. VAT, Capital Gains Tax, dividend tax, and Corporation Tax: 2020-21 to 2026-27.
Records	7 tax years across VAT/CGT/dividends/Corporation Tax; 36+ years of Income Tax and NI history
Updated	Annually (after Budget)
Limitations	VAT, CGT, dividend tax, and Corporation Tax rates before 2020-21 not yet available. Student loan and pension allowance history starts at 2025-26.