--- title: "Resolve up to 100 companies in one call" method: POST path: "/companies/lookup" tags: ["Companies"] --- # Resolve up to 100 companies in one call `POST /companies/lookup` ## Request - Base URL: `https://api.prometiam.com/functions/v1/risk-api` - URL: `https://api.prometiam.com/functions/v1/risk-api/companies/lookup` - Auth: HTTP bearer Batch form of `GET /companies/search`. Each item resolves through the same rules as the single-endpoint call (country routing, surface ids, match scoring). Every item costs 1 credit against the plan's per-minute, daily and monthly limits; a batch that does not fit is refused up front with 429 `batch_exceeds_quota` and `max_items_now`. Items are processed in parallel groups; anything not finished inside the time budget comes back as `timeout` and can be resent. Supports an optional `Idempotency-Key` header (see the parameter) for safe replay of the whole batch. ## Headers - `Idempotency-Key` string ## Request body - object - `items` CompanyLookupItem[], required - `country` 'ES' | 'FR' | 'GB' | 'IE' | 'PL' | 'NO' | 'FI' | 'SE' | 'HR' | 'BE' | 'DK' | 'EE' | 'SK' | 'CH' | 'LV' | 'CY' | 'RO' | 'LT' | 'CA' | 'AU' | 'JP' | 'IL' | 'BR' | 'CO' | 'SG' | 'TW' | 'CZ' | 'DE' | 'US': Registry to search. Defaults to the key's first allowed country, then ES. - `company_number` string: Registry number: NIF (ES), SIREN (FR), Companies House number (GB), CRO (IE), KRS (PL), organisasjonsnummer (NO). Aliases: `nif`, `siren`, `vat`. - `nif` string - `siren` string - `vat` string - `name` string: Company name for a fuzzy lookup; the best match is returned with its match_score. ## Response `200` Results in request order - object - `data` CompanyLookupResult[]: One result per item, in request order. - `index` integer: Position of the item in the request array. - `input` object: The item as sent. - `error` string, nullable: Set when status is error or timeout. - `status` 'found' | 'not_found' | 'error' | 'timeout' - `company` Company: The standard company object. Every company the API returns (search items, the detail, a batch lookup `company`) has these keys in this order in every live country; a value the register does not publish is null, never left out. The register's own values stay beside the standard ones as `local_*` fields; what only one register has is in `registry_details`. Name, address, city, municipality and region are UPPERCASE; activity_description is sentence case. - `id` integer: Company id. Spanish ids are plain numbers; Norwegian ids are the organisasjonsnummer; France, the United Kingdom, Ireland and Poland carry a country offset (FR +1e12, GB +2e12, IE +3e12, PL +4e12), as do Sweden (+6e12), Finland (+7e12), Belgium (+8e12), Denmark (+9e12), Croatia (+10e12), Switzerland (+11e12), Estonia (+12e12), Slovakia (+13e12), the United States (+14e12), Latvia (+18e12), Cyprus (+19e12), Romania (+17e12), Lithuania (+20e12), Canada (+21e12), Australia (+22e12), Japan (+23e12), Brazil (+24e12), Israel (+25e12), Colombia (+26e12), Singapore (+28e12), Taiwan (+29e12) the Czech Republic (+16e12) and Germany (+30e12). Every id names its country, so GET /companies/{id} needs no country parameter. - `match_score` integer, nullable: Relevance/confidence of a fuzzy name match, 0–100 (pg_trgm similarity × 100 — identical to the sanctions screen's score). Present only for `name` search; null for exact id/number lookups and the founded_after feed. Name-search results are ranked by this score, best first. - `country` 'ES' | 'FR' | 'GB' | 'IE' | 'PL' | 'NO' | 'FI' | 'SE' | 'HR' | 'BE' | 'DK' | 'EE' | 'SK' | 'CH' | 'LV' | 'CY' | 'RO' | 'LT' | 'CA' | 'AU' | 'JP' | 'IL' | 'BR' | 'CO' | 'SG' | 'TW' | 'CZ' | 'DE' | 'US' - `company_number` string, nullable: The register's own number, every country: NIF (ES), SIREN (FR), Companies House number (GB), CRO number (IE), KRS (PL), organisasjonsnummer (NO, SE), business ID (FI), enterprise number (BE), MBS (HR), CVR number (DK), registry code (EE), IČO (SK), UID (CH), registration number (LV), registration number (CY), CUI (RO), the state code and register number such as NY-4424185 (US), or CIK-… / LEI-… for an SEC filer or LEI holder without a state registration in the five registers; legal entity code (LT), corporation number (CA), ACN or ARBN (AU), corporate number (JP), company number (IL), CNPJ shown 00.000.000/0001-91 (BR), NIT (CO), UEN (SG), unified business number (TW), IČO (CZ), LEI (DE). The same value is the first entry of `identifiers`. - `company_name` string: Registered name, always UPPERCASE. Null for a French company that opted out of publication (INSEE non-diffusible; `status` is `withheld` and `registry_details.non_diffusible` is true): the register gives a placeholder instead of a name, and the API does not pass it on as one. Name searches and the founding-date feed never return these companies; a SIREN or SIRET lookup does. - `previous_names` object[], nullable: Former registered names, one shape for every country (GB, NO, PL; PL is filled progressively from the full KRS extract); null when the register publishes none. - `name` string - `from_date` string, date, nullable - `until_date` string, date, nullable - `identifiers` object[]: Every identifier the register publishes for the company, the registry number first. Replaces the per-country keys nif, siren, siret, rcs_number, nip, regon and oib. - `type` string: nif (ES); siren, siret, rcs (FR); crn (GB); cro_number (IE); krs, nip, regon (PL); orgnr (NO, SE); business_id (FI); enterprise_number (BE); mbs, oib (HR); cvr (DK); registry_code (EE); ico (SK); uid, ch_id (CH); state_registration, cik, ein, lei (US: the state registration number such as NY-4424185, the SEC CIK, the EIN of SEC filers and the LEI); vat (the VAT number, same value as `vat_number`). - `value` string - `vat_number` string, nullable: VAT number of the company, also listed in identifiers as type vat. See vat_number_source for how it was obtained. `register`: published by the register (EE; LV from the State Revenue Service’s list of VAT payers; LT from the State Tax Inspectorate’s list; AU the ABN while GST-registered; TW the unified business number where the company is in the tax file) or the register confirms VAT registration and the number is the law's format of its identifier (NO, FI, BE). `rule`: built from the company's identifier (ES `ES`+NIF, FR `FR`+key+SIREN, PL `PL`+NIP, NO `NO`+number+`MVA`, FI, SE `SE`+number+`01`, BE, HR `HR`+OIB, DK): the format is right, the registration is not confirmed (check it with `GET /vat/{number}`). Null where the register says the company is not VAT-registered (NO, FI), where a Latvian company is not on the State Revenue Service’s list of VAT payers, and where no rule exists (GB, IE, SK, CY, US, CA, JP, IL, BR, CO, SG, CZ, DE, and EE without a published KMKR). - `vat_number_source` 'register' | 'rule', nullable: register: the register publishes the number or confirms VAT registration (EE, NO, FI, BE). rule: built from the company's identifier, format right but registration not confirmed (check it with GET /vat/{number}). Null when vat_number is null. - `lei` string, nullable: Legal Entity Identifier (20 characters) when the company has one; null otherwise. The GLEIF record itself is `lei_record` (ES, `include=lei`). - `legal_form` string, nullable: Standard abbreviation of the legal form (SA, SL, Ltd, sp. z o.o., AS, Oy, AB, BV, d.o.o., A/S...), or, for a form with no abbreviation, the form's name (English where available, else the register's language: for example "Branch" for a Swiss branch, "Overseas entity" for a GB overseas entity, a Belgian form's Dutch or French name). Never an internal code. Null only when the form is not mapped; `local_legal_form` and `local_legal_form_name` then still carry the register's own value. - `legal_form_family` string, nullable: Cross-country family of the legal form (for example private_limited_company, public_limited_company, sole_proprietorship), for comparing entity types across countries. - `local_legal_form` string, nullable: The register's own legal-form value or code as stored (for example "SA", "114" in BE, "60" in DK, "UTLA" in NO). - `local_legal_form_name` string, nullable: The register's name for `local_legal_form`, where it publishes one. - `status` 'active' | 'active_strike_off_pending' | 'suspended' | 'not_yet_active' | 'in_restructuring' | 'in_administration' | 'in_receivership' | 'insolvent' | 'in_liquidation_insolvent' | 'in_liquidation' | 'in_compulsory_liquidation' | 'in_dissolution' | 'deregistered' | 'merged' | 'withheld', nullable: STANDARD status, the same list in every country (from the multilingual mapping dictionary). Null when the dictionary does not know the stored value. Ambiguities the dictionary keeps apart: ES/FR "dissolved" means the company still exists pending liquidation (`in_dissolution`), while GB/IE/PL/NO "dissolved" is `deregistered`. `withheld`: the register does not disclose the state (France's non-diffusible entities, whose `company_name` is null and `registry_details.non_diffusible` true). The register's own value is `local_status`. - `stage` 'active' | 'distress' | 'winding_up' | 'closed' | 'unknown', nullable: Lifecycle stage of `status`: active (registered and trading), distress (a formal rescue/administration/insolvency proceeding is open, still exists), winding_up (dissolved or in liquidation, still exists only to be wound up), closed (no longer exists), unknown (the register does not disclose the state). Null when `status` is null. - `local_status` string, nullable: The register's own state as stored (for example GB "dissolved", FR "radiated", ES "absorbed" for a company closed by a merger). Filter by it with the `local_status` query parameter. - `status_date` string, date, nullable: Date of the latest status change, where the register states it. CY, LV and SK: the date the current status began; null for an active company where the register states none. - `founding_date` string, date, nullable: Incorporation date. - `registration_date` string, date, nullable: Date of entry in the register, where it differs from the incorporation date. - `dissolution_date` string, date, nullable: Dissolution date, where the register states it. - `activity_code` string, nullable: Main economic-activity code as the register gives it (one code; the others are in `secondary_activity_codes`). `activity_code_scheme` names its classification. - `activity_code_scheme` 'CNAE' | 'NAF-REV2' | 'NAF-REV1' | 'UK-SIC-2007' | 'UK-SIC-2003' | 'NACE-REV2' | 'PKD' | 'SN-2025' | 'TOL-2025' | 'SNI-2025' | 'NACE-BEL-2025' | 'NKD-2025' | 'NKD-2007' | 'DB-2025' | 'EMTAK-2008' | 'EMTAK-2025' | 'SK-NACE-2025' | 'CAEN-REV3' | 'CAEN-REV2' | 'CAEN-2003' | 'CAEN-1998' | 'LT-NACE-2025' | 'CZ-NACE-2025' | 'BR-CNAE-2.3' | 'CO-CIIU-REV4-AC' | 'SG-SSIC-2020' | 'TW-TAX-SIC', nullable: The classification `activity_code` is written in: `CNAE` (ES), `NAF-REV2` (FR; `NAF-REV1` for codes still in the old format), `UK-SIC-2007` (GB; `UK-SIC-2003` for older 4-digit codes), `NACE-REV2` (IE), `PKD` (PL), `SN-2025` (NO), `TOL-2025` (FI), `SNI-2025` (SE), `NACE-BEL-2025` (BE), `NKD-2025` or `NKD-2007` (HR), `DB-2025` (DK), `EMTAK-2008` or `EMTAK-2025` (EE), `SK-NACE-2025` (SK), `LT-NACE-2025` (LT; NACE Rev. 2.1 class), `CZ-NACE-2025` (CZ; CZ-NACE 2025, NACE Rev. 2.1 class), `BR-CNAE-2.3` (BR; CNAE-Subclasses 2.3, 7 digits), `CO-CIIU-REV4-AC` (CO; CIIU Rev. 4 adapted for Colombia, 4 digits), `SG-SSIC-2020` (SG; 5 digits, a legacy 4-digit code has no scheme) and `TW-TAX-SIC` (TW; the Ministry of Finance tax industry code, 6 digits). BR, CO, SG and TW codes are not NACE codes and `nace_class` is null for them. ES and PL name the system without a version: their records hold codes of both the older version (CNAE-2009, PKD 2007) and the 2025 one, and do not say which. RO names the CAEN edition: `CAEN-REV3` (CAEN Rev.3 = NACE Rev. 2.1), `CAEN-REV2` (= NACE Rev. 2); older codes keep their edition (`CAEN-2003`, `CAEN-1998`). The 2025 versions follow NACE Rev. 2.1, the older ones NACE Rev. 2. Null when there is no code or the value is not a code (a sector label on some Spanish companies). - `activity_description` string, nullable: Label of `activity_code` from the official classification table, in the register's language (English for GB and IE), in sentence case. - `activity_description_en` string, nullable: English label: the UK SIC title for GB, otherwise the NACE class title from Eurostat. - `nace_class` string, nullable: The NACE class of the activity code, comparable across countries (for example "46.33"). - `nace_version` string, nullable: NACE version of `nace_class`: "2" or "2.1". - `secondary_activity_codes` object[]: The other activity codes the register lists: GB's other SIC codes, SE's other SNI codes, and for CO and SG the other codes with their titles. Empty array elsewhere. - `code` string - `scheme` string, nullable - `description` string, nullable - `business_purpose` string, nullable: The purpose clause as registered: objeto social (ES), objet social (FR), Zweck (CH), verksamhetsbeskrivning (SE, personal identifiers redacted). Null elsewhere. - `address` string, nullable: Registered address, UPPERCASE. - `postal_code` string, nullable - `city` string, nullable: UPPERCASE. - `municipality` string, nullable: Municipality, where the register gives one (NO, FI, SE, BE, HR, DK); UPPERCASE. - `region` string, nullable: First-level region, UPPERCASE: provincia (ES), departement (FR), county (GB, IE), wojewodztwo (PL), fylke (NO), maakunta (FI), lan (SE), province or Brussels-Capital Region (BE), zupanija (HR), region (DK), maakond (EE), kraj (SK), canton (CH), region (LV), district (CY), county (RO), state or county (US), county (LT), province or territory (CA), state (AU), prefecture (JP), district (IL), state (BR), department (CO), county or city (TW), region (kraj) (CZ); none for SG. - `address_country` string, nullable: ISO 3166 country code of the address. - `capital_amount` number, nullable: Share capital in `capital_currency`, as last published by the registry. ES: BORME only publishes capital inside incorporation / capital-increase / capital-reduction notices, so a company whose capital was last set before the 2009 digital editions may return null even when it is a public SA. - `capital_currency` string, nullable: ISO 4217 code of `capital_amount`. - `capital_eur` number, nullable: One euro figure for share capital in every country: the amount when it is in EUR, otherwise converted at the ECB reference rate of 2 October 2026 (one fixed date, an approximation for comparing sizes, not the rate of the registration day); Croatian kuna at the fixed rate of 7.53450. Null when the capital or its currency is missing (Denmark publishes none). - `employees` integer, nullable: Employee count where the register publishes one. - `employee_band` string, nullable: Size band of the workforce (FR); DK: the register's employment interval where CVR states it. Null elsewhere. - `website` string, nullable: The company's website when it is known with proof: from the register itself (NO, FI; BE from the KBO contact file; PL from the KRS record) or from Wikidata's official website matched by register number. Read `website_source` for how it was found. Null when none is known. Websites guessed from the company name (ES, FR, GB) stay in `contacts`. - `website_source` object, nullable: How `website` was found. Null when `website` is null. - `method` 'registry' | 'wikidata' | 'id_on_site' | 'name_address' | 'email_domain': registry: published by the company register; wikidata: Wikidata's official website on the item carrying the company's register number; id_on_site: the site shows the company's register or VAT number; name_address: the site shows its name and its postcode or town; email_domain: the domain of an e-mail the register publishes, confirmed by fetching the site. - `confidence` number: 0-1. 0.98 registry, 0.95 wikidata, 0.90 id_on_site, 0.80 email_domain, 0.75 name_address. - `found_in` string, nullable - `source_url` string, nullable - `checked_at` string, date-time, nullable - `register` string, nullable: Name of the register the record comes from. - `first_seen_date` string, date, nullable: First date this record appeared in a registry publication held by the API. For registers loaded from a bulk snapshot this is the load date, not the incorporation date; use founding_date for incorporation. - `last_seen_date` string, date, nullable: Most recent registry publication or snapshot in which this record appeared. For GB the value can lag the register by up to a month between snapshots. - `updated_at` string, date-time, nullable - `registry_details` object: What only one register has. ES: registro_tomo, registro_libro, registro_folio, registro_seccion, registro_hoja, registro_inscripcion, registry_sheet_closed_date (the latest BORME provisional closure of the registry sheet still in force; a registry-compliance signal, not a dissolution; also served as the `registry_compliance` entry under `include=risk_flags`). FR: greffe (also from INPI's RNE), category, non_diffusible (true when INSEE withholds the company's name, false otherwise). GB: jurisdiction (read from the company-number prefix in Companies House's own terms, upper case: ENGLAND-WALES, SCOTLAND, NORTHERN-IRELAND, and UNITED-KINGDOM for overseas companies and registered overseas entities, prefixes FC/NF/SF/OE/SE/BR), next_accounts_due, next_confirmation_due, address_line1, address_line2. IE: jurisdiction, next_accounts_due, last_ar_date. AU: abn_status (ACT or CAN), gst_from (null unless GST-registered). LT: sector_code (the ESA institutional sector code, no label). BR: size_class (ME, EPP or DEMAIS) with size_class_name, and district (the bairro). PL: jurisdiction. NO, FI, SE, BE, HR, DK: sector_code, in_group, vat_registered, last_accounts_year. CH: ch_id, legal_seat. US: jurisdiction (state of formation), registration_state, registration_type (domestic or foreign), status_code and sub_status (the register's own), naics_code, sic_code, tickers, sources (which feeds the record merges). - `match_score` integer, nullable: 0-100 for name items; null for exact identifier lookups. - `meta` object - `items` integer - `errors` integer - `query_ms` integer - `note` string - `rate_limit` object - `found` integer - `not_found` integer ## Other responses - `400`: Malformed body, empty items, more than the per-call maximum, or a malformed `Idempotency-Key` (`validation_error`). - `403`: Scope not in the plan (`upgrade_required`). Batch calls do not draw on the free trial allowance. - `409`: `idempotency_key_in_progress`: a request with this `Idempotency-Key` is still running. `Retry-After` says how long to wait. - `422`: `idempotency_key_reuse`: this `Idempotency-Key` was already used with a different request body. - `429`: `batch_exceeds_quota`: the batch has more items than the tightest active limit allows (credits or requests); `max_items_now` says how many fit. --- [API](https://skmtc.dev/prometiam/apis/prometiam-risk-intelligence-api.md) · [All operations](https://skmtc.dev/prometiam/apis/prometiam-risk-intelligence-api/llms.txt) · [OpenAPI document](https://skmtc.dev/prometiam/apis/prometiam-risk-intelligence-api/revisions/b01703443e4e?raw)