From Company Lookup to Verification Decision: A Fuentio API Walkthrough

A real walkthrough of Fuentio's API: coverage, name search, lookup, verification outcomes, proof codes and receipts, with working Python and recorded answers.

· Updated 17 October 2026 · By the Fuentio team · 7 min read

Share image: "From Company Lookup to Verification Decision: A Fuentio API Walkthrough" on Fuentio's paper background, with the Tutorial label.

This walkthrough follows one company check from start to finish with Fuentio's REST API: find the company, look it up, verify it, keep the evidence, and turn the outcome into a decision in your own code. Every answer shown is a real one, recorded from the live API and trimmed for length, and the Python at the end was run against the API before this article was published.

What you'll learn

  • How to check coverage, search by name and look a company up by its number
  • What a verification returns: outcome, reasons, checks, signals and a proof code
  • How to retrieve the result later, as a proof page or a receipt
  • How to map outcomes to approve, review and decline, in working Python

Short answer: search by name if you don't have the official number (2 units), look the company up by its number (1 unit), then call POST /v1/verifications (5 units) for an outcome with reasons and a proof code. Map verified, partial and unverified to your own actions, and keep the proof code with your decision. No key is needed to try it: the keyless trial gives 20 units a day.

Before you start

The base address is https://api.fuentio.com. Every answer has the same envelope: data, meta (source, freshness, units charged) and error. Without a key you use the keyless trial, limited to 20 units a day and 1 request per second; with a key, send it as X-API-Key or Authorization: Bearer. A free key gives 100 units a month. If this is your very first call, the API quickstart covers units, errors and retries.

Step 1: check what's covered

GET /v1/countries is free and says which countries, identifier types and sources are available. For the United Kingdom it answers, among other things, that the coverage is the Companies House register, with each company's current record, dissolved ones included, its insolvency cases, charges and latest filings, and no officers or other people. France and Spain are covered too; the coverage page shows the same thing for people.

Step 2: find the company by name

If all you have is a name, search first. A real search for "mercadona" in Spain, recorded on 12 October 2026:

curl "https://api.fuentio.com/v1/companies/search?country=ES&q=mercadona"
{
  "data": [{
    "id": "ES-RMHOJA-V-5581",
    "name": {"original": "MERCADONA SA"},
    "identifiers": [{"scheme": "ES_RM_HOJA", "value": "V-5581", "primary": true}],
    "registered_address": {"original": "C/ ALFONSO ROIG ALFONSO S/N (ALBALAT DELS SORELLS)", "region": "VALENCIA/VALÈNCIA"},
    "match": {"score": 0.95, "reasons": ["name_normalized_exact"]}
  }],
  "meta": {"total": 1}
}

One candidate, matched exactly after normalisation. With a common name you would get many: the same search for "telefonica" returned 251. Pick the candidate by its identifier, never by the top score alone; how to find a Spanish company by name and read its sheet shows the full routine.

Step 3: look the company up

With the official number, a lookup returns the record. A real answer for DANONE, SIREN 552032534, recorded on 12 October 2026 and trimmed:

curl https://api.fuentio.com/v1/companies/FR/552032534
{
  "id": "FR-SIREN-552032534",
  "name": {"original": "DANONE"},
  "legal_form": {"original_label": "SA à conseil d'administration (s.a.i.)", "elf_code": "K65D"},
  "status": {"value": "active", "original_label": "Active", "as_of": "2026-09-10"},
  "registered_address": {"original": "59-61 RUE LA FAYETTE 75009 PARIS"},
  "activity": {"original_code": "70.10Z", "original_label": "Activités des sièges sociaux", "nace_rev2": "70.10"},
  "identifiers": [
    {"scheme": "FR_SIREN", "value": "552032534", "primary": true},
    {"scheme": "FR_SIRET", "value": "55203253400703", "primary": false},
    {"scheme": "EU_VAT", "value": "FR27552032534", "primary": false}
  ],
  "provenance": {"source": "fr_recherche_entreprises", "last_verified_at": "2026-10-11T22:06:01.689264Z"}
}

Each value keeps the register's own wording (original_label) next to a normalised one, and the provenance says where it came from and when it was last verified. A lookup costs 1 unit. It tells you what the record says; it doesn't give you a decision.

Step 4: verify the company

A verification reads the record, runs a fixed set of checks and returns an outcome. A real verification of TESCO PLC, run on 16 October 2026:

curl -X POST https://api.fuentio.com/v1/verifications \
  -H "Content-Type: application/json" \
  -d '{"country": "GB", "identifier": "00445790"}'
{
  "data": {
    "proof_code": "FUE-GB-20261016-5QBDT2",
    "checked_at": "2026-10-16T08:41:27.492024+00:00",
    "checks": [
      {"check": "identifier_valid", "result": "pass"},
      {"check": "record_found", "result": "pass"},
      {"check": "status_active", "result": "pass"},
      {"check": "address_present", "result": "pass"},
      {"check": "fresh", "result": "pass"}
    ],
    "signals": {"insolvency": {"value": "none_found", "note": "Companies House insolvency record checked (the company's whole life); none found"}},
    "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."}
  },
  "meta": {"cost": {"units": 5}}
}

The outcome is one of three for a company check: verified, partial or unverified. The reasons say why in machine-readable codes, the checks show each step, and the signals report closure, dissolution and insolvency findings.

What an "unverified" answer looks like

The same call for APPLETREE FARM CRESSING LIMITED (company number 12401266), on the same day:

"checks": [{"check": "no_open_insolvency", "result": "fail", "detail": "Companies House: status 'In Administration' (administration open)."}],
"result": {"outcome": "unverified", "reasons": ["insolvency_administration"]}

The company is still on the register, but an administration is open, so it is not verified. Why that distinction matters is covered in an active company is not always a safe company to onboard.

And a "partial" one

For MERCADONA SA in Spain, recorded on 12 October 2026, the outcome was partial with the reasons status_unknown and events_only_coverage: the BORME publishes acts, and none states the company's current status. The check status_active came back unknown, not fail.

Step 5: keep and retrieve the evidence

Every verification has a proof code. Keep it with your decision; you can get the result back at any time, free:

  • GET /v1/verifications/{id or proof code} returns the stored verification.
  • GET /v1/public/proofs/{proof_code} returns the public version, no key needed, and anyone can open it on our proof page: FUE-GB-20261016-5QBDT2.
  • GET /v1/receipts/{request_id} returns the receipt of an answer: the stored copy with its hash and snapshot reference.

Proof codes are kept for 24 months. What a complete record should hold, and why a receipt isn't a legal certificate, is in what a verifiable company check record should contain.

Step 6: turn the outcome into a decision

The API reports; your code decides. This Python uses only the standard library and maps outcomes to actions. Anything unexpected goes to review:

import json
import urllib.error
import urllib.request

API = "https://api.fuentio.com"
DECISION = {"verified": "approve", "partial": "manual_review", "unverified": "decline"}


def verify(country, identifier, key=None):
    """POST /v1/verifications: the outcome, reasons and a proof code (5 units)."""
    headers = {"Content-Type": "application/json", "Accept": "application/json"}
    if key:
        headers["X-API-Key"] = key
    req = urllib.request.Request(f"{API}/v1/verifications", method="POST", headers=headers,
                                 data=json.dumps({"country": country, "identifier": identifier}).encode())
    try:
        with urllib.request.urlopen(req, timeout=30) as r:
            return json.load(r)
    except urllib.error.HTTPError as e:  # 4xx and 5xx answers carry the same {data, meta, error} body
        return json.load(e)


body = verify("GB", "00445790")
if body.get("error"):
    print("error:", body["error"]["code"], "-", body["error"].get("hint", ""))
else:
    v = body["data"]
    outcome = v["result"]["outcome"]
    print(outcome, v["result"]["reasons"], v["proof_code"])
    print("decision:", DECISION.get(outcome, "manual_review"))

Run keyless on 16 October 2026, it printed:

verified ['company_active'] FUE-GB-20261016-VY43F6
decision: approve

That run created its own proof code, which anyone can open: FUE-GB-20261016-VY43F6.

Handling errors

Errors come from a closed list, each with a hint. The ones to handle first:

  • invalid_identifier (400): the number is malformed; ask the user to correct it.
  • not_found (404): valid number, no record. It costs 1 unit.
  • rate_limited (429): too many requests per second; wait for Retry-After.
  • quota_exceeded (402): units used up. The keyless trial resets the next day (UTC).
  • upstream_unavailable (503): the official source isn't answering; retry later.

For more on verification options, such as passing your own reference with the request, see how to verify a company and get a proof code.

What it costs, and how to pay

A search costs 2 units, a lookup 1 and a verification 5; receipts, stored verifications and coverage are free. When the trial and the free key aren't enough, plans start with Starter at €49 a month for 2,000 units. You pay by card from the pricing page (how to pay for Fuentio: secure checkout with Creem), and the paid key is emailed as soon as the payment clears. Prices exclude VAT, and there is no overage billing: at the limit, the API answers quota_exceeded. More in company data API pricing explained.

Limits

Frequently asked questions

Do I need an API key to follow this walkthrough?

No. The keyless trial gives 20 units a day, enough for a search, a lookup and two verifications. A free key gives 100 units a month.

What is the difference between a lookup and a verification?

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

How do I get a verification result again later?

Call GET /v1/verifications/{id or proof code}, free, or open the proof code on fuentio.com/proof/. Codes are kept 24 months.

Which outcome should block onboarding?

That is your policy. A common choice: approve verified, review partial, decline or escalate unverified, and review anything else.

Sources

← All articles · RSS feed