DEV Community

EdySpider
EdySpider

Posted on

Validating the Portuguese social security number (NISS) in JavaScript

In part 1 we looked at the NIF, the Portuguese tax number. This time it's its less famous sibling: the NISS (Número de Identificação da Segurança Social), the 11-digit social security number.

You'll run into it as soon as you build anything around employment: HR and payroll software, onboarding forms, contracts, timesheets. And just like the NIF, "it has 11 digits" is not real validation.

So here's @edyspider/validate-niss.

TL;DR

npm i @edyspider/validate-niss
Enter fullscreen mode Exit fullscreen mode
import { validateNISS, randomNISS } from '@edyspider/validate-niss';

validateNISS('12345678910'); // true
validateNISS('99999999999'); // false
randomNISS();                // e.g. '12109072813'
Enter fullscreen mode Exit fullscreen mode
  • Zero runtime dependencies
  • Works with ES modules, CommonJS and TypeScript (types included)
  • Runs in Node.js 22.12+, Bun, Deno and the browser

The rules

A NISS has two checks you can do locally.

1. The first digit says who it belongs to.

First digit Meaning
1 Individual (singular person)
2 Organisation (collective person)

Anything starting with 0 or 3–9 is rejected.

2. The last digit is a check digit. This is where the NISS differs from the NIF. Instead of the 9, 8, 7… weights and mod 11, it uses prime numbers as weights and mod 10:

  • multiply the first 10 digits by 29, 23, 19, 17, 13, 11, 7, 5, 3, 2;
  • add everything up;
  • the check digit is 9 - (sum mod 10).

Here's 12345678910 worked out:

1×29 + 2×23 + 3×19 + 4×17 + 5×13 + 6×11 + 7×7 + 8×5 + 9×3 + 1×2 = 449
449 mod 10 = 9
9 - 9 = 0  ✅ matches the last digit
Enter fullscreen mode Exit fullscreen mode

And the code:

const WEIGHTS = [29, 23, 19, 17, 13, 11, 7, 5, 3, 2];

function computeCheckDigit(base) {
  const sum = WEIGHTS.reduce(
    (total, weight, index) => total + Number(base[index]) * weight,
    0,
  );
  return 9 - (sum % 10);
}
Enter fullscreen mode Exit fullscreen mode

Same disclaimer as last time: this catches typos, not fraud. A NISS can pass the check and still not belong to anyone. Only Social Security (PT: Segurança Social) can confirm that.

Using it in a form

validateNISS() takes unknown and is strict: only an 11-digit string passes.

validateNISS(12345678910);      // false, numbers are rejected on purpose
validateNISS(' 12345678910');   // false, leading space
validateNISS('12345678910\n');  // false, trailing new line
validateNISS(null);             // false
Enter fullscreen mode Exit fullscreen mode

That strictness is deliberate: the validator tells you whether the value is a NISS, and cleaning user input stays your call. With Zod, for example:

import { z } from 'zod';
import { validateNISS } from '@edyspider/validate-niss';

const employeeSchema = z.object({
  name: z.string().min(1),
  niss: z
    .string()
    .transform((value) => value.replace(/\s/g, ''))
    .refine(validateNISS, { message: 'Invalid NISS' }),
});
Enter fullscreen mode Exit fullscreen mode

Combined with part 1, you can validate both numbers an employee form usually asks for:

import { validateNIF } from '@edyspider/validate-nif';
import { validateNISS } from '@edyspider/validate-niss';

const isValidEmployee = (e: { nif: string; niss: string }) =>
  validateNIF(e.nif) && validateNISS(e.niss);
Enter fullscreen mode Exit fullscreen mode

CommonJS and CDN work too:

const { validateNISS } = require('@edyspider/validate-niss');
Enter fullscreen mode Exit fullscreen mode
import { validateNISS } from 'https://cdn.jsdelivr.net/npm/@edyspider/validate-niss@2/+esm';
Enter fullscreen mode Exit fullscreen mode

Test data with randomNISS()

randomNISS() returns a random valid NISS starting with 1 or 2. Handy for seeding a payroll demo, writing tests, or filling a staging database without using real people's numbers:

import { randomNISS } from '@edyspider/validate-niss';

const fakeEmployee = { name: 'Test Employee', niss: randomNISS() };
Enter fullscreen mode Exit fullscreen mode

Lessons from rewriting v1

Version 2.0.0 is a rewrite, and going back to code I wrote in 2024 was humbling. The old version had a few bugs worth sharing, because they're easy to make:

  • require() was broken. In 1.0.2, main in package.json pointed to a file that didn't exist, so require('@edyspider/validate-niss') threw MODULE_NOT_FOUND. If your tests import from src/ instead of the package name, you'll never notice. The v2 tests now import @edyspider/validate-niss itself, through both import and require().
  • The validator leaked global variables. factor, calc and i were assigned without let or const, so calling validateNISS() quietly created globals. Native ES modules run in strict mode, so that mistake now throws instead of hiding.
  • It was too permissive. v1 accepted NISS numbers starting with 3 to 9. v2 only accepts 1 and 2. That's the one breaking change to watch for if you upgrade.
  • randomNISS() existed but was never published. It's on npm for the first time in v2.

The rest matches the NIF package: native ESM with a CommonJS entry point, TypeScript types for both, no runtime dependencies, tests on the built-in Node.js test runner, and releases published from GitHub Actions with npm provenance. The full list is in the changelog.

Try it online

To check or generate a NISS without writing code: edyspider.com/tools/niss.

Next up

The last part of the series is the biggest package: NIB and IBAN validation, plus finding a bank's name and SWIFT/BIC straight from the account number, with @edyspider/validate-bank-account-pt.


Spotted an edge case? Open an issue or drop it in the comments. A ⭐ on GitHub is always appreciated.

Top comments (0)