KRS Validation in Node.js

1. What is a KRS number?

KRS (Krajowy Rejestr Sadowy — National Court Register) is a centralised public registry maintained by the Ministry of Justice of Poland. Every company, association, foundation, and certain other legal entities registered in Poland receives a unique KRS number. It serves as the primary identifier in:

• B2B contracts and invoicing between Polish companies
• Public procurement and tender processes
• Due diligence and KYC/AML checks
• Cross-referencing with NIP (tax) and REGON (statistical) registries
• Court filings and legal proceedings

The KRS database is split into two main registries:

2. KRS structure

A KRS number is a simple 10-digit zero-padded sequential number. Unlike NIP or REGON, KRS does not contain a check digit — there is no built-in checksum algorithm to verify structural correctness.

3. Why KRS validation matters

4. The right solution: one API call

The IsValid KRS API handles format validation and government registry lookup in a single GET request:

Get your free API key at isvalid.dev. The free tier includes 100 calls per day with no credit card required.

Full parameter reference and response schema: KRS Validation API docs →

5. Node.js code example

Using the @isvalid-dev/sdk package or the built-in fetch API (Node.js 18+):

// krs-validator.mjs
import { createClient } from '@isvalid-dev/sdk';

const iv = createClient({ apiKey: process.env.ISVALID_API_KEY });

// ── Basic validation ────────────────────────────────────────────────────────
const result = await iv.pl.krs('0000896246');

if (!result.valid) {
  console.log('Invalid KRS number');
} else {
  console.log('KRS:', result.number); // "0000896246"
}

// ── With government registry lookup ─────────────────────────────────────────
const detailed = await iv.pl.krs('0000896246', { lookup: true });

if (detailed.valid && detailed.krs?.found) {
  console.log('Name     :', detailed.krs.name);
  console.log('Registry :', detailed.krs.registry);   // "P" or "S"
  console.log('NIP      :', detailed.krs.nip);
  console.log('REGON    :', detailed.krs.regon);
  console.log('City     :', detailed.krs.address.city);
  console.log('OPP      :', detailed.krs.hasOppStatus);
}

6. cURL examples

Basic format validation:

curl -H "Authorization: Bearer YOUR_API_KEY" \
  "https://api.isvalid.dev/v0/pl/krs?value=0000896246"

With government registry lookup:

curl -H "Authorization: Bearer YOUR_API_KEY" \
  "https://api.isvalid.dev/v0/pl/krs?value=0000896246&lookup=true"

7. Understanding the response

Valid KRS (basic)

{
  "valid": true,
  "number": "0000896246"
}

Valid KRS (with lookup)

{
  "valid": true,
  "number": "0000896246",
  "krs": {
    "checked": true,
    "found": true,
    "krs": "0000896246",
    "registry": "P",
    "name": "CREACT.DEV SPÓŁKA Z OGRANICZONĄ ODPOWIEDZIALNOŚCIĄ",
    "legalForm": "SPÓŁKA Z OGRANICZONĄ ODPOWIEDZIALNOŚCIĄ",
    "nip": "5252859428",
    "regon": "388770013",
    "hasOppStatus": false,
    "registeredAt": "2021-04-21",
    "dataAsOf": "2026-01-15",
    "lastEntryAt": "2026-01-14",
    "address": {
      "city": "WARSZAWA",
      "voivodeship": "MAZOWIECKIE",
      "street": "UL. ŚWIĘTOKRZYSKA",
      "houseNumber": "30",
      "flatNumber": "63",
      "postalCode": "00-116",
      "country": "POLSKA",
      "website": "HTTPS://CREACT.DEV/"
    }
  }
}

Invalid KRS

{ "valid": false }

8. Edge cases to handle

// WRONG — loses leading zeros
const krs = Number('0000028860'); // 28860

// CORRECT — preserve as string
const krs = '0000028860';

const result = await iv.pl.krs('0000896246', { lookup: true });

if (result.valid && result.krs?.found) {
  if (result.krs.registry === 'P') {
    console.log('Commercial entity — standard B2B flow');
  } else if (result.krs.registry === 'S') {
    console.log('Association/foundation — verify OPP status');
  }
}

const result = await iv.pl.krs('0000896246', { lookup: true });

if (result.valid && result.krs?.found && result.krs.hasOppStatus) {
  console.log('This entity can receive 1.5% tax donations');
}

const result = await iv.pl.krs('0000896246', { lookup: true });

if (result.valid && result.krs) {
  if (!result.krs.found) {
    console.log('KRS number not found — entity may be dissolved');
  } else {
    console.log('Last entry:', result.krs.lastEntryAt);
    console.log('Data as of:', result.krs.dataAsOf);
  }
}

const result = await iv.pl.krs('0000896246', { lookup: true });

if (result.valid && result.krs?.found) {
  const expectedNip = '5252859428';
  const expectedRegon = '388770013';

  if (result.krs.nip !== expectedNip) {
    console.error('NIP mismatch!');
  }
  if (result.krs.regon !== expectedRegon) {
    console.error('REGON mismatch!');
  }
}