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

Source: https://fuentio.com/blog/fuentio-api-walkthrough-lookup-to-verification/

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](/blog/fuentio-api-quickstart-first-call-units-errors/) 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](/coverage/) 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"
```

```json
{
  "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](/blog/find-spanish-company-by-name-registro-mercantil-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
```

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

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

```json
"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](/blog/active-company-not-always-safe-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](/proof/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](/blog/verifiable-company-check-record/).

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

```python
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](/proof/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](/blog/verify-company-proof-code-api/).

## 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](/blog/how-to-pay-for-fuentio-creem-checkout/)), 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](/blog/company-data-api-pricing-units-explained/).

## Limits

> A verification reports what the official register states on the day; it isn't full KYB, ownership checking or sanctions screening, and "verified" isn't a statement that a company is safe to deal with. In Spain a company can't be looked up by its NIF/CIF, and its status is unknown unless a BORME act says otherwise; in France, "ceased" isn't a legal dissolution. No answer contains a person's name. The keyless trial is limited to 20 units a day and 1 request per second.

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

- Fuentio API reference: [api.fuentio.com/llms.txt](https://api.fuentio.com/llms.txt)
- Fuentio outcomes: [api.fuentio.com/docs/outcomes](https://api.fuentio.com/docs/outcomes)
- Fuentio errors: [api.fuentio.com/docs/errors](https://api.fuentio.com/docs/errors)
- OpenAPI description: [api.fuentio.com/openapi.json](https://api.fuentio.com/openapi.json)
