Poland Supplier Verification: VAT White List & Bank Check

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.

Quick start (no key): put your suppliers' NIPs (and optionally NIP:account pairs) in the input → set Source mode = live → Start. Unlike the watch Actors, the first live run already returns one verified packet per supplier; schedule it (e.g. before each payment run) to re-check. Clicking Start with the defaults runs a free health check only.

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

No baseline step: the first live run returns a packet for each verified supplier. Later runs re-check and only deliver (and charge) a new packet 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 only for unique verified KYB packets. 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)

Store default ≠ product. Schema defaults use sourceMode=fixture so Apify Store daily auto-tests leave a non-empty health dataset without calling MF or KRZ. That fixture path 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.

Apify Store daily auto-test / default input

Field	Default
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	fixture (default) or live
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: kyb-packet-delivered at $0.02 per delivered unique verified KYB packet ($20 / 1,000). Single tier (see docs/monetization.md and ADR 0010). 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.