Poland KRZ Debtor Registry Scraper & Monitor

Search Poland's Krajowy Rejestr Zadłużonych (KRZ, the National Register of Debtors) by KRS number, NIP, or company name. Check up to 500 companies per run, export normalized insolvency and restructuring findings, or schedule recurring portfolio monitoring.

Pricing: $0.02 per registry session (once per run), $0.005 per completed company check, $0.01 per delivered monitor change. A run that never reaches KRZ costs nothing at all, and failed checks, invalid input and internal retries are never charged.

What it does

You give it a list of Polish companies - by KRS number, NIP, or name. For each one it looks the company up in the KRZ public register, extracts any bankruptcy, restructuring, business-ban or enforcement proceedings, and returns a single normalized status plus the underlying proceedings.

It is deliberately narrow. It answers "what does KRZ show for this company?" for companies. It is not a general solvency certificate, a current KRS-status check, or an interface for natural persons.

The one rule it never breaks:

A zero-result lookup is NO_KRZ_RECORD, never CLEAR. KRZ contains only proceedings begun after 1 December 2021, so no KRZ match does not prove that a company is solvent or free of older proceedings.

"Nothing found" and "the request failed" are different fields with different values, so a downstream credit decision can tell them apart.

Main use cases

• One input to counterparty screening before signing a contract or extending credit. Do not use KRZ alone as a solvency clearance.
• Portfolio monitoring - run it on a schedule with monitorMode: true and get an event when a new KRZ proceeding appears for a customer or supplier.
• KYC / onboarding checks as part of a supplier or partner review.
• Receivables risk - spot debtors entering restructuring before a payment becomes uncollectable.

Input

{
  "krsNumbers": ["0000026438", "0000127140"],
  "monitorMode": false,
  "includeHistorical": true,
  "proxyConfiguration": {
    "useApifyProxy": true,
    "apifyProxyGroups": ["RESIDENTIAL"],
    "apifyProxyCountry": "PL"
  }
}

Field	Type	Default	Notes
krsNumbers	string list	empty	Fast start for KRS lookups; one number per line
nipNumbers	string list	empty	Fast start for NIP lookups; one number per line
companies	object array	empty	Advanced name/mixed-identifier entries and optional externalId; combined limit across all three fields is 500
monitorMode	boolean	false	Compare against the previous run and report changes
includeHistorical	boolean	true	Include closed proceedings
proxyConfiguration	object	Apify Proxy, RESIDENTIAL, PL	See Proxy requirement

Identifier precedence: KRS → NIP → name. If you supply several, the most specific one is used for the search and the rest are echoed back. Give a KRS or NIP whenever you have one. A zero-candidate lookup is reported as NO_KRZ_RECORD; this describes the KRZ response only and is not a company-level clearance.

A name that matches several debtors is never resolved to a guess. The record comes back unmatched with match.ambiguous: true and the candidate count, so you can tell "not in the register" from "we could not tell which one you meant".

externalId is yours - an opaque string echoed back untouched on the result so you can join it to your own rows. It is never sent to KRZ and never affects the search or the monitoring state key.

Identifiers are validated before any request is made. NIP checksums are verified, KRS numbers are zero-padded to ten digits. An invalid entry does not stop the batch - it becomes one FAILED record explaining what was wrong with that row, and the other companies are still checked.

Output

One dataset record per input row. This is a real no-record response shape for the second company in the sample input above:

{
  "query": {
    "nip": null,
    "krs": "0000127140",
    "name": null,
    "externalId": "example-no-krz-record"
  },
  "company": null,
  "businessStatus": "NO_KRZ_RECORD",
  "match": { "method": "krs", "candidates": 0, "ambiguous": false, "truncated": false },
  "proceedings": [],
  "changes": [],
  "source": "KRZ",
  "sourceId": "krz:query:krs:0000127140",
  "sourceUrl": "https://krz.ms.gov.pl/",
  "checkedAt": "2026-08-29T14:50:55.548461Z",
  "scrapedAt": "2026-08-29T14:50:55.548461Z",
  "fingerprint": "0f063095798d38fccde732555b5204a0161d51606543a0e733fc7f76f3f9dd09",
  "checkStatus": "NOT_FOUND",
  "error": null,
  "schemaVersion": 3
}

Every verified row is ready for repeat ingestion: sourceId is stable across runs, scrapedAt is the UTC observation time, and fingerprint hashes only the normalized company/proceeding state. It excludes timestamps, run IDs, externalId and monitoring events, so unchanged source state produces the same fingerprint. A FAILED row carries fingerprint: null because no source state was verified.

businessStatus - what we know about the company

Value	Meaning
NO_KRZ_RECORD	KRZ returned zero matching records. This is not proof of solvency and does not exclude proceedings begun before 1 December 2021
ACTIVE_PROCEEDING	In the register with at least one characterized proceeding that is open (or of a known type whose status KRZ did not state)
HISTORICAL_PROCEEDING	In the register with characterized proceedings, all closed
LISTED_UNVERIFIED	In the register, but the proceeding could not be characterized - the detail lookup gave no type or status. Not clear, not a confirmed active proceeding. Verify manually
UNKNOWN	The check did not complete (transport error, or an ambiguous name miss). Never treat as clear

Presence in the register is a signal, but absence is not a clearance. KRZ lists only proceedings begun after 1 December 2021. A company that appears is never CLEAR; a company with zero candidates is NO_KRZ_RECORD, even under an exact KRS or NIP.

The entity search alone returns only an id and a start date - no type or status - so each proceeding's nature comes from a per-company detail lookup. When the detail resolves, ACTIVE_PROCEEDING and HISTORICAL_PROCEEDING are distinguished (a known type with an unstated status still counts as open - a missed insolvency is the expensive error). When the detail cannot be read, the company reads LISTED_UNVERIFIED, not ACTIVE_PROCEEDING: the Actor knows the company is in KRZ but will not assert an active proceeding it has not seen. This is deliberate - reporting a large solvent company as being in active insolvency on the strength of one unresolved row is the failure mode this status prevents. A matched company is still never downgraded to CLEAR by a detail error. includeHistorical shapes which proceedings are listed, never the status.

checkStatus - whether the check worked

Value	Meaning
SUCCESS	KRZ answered and the company was matched
NOT_FOUND	KRZ answered, no entity matched this identifier
FAILED	The lookup did not complete. error says why; businessStatus is UNKNOWN

NOT_FOUND with businessStatus: NO_KRZ_RECORD means the query completed and KRZ returned zero matching records. It does not mean "healthy company".

proceedings[].type

BANKRUPTCY, BANKRUPTCY_PETITION, RESTRUCTURING, BUSINESS_BAN, ENFORCEMENT, OTHER. The original Polish label is kept in sourceType so a normalization you disagree with is visible in the data.

Partial failures

A bad company does not stop the rest of a batch. For example, 100 inputs with 3 failed lookups still produce 100 dataset records: 97 usable records and 3 records marked FAILED. The log and RUN_SUMMARY make the totals explicit:

Processed: 100
Successful: 16
Not found: 81
Failed: 3
No matching KRZ record: 81
Active proceedings: 4
Historical proceedings: 11
Listed, details unverified: 1

The same numbers are written to RUN_SUMMARY in the run's key-value store. The run itself is only marked failed when KRZ is unreachable or every check failed, because that is a source problem rather than a data problem.

The summary also includes an operational health envelope, stage, terminalReason, build/run IDs, endpoint counters and timeout counts. Handled input, proxy and bootstrap failures save this diagnostic record before exit.

A malformed registry response produces FAILED / UNKNOWN, never a claim that the company has no KRZ record. Failed, ambiguous and truncated searches preserve the last verified monitoring state. Only a validated empty response can establish that no matching record was returned.

Monitoring mode

Set monitorMode: true and schedule the Actor. Each run compares against the previous one and fills changes:

"changes": [
  {
    "type": "NEW_PROCEEDING",
    "caseNumber": "WA1M/GU/301/2026",
    "proceedingType": "BANKRUPTCY_PETITION",
    "previousStatus": null,
    "currentStatus": "ACTIVE",
    "detectedAt": "2026-08-27T11:46:51+00:00"
  }
]

Change types: NEW_PROCEEDING, STATUS_CHANGED, PROCEEDING_CLOSED.

State is kept in an Apify key-value store, one record per company, keyed by the strongest identifier supplied. Keep passing the same KRS or NIP for a company so its history lines up. The first monitored run reports no changes because it has no earlier successful observation to compare against.

A proceeding that disappears from KRZ produces no event. Disappearing is not a fact about the company; only new entries and status transitions are reported.

Failures do not manufacture change events. A failed or incomplete check does not overwrite the last successful state. Once KRZ becomes readable again, the Actor compares two successful observations rather than treating the outage as a company event.

includeHistorical shapes the proceedings listing only. Change detection and state always run on everything KRZ returned, so a proceeding closing is still reported as PROCEEDING_CLOSED even with includeHistorical: false.

Proxy requirement

KRZ rejects requests from IP addresses outside Poland. Use Apify Proxy with country PL. The input defaults to RESIDENTIAL. One successful sticky Polish residential session performs the browser bootstrap and every HTTP lookup in that run. If Imperva refuses an exit or the token bootstrap times out, the Actor rotates to a fresh sticky session, with a hard limit of three total attempts. This bounds source load, browser cost and run time. The Actor does not solve or bypass CAPTCHA; if KRZ presents one, it stops immediately without rotating and no company is reported absent.

The cloud gate on 1 September 2026 completed 30 fresh Polish residential sessions: 29 minted a guest token, none displayed hCaptcha, and the 95% access gate passed. The run cost $0.4911 ($0.0164 per attempted session), including a new browser bootstrap for every session. Production batches reuse one session, so that probe is intentionally more expensive than a normal run.

Without a working Polish proxy the run fails immediately with a clear message rather than producing a dataset full of false no-record results.

Limitations

• Companies only. KRZ also covers natural persons; this Actor does not, and passing a personal identifier is not supported.
• Historical coverage starts on 1 December 2021. The Polish Ministry of Justice states that KRZ contains only proceedings begun after that date. Older proceedings can remain active without appearing in KRZ.
• No KRS health verification. The Actor does not currently verify whether a company is active, deleted, in liquidation, or named "w upadłości" in KRS. NO_KRZ_RECORD must not be used as a compliance or credit clearance.
• Name searches are weak. Several candidates or a truncated result produce NOT_FOUND with businessStatus: UNKNOWN rather than a guess. Use KRS or NIP.
• No official public API. The Actor reads the public KRZ portal. A portal redesign can interrupt extraction; such failures are returned as FAILED, never as an empty or clear result.
• Register lag. KRZ reflects court announcements. A proceeding exists in reality from the moment a court acts, which can precede its publication.
• sourceUrl is the portal root, not a per-company deep link; no stable deep-link format has been confirmed.
• Batch cap of 500 companies per run. Split larger lists across runs.

Storage and integrations

Results are available in Apify Console, through the API, and to integrations or AI agents:

• results - the default dataset, one record per input company ({{apiDefaultDatasetUrl}}/items).
• runSummary - the RUN_SUMMARY record in the default key-value store: processed / successful / not found / failed counts, per-status totals, and the request/browser counters used for costing.

Use with AI agents through Apify MCP

Expose this public Actor as a typed MCP tool:

https://mcp.apify.com?tools=automa-flow/poland-krz-debtor-registry-insolvency-check

Example prompt:

Run automa-flow/poland-krz-debtor-registry-insolvency-check for these Polish KRS
or NIP identifiers. Summarize returned insolvency and restructuring proceedings,
separate NOT_FOUND from FAILED checks, and cite the sourceUrl on every company.

An agent must never translate a NOT_FOUND KRZ result into a solvency certificate: KRZ covers the public post-2021 register scope documented below.

Pricing

The Actor supports Pay per event. Every event is a logical, customer-visible unit of work - a session on the register, a delivered company result, a detected change - never an HTTP request or a retry:

Event	Price	Charged when
registry-session	$0.02	Once per run, after a guest session on the KRZ portal has been established
company-check	$0.005	One SUCCESS or verified NOT_FOUND company result is delivered
monitor-change	$0.01	One new proceeding or verified proceeding-status transition is delivered

The registry-session event is scheduled to become active on 16 September 2026 at 21:35 UTC. The Actor only calls it when the run's active pricing includes that event; before activation, it is skipped. The Pricing tab remains authoritative.

The session is what a run actually costs. KRZ answers Polish IPs only and guards the portal with a JavaScript checkpoint, so every run pays for a Polish residential exit and a real browser clearing it - the same cost whether the run checks one company or five hundred. Checking a portfolio in one run is therefore far cheaper per company than one run per company. The session is billed only once it exists: if KRZ is blocked, presents a CAPTCHA or is down, the run fails and charges nothing.

The platform's standard Actor-start event is currently $0.00005 per run. That event is configured in Apify monetization rather than emitted by the application, and does not make retries or failed company rows billable.

Situation	company-check billed?
SUCCESS (KRZ answered, company matched)	yes
NOT_FOUND (KRZ answered, no record matched)	yes - the lookup was performed
FAILED (transport error, source blocked, skipped)	no
Invalid input row (bad NIP, too-short name, …)	no - it never reaches KRZ
Internal client retries / token refresh	no - billing is per result, not per request

Situation	registry-session billed?
The guest session was established	yes - once, no matter how many companies follow
Imperva block page on every rotated session	no - the run fails without reaching the register
KRZ presented a CAPTCHA	no - the Actor stops rather than solving it
Input was rejected before the browser started	no - no session was ever opened

monitor-change is an additional event charged only alongside a billable company-check, one per detected change - so a failed check is never billed for phantom changes.

Users can set a maximum charge for an individual run. Once the remaining budget cannot pay for another company-check, the Actor starts no more KRZ lookups and reports the number skipped in RUN_SUMMARY. A few checks already in flight may finish, bounded by the Actor's conservative internal concurrency; the SDK atomically prevents their dataset writes from exceeding the limit. If the Actor start event consumes the entire budget, the browser and proxy are not initialized at all.

API usage

Run it from your own code with the Apify API or a client library:

curl -X POST "https://api.apify.com/v2/acts/automa-flow~poland-krz-debtor-registry-insolvency-check/run-sync-get-dataset-items" \
  -H "Authorization: Bearer $APIFY_TOKEN" \
  -H 'Content-Type: application/json' \
  -d '{
        "companies": [{"krs": "0000026438"}, {"krs": "0000127140"}],
        "proxyConfiguration": {"useApifyProxy": true, "apifyProxyGroups": ["RESIDENTIAL"], "apifyProxyCountry": "PL"}
      }'

from apify_client import ApifyClient

client = ApifyClient("<APIFY_TOKEN>")
run = client.actor("automa-flow/poland-krz-debtor-registry-insolvency-check").call(
    run_input={
        "companies": [{"krs": "0000026438"}],
        "monitorMode": True,
        "proxyConfiguration": {
            "useApifyProxy": True,
            "apifyProxyGroups": ["RESIDENTIAL"],
            "apifyProxyCountry": "PL",
        },
    }
)
for item in client.dataset(run["defaultDatasetId"]).iterate_items():
    print(item["query"], item["businessStatus"], item["checkStatus"])

Always branch on checkStatus before acting on businessStatus.

Keep API tokens in environment variables or Apify secrets. Do not paste them into input, source code, issue reports, or URLs.

Scheduling and webhooks

Save the same company list as an Apify Task, set monitorMode: true, and run it daily or weekly. The first successful run establishes the baseline. Later runs put NEW_PROCEEDING, STATUS_CHANGED and PROCEEDING_CLOSED events in each company row's changes array.

Attach a webhook on ACTOR.RUN.SUCCEEDED and let the receiver fetch the Dataset:

{
  "runId": "{{resource.id}}",
  "datasetId": "{{resource.defaultDatasetId}}",
  "itemsUrl": "https://api.apify.com/v2/datasets/{{resource.defaultDatasetId}}/items?clean=true"
}

Filter the fetched rows for a non-empty changes array. Also attach an ACTOR.RUN.FAILED webhook: a failed run means KRZ was not verified and must not be interpreted as a quiet portfolio.

Troubleshooting and support

• Run fails before producing results: keep the default Polish residential proxy and inspect the bootstrap reason in RUN_SUMMARY. The Actor already rotates up to three fresh sessions for block pages, navigation failures and token timeouts. CAPTCHA is deliberately not retried.
• A name search is ambiguous: use KRS or NIP. The Actor deliberately refuses to guess between multiple companies.
• A row says FAILED: inspect its error field and retry it. Never treat a failed row as absence from KRZ.
• A row says NO_KRZ_RECORD: the KRZ query completed but returned no match. This is not a KRS-status or solvency clearance.
• Unexpected output: open an issue on the Actor page and include the run ID, expected result, and affected KRS or company identifier. Never include an API token or private proxy credentials.

Data and source disclaimer

Data comes from the Krajowy Rejestr Zadłużonych, a public register operated by the Polish Ministry of Justice at https://krz.ms.gov.pl/. The register is public and free to consult; this Actor automates reading it and normalizes the result.

• This Actor is not affiliated with or endorsed by the Ministry of Justice.
• Output is provided as-is with no warranty of accuracy, completeness or timeliness, and is not legal, credit or financial advice. For anything with legal consequence, consult the register or an official document directly.
• KRZ is the authoritative source. Where this Actor's output and KRZ disagree, KRZ is right.
• Only company records are returned. Do not use this Actor to profile natural persons; if a personal record is ever returned, that is a bug - please report it.
• You are responsible for using the data lawfully, including under GDPR where any personal data (a court official's name in a case record, for instance) is involved.

The source risk is classified MODERATE: the public portal is openly available without login, but it has no supported public API, restricts traffic geographically and protects the browser bootstrap with Imperva. The Actor uses only the public company view, stops on CAPTCHA, retains one compact successful monitoring snapshot per company, and never exposes guest tokens, cookies or proxy credentials.