Skip to main content
Developer Hub

Build with VATBuild

Integrate the VATBuild VAT routing engine into your own tools, accountancy software, or agent workflows. REST and MCP interfaces available — no auth required for the routing endpoint.

API ReferenceOpenAPI Spec

Quick start — REST

Check a single line item with POST /api/v1/check-line-item

curl -X POST https://vatbuild.com/api/v1/check-line-item \
  -H "Content-Type: application/json" \
  -d '{
    "description": "Timber frame erection",
    "amount": 12000,
    "vatCharged": 0,
    "projectType": "new_build",
    "claimantRoute": "hmrc_refund",
    "supplyType": "service"
  }'

Response

{
  "outcome": "zero_rated",
  "reclaimAmount": 0,
  "firedRuleId": "rule_7d3f9a2c4e8b1506",
  "rule": {
    "label": "New build contractor service — correctly zero-rated",
    "noticeRef": "HMRC Notice 708, s3.3",
    "explanation": "Contractor services for a qualifying new dwelling are
    zero-rated at source. No VAT should be charged; no reclaim needed."
  }
}

Documentation

API Reference

Full endpoint docs: request/response schemas, all fields, error codes, and rate-limit notes.

VAT Routing Guide

How the routing engine classifies line items — all claim routes, supply types, rule IDs, and HMRC notice references.

MCP Setup Guide

Connect Claude Desktop or any MCP-capable agent to VATBuild's routing tools over Streamable HTTP.

OpenAPI 3.1 YAML

Machine-readable spec — import into Postman, Insomnia, or generate a typed client automatically.

AI client integration guides

Step-by-step setup, agent workflow examples, OAuth/PKCE configuration, and scopes references for each supported AI client.

Claude

Claude Desktop, Cursor, and Zed — config, agent workflow, and OAuth/PKCE.

ChatGPT

Desktop app, in-browser connector, and Custom GPT Actions setup.

Gemini

Gemini CLI, AI Studio, and Vertex AI Agent Builder integration.

Quick start — MCP

Send a JSON-RPC 2.0 call to POST /mcp. No authentication required.

{
  "jsonrpc": "2.0",
  "method": "tools/call",
  "params": {
    "name": "check_line_item",
    "arguments": {
      "description": "Timber frame erection",
      "amount": 12000,
      "vatCharged": 0,
      "projectType": "new_build",
      "claimantRoute": "hmrc_refund",
      "supplyType": "service"
    }
  }
}

Integration paths

MethodEndpoint
POST/api/v1/check-line-item
POST/mcp
GET/api-docs

GitHub

Coming soon — public repo with examples and SDK stubs.

HMRC Notice 708

The HMRC source of truth — buildings and construction VAT rules the routing engine implements.

Auth & rate limits

/api/v1/check-line-item and /mcp are public — no API key required. Requests are subject to standard IP rate-limiting. For high-volume or production integrations, contact us about API key access.