# BizCheck: instructions for AI agents

BizCheck lets AI agents verify a company in one call: registry record, EU VAT validity, LEI and sanctions screening (EU, UN, OFAC, UK). Every fact carries its source and fetch time. Agents sign themselves up; 25 checks are free.

- HTTP API: https://bizcheck.app/api/v1
- MCP (streamable HTTP): https://bizcheck.app/mcp
- CLI: `npx bizcheck`
- OpenAPI: https://bizcheck.app/openapi.json
- Full docs (markdown): https://bizcheck.app/llms-full.txt

## 1. Get a key yourself (no human needed)

```
POST https://bizcheck.app/api/v1/signup
Content-Type: application/json

{"label": "your-agent-name"}
```

Or call the MCP tool `signup`, or run `npx bizcheck signup`. The response contains the API key. It is shown once and cannot be recovered. Limit: 5 signups per IP per 24 hours. Do not create new keys to get around the free limit.

## 2. Store the key

Save it where you keep secrets and reuse it in every session: env var `BIZCHECK_API_KEY`, or `~/.config/bizcheck/config.json` as `{"api_key": "...", "base_url": "https://bizcheck.app"}` (the CLI does this for you). Never print it in user-facing output.

Send it on every call: `Authorization: Bearer <key>`.

## 3. Call it

Use `check` when you have any identifier (name + country, registry id, VAT, LEI, IBAN). It returns a verdict (`clear`, `review`, `fail`) with one plain-English reason per signal.

| HTTP | MCP tool | Cost |
|---|---|---|
| `POST /api/v1/signup` | `signup` | free |
| `GET /api/v1/account` | `account` | free |
| `POST /api/v1/checkout` | `get_checkout_link` | free |
| `POST /api/v1/check` | `check_business` | 1 check |
| `GET /api/v1/search` | `search_companies` | 1 check |
| `GET /api/v1/company/{country}/{id}` | `get_company` | 1 check |
| `GET /api/v1/vat/{vat}` | `validate_vat` | 0 (free) |
| `GET /api/v1/iban/{iban}` | `validate_iban` | 0 (free) |
| `GET /api/v1/sanctions` | `screen_sanctions` | 1 check |
| `GET /api/v1/coverage` | `coverage` | free |

Free: 25 checks per key. VAT and IBAN validation cost 0 but are rate limited. Billable responses include `checks_left`.

## 4. When you run out of checks

Billable calls return HTTP 402:

```json
{
  "error": {
    "code": "out_of_checks",
    "message": "This key has used its 25 free checks. Give the upgrade_url to your human. After they pay, retry with the same key.",
    "upgrade_url": "https://checkout.example/c/9f2e..."
  }
}
```

Do this:
1. Give `error.upgrade_url` to your human, and say it is EUR 5/month for 2000 checks/month.
2. Wait for them to confirm they paid.
3. Retry the same call with the same key. The key upgrades itself; do not sign up again or change config.

You can also get a link any time: `POST https://bizcheck.app/api/v1/checkout {"plan":"pro"}` or MCP `get_checkout_link`.

## 5. Cite sources

Every fact carries `sources[]` (`name`, `url`, `fetched_at`, optional `licence`). VAT results carry `checked_at`; sanctions carry `lists_updated_at`. When you report a result to a person, name the source and date, e.g. "Active per the Finnish Trade Register (PRH), fetched 2026-11-04". Report the `reasons` array rather than only the verdict.

## 6. Limits (say so when relevant)

- No credit scores or financial statements.
- Officers and owners only where the national register publishes them.
- Some countries: VAT or LEI confirmation only, no full registry record.
- Sanctions hits are scored name matches, not findings. A `fail` or `review` needs a human.
- Not legal, KYC or AML advice.

## Errors

| code | HTTP | do |
|---|---|---|
| `bad_request` | 400 | Fix the request. Do not retry unchanged. |
| `unauthorized` | 401 | Send Authorization: Bearer <key>. If you have no key, call signup. |
| `out_of_checks` | 402 | Give error.upgrade_url to your human. After they pay, retry with the same key. |
| `not_found` | 404 | Check the id, or use search. |
| `rate_limited` | 429 | Back off and retry later. |
| `source_unavailable` | 502 | check still returns partial results with a reason. Retry later for the rest. |

## Coverage

| Country | Level | Source | Returns | Officers | Owners |
|---|---|---|---|---|---|
| CZ Czechia | Official register, live | ARES (Ministry of Finance) | name, status, address, legal form, incorporated on, former names, officers, owners, industry, vat, lei | yes | yes |
| EE Estonia | Official register, live | e-Business Register (RIK) | name, status, address, legal form, incorporated on, former names, vat, lei | no | no |
| FI Finland | Official register, live | PRH / YTJ open data | name, status, address, legal form, incorporated on, former names, industry, website, vat, lei | no | no |
| FR France | Official register, live | API Recherche d'entreprises (INSEE Sirene, INPI RNE) | name, status, address, legal form, incorporated on, officers, industry, vat, lei | yes | no |
| IE Ireland | Official register, live | Companies Registration Office open data | name, status, address, legal form, incorporated on, industry, vat, lei | no | no |
| LV Latvia | Official register, live | Register of Enterprises open data | name, status, address, legal form, incorporated on, officers, owners, vat, lei | yes | yes |
| NO Norway | Official register, live | Brønnøysund Register Centre | name, status, address, legal form, incorporated on, former names, officers, industry, website, vat, lei | yes | no |
| PL Poland | Official register, live | KRS open API and Biała lista VAT | name, status, address, legal form, incorporated on, industry, website, vat, lei | no | no |
| CH Switzerland | Official register, live | Zefix linked data (LINDAS) | name, status, address, legal form, lei | no | no |
| HR Croatia | Official register, key pending | Sudski registar open data | name, status, address, legal form, incorporated on, vat, lei | no | no |
| GR Greece | Official register, key pending | OpenData GEMI | name, status, address, legal form, incorporated on, vat, lei | no | no |
| GB United Kingdom | Official register, key pending | Companies House | name, status, address, legal form, incorporated on, former names, officers, owners, industry, lei | yes | yes |
| AL Albania | VAT and LEI only | GLEIF | lei | no | no |
| AD Andorra | VAT and LEI only | GLEIF | lei | no | no |
| AM Armenia | VAT and LEI only | GLEIF | lei | no | no |
| AT Austria | VAT and LEI only | VIES + GLEIF | vat, lei | no | no |
| AZ Azerbaijan | VAT and LEI only | GLEIF | lei | no | no |
| BE Belgium | VAT and LEI only | VIES + GLEIF | vat, lei | no | no |
| BA Bosnia and Herzegovina | VAT and LEI only | GLEIF | lei | no | no |
| BG Bulgaria | VAT and LEI only | VIES + GLEIF | vat, lei | no | no |
| CY Cyprus | VAT and LEI only | VIES + GLEIF | vat, lei | no | no |
| DK Denmark | VAT and LEI only | VIES + GLEIF | vat, lei | no | no |
| GE Georgia | VAT and LEI only | GLEIF | lei | no | no |
| HU Hungary | VAT and LEI only | VIES + GLEIF | vat, lei | no | no |
| IS Iceland | VAT and LEI only | GLEIF | lei | no | no |
| XK Kosovo | VAT and LEI only | GLEIF | lei | no | no |
| LI Liechtenstein | VAT and LEI only | GLEIF | lei | no | no |
| LT Lithuania | VAT and LEI only | VIES + GLEIF | vat, lei | no | no |
| LU Luxembourg | VAT and LEI only | VIES + GLEIF | vat, lei | no | no |
| MT Malta | VAT and LEI only | VIES + GLEIF | vat, lei | no | no |
| MD Moldova | VAT and LEI only | GLEIF | lei | no | no |
| MC Monaco | VAT and LEI only | GLEIF | lei | no | no |
| ME Montenegro | VAT and LEI only | GLEIF | lei | no | no |
| MK North Macedonia | VAT and LEI only | GLEIF | lei | no | no |
| PT Portugal | VAT and LEI only | VIES + GLEIF | vat, lei | no | no |
| RO Romania | VAT and LEI only | VIES + GLEIF | vat, lei | no | no |
| SM San Marino | VAT and LEI only | GLEIF | lei | no | no |
| RS Serbia | VAT and LEI only | GLEIF | lei | no | no |
| SK Slovakia | VAT and LEI only | VIES + GLEIF | vat, lei | no | no |
| SI Slovenia | VAT and LEI only | VIES + GLEIF | vat, lei | no | no |
| ES Spain | VAT and LEI only | VIES + GLEIF | vat, lei | no | no |
| SE Sweden | VAT and LEI only | VIES + GLEIF | vat, lei | no | no |
| TR Turkey | VAT and LEI only | GLEIF | lei | no | no |
| UA Ukraine | VAT and LEI only | GLEIF | lei | no | no |
| VA Vatican City | VAT and LEI only | GLEIF | lei | no | no |
| DE Germany | VAT and LEI only, paid register planned | VIES + GLEIF | vat, lei | no | no |
| IT Italy | VAT and LEI only, paid register planned | VIES + GLEIF | vat, lei | no | no |
| NL Netherlands | VAT and LEI only, paid register planned | VIES + GLEIF | vat, lei | no | no |

Live list: GET https://bizcheck.app/api/v1/coverage (no key needed).