How do I retrieve the current list of a business’s bank accounts from the VAT Taxpayer Registry via the API?

MGBI provides a comprehensive API for retrieving data from public registers and records, including the VAT Payers List (White List). You can find a list of data sources available through this service at:
👉 Public Registers API

This guide covers the API for the VAT Payers List (White List), which we provide as part of the following product:
👉 VAT Payers List API (White List API)

Below, we describe how you can use the API to retrieve the current list of a business’s bank accounts from the VAT Taxpayers Register based on its tax identification number (NIP).

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:
👉 VAT Payers API List (White List API)

Step 2: Call the Create Refresh endpoint

We make the data available in the VAT Taxpayers Register accessible via the MGBI API in the data model with the identifier pl-wpv-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 VAT Taxpayers List 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-wpv-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 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-wpv-record model provides a Get Records endpoint that returns records containing the full response content from the VAT Payers Register for the specified debtor.
👉 Documentation for the Get Records endpoint for the pl-wpv-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-wpv-record/records?refresh_id=[order ID] HTTP/1.1
Host: api.mgbi.pl
Authorization: [authorization key]

Step 5: Retrieve the current list of bank accounts from 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 podmiotu],
            "version": [informacje o wersji rekordu],
            "content": [treść odpowiedzi z wyszukiwarki],
            "meta": [metadane rekordu]
        }
    ]
}

All data available in the VAT Taxpayer Directory search engine for the specified entity can be found in the content.subject dictionary.

Sample contents of the content.subject dictionary:

{
    "name": [nazwa podmiotu],
    "nip": [numer NIP],
    "statusVat": [status podatnika VAT],
    "regon": [numer REGON],
    "krs": [numer KRS],
    "workingAddress": [adres siedziby],
    "representatives": [dane reprezentantów],
    "authorizedClerks": [dane pełnomocników],
    "partners": [dane wspólników],
    "registrationLegalDate": [data rejestracji podanika VAT],
    "accountNumbers": [lista numerów rachunków bankowych],
    "hasVirtualAccounts": [informacja, czy podatnik posiada rachunki wirtualne]
}

You can view the current list of bank accounts for the specified entity, as disclosed in the VAT Taxpayers Directory, in the ` content.subject.accountNumbers` field.

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