VAT Routing Guide

This guide explains the claimantRoute vocabulary used by the VATBuild API, what each route means for VAT treatment, and how classification outcomes map to actions.

Claimant routes

The claimantRoute field tells the engine which UK VAT scheme applies to a project. It is required in POST /api/v1/check-line-item (context.claimantRoute) and POST /api/v1/projects (claimantRoute).

|---|---|---|

The full route configuration (labels, checklist keys, allowed outcome values) is available from the public reference endpoint:

GET /api/v1/reference/routes

Classification outcomes (claimRoute)

The engine returns one of the following claimRoute values in every classification response. Machine clients should branch on this field — values are stable within /api/v1/.

|---|---|---|

VAT treatment by route

self_build_431nb — New Build

Qualifying services (labour, subcontractor work, supply-and-install):

• Correct rate: 0%
• If charged 20%: claimRoute = "supplier_correction" — request a corrected invoice
• If charged 0%: claimRoute = "zero_at_source" — no action

Self-purchased materials (materials, professional services):

• Correct rate: 20%
• claimRoute = "hmrc_refund" — include in the VAT431NB form after practical completion

self_build_431c — Qualifying Conversion

Qualifying services:

• Correct rate: 5% (this is correct — do not flag 5% as an error for 431C)
• If charged 5%: claimRoute = "hmrc_refund" — fully reclaimable via VAT431C
• If charged 20%: claimRoute = "supplier_correction" — request corrected invoice at 5%
• If charged 0%: claimRoute = "supplier_correction" — undercharge; 5% is correct

Materials bought directly (not via contractor):

• claimRoute = "hmrc_refund" at 20%

self_build_standard — Standard Renovation

No relief scheme applies. VAT at 20% is the correct rate throughout. claimRoute = "not_reclaimable" for services and materials (there is no 431 form claim available).

self_build_reduced — Reduced Rate at Source

5% is applied at source by the contractor. There is no refund — this is claimRoute = "reduced_at_source". Nothing to reclaim.

developer / contractor — Input Tax Recovery

VAT is recovered via the developer's or contractor's periodic VAT return, not a 431 form. Reclaimable items return claimRoute = "input_tax". Blocked items (private use, entertainment) return claimRoute = "input_tax_blocked".

Complex-VAT types

Some line items require additional context before they can be definitively classified. These are flagged with a vatComplexTypeHint and return claimRoute = "pending_complex_answer" until a confirmation answer is provided.

|---|---|

Provide confirmedAnswer: true or confirmedAnswer: false (or a three-way string answer for supply_and_install) to resolve the outcome.

firedRuleId — which rule fired?

Every classification response includes a firedRuleId string (e.g. rule_4a7f3c8e2b916d05). This is a stable opaque token — the same rule always returns the same value across requests. The rule.label, rule.noticeRef, and rule.explanation fields translate this into human-readable form suitable for displaying to end users or auditors.

Compare firedRuleId for equality against a previously-observed token when you need to detect a specific outcome programmatically. Do not parse, pattern-match, or branch on the token's internal structure — it is intentionally opaque and the format may change between major API versions.

Example: classifying a line item

POST /api/v1/check-line-item

{
  "context": {
    "claimantRoute": "self_build_431c",
    "buildingType": "barn conversion",
    "newDwelling": "yes"
  },
  "item": {
    "lineText": "Structural steelwork",
    "netAmount": "12000.00",
    "vatCharged": "600.00",
    "supplyType": "subcontractor",
    "identifierName": "Structural works"
  }
}

Response:

{
  "ok": true,
  "data": {
    "outcome": {
      "claimRoute": "hmrc_refund",
      ...
    },
    "reclaimAmount": "600.00",
    "firedRuleId": "rule_9c2e5a1f7b843d0e",
    "rule": {
      "label": "431C conversion — correct 5% service charge",
      "noticeRef": "Notice 708 s3.3",
      "explanation": "Contractor services on a qualifying 431C conversion are correctly charged at 5% and are fully reclaimable via the VAT431C scheme."
    }
  }
}

The 5% charge (£600 on £12,000 net) is correct for a 431C conversion. Include the £600 in the VAT431C claim.

Supply types

The supplyType field tells the engine the nature of the supply. Providing it significantly improves classification accuracy.

|---|---|

HMRC reference

All routing decisions reference HMRC Notice 708 — Buildings and Construction:

https://www.gov.uk/government/publications/vat-notice-708-buildings-and-construction