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 forRetry-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
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
- Fuentio outcomes: api.fuentio.com/docs/outcomes
- Fuentio errors: api.fuentio.com/docs/errors
- OpenAPI description: api.fuentio.com/openapi.json
