> ## Documentation Index
> Fetch the complete documentation index at: https://docs.topograph.co/llms.txt
> Use this file to discover all available pages before exploring further.
# Poland
> Country-specific identifiers, data sources, and implementation details
## Start here
This guide contains public integration notes for Poland. Use it for identifier formats, search behavior, and country-specific caveats. The live source of truth for coverage, pricing, data sources, documents, legal forms, roles, and status values is the pricing page.
Open the current catalog for supported datapoints, documents, sources, identifiers, and availability.
Country details below are preserved as integration notes. If a table or example conflicts with the live pricing page, use the pricing page as the source of truth and contact support.
## Data Sources
Poland uses a **hybrid approach** with two different registries and APIs, routing company lookups based on entity type. For a given entity, data comes from a single source determined by the registration prefix.
### KRS companies (legal entities)
* **KRS (Krajowy Rejestr Sadowy / National Court Register).** Operated by the Ministry of Justice, the KRS is the **primary source for all legal entities**: limited liability companies (sp. z o.o.), joint-stock companies (S.A.), partnerships, associations, foundations, cooperatives, and other registered entities. Data is retrieved from two complementary API endpoints (`odpisaktualny` for current extracts and `danepodmiotu` for entity-level data), fetched in parallel with automatic failover. Provides company name, legal form, status, address, capital, activity codes (PKD), management board members, procurators, and shareholders (sp. z o.o. only).
* **CRBR (Centralny Rejestr Beneficjentow Rzeczywistych / Central Register of Beneficial Owners).** Poland's official UBO registry, mandatory for all entities registered in KRS. Provides ultimate beneficial owner data including ownership percentages, control types (direct/indirect), and management positions. Accessed programmatically.
* **eKRS Financial Documents Portal (ekrs.ms.gov.pl).** Official portal for financial documents filed by KRS companies. Provides annual financial statements, consolidated statements, management reports, auditor opinions, and approval resolutions. Documents may be in XML format (automatically converted to PDF).
### CEIDG sole proprietors (individual businesses)
* **biznes.gov.pl API.** Government API for the Central Register and Information on Business Activity (CEIDG). Used for **search across both registers** (KRS + CEIDG) and as the **sole data source for sole proprietors**. Provides company name, owner name, address, PKD activity codes, status, and basic contact information.
**Dual Register System:** Poland maintains two separate registers -- KRS for legal entities (companies, non-profits, cooperatives) and CEIDG for sole proprietors (individual businesses). Our system uses prefixed identifiers (`krs-` / `nip-`) to route requests to the correct register and API.
* **`krs-{number}` prefix**: Routes to the KRS API. Used for all legal entities registered in the National Court Register (companies, associations, foundations, cooperatives).
* **`nip-{number}` prefix**: Routes to the biznes.gov.pl API. Used for sole proprietors registered in CEIDG.
The prefix is **required** because both KRS and NIP numbers are 10-digit identifiers that could collide. Not all KRS entities have a NIP (e.g., some associations and foundations), making KRS the only reliable identifier for those entities.
**Key Takeaway:** Always use the appropriate prefix when querying. Search results from the API already include the correct prefix.
## Company Identifiers
### Query Identifiers
| Company Type | Source | Format | Example | Notes |
| -------------------------- | ------ | ------------------ | ---------------- | ------------------------------- |
| **KRS legal entities** | KRS | `krs-` + 10 digits | `krs-0001010154` | Padded with leading zeros |
| **CEIDG sole proprietors** | CEIDG | `nip-` + 10 digits | `nip-1234567890` | NIP (tax identification number) |
**Prefixed identifiers are required.** Company IDs must use `krs-` or `nip-` prefixes to route to the correct register. Without a prefix, the system cannot determine the data source and will return an error.
**KRS Number Padding:** KRS numbers are always 10 digits with leading zeros (e.g., `0001010154`). When searching by KRS number, shorter inputs are automatically padded to 10 digits.
### Identifiers in API Response
Once you retrieve company data, the `identifiers` object contains all available identifiers for that entity:
| Identifier Type | Format | Example | Found In |
| --------------- | ----------------------------- | ------------ | ---------------------------------------- |
| `krs` | 10 digits | `0001010154` | KRS legal entities only |
| `nip` | 10 digits | `1234567890` | Most KRS entities and all CEIDG entities |
| `regon` | 9 digits (or 14 for branches) | `003295237` | Most entities across both registers |
| `vatNumber` | 10 digits (same as NIP) | `1234567890` | Entities with NIP |
## Search Capabilities
| Search Type | Pattern | Example | Match Type | Expected Results |
| --------------- | -------------- | ------------- | ---------- | -------------------------------------------------------------------- |
| By KRS Number | 1-10 digits | `0001010154` | Exact | Exact match returned first (matchType: id); other results may follow |
| By NIP Number | 10 digits | `1234567890` | Exact | Exact match returned first (matchType: id); other results may follow |
| By REGON Number | 9 or 14 digits | `003295237` | Exact | Exact match returned first (matchType: id); other results may follow |
| By Name | Text string | `"Topograph"` | Contains | Multiple results across KRS + CEIDG |
**Search Performance:** Use identifier-based searches (KRS, NIP, REGON) for best performance and exact matching. Name searches query biznes.gov.pl and may return multiple results from both KRS and CEIDG registers.
**Search queries multiple sources in parallel.** For identifier searches, the system queries KRS by KRS number, KRS by NIP, CEIDG by NIP, and CEIDG by REGON simultaneously. Results are deduplicated by ID, with KRS results taking precedence over CEIDG when both match.
## Company Status
Company status is determined from KRS register data and enhanced with AI mapping. CEIDG (sole proprietor) statuses use a separate mapping path.
### KRS Companies (primary path)
Status is derived from multiple KRS data points: deletion indicators, bankruptcy proceedings, merger records, and name-based liquidation detection.
| Local Status (Polish) | English | Standardized Status | Detection Method |
| -------------------------- | --------------------------- | --------------------------- | ------------------------------------------------ |
| AKTYWNA | Active | Active | Default (no closure indicators) |
| W LIKWIDACJI | In Liquidation | Closed | Company name contains "W LIKWIDACJI" |
| WYKRESLONA Z REJESTRU | Deleted from Register | Closed | Deletion entries in KRS extract header or dzial6 |
| W UPADLOSCI | In Bankruptcy | Under Insolvency Proceeding | Bankruptcy announced but not completed |
| UPADLOSC ZAKONCZONA | Bankruptcy Completed | Closed | Bankruptcy proceedings have completion date |
| PRZEJETA PRZEZ INNA SPOLKE | Acquired by Another Company | Closed | Merger/acquisition records in dzial6 |
| DZIALALNOSC ZAWIESZONA | Activity Suspended | Under Insolvency Proceeding | Suspension date present without resumption |
**Closure reasons** (when status is Closed or Under Insolvency Proceeding):
| Scenario | Standardized Closure Reason |
| ---------------------------------- | --------------------------- |
| Deletion from KRS/RP register | Administrative Dissolution |
| Bankruptcy proceedings | Bankruptcy |
| Liquidation (name-based detection) | Liquidation |
| Merger/acquisition | Merger |
### CEIDG Sole Proprietors
| Local Status (Polish) | English | Standardized Status |
| --------------------- | ------- | ------------------- |
| AKTYWNY | Active | Active |
| WYKRESLONY | Deleted | Closed |
### Closure Date Priority
The system prioritizes closure dates in the following order:
1. **Deletion finalization date** (`dataUprawomocnienia` in extract header) -- highest priority
2. **Register deletion dates** (`dataWykreslenia` from dzial6 KRS/RP deletion records)
3. **Bankruptcy completion date** (`dataZakonczeniaPostepowania`)
4. **CEIDG cancellation/cessation dates** (for sole proprietors)
Status classification is AI-enhanced. The local Polish status name from KRS is always preserved verbatim. The AI analyzes the status in context to provide standardized mapping. Deterministic rules (deletion, bankruptcy, liquidation) take precedence before AI enrichment.
## Legal Forms
Poland ships a **closed enum of 51 legal forms** sourced directly from the Polish registers. The enum covers the 50 distinct `formaPrawna` strings the KRS returns, plus one canonical entry for CEIDG sole traders. There is no AI fallback: an unknown value is rejected with `invalid` at ingestion time so the enum stays accurate and any new form the register introduces surfaces as a deploy blocker.
Provenance:
* **KRS values** were harvested from the full July 2024 snapshot of the Krajowy Rejestr Sadowy (849,757 entities across the commercial register RejP and the association register RejS). The top 13 forms cover 99.7% of the register and the full set is 50 distinct strings.
* **CEIDG sole traders** are projected onto a single canonical entry (`Osoba fizyczna prowadząca działalność gospodarczą`), because the biznes.gov.pl API does not expose a `formaPrawna` field for CEIDG entries (a sole trader has no entity-level legal form under Polish law).
* **ISO 20275 (ELF) codes** are attached as a cross-reference where GLEIF publishes one. Out of the 51 entries, 33 have an ELF code and 18 do not. GLEIF is not the source of the enum; the register is. We attach ELF codes opportunistically for LEI matching and nothing more.
GLEIF's ISO 20275 list for Poland is **incomplete** and is not a safe source of truth. 18 of the 50 KRS-returned forms have no ELF code at all (for example the granular `stowarzyszenie` subtypes, public-benefit organizations, and church-related entities). This is why the enum is built from the register itself, not from ISO 20275.
### Core commercial forms
| Polish Name | Abbr. | English Translation | Standardized | ISO 20275 |
| ----------------------------------------------- | ---------- | ----------------------------------- | ------------------------- | --------- |
| Spółka z ograniczoną odpowiedzialnością | sp. z o.o. | Limited Liability Company | Limited Liability Company | O7XB |
| Spółka akcyjna | S.A. | Joint-Stock Company | Corporation | FJ0E |
| Prosta spółka akcyjna | P.S.A. | Simple Joint-Stock Company | Corporation | B21W |
| Spółka jawna | sp.j. | General Partnership | Partnership | 629I |
| Spółka komandytowa | sp.k. | Limited Partnership | Partnership | BSJT |
| Spółka komandytowo-akcyjna | S.K.A. | Limited Joint-Stock Partnership | Partnership | OMX0 |
| Spółka partnerska | sp.p. | Professional Partnership | Partnership | 3BJG |
| Spółka europejska | SE | European Company | Corporation | J3A3 |
| Europejskie zgrupowanie interesów gospodarczych | EEIG | European Economic Interest Grouping | Partnership | 85PM |
### Cooperatives and mutuals
| Polish Name | English Translation | Standardized | ISO 20275 |
| ------------------------------------------- | ---------------------------------- | ------------ | --------- |
| Spółdzielnia | Cooperative | Cooperative | 8TOF |
| Spółdzielnia europejska | European Cooperative Society (SCE) | Cooperative | (no ELF) |
| Spółdzielcza kasa oszczędnościowo-kredytowa | Credit Union (SKOK) | Cooperative | H7OD |
| Towarzystwo ubezpieczeń wzajemnych | Mutual Insurance Society (TUW) | Cooperative | WNX1 |
### State and public-sector entities
| Polish Name | English Translation | Standardized | ISO 20275 |
| ---------------------------------------------------------- | ------------------------------------------------- | ----------------------- | --------- |
| Przedsiębiorstwo państwowe | State-Owned Enterprise | Government-Owned Entity | SMIS |
| Instytut badawczy (including Łukasiewicz Research Network) | Research Institute | Government-Owned Entity | KM66 |
| Instytucja gospodarki budżetowej | Budgetary Institution | Government-Owned Entity | CY1M |
| Samodzielny publiczny zakład opieki zdrowotnej | Independent Public Healthcare Institution (SPZOZ) | Government-Owned Entity | 13ZV |
### Associations and foundations
| Polish Name | English Translation | Standardized | ISO 20275 |
| -------------------------------------------------------------- | ------------------------------------------------------ | ---------------------- | --------- |
| Stowarzyszenie | Association | Nonprofit Organization | ZZKE |
| Związek stowarzyszeń | Union of Associations | Nonprofit Organization | ZZKE |
| Jednostka terenowa stowarzyszenia posiadająca osobowość prawną | Regional Unit of an Association with Legal Personality | Nonprofit Organization | (no ELF) |
| Stowarzyszenie kultury fizycznej | Sports Association | Nonprofit Organization | (no ELF) |
| Stowarzyszenie kultury fizycznej o zasięgu ogólnokrajowym | Nationwide Sports Association | Nonprofit Organization | (no ELF) |
| Stowarzyszenie ogrodowe | Gardening Association | Nonprofit Organization | (no ELF) |
| Fundacja | Foundation | Nonprofit Organization | 96XK |
### Trade unions and employer associations
| Polish Name | English Translation | Standardized | ISO 20275 |
| ----------------------------------------------------------------------- | ---------------------------------------------------- | ---------------------- | --------- |
| Związek zawodowy | Trade Union | Nonprofit Organization | LT9U |
| Jednostka organizacyjna związku zawodowego posiadająca osobowość prawną | Organizational Unit of a Trade Union | Nonprofit Organization | LT9U |
| Związek zawodowy rolników indywidualnych | Individual Farmers Trade Union | Nonprofit Organization | LT9U |
| Ogólnokrajowy związek międzybranżowy | National Inter-Industry Union | Nonprofit Organization | WOK7 |
| Związek pracodawców | Employers Association | Nonprofit Organization | WOK7 |
| Federacja / Konfederacja związków pracodawców | Federation or Confederation of Employer Associations | Nonprofit Organization | WOK7 |
### Guilds, chambers, and business organizations
| Polish Name | English Translation | Standardized | ISO 20275 |
| ---------------------------------------- | ----------------------------------------- | ---------------------- | --------- |
| Cech rzemieślniczy | Guild of Craftsmen | Nonprofit Organization | 5F76 |
| Izba rzemieślnicza | Chamber of Crafts | Nonprofit Organization | 5F76 |
| Związek Rzemiosła Polskiego | Polish Crafts Union | Nonprofit Organization | 5F76 |
| Izba gospodarcza | Chamber of Commerce | Nonprofit Organization | 5F76 |
| Inna organizacja podmiotów gospodarczych | Other Business Entity Organization | Nonprofit Organization | FQ5Y |
| Inna organizacja społeczna lub zawodowa | Other Social or Professional Organization | Nonprofit Organization | FQ5Y |
### Agricultural and transport associations
| Polish Name | English Translation | Standardized | ISO 20275 |
| --------------------------------------------------- | --------------------------------------------- | ---------------------- | --------- |
| Kółko rolnicze | Farmers Circle | Nonprofit Organization | FANM |
| Rolnicze zrzeszenie branżowe | Agricultural Branch Association | Nonprofit Organization | 6OYI |
| Związek rolniczych zrzeszeń branżowych | Union of Agricultural Branch Associations | Nonprofit Organization | 6OYI |
| Związki rolników, kółek i organizacji rolniczych | Unions of Farmers and Farmers Circles | Nonprofit Organization | WOK7 |
| Zrzeszenie handlu i usług | Trade and Services Association | Nonprofit Organization | 6OYI |
| Ogólnokrajowa reprezentacja zrzeszeń handlu i usług | National Representation of Trade Associations | Nonprofit Organization | 6OYI |
| Zrzeszenie transportu | Transport Association | Nonprofit Organization | 6OYI |
| Ogólnokrajowe zrzeszenie międzybranżowe | National Inter-Industry Association | Nonprofit Organization | 6OYI |
### Sports bodies
| Polish Name | English Translation | Standardized | ISO 20275 |
| ----------------------- | ------------------- | ---------------------- | --------- |
| Związek sportowy | Sports Union | Nonprofit Organization | WOK7 |
| Polski związek sportowy | Polish Sports Union | Nonprofit Organization | WOK7 |
### Public-benefit organizations and church entities
| Polish Name | English Translation | Standardized | ISO 20275 |
| --------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------ | ---------------------- | --------- |
| Inna osoba prawna będąca organizacją pożytku publicznego | Other Legal Person Acting as a Public Benefit Organization | Nonprofit Organization | (no ELF) |
| Nieposiadająca osobowości prawnej organizacja pożytku publicznego | Public Benefit Organization without Legal Personality | Nonprofit Organization | (no ELF) |
| Kościelna osoba prawna będąca organizacją pożytku publicznego | Church Legal Person Acting as a Public Benefit Organization | Nonprofit Organization | SP4S |
| Nieposiadająca osobowości prawnej instytucja kościelna będąca organizacją pożytku publicznego | Church Institution without Legal Personality Acting as a Public Benefit Organization | Nonprofit Organization | SP4S |
### Sole traders (CEIDG)
| Polish Name | English Translation | Standardized | ISO 20275 |
| ------------------------------------------------- | ------------------- | ------------------- | --------- |
| Osoba fizyczna prowadząca działalność gospodarczą | Sole Trader (CEIDG) | Sole Proprietorship | ZVVM |
## Legal Representatives
Legal representatives are extracted from two KRS data sections: the **management board** (`reprezentacja.sklad`) and **procurators** (`prokurenci`). Role classification is **AI-enriched** -- the AI analyzes each role in the context of the company's legal form to assign ISO 5009 codes.
**Board member and shareholder names: use verification mode.** Poland's National Court Register masks personal data on its online lookup, returning names like `W***** L********`. Topograph reads the full names from the official court extract instead, so in **verification mode** `legalRepresentatives` and `shareholders` come back with complete first names and surnames for companies, associations, and foundations. The names are read from the court extract by AI, so verify against the source document before relying on them for compliance.
Details for the response payload:
* **Onboarding mode** returns only the company identity fields (name, legal form, registered seat, status, capital, activity codes, dates). It does not include board members or shareholders. Use verification mode (the default) when you need the people.
* `legalRepresentatives[].individual.name.firstName` and `lastName` are full and unredacted in verification mode.
* `legalRepresentatives[].individual.birthDate` and `gender` are not currently populated for Polish entities.
* `shareholders` are listed for limited liability companies (sp. z o.o.) where the register publishes them, with full names.
* The role (`localName` and `standardized`), structural fields, addresses, capital, and dates are all complete.
The [ultimate beneficial owners](#ultimate-beneficial-owners) datapoint comes from CRBR, a separate Polish register, with full names, birth dates, and nationalities. UBOs and legal representatives answer different questions and one is not a substitute for the other.
### KRS Management Board Roles
| Polish Role | English Translation | Standardized Role |
| ----------------------- | ----------------------------- | ----------------- |
| PREZES ZARZADU | President of the Board / CEO | Manager |
| WICEPREZES ZARZADU | Vice President of the Board | Manager |
| CZLONEK ZARZADU | Board Member | Director |
| CZLONEK RADY NADZORCZEJ | Supervisory Board Member | Director |
| PREZES RADY NADZORCZEJ | Chairman of Supervisory Board | Director |
| Polish Role | English Translation | Standardized Role |
| ------------------- | --------------------------------- | ----------------- |
| PROKURENT | Procurator (Authorized Signatory) | Other |
| PROKURENT SAMOISTNY | Independent Procurator | Other |
| PROKURENT LACZNY | Joint Procurator | Other |
| Polish Role | English Translation | Standardized Role |
| ----------- | ------------------- | ----------------- |
| Wlasciciel | Owner | Owner |
### PESEL-Based Data Extraction
For KRS management board members and procurators, birth dates and gender would normally be extracted from **PESEL numbers** (Polish Personal Identification Number, 11 digits). The parser is in place, but `birthDate` and `gender` are not currently populated for Polish legal representatives. Full names are returned in verification mode (see the note above); the PESEL itself is sensitive personal data and is not part of the response today.
**PESEL format:** `YYMMDDCCCSS` (11 digits)
* `YY` -- Year (last 2 digits)
* `MM` -- Month (with century indicator: 01-12 = 1900s, 21-32 = 2000s)
* `DD` -- Day of birth
* `CCC` -- Serial number
* `S` -- Gender digit (even = female, odd = male)
* `S` -- Checksum digit
When unredacted PESEL becomes available, the parser will extract birth date (year, month, day) and gender for each representative without code changes.
Procurators (authorized signatories) from KRS are mapped as **additional legal representatives** with the `PROKURENT` role and standardized as `Other`. For CEIDG sole proprietors, the entrepreneur is automatically mapped as the sole legal representative with role "Wlasciciel" (Owner).
## Other Key Persons
Other key persons are **not currently extracted** from Polish registries. All management board members and procurators are mapped as legal representatives.
## Shareholders
Shareholders are extracted from the KRS register for **sp. z o.o. (Limited Liability Companies) only**, from the `wspolnicySpzoo` section (Section 1 of the KRS extract).
**Individual shareholder names are redacted by the KRS API**, the same way representative names are. Where the KRS used to return a full first name and surname for an individual shareholder, the API now returns first-character masks (`J***** K******`). Corporate shareholder records are unaffected: the company name, KRS, NIP and REGON identifiers all come through intact, and you can use those identifiers to fetch the corporate shareholder's own profile if needed.
### Extraction Logic
| Source | When Used | Data Extracted |
| ------------------------ | ------------------------- | ---------------------------------------------------------- |
| **KRS `wspolnicySpzoo`** | sp. z o.o. companies only | Name, share count, corporate identifiers (KRS, NIP, REGON) |
### Share Count Parsing
Share counts are parsed from Polish KRS text strings using a combination of regex (fast path) and AI (complex cases):
| Example Text | Parsed Value |
| -------------------------------------------- | ------------- |
| `93.387 UDZIALOW O WARTOSCI 4.669.350,00 ZL` | 93,387 shares |
| `1 UDZIAL O WARTOSCI 50,00 ZL` | 1 share |
| `500 UDZIALOW` | 500 shares |
| `10.000 AKCJI` | 10,000 shares |
**Polish number format:** Poland uses dot (`.`) as thousands separator and comma (`,`) as decimal separator. The parser handles this automatically. Share **percentages** are not directly available from KRS -- only absolute share counts are extracted.
### Shareholder Type Detection
| Indicator | Shareholder Type |
| --------------------------------------------------------------------- | ------------------------------ |
| Has KRS/NIP/REGON identifiers | Company |
| Name contains legal form suffix (AG, SA, GMBH, SP. Z O.O., LTD, etc.) | Company |
| KRS number is all zeros (`0000000000`) | Foreign company (no Polish ID) |
| No corporate indicators | Individual |
### Limitations
| Legal Form | Shareholder Data Available? | Notes |
| ---------------------------- | --------------------------- | ------------------------------------------------------- |
| sp. z o.o. (LLC) | Yes | Individual and corporate shareholders with share counts |
| S.A. (Joint-Stock) | No | Shareholders not listed in public KRS register |
| sp.k. / sp.j. (Partnerships) | No | Partner data not structured in shareholder format |
| Associations / Foundations | No | Not applicable |
| CEIDG (Sole Proprietors) | No | Not applicable |
For corporate shareholders, Polish identifiers (KRS, NIP, REGON) are included when available. Foreign corporate shareholders without Polish identifiers are included with name only. Share percentages are **not** directly available from KRS; only share counts are extracted.
## Ultimate Beneficial Owners
UBO data is sourced from **CRBR (Centralny Rejestr Beneficjentów Rzeczywistych)**, the Polish Central Register of Beneficial Owners operated by the Ministry of Finance. CRBR is a separate register from KRS, established under Polish AML law (transposing 4AMLD/5AMLD), and it is mandatory for almost every entity registered in KRS to disclose its beneficial owners there.
A beneficial owner in CRBR is the natural person who ultimately owns or controls the entity, defined by the Polish AML act as direct or indirect ownership above 25%, or any other form of effective control. Where no natural person meets that threshold (typical for state-owned entities, listed companies, and complex structures), CRBR records senior managing officials as a fallback per the AML directive.
**CRBR is not redacted.** Unlike the KRS API, CRBR returns full first names, surnames, birth dates, nationalities, and a description of how control is exercised. The redaction policy the Ministry of Justice applies to KRS does not apply to CRBR, because the whole point of CRBR is to expose this data for AML and KYC compliance.
Each UBO record returned by the API contains:
| Field | Source | Notes |
| ------------------------------------------ | ------ | ------------------------------------------------------------------------------------------------------ |
| `name.firstName` / `lastName` / `fullName` | CRBR | Unredacted |
| `birthDate` | CRBR | Day, month, year |
| `nationality` | CRBR | ISO 3166-1 alpha-2 |
| `control.types[]` | CRBR | One or more of `ownership-of-shares`, `significant-influence-or-control`, `senior-management-position` |
| `control.description` | CRBR | Polish-language description of how the control is exercised, as filed by the entity |
| `control.details[].nature` | CRBR | `direct` or `indirect` |
| `control.details[].monetaryAmount` | CRBR | When the filing expresses the stake as a PLN or EUR amount instead of a percentage |
CRBR returns no UBOs for entities that are exempt from disclosure (state-owned enterprises, the State Treasury, certain public-benefit organizations) or for entities whose ownership chain resolves to a listed parent. In those cases the response contains an empty `ultimateBeneficialOwners` array, which is correct, not a gap.
UBO data is fetched on demand. Use either the dedicated endpoint `topo api ubo PL ` / `GET /v2/company/{id}/ubo`, or include `ultimateBeneficialOwners` in the `dataPoints` array on a profile request. The `ubo_extract` document catalog item (`pol-ubo-data`) returns the full CRBR PDF excerpt for filing in compliance dossiers.
## Activity Code Mapping
Poland uses the **PKD (Polska Klasyfikacja Dzialalnosci)** classification, which is the Polish adaptation of the European NACE Rev. 2 standard. PKD codes are structurally identical to NACE codes and are mapped directly without transformation.
```
PKD (Polish) = NACE Rev. 2 (European) -> ISIC Rev. 4 (International)
```
| Classification | Source | Example | AI Inferred? |
| -------------- | --------------------------------------------------------------- | --------- | ------------- |
| **PKD / NACE** | KRS (`przedmiotDzialalnosci`) or CEIDG (`mainPkd` / `otherPkd`) | `62.01.Z` | No (official) |
| **ISIC** | Derived from NACE or AI-inferred | `6201` | Sometimes |
The KRS provides both the **main activity** (`przedmiotPrzewazajacejDzialalnosci`) and **secondary activities** (`przedmiotPozostalejDzialalnosci`). CEIDG provides `mainPkd` (primary) and `otherPkd[]` (additional).
**AI Enrichment:** When ISIC codes cannot be derived from NACE via formal mapping tables, the system uses an LLM to match activity descriptions to ISIC Rev. 4 codes. Every activity item includes an `isAIInferred` flag. PKD/NACE codes are **never** AI-inferred for Poland.
### Activity Codes by Source
| Source | Classifications returned | Notes |
| --------- | ------------------------ | ---------------------------------------------------------------- |
| **KRS** | NACE + ISIC | From `dzial3.przedmiotDzialalnosci` (main + secondary PKD codes) |
| **CEIDG** | PKD + NACE + ISIC | From `mainPkd` and `otherPkd` fields, AI-analyzed |
## Data Availability Matrix
| Data Type | KRS Companies | CEIDG (Sole Proprietors) | Notes |
| -------------------------- | ------------------------------------------------ | ------------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Company Profile | Async | Async | Full data for KRS, limited for CEIDG |
| Legal Representatives | Yes (names redacted) | Yes | KRS: roles + structure available; first names, surnames and PESEL are first-character masked at the source. CEIDG: owner mapped from CEIDG metadata. |
| Shareholders | Yes (sp. z o.o. only, individual names redacted) | No | Only for Limited Liability Companies. Corporate shareholder identifiers (KRS, NIP, REGON) are intact; individual shareholder names are first-character masked. |
| Other Key Persons | No | No | Not currently extracted |
| Ultimate Beneficial Owners | Yes | No | From CRBR (Central Register of Beneficial Owners) |
| Activity Codes | Yes | Yes | PKD codes from KRS or CEIDG |
| Documents | Yes | Yes | Different document sets per register type |
| Financial Statements | Yes | No | From ekrs.ms.gov.pl, automatic XML-to-PDF conversion |
| Establishments | No | No | Not currently extracted |
**Legend:** Yes = Available | No = Not Available | Async = Asynchronous processing
## Documents by Company Type
### KRS Companies (prefix: `krs-`)
| Document Type | API Category | Format | Catalog item | Availability | Notes |
| -------------------------- | ----------------------- | ----------------------------- | --------------------------------- | --------------------- | -------------------------------------------- |
| **Current KRS Extract** | `tradeRegisterExtract` | PDF | `pol-register-extract` | Active companies only | Aktualny odpis z KRS |
| **Historical KRS Extract** | `otherDocuments[]` | PDF | `pol-historical-register-extract` | All companies | Pelny odpis historyczny z KRS (full history) |
| **UBO Extract** | `otherDocuments[]` | PDF | `pol-ubo-extract` | When UBO data exists | Wyciag z CRBR o beneficjentach rzeczywistych |
| **Financial Statements** | `financialStatements[]` | PDF (auto-converted from XML) | `pol-financial-statements` | When filed | Various types from ekrs.ms.gov.pl |
### CEIDG Sole Proprietors (prefix: `nip-`)
| Document Type | API Category | Format | Catalog item | Availability | Notes |
| ---------------------------- | ---------------------- | ------ | ---------------------- | ------------ | --------------------------- |
| **CEIDG Certificate** | `tradeRegisterExtract` | PDF | `pol-register-extract` | All entities | Zaswiadczenie z CEIDG |
| **Representatives Document** | `otherDocuments[]` | PDF | `pol-representatives` | All entities | Informacja o pelnomocnikach |
**Current KRS Extract availability:** The current extract (`tradeRegisterExtract`) is **only available for active companies**. Inactive, dissolved, or deleted companies can only access the historical extract (`otherDocuments[]`), which contains the full history including closure details.
### Financial Document Types
Available financial document types from the eKRS portal include:
* **Roczne sprawozdanie finansowe** -- Annual Financial Statements
* **Skonsolidowane roczne sprawozdanie finansowe** -- Consolidated Annual Financial Statements
* **Sprawozdanie z dzialalnosci** -- Management Reports
* **Opinia bieglego rewidenta** -- Auditor's Opinions
* **Uchwaly o zatwierdzeniu sprawozdan** -- Approval Resolutions
* **Uchwaly o podziale zysku** -- Profit Distribution Resolutions
**Automatic XML-to-PDF Conversion:** Financial documents in Poland are often published in XML format using the Ministry of Finance schema. We automatically convert these XML files to human-readable PDF format using the official Polish government visualization tool at [e-sprawozdania.mf.gov.pl](https://e-sprawozdania.mf.gov.pl/ap/). Both the original XML and the converted PDF are stored and accessible. If conversion fails, the original XML file is still returned.
Due to technical limitations of the Polish financial documents portal, the document format (XML vs PDF) is not available in the `availableDocuments` listing. The `format` field will be `undefined` during listing and is only determined when the document is actually downloaded.
## Example API Responses
All examples use **placeholder data**. Query: `POST /v2/company` with `{ "id": "", "countryCode": "PL", "dataPoints": ["company", "legalRepresentatives"] }`
```json theme={null}
{
"company": {
"id": "krs-0001234567",
"countryCode": "PL",
"identifiers": { "krs": "0001234567", "nip": "1234567890", "regon": "123456789", "vatNumber": "1234567890" },
"legalName": "Przyklad Technologia sp. z o.o.",
"registrationDate": "2018-03-20",
"status": { "localName": "AKTYWNA", "active": true, "statusDetails": { "status": "ACTIVE" } },
"legalForm": { "localName": "Spółka z ograniczoną odpowiedzialnością", "englishTranslation": "Limited Liability Company (sp. z o.o.)", "standardized": "Limited Liability Company", "iso20275Code": "O7XB" },
"capital": { "amount": 50000, "currency": "PLN" },
"activities": {
"NACE": [
{ "code": "62.01.Z", "description": "DZIALALNOSC ZWIAZANA Z OPROGRAMOWANIEM", "isAIInferred": false },
{ "code": "62.02.Z", "description": "DZIALALNOSC ZWIAZANA Z DORADZTWEM W ZAKRESIE INFORMATYKI", "isAIInferred": false }
]
},
"legalAddress": { "addressLine1": "Aleja Jana Pawla II 29", "city": "Warszawa", "postalCode": "00-867", "countryCode": "PL" }
},
"legalRepresentatives": [
{ "type": "individual", "role": { "localName": "PREZES ZARZĄDU", "standardized": "Manager" }, "individual": { "name": { "fullName": "J** K*******", "firstName": "J**", "lastName": "K*******" }, "identifiers": { "pesel": "8**********" }, "nationality": "PL" } },
{ "type": "individual", "role": { "localName": "CZŁONEK ZARZĄDU", "standardized": "Director" }, "individual": { "name": { "fullName": "A*** N****", "firstName": "A***", "lastName": "N****" }, "identifiers": { "pesel": "7**********" }, "nationality": "PL" } }
],
"shareholders": [
{ "type": "individual", "individual": { "name": { "fullName": "J** K*******" } }, "numberOfShares": 500, "source": "KRS" },
{ "type": "company", "company": { "id": "krs-0009876543", "countryCode": "PL", "legalName": "Holding sp. z o.o.", "identifiers": { "krs": "0009876543" } }, "numberOfShares": 500, "source": "KRS" }
]
}
```
**Note:** First names, surnames and PESEL of individual representatives and shareholders are first-character masked at the source by the KRS API. The example above shows the actual on-the-wire shape for a real Polish company today. PESEL-derived `birthDate` and `gender` are unavailable for the same reason.
```json theme={null}
{
"company": {
"id": "krs-0007654321",
"countryCode": "PL",
"identifiers": { "krs": "0007654321", "nip": "9876543210", "regon": "987654321", "vatNumber": "9876543210" },
"legalName": "Stara Firma S.A.",
"registrationDate": "2005-01-10",
"status": { "localName": "WYKRESLONA Z REJESTRU", "active": false, "statusDetails": { "status": "CLOSED", "closureReason": "ADMINISTRATIVE_DISSOLUTION", "closureDate": "2023-06-30" } },
"legalForm": { "localName": "Spółka akcyjna", "englishTranslation": "Joint-Stock Company (S.A.)", "standardized": "Corporation", "iso20275Code": "FJ0E" },
"legalAddress": { "addressLine1": "Marszalkowska 10", "city": "Warszawa", "postalCode": "00-001", "countryCode": "PL" }
},
"legalRepresentatives": [
{ "type": "individual", "role": { "localName": "PREZES ZARZĄDU", "standardized": "Manager" }, "individual": { "name": { "fullName": "P**** W*********" }, "identifiers": { "pesel": "6**********" }, "nationality": "PL" } }
],
"shareholders": []
}
```
**Note:** Dissolved companies are mapped from the `danepodmiotu` endpoint only when the full extract (`odpisaktualny`) is not available. Shareholders are not available in this case. Only the historical trade register extract is available as a document. Personal data is first-character masked the same way as for active companies.
```json theme={null}
{
"company": {
"id": "nip-1234567890",
"countryCode": "PL",
"identifiers": { "nip": "1234567890", "regon": "123456789", "vatNumber": "1234567890" },
"legalName": "Jan Kowalski Uslugi Informatyczne",
"registrationDate": "2020-01-15",
"status": { "localName": "AKTYWNY", "active": true, "statusDetails": { "status": "ACTIVE" } },
"legalForm": { "localName": "Osoba fizyczna prowadząca działalność gospodarczą", "englishTranslation": "Sole Trader (CEIDG)", "standardized": "Sole Proprietorship", "iso20275Code": "ZVVM" },
"activities": {
"PKD": [
{ "code": "62.01.Z", "description": "Dzialalnosc zwiazana z oprogramowaniem" }
]
},
"legalAddress": { "addressLine1": "Krakowska 5", "city": "Krakow", "postalCode": "31-001", "countryCode": "PL" }
},
"legalRepresentatives": [
{ "type": "individual", "role": { "localName": "Wlasciciel", "englishTranslation": "Owner", "standardized": "Owner" }, "individual": { "name": { "fullName": "Jan Kowalski", "firstName": "Jan", "lastName": "Kowalski" }, "nationality": "PL" } }
],
"shareholders": []
}
```
**Note:** CEIDG entities have the entrepreneur mapped as the sole legal representative with role "Wlasciciel" (Owner). No shareholders, UBOs, or financial statements are available.
Query with `"dataPoints": ["ultimateBeneficialOwners"]`:
```json theme={null}
{
"ultimateBeneficialOwners": [
{
"name": { "fullName": "JAN KOWALSKI", "firstName": "JAN", "lastName": "KOWALSKI" },
"birthDate": { "year": 1985, "month": 6, "day": 15 },
"nationality": "PL",
"control": {
"types": ["ownership-of-shares"],
"description": "WSPÓLNIK SPÓŁKI Z O.O. (2500 PLN)",
"details": [
{
"nature": "direct",
"type": "shares",
"monetaryAmount": { "amount": 2500, "currency": "PLN", "formatted": "2500 PLN" }
}
]
}
},
{
"name": { "fullName": "KLAUS RÖHRIG", "firstName": "KLAUS", "lastName": "RÖHRIG" },
"birthDate": { "year": 1977, "month": 7, "day": 21 },
"nationality": "AT",
"control": {
"types": ["significant-influence-or-control"],
"description": "POŚREDNIA KONTROLA NAD PODMIOTEM DOMINUJĄCYM WOBEC SPÓŁKI",
"details": [
{
"nature": "indirect",
"type": "shares"
}
]
}
}
]
}
```
**Note:** UBO records are unredacted and verified live. CRBR is operated by the Polish Ministry of Finance, not by the Ministry of Justice that runs KRS, and the redaction policy on KRS does not apply here.
**Note:** UBOs are fetched from the CRBR (Central Register of Beneficial Owners). Three control types are recognized: (1) direct ownership of shares/assets, (2) indirect control through controlling entity, (3) senior management position under AML law. Ownership amounts may be in PLN (monetary) or percentage.
Documents are returned when `"dataPoints": ["availableDocuments"]` is requested.
**For active KRS companies:**
| API Category | Document | Notes |
| ----------------------- | ----------------------------- | -------------------------------------- |
| `tradeRegisterExtract` | Aktualny odpis z KRS | Current extract, active companies only |
| `otherDocuments[]` | Pelny odpis historyczny z KRS | Full historical extract |
| `otherDocuments[]` | Wyciag z CRBR | UBO extract, when UBO data exists |
| `financialStatements[]` | Various financial documents | From ekrs.ms.gov.pl |
**For inactive KRS companies:**
| API Category | Document | Notes |
| ------------------ | ----------------------------- | ------------------------------------------------- |
| `otherDocuments[]` | Pelny odpis historyczny z KRS | Full historical extract (only document available) |
**For CEIDG entities:**
| API Category | Document | Notes |
| ---------------------- | --------------------------- | ------------------------ |
| `tradeRegisterExtract` | Zaswiadczenie z CEIDG | CEIDG certificate |
| `otherDocuments[]` | Informacja o pelnomocnikach | Representatives document |
## Quirks & Gotchas
| Quirk | Details |
| --------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Prefixed identifiers required** | Company IDs must use `krs-` or `nip-` prefixes to route to the correct register. Without a prefix, the system returns an error. |
| **KRS and NIP can collide** | Both KRS and NIP are 10-digit numbers. The prefix system prevents ambiguity. Not all KRS entities have a NIP (e.g., associations, foundations). |
| **Shareholders only for sp. z o.o.** | Only Limited Liability Companies have shareholder data in KRS. Joint-stock companies, partnerships, and CEIDG entities do not expose shareholder information. |
| **Share percentages unavailable** | KRS provides only absolute share counts (e.g., "93.387 shares"), not ownership percentages. The parser extracts the count from Polish text using regex + AI. |
| **Liquidation detected from company name** | Companies in liquidation are identified by "W LIKWIDACJI" appearing in the legal name, not from a dedicated status field in KRS. |
| **Legal forms are a closed enum** | Poland uses a closed enum of 51 legal forms sourced directly from the registers (50 from the KRS July 2024 snapshot of 849,757 entities plus one canonical CEIDG sole-trader entry). Unknown values are rejected with an `invalid` error at ingestion time. No AI fallback. |
| **ISO 20275 is incomplete for Poland** | GLEIF's ELF list publishes codes for 33 of the 51 forms; the remaining 18 (granular `stowarzyszenie` subtypes, public-benefit organizations, church entities) have no ELF. We attach ELF codes where they exist for LEI matching and ignore the gap elsewhere. |
| **Personal data is redacted at the source** | Verified live on 2026-04-14: every name and PESEL the KRS API returns is first-character masked (`W***** L********`, `PESEL 6**********`). This applies to both the public KRS Open API and the Wyszukiwarka API we use in production. Names of board members, procurators, individual shareholders, and PESEL-derived birth date and gender are therefore unavailable until the ministry restores access. Roles, addresses, capital, identifiers, and structural fields are unaffected. |
| **PESEL parser is dormant** | The PESEL-to-birth-date and PESEL-to-gender parser is in place but unreachable in practice because PESEL is masked at the source. When unredacted PESEL becomes available again, the parser will populate `birthDate` and `gender` without code changes. |
| **Procurators as legal representatives** | Procurators (authorized signatories) from KRS are mapped as additional legal representatives with the `PROKURENT` role, standardized as `Other`. |
| **Financial documents may be XML** | Financial statements from the Ministry of Finance portal may be in XML format. The system automatically converts XML to PDF, but the format is unknown until download. |
| **KRS API resilience** | The KRS API uses parallel request attempts (3 concurrent per endpoint) with automatic failover. Both `odpisaktualny` and `danepodmiotu` endpoints are fetched in parallel for maximum data coverage. |
| **CEIDG data is limited** | CEIDG (sole proprietor) profiles have significantly less structured data than KRS companies. No shareholders, UBOs, or financial statements are available. The owner is mapped as the sole legal representative. |
| **PKD codes = NACE codes** | Polish PKD classification is structurally identical to NACE Rev. 2. PKD codes are mapped directly as NACE codes without transformation. |
| **Dissolved companies use fallback endpoint** | When a company is dissolved, the full KRS extract (`odpisaktualny`) may not be available. The system falls back to `danepodmiotu` which provides limited data (no shareholders, limited representatives). |
| **Current extract only for active companies** | The Aktualny odpis z KRS (current trade register extract) is unavailable for closed/dissolved companies. Use the historical extract instead. |
| **UBO data from CRBR** | UBO data is fetched from the CRBR registry. This may occasionally be slower than direct API calls. |