io.github.CloudCorpRecords/firmproof

Validate a company's registered address against the official address base: France via API Adresse (Base Adresse Nationale, IGN). Use it to check that an address exists and is the company's, or to geolocate it. Don't use it to find companies: call search_companies. Inputs: country and identifier, as lookup_company (e.g. 'FR', '441639465'). Returns: validated (true, false or null with a reason), normalized address, BAN ids, coordinates, precision, confidence, and how many active companies share the address. Limits: 1 unit. Spain not available yet. Read-only.

Check a company's insolvency notices and state: France from BODACC (safeguard, reorganisation, liquidation, plans, closures), Spain from BORME insolvency acts. Use it for credit or supplier checks. Don't use it for sanctions: call screen_company. Inputs: country and identifier, as lookup_company (e.g. 'FR', '441639465'). Returns: state (in_procedure, under_plan, closed, notice_found, none_found, not_covered), procedure, dates, notices with official citations, covered_since. Limits: 1 unit. No notice outside the loaded years is not proof of no procedure. Read-only.

Check a supplier list against the official registers: which suppliers are ok, which need a look and why (e.g. in liquidation since a date, per BODACC), with a proof code each, and a private report link to share. Use it for 2 to 100 suppliers at once, or to read a batch you started. Don't use it for one company: call verify_company. Inputs: rows [{reference, company_name, country, identifier}] (an official ID is best; a name alone counts only with postal_code and street matching one company), or batch_id. Returns: counts by review_state (ok, review, could_not_confirm, not_covered, error), the review rows with reasons, share_url; 'next' when still checking. Limits: 5 units a row (+2 for a name), checks reused 24 h free. A registry check, not KYB or sanctions clearance; no person's name.

Give a company's EU VAT number and how it was obtained. Registration is never checked: the answer links the official VIES page. Use it to fill an invoice or a supplier file. Don't use it as proof of VAT registration: check it on VIES. Inputs: country and identifier, as lookup_company (e.g. 'FR', '441639465'). Returns: number, origin (published or computed), registration_checked false, note, check_url. Limits: 1 unit. Spain: no VAT numbers published. Read-only.

Explain why two register records are, or are not, the same company: today's decision with reason codes and evidence, stored decisions, links, and whether they share one Fuentio entity. Use it after resolve_company or lookup_company when you must justify a match or a rejection. Don't use it to find companies: call resolve_company. Inputs: left and right, Fuentio record IDs (e.g. 'FR-SIREN-441639465', 'FR-LEI-969500F7JLTX36OUI695'). Returns: same_entity, summary, decision (status, band, reasons), stored_decisions, links, uncertainty. Limits: 1 unit. Read-only.

See what changed at a company, and when: versions with the fields that changed (address, status), each with its official source. Use it for changes over time. Don't use it for the current state: call lookup_company. Inputs: country FR or ES or GB; identifier as for lookup_company (441639465); optional id_scheme; page. Returns: versions newest first with source, fetched_at and the fields changed; dated events where the source has them (BORME acts, Companies House filings). meta.history_since says where history starts. Limits: 1 unit; keyless 20 units a day. Read-only. France: from Fuentio's first fetch of the company. Spain: from 2 January 2009. United Kingdom: the latest filings, and every change since Fuentio first held it. Search words: historique, historial, cambios, due diligence.

Show the evidence behind what Fuentio says about a company: for each field, the value served and every competing value with its source, record, retrieval time, source link and record hash; and the match decision behind each link. Use it to justify an answer in a review or an audit. Don't use it to look a company up: call resolve_company first for its entity_id. Inputs: entity_id (e.g. 'fu_7K3M9Q2XH4PZ'), optional field (name, status, address, legal_form, creation_date, activity), optional as_of 'YYYY-MM-DD'. Returns: evidence, links, decisions, uncertainty, how_to_check. Limits: 1 unit. Read-only.

Show a company's group: its parent and child companies from GLEIF (direct and ultimate parents), company to company, every edge with its source. Use it to map a company's group. Don't use it to look a company up: call resolve_company first for its entity_id. Inputs: entity_id (e.g. 'fu_7K3M9Q2XH4PZ'), depth 1 or 2. Returns: nodes (companies), edges (from, kind parent_of, to, source, evidence), ownership (signals only; beneficial owners not covered), uncertainty. Limits: 2 units; API key required. No people, no director links. A company without an LEI shows no links. Read-only.

Give back the Fuentio receipt of a verification by its proof code: outcome and reasons, status, legal form, registered office, insolvency (what was searched), source, check time, hash and the public link to check it. Use it when the user asks for a receipt or proof of a check. Always ask the user first: 'Normal or detailed receipt?', then call it. Use the proof code from verify_company. Don't use it to run a new check: call verify_company. Inputs: proof_code (e.g. 'FUE-FR-20261015-DZ7TP9', any case; a lookup's meta.receipt.request_id also works, same key), format 'normal' or 'detailed'. Returns: data.markdown, the branded receipt: show it as is; data.text, plain text. Limits: free; 30 a minute. The key that ran the check also sees its reference; anyone else, the public view. Read-only.

List the countries, ID formats and official sources Fuentio covers. Free, no key. Use it first when unsure whether a country or ID format is supported, or to explain coverage. Don't use it to check a company: call lookup_company or search_companies. Inputs: none. Example: list_coverage(). Returns: per country, status (available or planned), coverage level, ID formats with real examples and whether lookup works, regional registers, and sources with licence and update frequency. Limits: 0 units. Read-only. Covered today: France, Spain and United Kingdom. Search words: company registry, KYB, SIREN, RCS, Annuaire des Entreprises, société; BORME, Registro Mercantil, empresa, sociedad; Companies House, company number, Ltd, plc, LLP.

Look up one company in its official register by ID: status, address, legal form, activity, source and check date. Use it when you have an official ID. Don't use it with a name: call search_companies first. Inputs: country FR or ES or GB; identifier. FR: SIREN 441639465, SIRET 44163946500091, VAT FR63441639465, LEI 969500F7JLTX36OUI695. ES: Registro Mercantil sheet VI-23266, LEI 549300EEJH4FEPDBBR25 (no NIF/CIF). GB: company number 00445790, LEI 2138002P5RNKC5W2JZ46. Optional: id_scheme (if ambiguous), format (json, csv, tsv, markdown, html, xml, ndjson; xlsx or parquet as a 24 h link). Returns: the record, a one-line summary, meta with source, source_url, last_verified_at. Limits: 1 unit (also a valid ID not found); keyless 20/day. France: insolvency from BODACC since 2008. Public contracts won since 2024 (DECP, weekly). Spain: BORME acts since 2 January 2009. UK: no officers or PSCs. No person's name in any answer. For KYB steps, supplier checks, due diligence: SIREN, RCS, Annuaire des Entreprises, société; BORME, Registro Mercantil, empresa, sociedad; Companies House, company number, Ltd, plc, LLP.

Report an answer you believe is wrong or missing, so Fuentio checks it against the official source. Use it when a result contradicts an official document you hold. Don't use it to ask questions: call the lookup tools. Inputs: subject (entity ID, record ID such as 'FR-SIREN-441639465', or tool name), category (wrong_data, wrong_link, missing_data, wrong_status, other), message. Returns: issue_id, status 'open'. Limits: free; API key required; 20 reports per key per day.

Decide whether a company you know (an official ID, or a name with a postcode or town) is a company in the official registers, with evidence: candidates each with a decision, linked, possible or rejected, and the reasons. Use it to match a supplier or customer record to a register record. Don't use it to read a company you already identified: call lookup_company. Inputs: country FR or ES or GB; name ('Renault', postal_code '92100') and/or identifier (441639465); optional id_scheme, locality, limit (1-10). Returns: outcome (linked, possible_match, no_match), uncertainty, best, candidates with entity_id, reason codes and evidence. Limits: 2 units. Only an official ID links: a name, even with an address, is never proof. Read-only, nothing stored.

Produce one review-ready report on a company: identity and links with reasons, facts with sources, last year's changes and gaps, and every check at once (insolvency, sanctions, address, VAT, and in France the public contracts won). Use it for the registry part of a KYB or supplier review you must file (not full KYB: no UBO, PEP or adverse-media checks). Don't use it for one quick fact: call lookup_company. Inputs: country and identifier, as lookup_company (e.g. 'FR', '441639465'). Returns: company, facts, links, decisions, changes_last_year, modules, gaps, uncertainty, sha256, markdown. Limits: 8 units; API key required. Read-only.

Screen a company's own names against sanctions lists: EU Financial Sanctions File, UK Sanctions List, OFAC SDN list, France's registre des gels. Use it as the sanctions-list step of onboarding a supplier or customer (not full KYB). Don't use it to identify a company: call resolve_company or lookup_company first. Inputs: country and identifier, as lookup_company (e.g. 'FR', '441639465'). Returns: result 'possible_match' (list, entry, score, reasons, listing date, legal act, official link), 'no_match_found' or 'not_checked', the list versions, and a note. Limits: 2 units; API key required. A possible match is not proof; no match is never 'clear'. Read-only.

Find companies by name in the official registers of France, Spain and United Kingdom, 10 per page. Use it when you know a name but no ID, then call lookup_company or verify_company with an ID from the results. Don't use it when you already have an official ID. Inputs: country FR or ES or GB; query, 2 to 200 characters ('telefonica'). Optional: postal_code, locality, status, jurisdiction (regional registers), page, format; limit (up to 100 rows) with a file format. Returns: best match first, each with match.score (0-1) and reasons, name, status, address, IDs, provenance; meta.next_page. Limits: 2 units a page; files 2 per started 25 rows. Read-only. France: insolvency from BODACC since 2008. Public contracts won since 2024 (DECP, weekly). Spain: BORME acts since 2 January 2009. UK: no officers or PSCs. No person's name in any answer. Search words: SIREN, RCS, Annuaire des Entreprises, société; BORME, Registro Mercantil, empresa, sociedad; Companies House, company number, Ltd, plc, LLP, KYB, supplier check.

Verify a company against its official register, for onboarding or before paying or signing: an outcome with reasons, checks, warning signals and a proof code you can show an auditor. A registry check, not full KYB. Use it to decide about a company. Don't use it for a cheap single read (lookup_company) or with a name (call search_companies first). Inputs: country FR or ES or GB; identifier as for lookup_company (441639465); optional id_scheme; optional reference (your case id). Returns: outcome (verified, partial, unverified; open insolvency never verified) + reasons, checks, signals (present, none_found, not_covered), recent changes, provenance, proof code (FUE-…). Limits: 5 units (1 if not found); keyless 20/day. Stored 24 months. France: insolvency from BODACC since 2008. Public contracts won since 2024 (DECP, weekly). Spain: BORME acts since 2 January 2009. UK: no officers or PSCs. No person's name in any answer. Search words: KYB, KYC, verify supplier, vérifier une société, verificar empresa.

Watch a company: when its official records change, Fuentio POSTs the changes, signed, to your https endpoint. Use it to monitor a supplier or customer. Don't use it for a one-off check: call what_changed. Inputs: entity_id (from resolve_company), callback_url (your https endpoint; private or local addresses are refused). Returns: watch_id, signing_secret (shown once) and how to verify each POST. Limits: 1 unit; API key required; free plan 3 watches.

List what changed at a company since a date, from every official record Fuentio holds for it: status, name, address, legal form, and the source's dated events (BORME acts), each with its source and evidence. Use it to review a supplier or customer since your last check. Don't use it for the current state: call lookup_company. Inputs: entity_id (from resolve_company, e.g. 'fu_7K3M9Q2XH4PZ'), since 'YYYY-MM-DD', optional until. Returns: changes (type, old/new or added/removed, observed_at or effective_date, source, evidence), gaps (days not loaded, sources not checked since), uncertainty. Limits: 1 unit. A gap is never reported as no change. Read-only.