# UK VAT Number HMRC Official Checker (`song921619730/uk-vat-number-checker`) Actor

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

- **URL**: https://apify.com/song921619730/uk-vat-number-checker.md
- **Developed by:** [song](https://apify.com/song921619730) (community)
- **Stats:** 2 total users, 1 monthly users, 100.0% runs succeeded, 0 bookmarks
- **User rating**: No ratings yet

## Pricing

Pay per usage

This Actor is paid per platform usage. The Actor is free to use, and you only pay for the Apify platform usage, which gets cheaper the higher subscription plan you have.

Learn more: https://docs.apify.com/actors/running/actors-in-store.md#pay-per-usage

## What's an Apify Actor?

An Actor is a serverless cloud program that runs on the Apify platform. It has two run modes.
In Batch mode, an Actor accepts a well-defined JSON input, performs an action which can take anything from a few seconds to a few hours,
and optionally produces a well-defined JSON output, datasets with results, or files in key-value store.
In Standby mode, an Actor provides a web server which can be used as a website, API, or an MCP server.

Apify vocabulary and the platform model are defined once, in the agent quickstart at https://apify.com/agents.md.

## How to integrate an Actor?

If asked about integration, you help developers integrate Actors into their projects.
You adapt to their stack and deliver integrations that are safe, well-documented, and production-ready.

Do not guess an integration path. Every one of them is in the agent quickstart at https://apify.com/agents.md: the Apify MCP server, Agent Skills with the Apify CLI, the JavaScript and Python clients, the REST API, and the account-free path for an agent with no human to sign in. It also carries the rule on stating cost before the first paid run.

For examples already wired to this Actor's own input schema, see the [API](#api) section below.

Each client library has reference documentation the quickstart does not restate: [JavaScript/TypeScript](https://docs.apify.com/api/client/js/docs.md) (`npm install apify-client`) and [Python](https://docs.apify.com/api/client/python/docs.md) (`pip install apify-client`).

# README

## 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.

[![Apify Actor](https://img.shields.io/badge/Apify-Actor-blue?logo=apify)](https://apify.com)
[![Pricing](https://img.shields.io/badge/Pricing-Pay--Per--Event%20\($0.005\)-green)](https://apify.com)
[![Docker](https://img.shields.io/badge/Container-256MB%20Optimized-orange)](https://docker.com)

***

### 💡 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

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

***

### 📤 Output Format

Each verified item pushed to the Apify dataset contains:

```json
{
  "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`)

```python
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

```bash
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.

# Actor input Schema

## `targetVrn` (type: `string`):

9 or 12-digit UK VAT registration number (with or without 'GB' prefix or spaces, e.g. 'GB 220 4302 31', 'GB337440071', or '553557881').

## `requesterVrn` (type: `string`):

Your own 9-digit UK VAT number to obtain a formal HMRC audit consultation proof reference number.

## `batchVrns` (type: `array`):

Optional list of UK VAT numbers (e.g. \['GB220430231', 'GB337440071']) for sequential verification.

## `verifyAddress` (type: `boolean`):

Retrieve registered business trading name and structured address lines.

## `hmrcBearerToken` (type: `string`):

Optional user-supplied OAuth2 Bearer token for direct live HMRC v2 API production access. If omitted, uses Modulus 97 mathematical checksum verification and sandbox/public fallback.

## `useSandbox` (type: `boolean`):

When true, queries HMRC test sandbox environment (test-api.service.hmrc.gov.uk) with official test entities.

## Actor input object example

```json
{
  "targetVrn": "GB 220 4302 31",
  "requesterVrn": "",
  "batchVrns": [],
  "verifyAddress": true,
  "hmrcBearerToken": "",
  "useSandbox": false
}
```

# Actor output Schema

## `overview` (type: `string`):

Link to official HMRC VAT check records

# API

You can run this Actor programmatically using our API. Below are code examples in JavaScript, Python, and CLI, as well as the OpenAPI specification and MCP server setup.

## JavaScript example

```javascript
import { ApifyClient } from 'apify-client';

// Initialize the ApifyClient with your Apify API token
// Replace the '<YOUR_API_TOKEN>' with your token
const client = new ApifyClient({
    token: '<YOUR_API_TOKEN>',
});

// Prepare Actor input
const input = {
    "targetVrn": "GB 220 4302 31"
};

// Run the Actor and wait for it to finish
const run = await client.actor("song921619730/uk-vat-number-checker").call(input);

// Fetch and print Actor results from the run's dataset (if any)
console.log('Results from dataset');
console.log(`💾 Check your data here: https://console.apify.com/storage/datasets/${run.defaultDatasetId}`);
const { items } = await client.dataset(run.defaultDatasetId).listItems();
items.forEach((item) => {
    console.dir(item);
});

// 📚 Want to learn more 📖? Go to → https://docs.apify.com/api/client/js/docs

```

## Python example

```python
from apify_client import ApifyClient

# Initialize the ApifyClient with your Apify API token
# Replace '<YOUR_API_TOKEN>' with your token.
client = ApifyClient("<YOUR_API_TOKEN>")

# Prepare the Actor input
run_input = { "targetVrn": "GB 220 4302 31" }

# Run the Actor and wait for it to finish
run = client.actor("song921619730/uk-vat-number-checker").call(run_input=run_input)

# Fetch and print Actor results from the run's dataset (if there are any)
print(f"💾 Check your data here: https://console.apify.com/storage/datasets/{run.default_dataset_id}")
for item in client.dataset(run.default_dataset_id).iterate_items():
    print(item)

# 📚 Want to learn more 📖? Go to → https://docs.apify.com/api/client/python/docs/quick-start

```

## CLI example

```bash
echo '{
  "targetVrn": "GB 220 4302 31"
}' |
apify call song921619730/uk-vat-number-checker --silent --output-dataset

```

## MCP server setup

```json
{
    "mcpServers": {
        "apify": {
            "type": "http",
            "url": "https://mcp.apify.com/?tools=fetch-actor-details,song921619730/uk-vat-number-checker"
        }
    }
}
```

The hosted server signs you in with OAuth on first connect, so no API token belongs in this config. Clients without OAuth support can send an `Authorization: Bearer <APIFY_API_TOKEN>` header instead, using a token from API & Integrations in Apify Console (https://console.apify.com/settings/integrations).

## OpenAPI specification

Download the OpenAPI definition: https://api.apify.com/v2/actors/O7ibDaqgkTJMPJ3wj/builds/VH1m18X1VFUlcu8nE/openapi.json