Poland Supplier Verification: VAT White List & Bank Check

Press Start and get a verification record for each Polish supplier on the first run: VAT White List status, registered bank accounts (optional account check with MF requestId as audit proof), KRS number and a KRZ insolvency flag, one row per NIP. Official data, no API key. $0.003 per verified supplier record.

Schedule it (e.g. before each payment run) and later runs also return a change alert ($0.02 each) when a supplier's VAT status, bank-account match or insolvency flag changes. Turn off Return current supplier records for an alerts-only schedule.

Supplier verification for AP, treasury and procurement teams paying Polish suppliers. For each supplier NIP (+ optional bank account), get one JSON KYB packet: the official MF VAT White List status (biała lista podatników VAT), a bank account verification (accountAssigned TAK/NIE) with the MF requestId as audit proof, and a best-effort KRZ (National Debtor Register) insolvency signal — plus typed mismatch events such as BANK_ACCOUNT_MISMATCH and VAT_NOT_ACTIVE. Official public HTTP, no API key. Not a Northdata clone, not a VAT-only ghost monitor, not a KRS financial-statement dump.

Who this is for

• Accounts payable and treasury teams that must check a Polish supplier's bank account is on the MF White List before paying (split-payment / tax-liability risk).
• Procurement and vendor-onboarding teams doing supplier KYB on new Polish vendors.
• Shared-service centres re-verifying a supplier master file on a schedule.

Typical workflow

1. Export supplier NIPs (and the bank accounts you are about to pay, as NIP:NRB or NIP:IBAN).
2. Run with sourceMode: "live" (no key) — each verified supplier returns a packet with status_vat, bank_status, mf_request_id and mismatch_events.
3. Block or review payments where mismatch_events is non-empty (e.g. BANK_ACCOUNT_MISMATCH, VAT_NOT_ACTIVE); keep mf_request_id as audit evidence.
4. Schedule it (e.g. before each payment run). Unchanged packets are deduplicated and not re-charged; a VAT, bank or KRZ flip produces a new packet.

First run vs later runs

First run: the first live run returns a supplier record for each verified supplier ($0.003 each, unless Return current supplier records is off) and stores a baseline. Every later live run also returns and charges current supplier records; a $0.02 KYB packet is delivered (and charged) only when VAT, bank or KRZ status changes.

Run it live now (no API key)

{
  "supplierNips": [
    "5261040828"
  ],
  "bankAccounts": [
    "5261040828:07101010100024791339300000"
  ],
  "sourceMode": "live",
  "includeKrz": true,
  "maxRunSeconds": 120
}

Example output (SAMPLE)

SAMPLE — illustrative values in the real output shape; NIP 0000000000 / EXAMPLE SP. Z O.O. / the account and request IDs are placeholders, not a real supplier or a real MF response.

{
  "event_type": "KYB_PACKET",
  "event_subtype": "BANK_ACCOUNT_MISMATCH",
  "nip": "0000000000",
  "legal_name": "EXAMPLE SP. Z O.O.",
  "status_vat": "ACTIVE",
  "bank_status": "NOT_ASSIGNED",
  "bank_account": "00000000000000000000000000",
  "account_assigned": "NIE",
  "krz_status": "CLEAR",
  "mf_request_id": "<MF requestId>",
  "mismatch_events": [
    "BANK_ACCOUNT_MISMATCH"
  ],
  "verified": true,
  "summary": "KYB packet for NIP 0000000000: vat=ACTIVE bank=NOT_ASSIGNED krz=CLEAR verified=true mismatches=BANK_ACCOUNT_MISMATCH",
  "event_uid": "<md5>",
  "billable": true
}

What you get per $0.02 event: one verified KYB packet for one supplier (one dataset row like the sample above). Unverified results (MF outage or quota, NIP not found) are not delivered or charged (they are counted in the RUN_STATUS row); duplicates and health rows are never charged.

Honest title: batch / scheduled KYB packet over official/public HTTP. Not a paid Bisnode/Creditreform extract, not a certified KRS odpisu, not real-time KRZ push.

Value proposition

• Cross-source join: MF White List × bank accountAssigned proof × KRZ signal.
• Mismatch events: VAT_NOT_ACTIVE, VAT_REMOVED, VAT_EXEMPT, BANK_ACCOUNT_MISMATCH, BANK_ACCOUNT_UNCHECKED, KRZ_PROCEEDING_OPEN, KRZ_CHECK_UNAVAILABLE, MF_API_UNAVAILABLE, NIP_NOT_FOUND.
• Official / public HTTP only. No paid credit-bureau HTML.
• Pay per delivered result: $0.003 per verified supplier record returned on each live run (turn off Return current supplier records to skip) plus $0.02 per unique verified KYB packet. MF outage and fixture health ≈ $0 product charges.
• Durable KVS checkpoint + event_uid dedupe (VAT/bank/KRZ flips → new packet).

PRODUCTION USE (required for real KYB)

Default is live. The schema default is sourceMode=live, so a run with the prefilled example NIPs returns (and charges) real verified supplier records. sourceMode=fixture is an optional offline test mode that only writes a non-billable RUN_STATUS / FIXTURE_HEALTH row. It is not supplier verification.

For production KYB you must:

1. Set sourceMode = live
2. Provide supplierNips (10-digit NIPs; optional NIP:KRS)
3. Optionally provide bankAccounts as NIP:NRB / NIP:IBAN pairs for official accountAssigned checks
4. Use fair-use requestPaceMs (default 400) and respect MF API daily caps (~100 requests/day × up to 30 NIPs per bulk call)

Official references:

• API Wykazu podatników VAT — wl-api.mf.gov.pl
• Plik płaski (flat file) — prefer for books above API daily caps (hash-based NIP×account offline verify; download from podatki.gov.pl)
• KRZ / PRS — public National Debtor Register (no official third-party REST API yet per Ministry FAQ)

Data limitations (read before buying)

• Not a Northdata / Bisnode / Creditreform substitute. No paid bureau scrape.
• MF API daily caps: MF documents rate limits (order of 100 queries/day, up to 30 NIPs per bulk search). Exhausted quota → MF_API_UNAVAILABLE (not charged). For large supplier books use the official plik płaski offline path (documented above; this Actor’s live mode uses the search/check API for requestId audit proof).
• KRZ: Ministry states an official API is still under analytical/legislative work. Live KRZ is best-effort against the public portal; SPA/login shells often yield KRZ_CHECK_UNAVAILABLE without blocking VAT×bank verification. Do not treat absence of OPEN as a certified CLEAR.
• Optional CRBR UBO is out of scope for this version.
• KRS number is taken from the White List subject (and optional NIP:KRS hint) — this Actor does not dump KRS financial statements.
• Fair-use pacing applies; large batches need longer maxRunSeconds or chunked runs.
• We cite the Ministry of Finance (White List) and Ministry of Justice (KRZ portal) as data origins. This Actor is not affiliated with or endorsed by them.

Fixture test input (zero product charges)

Field	Value
supplierNips	["5261040828","5252344078"]
sourceMode	fixture
emitFixtureDemoEvents	false
maxRunSeconds	55
maxEvents	500
includeKrz	true

On that path the Actor SUCCEEDS quickly, pushes exactly one RUN_STATUS / FIXTURE_HEALTH row (billable: false), and does not charge kyb-packet-delivered.

Input (summary)

Field	Notes
supplierNips	NIPs required; optional NIP:KRS
bankAccounts	Optional NIP:account pairs
sourceMode	live (default) or fixture (offline test)
emitFixtureDemoEvents	Default false
includeKrz	Default true (best-effort)
asOfDate	Optional YYYY-MM-DD (default today UTC)
maxRunSeconds / maxEvents	Budgets
resumeFromCheckpoint	Default true
requestPaceMs	Fair-use delay (default 400)

Production example

{
  "supplierNips": ["5261040828", "5252344078"],
  "bankAccounts": ["5261040828:07101010100024791339300000"],
  "sourceMode": "live",
  "maxRunSeconds": 120,
  "requestPaceMs": 400,
  "includeKrz": true,
  "resumeFromCheckpoint": true
}

Output

KYB packets (billable under PPE when verified)

Typed rows include: nip, legal_name, status_vat, bank_status, account_assigned, mf_request_id, krz_status, mismatch_events, verified, evidence, event_uid, billable: true.

RUN_STATUS (never billed)

Every successful run pushes one health row (FIXTURE_HEALTH | MONITOR_IDLE | CATCHUP_COMPLETE | HEALTH_OK).

Pricing

Pay-per-event: supplier-record at $0.003 per verified supplier record returned on a live run ($3 / 1,000; on by default, turn off Return current supplier records for alerts-only), plus kyb-packet-delivered at $0.02 per delivered unique verified KYB packet ($20 / 1,000), plus the Apify Actor start event ($0.00005 per run, per GB of memory). Health / incomplete / duplicate / fixture rows are never charged.

Local development

cd actors/poland-supplier-kyb-packet
npm install
npm test
npm run build
# Store-safe fixture health:
apify run -p
# Demo typed packets locally:
# set input emitFixtureDemoEvents=true (still sourceMode=fixture)

Attribution

VAT status and bank-account assignment originate from the Ministry of Finance VAT White List (wl-api.mf.gov.pl). KRZ signals originate from the public National Debtor Register portal (Ministry of Justice). Not an official product of those bodies.