UK VAT Number HMRC Official Checker

UK HMRC official VAT number checker with offline Modulus 97 checksum verification, HMRC v2 OpenAPI integration, and consultation proof numbers at $0.005/check.

---

💡 The Problem Solved

Following Brexit, the United Kingdom (England, Scotland, Wales) separated from the EU VIES database. Validating British VAT registration numbers (VRNs) requires querying the UK HM Revenue & Customs (HMRC) or validating mathematical compliance via official Modulus 97 algorithms.

Accepting counterfeit or deregistered UK VAT numbers exposes merchants to severe tax penalties, lost input tax claims, and corporate fraud.

This Actor solves this by providing:

• Zero Monthly Subscription: Pay only $0.005 per check using Apify Pay-Per-Event (PPE).
• Dual Verification Engines:
  1. Instant mathematical Modulus 97 & Modulus 97-55 checksum algorithm (zero-auth, zero latency).
  2. Official HMRC v2 OpenAPI endpoint integration (/organisations/vat/check-vat-number/lookup/{vrn}).
• Audit Consultation Proof: Generates official HMRC consultationNumber tokens when requester VRN is supplied.
• Smart Formatting: Automatically strips GB prefixes, spaces, hyphens, and validates 9-digit standard or 12-digit branch VRNs.
• Single & Batch Support: Verify individual customers or audit supplier lists in bulk.

---

💰 Transparent Pay-Per-Event (PPE) Pricing

No recurring monthly subscriptions. You only pay for successful validation checks:

Billable Event	Unit Price	Deliverable
uk_vat_check	$0.005 USD	Verification status, registered trading name, address, Mod97 proof, and consultation number

---

📥 Input Parameters

Parameter	Type	Required	Default	Description
targetVrn	string	Yes	—	UK VAT Registration Number (e.g. 'GB 220 4302 31', '337440071', or '553557881').
requesterVrn	string	No	""	Your own 9-digit UK VRN to generate an official HMRC audit consultation proof reference.
batchVrns	array	No	[]	Optional list of UK VRNs for batch validation.
verifyAddress	boolean	No	true	Extract registered trading business name and address lines.
hmrcBearerToken	string	No	""	Optional user-supplied OAuth2 token for live HMRC API production access.
useSandbox	boolean	No	false	When true, tests against HMRC test sandbox environment.

Sample Input JSON

{
  "targetVrn": "GB 220 4302 31",
  "requesterVrn": "146295999727"
}

---

📤 Output Format

Each verified item pushed to the Apify dataset contains:

{
  "valid": true,
  "targetVrn": "220430231",
  "status": "MODULUS_97_VALID",
  "target": {
    "vatNumber": "220430231",
    "countryCode": "GB"
  },
  "consultationNumber": "ypAeKRPlW",
  "processingDate": "2026-10-18T19:42:00Z",
  "modulus97": {
    "isValid": true,
    "algorithm": "standard_modulus_97",
    "checksum": 31,
    "branch": null
  }
}

---

⚡ Integration Snippets

1. Python (apify-client)

from apify_client import ApifyClient

client = ApifyClient("YOUR_APIFY_API_TOKEN")

run = client.actor("your-username/uk-vat-number-checker").call(
    run_input={"targetVrn": "GB 220 4302 31"}
)

for item in client.dataset(run["defaultDatasetId"]).iterate_items():
    print(f"VRN: {item['targetVrn']} | Valid: {item['valid']} | Algorithm: {item['modulus97']['algorithm']}")

2. Make.com (Integromat)

1. Add an Apify module -> Run an Actor.
2. Select uk-vat-number-checker.
3. Map customer billing VRN from your invoicing system.
4. Route orders based on valid == true.

3. Zapier

1. Trigger: New UK B2B Customer in CRM.
2. Action: Apify -> Run Actor (uk-vat-number-checker).
3. Store verification timestamp and Modulus 97 validity flag in customer records.

4. cURL

curl -X POST "https://api.apify.com/v2/acts/your-username~uk-vat-number-checker/runs?token=YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"targetVrn": "GB 220 4302 31"}'

---

🧮 UK Modulus 97 Checksum Algorithms

UK 9-digit VAT numbers use a weighted modulus 97 check digit routine:

• Multipliers: [8, 7, 6, 5, 4, 3, 2] applied to digits 1 through 7.
• Standard Algorithm: (total + check_digits) mod 97 == 0.
• Alternative Algorithm (97-55): Introduced by HMRC in 2009 for newer series numbers (alt_cd = cd - 55). Both algorithms are automatically evaluated by this Actor.