# Polish VAT Whitelist & Pay-Safe Check (`cee-data/vat-whitelist-scraper`) Actor

Verify Polish VAT status and business bank account pairs through the official Ministry of Finance API.

- **URL**: https://apify.com/cee-data/vat-whitelist-scraper.md
- **Developed by:** [CEE Data](https://apify.com/cee-data) (community)
- **Categories:** Business
- **Stats:** 2 total users, 1 monthly users, 100.0% runs succeeded, 0 bookmarks
- **User rating**: No ratings yet

## Pricing

from $5.00 / 1,000 vat status results

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?

An Actor is a serverless cloud program that runs on the Apify platform. It has two run modes.
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.

Apify vocabulary and the platform model are defined once, in the agent quickstart at https://apify.com/agents.md.

## 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.

Do not guess an integration path. Every one of them is in the agent quickstart at https://apify.com/agents.md: the Apify MCP server, Agent Skills with the Apify CLI, the JavaScript and Python clients, the REST API, and the account-free path for an agent with no human to sign in. It also carries the rule on stating cost before the first paid run.

For examples already wired to this Actor's own input schema, see the [API](#api) section below.

Each client library has reference documentation the quickstart does not restate: [JavaScript/TypeScript](https://docs.apify.com/api/client/js/docs.md) (`npm install apify-client`) and [Python](https://docs.apify.com/api/client/python/docs.md) (`pip install apify-client`).

# README

### What does Polish VAT Whitelist & Pay-Safe Check do?

Verify a Polish company's **VAT status** or confirm that a **NIP and business bank account** match in the official Ministry of Finance registry.

- Receive the official VAT status, confirmation ID, and response timestamp.
- Check a NIP–bank account pair without exposing the full account number in results or logs.
- Process small, bounded batches through a simple JSON API—no login, browser, or scraping of HTML pages.

### Why use it?

Use this Actor to reduce payment fraud and automate counterparty checks in accounting, invoicing, procurement, and compliance workflows. It is useful for:

- validating a contractor before a first payment;
- checking whether a supplier is an active VAT taxpayer;
- adding an official confirmation ID to an audit trail;
- running recurring pay-safe checks in Make, Zapier, n8n, or your own system.

The Actor uses the official Ministry of Finance API and supports Apify scheduling, dataset exports, API access, and MCP.

### What data can you get?

| Field              | Description                                 |
| ------------------ | ------------------------------------------- |
| `mode`             | `status` or `paySafe`                       |
| `nip`              | Checked tax identification number           |
| `found`            | Whether the NIP exists in the registry      |
| `statusVat`        | VAT status returned by the ministry         |
| `accountAssigned`  | Whether the NIP and bank account match      |
| `bankAccountLast4` | Last four digits of the checked account     |
| `requestId`        | Official electronic confirmation identifier |
| `requestDateTime`  | Response timestamp from the ministry        |
| `date`             | Verification date                           |
| `sourceUrl`        | API endpoint or endpoint group              |
| `fetchedAt`        | Extraction timestamp                        |

The Actor intentionally excludes names, addresses, representatives, partners, full account numbers, and account lists.

### Example output

VAT status:

```json
{
    "mode": "status",
    "nip": "5272677009",
    "requestId": "Zq6Pg-99504e4",
    "requestDateTime": "29-10-2026 06:32:04",
    "date": "2026-10-28",
    "sourceUrl": "https://wykazpodatnikowvat.mf.gov.pl/api/search/nip/5272677009?date=2026-10-28",
    "fetchedAt": "2026-10-29T05:32:04.635Z",
    "found": true,
    "statusVat": "Czynny",
    "accountAssigned": null,
    "bankAccountLast4": null
}
```

Pay-safe check:

```json
{
    "mode": "paySafe",
    "nip": "5272677009",
    "requestId": "TTCKj-99504ai",
    "requestDateTime": "29-10-2026 06:30:42",
    "date": "2026-10-28",
    "sourceUrl": "https://wykazpodatnikowvat.mf.gov.pl/api/check",
    "fetchedAt": "2026-10-29T05:30:42.349Z",
    "found": null,
    "statusVat": null,
    "accountAssigned": true,
    "bankAccountLast4": "5745"
}
```

### How much will it cost?

- **$5.00 per 1,000 VAT status results** (`vat-status`).
- **$15.00 per 1,000 pay-safe checks** (`pay-safe-check`).

Each saved result is charged once. There is no additional Actor-start or dataset-item event, and platform usage is not charged separately to the user. Measured platform usage for one pay-safe check was approximately $0.0002925.

### Free n8n workflow: check a supplier before payment

[Download the ready-to-import VAT pay-safe workflow](https://api.apify.com/v2/key-value-stores/2adhfhT2wfW54leSK/records/vat-pay-safe-supplier-check.json). It takes a supplier NIP and bank account, calls this Actor, and returns the official confirmation ID plus a `reviewRequired` flag for your payment approval flow. The JSON contains no credentials; use n8n Header Auth credentials for your Apify token.

### How to run a check

1. Select **VAT status** or **Pay-safe bank account check**.
2. Enter one or more 10-digit NIP numbers. Pay-safe mode accepts exactly one NIP.
3. In pay-safe mode, enter the 26-digit business bank account.
4. Optionally choose a historical verification date and start the Actor.
5. Download results as JSON, CSV, or Excel.

A missing company returns `found: false`; it is not treated as an infrastructure failure.

### Input and safeguards

- **Maximum results:** 10 by default, capped at 100 per run.
- **Maximum concurrency:** 2 by default.
- **Maximum requests per minute:** 30 by default.
- **Maximum retries:** 4 by default for network errors, HTTP 429, and HTTP 5xx.
- **Request timeout:** 20 seconds by default.

HTTP 404 and other non-retryable 4xx responses fail immediately. Invalid JSON and unexpected response structures count as parsing failures. Every run ends with categorized error counters.

### Development and validation

```bash
npm install
npm run build
npm test
apify validate-schema
apify run
```

The bundled local input limits the live smoke run to one result. Unit tests cover active and missing companies, account assignment, invalid structures, retry policy, and silent failures.

### Legal, privacy, and support

This Actor uses publicly available business registry data from the official Ministry of Finance API. It does not bypass access controls and respects published API limits. Do not use it to collect personal data.

For bugs or feature requests, use the Issues tab. Programmatic access is available through API and MCP.

### Store metadata

- **Categories:** Finance, Compliance, Business Data, Government and Public Data
- **Keywords:** Poland VAT, NIP verification, white list VAT, pay safe, bank account verification, contractor validation, Ministry of Finance, KSeF, accounting automation

# Actor input Schema

## `mode` (type: `string`):

Check VAT status or verify a NIP and business bank account pair

## `nips` (type: `array`):

Polish tax identification numbers to check

## `bankAccount` (type: `string`):

26-digit business bank account required only in paySafe mode; never returned in full

## `date` (type: `string`):

Date in YYYY-MM-DD format; leave empty for today

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

Maximum NIP lookups and billable results per run

## `maxConcurrency` (type: `integer`):

Maximum number of lookups processed at once

## `maxRequestsPerMinute` (type: `integer`):

Request rate limit applied by Crawlee

## `maxRequestRetries` (type: `integer`):

Retries for network errors, HTTP 429, and HTTP 5xx

## `requestTimeoutSecs` (type: `integer`):

Timeout for a single HTTP request in seconds

## Actor input object example

```json
{
  "mode": "status",
  "nips": [
    "5272677009"
  ],
  "bankAccount": "",
  "date": "",
  "maxItems": 10,
  "maxConcurrency": 2,
  "maxRequestsPerMinute": 30,
  "maxRequestRetries": 4,
  "requestTimeoutSecs": 20
}
```

# Actor output Schema

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

No description

# 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 = {
    "nips": [
        "5272677009"
    ]
};

// Run the Actor and wait for it to finish
const run = await client.actor("cee-data/vat-whitelist-scraper").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 = { "nips": ["5272677009"] }

# Run the Actor and wait for it to finish
run = client.actor("cee-data/vat-whitelist-scraper").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 '{
  "nips": [
    "5272677009"
  ]
}' |
apify call cee-data/vat-whitelist-scraper --silent --output-dataset

```

## MCP server setup

```json
{
    "mcpServers": {
        "apify": {
            "type": "http",
            "url": "https://mcp.apify.com/?tools=fetch-actor-details,cee-data/vat-whitelist-scraper"
        }
    }
}
```

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/h3oOqDs1DijWhDmZL/builds/AviQMuD7miGL92xwJ/openapi.json