How do I use the API to retrieve a list of court cases from the National Court Register (KRZ) for a specific debtor?

MGBI provides a comprehensive API for retrieving data from public registers and records, including the National Debt Register (KRZ).

You can find a list of data sources available through this service at:
👉 Public Registers API

This guide covers the API for the KRZ entity search tool, which we provide as part of the following product:
👉 National Debt Register API (KRZ API) - Entity Search Tool

Below, we describe how you can use the API to retrieve a list of court cases from the National Court Register (KRZ) for a specific debtor based on their tax identification number (NIP) or personal identification number (PESEL).

Step 1: Obtain an API authorization key

To obtain the authorization key required to call endpoints available in the MGBI API, please contact us using the contact form on the product page:
👉 National Debt Register API (KRZ API) - Entity Search

Step 2: Call the Create Refresh endpoint

We make the data available in the KRZ Entity Search Engine accessible via the MGBI API in a data model with the identifier pl-krz-wp-record.

This model is synchronized on demand, which means that we do not have a complete copy of the data available in the source registry in our database.

To retrieve current data on a specific debtor from the model, you must first create a request to fetch it from the KRZ using the Create Refresh endpoint.
👉 Create Refresh endpoint documentation

Example of calling the Create Refresh endpoint with the tax ID number:

POST /v1/refresh HTTP/1.1
Host: api.mgbi.pl
Authorization: [klucz autoryzacji]

{
    "query: {
        "model": "pl-krz-wp-record",
        "identifiers.pl_nip": [numer NIP]
    }
}

If you need information about proceedings against a debtor who is an individual, you can also use their PESEL number.

Example of calling the Create Refresh endpoint with a PESEL number:

POST /v1/refresh HTTP/1.1
Host: api.mgbi.pl
Authorization: [klucz autoryzacji]

{
    "query: {
        "model": "pl-krz-wp-record",
        "identifiers.pl_nip": [numer NIP]
    }
}

A successful call to the Create Refresh endpoint returns a dictionary containing the request ID in the id field.

Step 3: Call the Get Refresh endpoint

Requests to retrieve data from the source registry typically take anywhere from a few to several seconds to complete after they are created by the Create Refresh endpoint.

To check the current status of the order, call the Get Refresh endpoint and include the order ID obtained in the previous step in the URL.
👉 Get Refresh endpoint documentation

Example of calling the Get Refresh endpoint with a request ID:

GET /v1/refresh/[order ID] HTTP/1.1
Host: api.mgbi.pl
Authorization: [authorization key]

If the status field in the returned dictionary is set to " pending," the request is still being processed, and you should call the Get Refresh endpoint again in a few seconds.

If the status field is set to "success," this means that the request has been processed and the data regarding the specified debtor has already been retrieved from the source registry.

Step 4: Call the Get Records endpoint

The API for the pl-krz-wp-record model provides a Get Records endpoint that returns records containing the full response content from the KRZ Entity Search Engine for the specified debtor.
👉 Documentation for the Get Records endpoint for the pl-krz-wp-record model

To retrieve data from the source registry in a previously created request, call the Get Records endpoint and pass the request ID in the refresh_id parameter.

Example of calling the Get Records endpoint with a request ID:

GET /v1/models/pl-krz-wp-record/records?refresh_id=[order ID] HTTP/1.1
Host: api.mgbi.pl
Authorization: [authorization key]

Step 5: Review the response to identify the list of proceedings pending against the debtor

A successful call to the Get Records endpoint returns a list of records that meet the specified criteria. In the example above, the endpoint should return a list of results containing a single record:

{
    "count": 1,
    "pages": 1,
    "results": [
        {
            "id": [identyfikator rekordu],
            "identifiers": [identyfikatory dłużnika],
            "content": [treść odpowiedzi z wyszukiwarki],
            "meta": [metadane rekordu]
        }
    ]
}

Court proceedings in the National Debt Register are grouped into so-called files. A single file may contain data on one or more related proceedings.

Depending on the debtor's legal form, you will find the list of files in the field:

• content.raw_result.search-by-entity.participant_list.0.files - for entities that are not natural persons,
• content.raw_result.search-by-of-jdg.participant_list.0.folder - for individuals operating a business,
• content.raw_result.search-by-of.participant_list.0.folder - for individuals who do not conduct business activities.

To view the complete list of all proceedings against the debtor disclosed in the KRZ, each item on the list must be processed in each of the files.

Sample content of the "procedure" list item:

{
    "aktualna-metryka": [dane dłużnika],
    "dataRozpoczecia": [data rozpoczęcia postępowania],
    "dataUtworzenia": [data utworzenia postępowania],
    "dataZakonczenia": [data zakończenia postępowania],
    "id": [identyfikator wewnętrzny postępowania],
    "idZewnetrzny": [identyfikator zewnętrzny postępowania],
    "rodzajPostepowania": [informacje o rodzaju postępowania],
    "stanPostepowaniaRejestr": [aktualny stan postępowania],
    "sygnaturaAkt": [sygnatura postępowania],
    "szczegoly": [szczegółowe informacje o postępowaniu],
    "szczegoly-UPE": [szczegółowe informacje o umorzonym postępowaniu egzekucyjnym]
}

Learn more:
👉 Data structure in the pl-krz-wp-record model
👉 Endpoint documentation for the pl-krz-wp-record model