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.
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 theRetry-Afterheader.quota_exceeded(402): your units are used up;error.detailssays 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. To do the same checks by hand, see how to check a UK company with Companies House, and for what a company's form tells you, company legal forms compared. See the pricing page and what we cover.
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
- Companies House Public Data API: developer.company-information.service.gov.uk
- Open Government Licence v3.0: nationalarchives.gov.uk
