# How to Verify a UK Company via API: Company Number, Status, Insolvency and a Proof Code

> A step-by-step tutorial: check a UK company number's format, look the company up, verify it with an outcome and a proof code, read insolvency, handle errors.

Source: https://fuentio.com/blog/verify-uk-company-api-companies-house/

You have a UK company's number, from an invoice, a contract or a sign-up form, and you want to know three things before you go further: does it exist, is it still trading, and is an insolvency procedure open? This tutorial does it through the Fuentio API, step by step, with cURL, Python and JavaScript, using real answers recorded from the API on 16 October 2026.

**The short answer:** look the company up with `GET /v1/companies/GB/{company_number}` (1 unit), or verify it with `POST /v1/verifications` and `{"country": "GB", "identifier": "00445790"}` (5 units). The verification returns an outcome (`verified` or `unverified`) with its reasons, every check it ran, the Companies House record, its insolvency cases and a proof code anyone can check later.

**What you'll learn**

- How to normalise a UK company number before you call anything
- How to look a company up, and how to read its status without being misled
- How to verify it and get an outcome, reasons and a proof code
- How to search by name when you have no number
- How to handle each error, what to keep, and what each call costs

## Step 1: Get an API key

Create a free key with one request (100 units a month on the Free plan):

```
curl -X POST https://api.fuentio.com/v1/keys
```

Store it in an environment variable, never in your code:

```
export FUENTIO_API_KEY="the key you received"
```

You can also try a few calls without a key: the keyless trial allows 20 units a day per address.

## Step 2: Normalise the company number

A Companies House company number has 8 characters: 8 digits for most companies registered in England and Wales, zero-padded (`00445790`), or a two-letter prefix and 6 digits, such as `SC` for Scotland, `NI` for Northern Ireland and `OC` for a limited liability partnership. Unlike a French SIREN, it has no check digit, so a format check catches a wrong length or a stray character, not a typo in the digits.

People often drop the leading zeros. Put them back before you look anything up:

```
import re

def company_number(raw: str) -> str | None:
    n = re.sub(r"\s", "", raw).upper()
    if n.isdigit() and len(n) <= 8:
        n = n.zfill(8)
    return n if re.fullmatch(r"[0-9]{8}|[A-Z]{2}[0-9]{6}", n) else None

print(company_number("445790"))    # Tesco PLC: 00445790
print(company_number("sc 123456")) # SC123456
```

```
function companyNumber(raw) {
  let n = raw.replace(/\s/g, "").toUpperCase();
  if (/^\d{1,8}$/.test(n)) n = n.padStart(8, "0");
  return /^(\d{8}|[A-Z]{2}\d{6})$/.test(n) ? n : null;
}
```

A number this pattern rejects isn't necessarily wrong, as a few older formats exist: send it to a person rather than refusing it.

## Step 3: Look the company up

One request, one unit:

```
curl https://api.fuentio.com/v1/companies/GB/00445790 -H "Authorization: Bearer $FUENTIO_API_KEY"
```

With Python (`httpx`):

```
import os, httpx

r = httpx.get("https://api.fuentio.com/v1/companies/GB/00445790",
              headers={"Authorization": f"Bearer {os.environ['FUENTIO_API_KEY']}"})
company = r.json()["data"]
print(company["name"]["original"], company["status"]["original_label"])
```

With JavaScript (`fetch`):

```
const res = await fetch("https://api.fuentio.com/v1/companies/GB/00445790", {
  headers: { Authorization: `Bearer ${process.env.FUENTIO_API_KEY}` },
});
const { data, meta, error } = await res.json();
console.log(data.name.original, data.status.original_label);
```

## Step 4: Read the record, and its status, carefully

Here is part of the record the API returned for Tesco PLC on 16 October 2026:

```
{
  "id": "GB-COMPANYNUMBER-00445790",
  "name": {"original": "TESCO PLC"},
  "legal_form": {"original_code": "plc", "original_label": "Public Limited Company"},
  "status": {"value": "active", "original_label": "Active", "as_of": null},
  "incorporation_date": "1947-11-27",
  "registered_address": {"street": "Tesco House, Shire Park, Kestrel Way", "postal_code": "AL7 1GA", "locality": "Welwyn Garden City", "country": "GB"},
  "activity": {"original_scheme": "UK_SIC_2007", "original_code": "47110", "nace_rev2": "47.11"},
  "provenance": {"source": "gb_companies_house_api", "source_url": "https://find-and-update.company-information.service.gov.uk/company/00445790"}
}
```

Read the status in two parts. `status.value` is a normalised value; `status.original_label` is Companies House's own word. They can tell different stories. For APPLETREE FARM CRESSING LIMITED (12401266), the same day, the API returned:

```
"status": {"value": "active", "original_label": "In Administration", "as_of": null,
           "summary": "Still registered, but an insolvency procedure is open: administration"}
```

The company is still on the register, so `value` is `active`, but an administration is open. If your code reads only `value`, it misses that. Read `original_label` and `summary` too, or let the verification in the next step decide.

The provenance carries Companies House's licence mention, the Open Government Licence v3.0. Keep it with any data you pass on.

## Step 5: Verify the company and get a proof code

A verification runs the checks for you and returns an outcome with its reasons (5 units):

```
curl -X POST https://api.fuentio.com/v1/verifications -H "Authorization: Bearer $FUENTIO_API_KEY" \
  -H "Content-Type: application/json" -d '{"country": "GB", "identifier": "00445790"}'
```

For Tesco PLC, the recorded answer's result:

```
"result": {"outcome": "verified", "reasons": ["company_active"],
           "summary": "TESCO PLC (GB, Companies House company number 00445790): verified, active per Companies House Public Data API, checked 2026-10-16. Proof FUE-GB-20261016-5QBDT2."}
```

The `checks` list shows each test with its result. For Tesco PLC there were five, all passed: the identifier's format, the record found, the register status, a published address and the freshness of the copy. For Appletree Farm Cressing there was a sixth, `no_open_insolvency`, and it failed, so the outcome followed:

```
"result": {"outcome": "unverified", "reasons": ["insolvency_administration"]},
"insolvency": {"state": "in_procedure", "procedure": "administration", "opened_on": "2023-10-05"}
```

The `proof_code`, for example `FUE-GB-20261016-5QBDT2`, lets anyone check later what the API answered and when, on the public proof page or with `GET /v1/public/proofs/{code}`. For what each Companies House status means, see [how to read a UK company's status](/blog/uk-company-status-companies-house/).

## Step 6: Search by name when you have no number

A name search costs 2 units and returns candidates with their company numbers:

```
curl "https://api.fuentio.com/v1/companies/search?country=GB&q=tesco" -H "Authorization: Bearer $FUENTIO_API_KEY"
```

Many companies share words in their names. Show the candidates to a person, or ask your user for the company number: a name is a label, a number is an identity. Once you have the right number, go back to step 3 or 5.

## Step 7: Handle every error

Errors use the same envelope, with an `error.code` from a closed list and a `hint` for the next step:

- `invalid_identifier` (400): the value isn't a company number. Free.
- `not_found` (404): a well-formed number with no company behind it. It costs one unit, because it's a real answer.
- `rate_limited` (429): too many requests per second for your plan. Wait the seconds given in the `Retry-After` header.
- `quota_exceeded` (402): your units are used up; `error.details` says your limit and when it resets.
- `upstream_unavailable` (503): Companies House isn't answering and there's no earlier copy to serve. Retry later.

```
body = r.json()
if body["error"]:
    print(body["error"]["code"], "-", body["error"]["hint"])
```

## Step 8: Keep the answer with your record

When someone asks later how you knew a company was trading, show the answer as it was on the day. Store, next to your customer or supplier record: the company number, the outcome and its reasons, the `proof_code`, and the `provenance` and `freshness` blocks (source, source link, licence, when the record was fetched). The recorded answers say how fresh the copy is: Fuentio reuses its copy of a Companies House record for up to 7 days, then fetches it again, sooner if you ask with `max_age`.

## What does each step cost?

- Lookup by company number: 1 unit.
- Verification with an outcome, reasons and a proof code: 5 units.
- Search by name: 2 units.
- An invalid number: free.

The same tutorial for France is [how to verify a French company via API](/blog/verify-french-company-siren-siret-api/). To do the same checks by hand, see [how to check a UK company with Companies House](/blog/check-uk-company-companies-house/), and for what a company's form tells you, [company legal forms compared](/blog/company-legal-forms-france-spain-uk-compared/). See [the pricing page](/pricing/) and [what we cover](/coverage/).

> **Limits.** The answers shown were recorded from the API on 16 October 2026; a company's record changes. No person's name is served: officers, persons with significant control and other people are left out of every answer. The verification tells you what the register records; it isn't full KYB or sanctions screening, and the decision you take with it stays yours.

## Frequently asked questions

### Does a UK company number have a check digit?

No. Unlike a French SIREN, it has none, so a local check catches a wrong format, not a typo in the digits. The lookup tells you whether a company exists behind the number.

### Why does an active company come back unverified?

Because the register status isn't the whole story. A company in administration is still registered, so its status value is active, but the open insolvency procedure makes the outcome unverified, with the reason `insolvency_administration`.

### What's the difference between a lookup and a verification?

A lookup (1 unit) returns the company's record. A verification (5 units) runs the checks on that record and returns an outcome, its reasons, the insolvency state and a proof code.

### Can I look a UK company up by its LEI?

Yes. The API's coverage list shows two identifier schemes for the UK: the company number and the LEI.

## Sources

- Fuentio API, recorded answers for 00445790 and 12401266 (16 October 2026), and the coverage list `GET /v1/countries` (read on 22 October 2026)
- Companies House, Find and update company information: [find-and-update.company-information.service.gov.uk](https://find-and-update.company-information.service.gov.uk/)
- Companies House Public Data API: [developer.company-information.service.gov.uk](https://developer.company-information.service.gov.uk/)
- Open Government Licence v3.0: [nationalarchives.gov.uk](https://www.nationalarchives.gov.uk/doc/open-government-licence/version/3/)
