# Poland KRZ Debtor Registry Scraper (`bovi/krz-debtor-registry`) Actor

Browser-tier scraper for Poland's official KRZ debtor registry.

- **URL**: https://apify.com/bovi/krz-debtor-registry.md
- **Developed by:** [Vitalii Bondarev](https://apify.com/bovi) (community)
- **Categories:** Business, Lead generation, MCP servers
- **Stats:** 1 total users, 0 monthly users, 0.0% runs succeeded, 0 bookmarks
- **User rating**: No ratings yet

## Pricing

from $10.00 / 1,000 poland krz debtor registry scrapers

This Actor is paid per event. You are not charged for the Apify platform usage, but only a fixed price for specific events.

Learn more: https://docs.apify.com/actors/running/actors-in-store.md#pay-per-event

## What's an Apify Actor?

Actors are web data automations that power AI and operations. They run on the Apify platform to scrape websites, process data, connect APIs, and automate workflows.
In Batch mode, an Actor accepts a well-defined JSON input, performs an action which can take anything from a few seconds to a few hours,
and optionally produces a well-defined JSON output, datasets with results, or files in key-value store.
In Standby mode, an Actor provides a web server which can be used as a website, API, or an MCP server.
Actors are written with capital "A".

## How to integrate an Actor?

If asked about integration, you help developers integrate Actors into their projects.
You adapt to their stack and deliver integrations that are safe, well-documented, and production-ready.
The best way to integrate Actors is as follows.

- **AI agents and MCP clients** — the [Apify MCP server](https://docs.apify.com/integrations/mcp.md) at `https://mcp.apify.com` (remote, streamable HTTP, OAuth on first use).
- **Agentic workflows and local Actor development** — [Agent Skills](https://apify.com/.well-known/agent-skills/index.json) with the [Apify CLI](https://docs.apify.com/cli/docs.md): `npm install -g apify-cli`, then `apify login`.
- **JavaScript/TypeScript projects** — the official [JS/TS client](https://docs.apify.com/api/client/js/docs.md): `npm install apify-client`.
- **Python projects** — the official [Python client](https://docs.apify.com/api/client/python/docs.md): `pip install apify-client`.
- **Any other language** — the [REST API](https://docs.apify.com/api/v2.md).

For usage examples, see the [API](#api) section below.

For more details, see Apify documentation as [Markdown index](https://docs.apify.com/llms.txt) and [Markdown full-text](https://docs.apify.com/llms-full.txt).

# README

## KRZ Debtor Registry

This actor searches Poland’s official National Debtors Register (Krajowy Rejestr Zadłużonych, or KRZ) at [krz.ms.gov.pl](https://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.

# Actor input Schema

## `queries` (type: `array`):

Queries to search in the KRZ debtor registry. Each query should contain a search phrase and search type. The runtime also accepts plain strings, which are treated as auto-detected queries.

## `maxItems` (type: `integer`):

Maximum number of debtor registry records to return across all queries.

## `proxyConfiguration` (type: `object`):

Proxy settings used when accessing the KRZ registry.

## Actor input object example

```json
{
  "maxItems": 100,
  "proxyConfiguration": {
    "useApifyProxy": true,
    "apifyProxyGroups": [
      "RESIDENTIAL"
    ],
    "apifyProxyCountry": "PL"
  }
}
```

# Actor output Schema

## `results` (type: `string`):

Dataset of debtor registry records (entityName/firstName+lastName, nip, krs, regon, pesel, proceedingId, court, proceedingStatus, sourceUrl).

# API

You can run this Actor programmatically using our API. Below are code examples in JavaScript, Python, and CLI, as well as the OpenAPI specification and MCP server setup.

## JavaScript example

```javascript
import { ApifyClient } from 'apify-client';

// Initialize the ApifyClient with your Apify API token
// Replace the '<YOUR_API_TOKEN>' with your token
const client = new ApifyClient({
    token: '<YOUR_API_TOKEN>',
});

// Prepare Actor input
const input = {};

// Run the Actor and wait for it to finish
const run = await client.actor("bovi/krz-debtor-registry").call(input);

// Fetch and print Actor results from the run's dataset (if any)
console.log('Results from dataset');
console.log(`💾 Check your data here: https://console.apify.com/storage/datasets/${run.defaultDatasetId}`);
const { items } = await client.dataset(run.defaultDatasetId).listItems();
items.forEach((item) => {
    console.dir(item);
});

// 📚 Want to learn more 📖? Go to → https://docs.apify.com/api/client/js/docs

```

## Python example

```python
from apify_client import ApifyClient

# Initialize the ApifyClient with your Apify API token
# Replace '<YOUR_API_TOKEN>' with your token.
client = ApifyClient("<YOUR_API_TOKEN>")

# Prepare the Actor input
run_input = {}

# Run the Actor and wait for it to finish
run = client.actor("bovi/krz-debtor-registry").call(run_input=run_input)

# Fetch and print Actor results from the run's dataset (if there are any)
print(f"💾 Check your data here: https://console.apify.com/storage/datasets/{run.default_dataset_id}")
for item in client.dataset(run.default_dataset_id).iterate_items():
    print(item)

# 📚 Want to learn more 📖? Go to → https://docs.apify.com/api/client/python/docs/quick-start

```

## CLI example

```bash
echo '{}' |
apify call bovi/krz-debtor-registry --silent --output-dataset

```

## MCP server setup

```json
{
    "mcpServers": {
        "apify": {
            "type": "http",
            "url": "https://mcp.apify.com/?tools=fetch-actor-details,bovi/krz-debtor-registry"
        }
    }
}

```

The hosted server signs you in with OAuth on first connect, so no API token belongs in this config. Clients without OAuth support can send an `Authorization: Bearer <APIFY_API_TOKEN>` header instead, using a token from API & Integrations in Apify Console (https://console.apify.com/settings/integrations).

## OpenAPI specification

Download the OpenAPI definition: https://api.apify.com/v2/actors/OeAhfHfZXX5Ya1bew/builds/Q3P9DvaJyX7OjwEPy/openapi.json