Build a Company Verification API: What Developers Need to Get Right

Lookup, matching, outcomes, source attribution, errors, caching and incomplete data: the decisions that make a company verification API trustworthy.

· By the Fuentio team · 7 min read

Share image: "Build a Company Verification API: What Developers Need to Get Right" on Fuentio's paper background, with the Guide label.

Calling a company register is the easy part. The hard part is everything around the call: deciding which company you mean, saying how sure you are, naming where each fact came from, failing in a way the caller can act on, and not passing off yesterday's copy as today's truth. This guide walks through the decisions an engineering team has to get right, whether you build the API yourself or evaluate one.

What you'll learn

  • Why lookups must start from identifiers, and how to validate them
  • How to handle name matching without silently picking the wrong company
  • Why a closed list of outcomes beats a true/false answer
  • How to attribute sources, handle errors, cache safely and say "we don't know"

Short answer: identify companies by their official number, never by name alone; return an outcome from a fixed list with machine-readable reasons; put the source, licence and check date on every answer; use a closed list of error codes with a next step; and cache with an explicit freshness rule, so a stale copy is labelled as stale.

Lookup: start from the identifier

A register is keyed by an official number, so your API should be too. Validate the format before you spend a call on it. A French SIREN has 9 digits and a check digit; a SIRET has 14. A UK company number has 8 characters (00445790, SC123456). A Spanish company is found by its Registro Mercantil sheet (V-5581).

Three cases deserve their own answers rather than a generic 404:

  • Invalid: the number fails the format or check digit. Nothing was looked up.
  • Ambiguous identifier: one string fits several ID types in a country. Ask the caller to say which one, for example with an id_scheme parameter.
  • Not found: the number is valid and inside your coverage, but the register has no record. That is a real answer, and in France it doesn't prove the company never existed, because some units opted out of public diffusion.

Matching: a name never decides on its own

Most onboarding forms start with a name. Names repeat, change and get abbreviated, so a name search should return candidates, each with a score and the reasons for it, never one silent "best match". When several companies fit, the honest answer is "ambiguous", with the candidates, so a person or the calling system can pick one by its official number.

Explain matches in words the caller can log: same identifier, same postcode, name equal after removing the legal form. A match without reasons can't be reviewed later.

Outcomes: don't return a boolean

"verified": true hides everything that matters. Is the company active, or merely present? Was the source reachable? Is the country even covered? A closed list of outcomes, each with a precise meaning, lets callers write rules they can trust. Fuentio uses nine, and documents what each one does not mean:

OutcomeWhat it says
verifiedThe named official source states what is returned, within the freshness rule
partialPart of the answer rests on the source; the reasons say what is missing
unverifiedThe source answered but doesn't confirm it (for example the company is ceased)
status_unknownThe company is in the source, but the source states no current status
not_foundValid identifier, inside coverage, no record
not_coveredThe country, identifier type, data or period isn't covered
ambiguousSeveral companies could match
staleA stored copy older than the freshness rule, because the source couldn't be refreshed
source_unavailableThe source didn't answer and nothing usable is held

When several apply, define which wins. Fuentio applies them in a fixed order, from source_unavailable down to verified, so the most cautious one is returned.

Each outcome needs machine-readable reasons (company_active, company_inactive, status_unknown, insolvency_administration…) and, ideally, the individual checks behind it. Here is the checks list from a real verification of TESCO PLC, recorded on 16 October 2026:

"checks": [
  {"check": "identifier_valid", "result": "pass", "detail": "The ID has a valid format."},
  {"check": "record_found", "result": "pass", "detail": "Found in the official source."},
  {"check": "status_active", "result": "pass", "detail": "Register status: active."},
  {"check": "address_present", "result": "pass", "detail": "Registered address published."},
  {"check": "fresh", "result": "pass", "detail": "Checked against the source within its refresh window."}
]

Source attribution on every answer

Every answer should name its source, its licence and when it was read, not just in the documentation but in the response itself. Open registers come with attribution duties: France's Licence Ouverte asks you to cite the source and date; UK Companies House data is licensed under the Open Government Licence v3.0, which asks for its own attribution line. More on this in provenance on every answer.

Separate three dates that are often confused: when the source published the data, when you retrieved it, and when you last verified it against the source.

Error handling the caller can act on

A closed list of error codes, each with an HTTP status and a hint, turns failures into decisions. A few that matter in practice:

  • invalid_identifier (400): fix the input; retrying won't help.
  • not_found (404): a real answer about the company, not a failure.
  • rate_limited (429): wait for Retry-After.
  • quota_exceeded (402): the caller's units are used up.
  • upstream_unavailable (503): the official source isn't answering; retry later.

Make the error body predictable too. A real one, from Fuentio's keyless trial once its daily units are used:

{"data": null, "meta": {"request_id": "req_IeGVSzl1UrGq9C6C"},
 "error": {"code": "quota_exceeded", "message": "Quota used up: 20 of 20 units today.",
  "hint": "The keyless trial starts again tomorrow (UTC). For more now, get a free key (100 units a month) with POST /v1/keys."}}

Our quickstart covers retries in more detail: first call, units, errors and retries.

Caching without lying

Registers are slow to change and sometimes slow to answer, so you will cache. The rule is to say so. Give each source a freshness window, return retrieved_at and last_verified_at, flag answers served from cache, and when the source is down, return the stored copy as stale rather than as current. Let callers ask for fresher data when they need it (Fuentio takes a max_age in seconds).

Keep a snapshot of what you served, with a hash, so you can prove later what the answer was. That is the idea behind receipts and proof codes.

Saying "we don't know"

Incomplete information is normal, and the API's job is to make it visible:

  • Spain: the BORME publishes acts, not a status. A company with no act about its status since 2009 has no stated status, so the honest outcome is status_unknown or partial, never "active".
  • France: "cessée" in Sirene is a closed unit, not proof of legal dissolution. Say "ceased", not "dissolved".
  • United Kingdom: figures come only from accounts filed electronically, and small companies rarely file turnover. An empty field means "not filed", not "zero".

Personal data and untrusted text

Company records contain people: directors, shareholders, sole traders. Decide early what you never serve, and strip it at ingestion rather than at display. And treat every text field copied from a register as data, never as instructions, especially if AI agents read your answers.

Limits

Frequently asked questions

Should a company verification API return true or false?

No. A boolean can't distinguish "ceased", "not covered", "source down" and "status not stated". Return an outcome from a closed list with reasons.

How should an API handle a company it can't find?

Separate an invalid identifier, a valid identifier outside coverage, and a valid identifier with no record. They lead to different next steps.

How long can company data be cached?

As long as the source's own refresh cycle and your use case allow, provided the answer says when it was last verified and is marked stale when it is older than the rule.

Do I need source attribution in API responses?

Open registers usually require it under their licences, and it lets your users prove where a fact came from. Put it in every response, not only in the documentation.

Sources

← All articles · RSS feed