KRZ Debtor Registry

This actor searches Poland’s official National Debtors Register (Krajowy Rejestr Zadłużonych, or KRZ) at krz.ms.gov.pl.

KRZ must be accessed through a browser. Direct HTTP requests to the site and its backend endpoints are blocked by the site’s web application firewall (WAF), including when sent through a proxy. The actor therefore opens a browser session, loads the live KRZ page, submits the search form, and reads the resulting structured response or rendered results.

Input

Provide queries as an array of query objects. Each query contains the search text and may specify a search type and result limit.

Example:

{ "queries": [ { "query": "Getin Noble Bank", "searchType": "entity", "maxItems": 10 }, { "query": "Jan Kowalski", "searchType": "person", "maxItems": 10 } ] }

Query fields

• query — The value to submit to the KRZ search form. For an entity search, this is normally a company or organization name. For a person search, this is normally the person name or other value accepted by the live person form.
• searchType — Optional search mode:
  • auto — The default. The actor inspects the live page and selects a search path that the page actually exposes. If the page exposes only entity search, the query is handled through the entity search path. A person search is not inferred from text alone.
  • entity — Request the entity or organization search form.
  • person — Request the person search form when that form is exposed by the live page.
• maxItems — Optional maximum number of dataset records to emit for that query. This is a limit, not a guarantee that the query will return that many records. The number of available matching records, the live form, and the upstream response determine the final count.

The actor processes each query independently. A separate browser session is created for every query.

Person-search behavior

Person search is implemented as a runtime-detected branch. The actor checks the live KRZ page to determine whether it exposes a separate person search form and only uses the person branch when that form is present.

If the live page exposes entity search only, person queries are skipped or reported as unsupported. The actor does not submit a person query through the entity form and does not fabricate person records or person-specific fields.

Because the form is detected at runtime, the availability of person search can change if KRZ changes its page or search interface.

Browser and proxy behavior

• Browser access is mandatory. A direct HTTP/API implementation is not used because KRZ is WAF-blocked for direct requests.
• The actor uses a standard Apify residential proxy configuration managed by Apify.
• A buyer-supplied proxy URL is not required.
• A buyer-supplied proxy API key is not required.
• Browser state, cookies, and page context are not reused between queries. Every query starts in a fresh browser session.
• Fresh sessions improve isolation between searches but can make multi-query runs slower and more resource-intensive than a single persistent session.

The actor may fail or return fewer results if the live site is unavailable, changes its form, blocks the browser session, or does not expose the requested search mode.

Dataset output

The actor writes one dataset item for each debtor record obtained from KRZ. Fields that are not present in the upstream record or do not apply to the selected search type are left empty or null.

Field	Description
entityName	Entity or organization name returned by the registry.
firstName	First name returned for a person record, when available.
lastName	Last name returned for a person record, when available.
nip	Polish NIP tax identification number, when available.
krs	Polish National Court Register number, when available.
regon	Polish REGON statistical/business identification number, when available.
pesel	PESEL personal identification number, when returned by the registry.
legalForm	Legal form of an entity, such as a joint-stock company.
city	Registered office or residence city returned by the registry.
proceedingId	KRZ proceeding identifier.
proceedingStartDate	Start date and time of the proceeding, when available.
internalId	Internal numeric or other record identifier returned by KRZ.
caseSignature	Court case signature, when available.
proceedingType	Type of proceeding, when available.
proceedingStatus	Current proceeding status, when available.
court	Court associated with the proceeding, when available.
role	Person or entity role in the proceeding, when available.
searchType	Effective search mode associated with the record, such as entity or person.
sourceUrl	KRZ page used as the source, normally https://krz.ms.gov.pl/.
scrapedAt	UTC timestamp indicating when the actor collected the record.
_raw	The complete upstream KRZ record for this item.

_raw preserves the complete upstream record rather than only the normalized fields listed above. It can contain additional fields and the original upstream field names, including Polish names such as nazwa, formaPrawna, miejscowoscSiedziby, postepowanieId, and dataPoczatku. Use _raw when you need values that are not yet mapped to a top-level output field.

PPE event

The PPE event name for this actor is debtor-record-scraped.

This documentation describes the actor’s behavior and output contract. It does not claim that a live run has been performed; result availability and supported search forms depend on the live KRZ site at run time.