How can I use the API to retrieve information from the National Debt Register (KRZ) about discontinued enforcement proceedings involving 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 information from the KRZ about closed enforcement proceedings for a specific debtor based on their NIP or PESEL number.

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]

{
    "model": "pl-krz-wp-record",
    "pl_pesel": [numer PESEL]
}

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 a Get Refresh endpoint call with the following 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 list of discontinued enforcement proceedings against the debtor provided in the response

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 enforcement proceedings against the debtor that have been discontinued and disclosed in the KRZ, each entry in the list must be processed in each file.

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]
}

You can distinguish discontinued enforcement proceedings from other types of proceedings listed in the KRZ based on the contents of the *typeproceeding* dictionary.

Contents of the "Type of Proceedings" glossary for discontinued enforcement proceedings:

{
    "kod": "PE-upe",
    "kodRodzajuEwidencji": "PE",
    "tytul": "umorzone postępowanie egzekucyjne"
}

You can find detailed information about the proceedings—such as the name of the authority that issued the enforcement order, the date of cancellation, or the amount that remains unpaid—in the szczegoly-UPE database.

Contents of the szczegoly-UPE dictionary for discontinued enforcement proceedings:

{
    "danePodstawowePostepowania": {
        "dataUjawnienia": [data ujawnienia postępowania w KRZ],
        "dataUmorzenia": [data umorzenia postępowania],
        "sumaNiewyegzekwowana": [niewyegzekwowana suma],
        "sygnatura": [sygnatura postępowania],
        "tytulWykonawczy": [tytuł wykonawczy]
    },
    "dluznik": {
        "nip": [numer NIP dłużnika],
        "krs": [numer KRS dłużnika],
        "siedziba": [siedziba dłużnika],
        "nazwa": [nazwa dłużnika]
        "formaPrawna": [forma prawna dłużnika]
    },
    "organWydajace": {
        "nazwaOrganu": [nazwa organu wydającego tytuł wykonawczy]
    }
}

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