Can I look companies up by name in a batch?

Yes. Give name and country. You get the best match with a match_score, not an exact hit, so keep a human or a rule on low scores.

Does a not_found mean the company does not exist?

It means no record in the register data carries that identifier, which also happens with a typo that still passes the check. Check the number at the source for anything that matters.

How do I check the customers I found for insolvency or sanctions?

Run the companies through POST /insolvency/check (2 credits an item) or POST /sanctions/screen (3 credits a name, beta). Each is its own batch.

Is the batch faster than single calls?

It saves the round trips: one request and one answer instead of one per company. No speed figure is published; items not finished inside the time budget come back as timeout and can be resent.

How do I verify a whole customer list in one API call?

POST /companies/lookup takes up to 100 items, each a country plus an identifier or a name, and answers one result per item in your order: found, not_found or error. The demo key works.

The call

Four items: a Spanish NIF, a British company number, a French SIREN that does not exist and a Spanish NIF with a typo.

curl -X POST 'https://api.prometiam.com/functions/v1/risk-api/companies/lookup' \
  -H 'Authorization: Bearer rk_live_demo_publichn' \
  -H 'Content-Type: application/json' \
  -d '{"items": [
        {"country": "ES", "company_number": "A15075062"},
        {"country": "GB", "company_number": "00445790"},
        {"country": "FR", "siren": "999999999"},
        {"country": "ES", "company_number": "A1507506"}
      ]}'

The answer

Returned on 10 November 2026 with the demo key. Each company is the full company object, cut here to a few fields:

{
  "data": [
    { "index": 0, "input": { "country": "ES", "company_number": "A15075062" },
      "status": "found",
      "company": { "id": 1741526, "company_number": "A15075062", "company_name": "INDUSTRIA DE DISEÑO TEXTIL, S.A", "status": "active", ... } },
    { "index": 1, "input": { "country": "GB", "company_number": "00445790" },
      "status": "found",
      "company": { "id": 2000004984338, "company_number": "00445790", "company_name": "TESCO PLC", "status": "active", ... } },
    { "index": 2, "input": { "country": "FR", "siren": "999999999" },
      "status": "not_found", "company": null },
    { "index": 3, "input": { "country": "ES", "company_number": "A1507506" },
      "status": "error",
      "error": "\"nif\" / company_number for country=ES is a company NIF (CIF): an entity letter, seven digits and a valid control character ...",
      "company": null }
  ],
  "meta": {
    "items": 4, "found": 2, "not_found": 1, "errors": 1,
    "note": "Each item costs 1 credit. Items with a name return the best match with its match_score; identifier items are exact.",
    ...
  }
}

How to read the answer

Field	What it tells you
`index`	The position of the item in your request. Results come back in request order.
`status` `found`	The register holds the identifier; `company` is the standard company object.
`status` `not_found`	A well-formed identifier that no record carries. `company` is null.
`status` `error`	The item could not be run, here a Spanish NIF that fails its check. `error` says why; the other items are still answered.
`input`	Your item, echoed back, so you can join the answer to your own rows.
`meta.found`, `not_found`, `errors`	The totals, for a quick check of the batch.

An item with a name instead of an identifier returns the best match with a match_score; look at it before you trust the match. Identifier items are exact.

What it costs

Every item counts as one request and costs 1 credit, as the note in the answer says. 100 items cost 100 credits. Plans: Starter EUR 9.99 includes 1,000 credits a month, Professional EUR 29.99 10,000, Scale EUR 99.99 50,000. Failed calls, such as a 400 for a malformed body, are free.

Limits

At most 100 items in a call. Send a longer list in several batches.
A batch that does not fit in the credits or the per-minute limit you have left is refused up front with 429 batch_exceeds_quota; nothing is run and max_items_now says how many items fit.
Items not finished inside the time budget come back as timeout and can be resent.
Send an Idempotency-Key header to replay a batch safely: the same key and body within 24 hours returns the first answer.
The scope limits of each country apply to its items: for example France includes sole proprietorships as INSEE publishes them, and a company that opted out of publication has company_name null.
The demo key is limited to 30 calls a minute, and a 30-item batch counts as 30 requests.

What can go wrong

400 validation_error: the body is malformed, items is empty or holds more than 100.
403 upgrade_required: the plan does not include the call.
429 batch_exceeds_quota: too many items for what is left of your allowance. Cut the batch to max_items_now and retry later.
409 or 422: an Idempotency-Key is still in use, or was used with a different body.

The free trial lasts 14 days and includes 500 credits. A card is required and nothing is charged during the trial; it then continues as Starter (EUR 9.99/month) unless you cancel.

Frequently asked questions

Can I look companies up by name in a batch?: Yes. Give name and country. You get the best match with a match_score, not an exact hit, so keep a human or a rule on low scores.
Does a not_found mean the company does not exist?: It means no record in the register data carries that identifier, which also happens with a typo that still passes the check. Check the number at the source for anything that matters.
How do I check the customers I found for insolvency or sanctions?: Run the companies through POST /insolvency/check (2 credits an item) or POST /sanctions/screen (3 credits a name, beta). Each is its own batch.
Is the batch faster than single calls?: It saves the round trips: one request and one answer instead of one per company. No speed figure is published; items not finished inside the time budget come back as timeout and can be resent.