verify-polish-company

Files (3)

• LICENSE
• README.md
• SKILL.md

SKILL.md (first lines)

# Verify a Polish company (skanfirmy.pl)

This skill verifies Polish businesses straight from official government
registers (Ministry of Finance, Ministry of Justice / KRS, Statistics Poland /
GUS, and the European Commission / VIES) through **skanfirmy.pl**, a free public
API. Every endpoint is a plain `GET` that returns JSON when you add
`?format=json`. **No API key, no account.** The service is meant for single,
user-driven lookups, not bulk data harvesting: REST allows at most 20 requests
per 10 seconds from one IP address (HTTP 429 for 10 seconds above that), the MCP
server 60 per 10 seconds.

**Sole traders and other natural persons (JDG, civil partnerships) get minimised
data** (GDPR): name, NIP, VAT status, town and the *number* of White List
accounts — no REGON, no address, no registration date, no PKD and no list of
account numbers. To check one specific account of such a counterparty, use
`POST /rachunek` (or the MCP tool `sprawdz_rachunek`). Companies (entities with a
KRS number) get full data.

## When to use it

Reach for this skill when the user asks to:

- check whether a Polish company is an **active VAT payer** or is VAT-exempt;
- verify that a **bank account** belongs to a contractor on the White List
  (needed for Polish "due diligence" on payments over 15 000 PLN);
- pull a company's **KRS** registry data (legal form, PKD, share capital,
  address, representation) by NIP or KRS number;
- look up **REGON** and official name/address of a company by NIP (for sole
  traders only the name, legal form, town and activity status);
- validate an **EU VAT number** (any member state) via **VIES**;
- check **many NIPs at once**.

`NIP` = 10-digit Polish tax ID. `KRS` = court-register number. `REGON` =
statistical register number. `VAT-UE`/VIES numbers are prefixed by a 2-letter
country code (e.g. `DE`, `IE`, `FR`).

## REST endpoints (GET, keyless)

Call these with any HTTP client (`curl`, `fetch`, `requests`, a web-fetch
tool). Append `?format=json` for machine-readable JSON; without it you get
crawlable HTML with embedded JSON-LD.

| Endpoint | What it returns |
|---|---|
| `GET https://skanfirmy.pl/nip/{nip}` | VAT status + White List (accounts) + KRS data + REGON, combined in one response (minimised for natural persons, see above) |
| `GET https://skanfirmy.pl/nips/{list}` | The same for **up to 30** comma-separated NIPs in one call (no KRS join) |
| `GET https://skanfirmy.pl/regon/{nip}` | REGON registry data: REGON number, official name, legal form, address (sole traders: name, form, town, activity status only) |
| `POST https://skanfirmy.pl/rachunek` | Is this bank account on the White List for this NIP? JSON body `{"nip": "…", "nrb": "…"}`; returns the Ministry's `accountAssigned` (`"TAK"`/`"NIE"`) and `requestId` |
| `GET https://skanfirmy.pl/vies/{country}/{number}` | Whether an EU VAT number is valid, plus the registered name/address |

Examples:

```bash
# Full check by NIP (VAT status + White List + KRS + REGON)
curl "https://skanfirmy.pl/nip/5260250995?format=json"

# REGON / GUS data only
curl "https://skanfirmy.pl/regon/5260250995?format=json"

# EU VAT number (VIES) — country code + number without the prefix
curl "https://skanfirmy.pl/vies/IE/6388047V?format=json"

# Many NIPs at once (comma-separated, up to 30)
curl "https://skanfirmy.pl/nips/5252344078,5260251049,7740001454?format=json"
```

`/regon/{nip}` returns a `dane` object. For a company: `regon`, `nazwa` (official
name), `typ` (`P` = legal person, `LP` = local unit) and address fields
(`wojewodztwo`, `powiat`, `gmina`, `miejscowosc`, `kodPocztowy`, `ulica`,
`nrNieruchomosci`, `nrLokalu`). For a natural person (`typ` `F`/`LF`, or a civil
partnership) only `nip`, `nazwa`, `typ`, `forma`, `miejscowosc` and `status`
(`active`/`ended`), with a `privacy` object that links to the official GUS search.

## Choosing the right endpoint

- Need VAT status **and** KRS in one shot → `/nip/{nip}`.
- Only official name/address/REGON of a company → `/regon/{nip}`.
- A **specific bank account** of a counterparty (also a sole trader) →
  `POST /rachunek`.
- A **foreign** EU counterparty's VAT number → `/vies/{country}/{number}`.
- A **list** of Polish counterparties → `/nips/{list}` (then, if you need KRS
  for a specific hit, re-query it with `/nip/{nip}`).

## Error handling

- Unknown entity → `404`. NIP with an invalid checksum → `400`. Handle both;
  do not assume every NIP has an entry.
- Too many requests → `429` (wait 10 seconds). The Ministry of Finance daily
  limit for the service exhausted → `503` with `Retry-After`.
- Some numbers are **restricted from presentation** (a data-protection
  procedure): the response is `200` with `restricted: true`, a fixed sentence and
  a link to the Ministry of Finance search, and no data. Tell the user to check
  the number there; do not treat it as "not registered".
- When comparing literal government values, key logic off the **original**
  Polish literals (VAT status `"Czynny"`/`"Zwolniony"`, account match
  `"TAK"`/`"NIE"`), not a translated label.

## MCP option (for MCP-capable agents)

If you speak the Model Context Protocol, connect to the server instead of
calling REST by hand:

`POST https://skanfirmy.pl/mcp` — stateless Streamable HTTP, JSON-RPC 2.0,
no key, 60 requests per 10 seconds from one IP address. Tools: `sprawdz_nip`, `sprawdz_lista_nip`, `sprawdz_regon`,
`sprawdz_vies`, `sprawdz_rachunek`, `generuj_mikrorachunek`, `szukaj_pkd`,
`oblicz_odsetki`, `szukaj_katalog_api`. A model-readable endpoint map lives at
`https://skanfirmy.pl/llms.txt`.

```bash
curl -s https://skanfirmy.pl/mcp \
  -H 'content-type: application/json' \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"sprawdz_nip","arguments":{"nip":"5260250995"}}}'
```

## Source & disclaimer

Data comes directly from official registers — Ministry of Finance (VAT White
List), Ministry of Justice (KRS), Statistics Poland / GUS (REGON), and the
European Commission (VIES). skanfirmy.pl is an independent tool, not an official

From bartosz-kuc/skanfirmy-mcp, MIT.

More from bartosz-kuc/skanfirmy-mcp