How to Validate Spanish NIF and NIE Numbers in Node.js

1. What are NIF and NIE numbers?

Spain uses the NIF (Número de Identificación Fiscal) as the umbrella term for tax identification numbers. In practice, there are two main types for individuals:

Both formats share the same control letter algorithm and are validated against the same lookup table. Any system that deals with Spanish customers, employees, or tax filings needs to handle both.

2. The structure of NIF/NIE

The two formats are closely related. Both result in a number between 0 and 99,999,999 that is divided by 23 to determine the control letter.

3. The control letter algorithm

The control letter is computed by dividing the numeric portion by 23 and looking up the remainder in a fixed table. For a DNI, the numeric portion is the 8-digit number itself. For a NIE, replace the prefix letter (X→0, Y→1, Z→2) and concatenate with the 7 digits.

For example, the DNI 12345678Z:

And the NIE X1234567L:

4. Why you need both format and checksum validation

5. The right solution

The IsValid NIF API handles format validation, control letter verification, and type detection (DNI vs NIE) in a single GET request. Pass the NIF/NIE value and get back a structured response with the validation result, document type, parsed number, and control letter.

Get your free API key at isvalid.dev. The free tier includes 100 calls per day — enough for most development and low-volume production use.

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

6. Node.js code example

Using the IsValid SDK or the native fetch API.

import { createClient } from '@isvalid-dev/sdk';
const iv = createClient({ apiKey: process.env.ISVALID_API_KEY });

// DNI (Spanish citizen)
const dni = await iv.es.nif('12345678Z');
console.log(dni.valid);   // true
console.log(dni.type);    // 'DNI'
console.log(dni.number);  // '12345678'
console.log(dni.letter);  // 'Z'

// NIE (Foreign resident)
const nie = await iv.es.nif('X1234567L');
console.log(nie.valid);   // true
console.log(nie.type);    // 'NIE'

// Invalid control letter
const bad = await iv.es.nif('12345678A');
console.log(bad.valid);   // false

// app.js (Express)
import express from 'express';
import { createClient } from '@isvalid-dev/sdk';

const app = express();
app.use(express.json());

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

app.post('/onboard', async (req, res) => {
  const { nif } = req.body;

  try {
    const result = await iv.es.nif(nif);

    if (!result.valid) {
      return res.status(400).json({ error: 'Invalid NIF/NIE number' });
    }

    // Optionally check the type matches your expectations
    if (result.type === 'NIE') {
      // Foreign resident — may need additional documentation
      console.log('NIE detected — foreign resident onboarding');
    }

    // Store the parsed components
    const user = await createUser({
      nifType: result.type,
      nifNumber: result.number,
      nifLetter: result.letter,
      rawNif: nif,
    });

    return res.json({ success: true, userId: user.id });
  } catch (err) {
    return res.status(502).json({ error: 'NIF validation service unavailable' });
  }
});

7. cURL example

Validate a Spanish DNI:

curl -H "Authorization: Bearer YOUR_API_KEY" \
  "https://api.isvalid.dev/v0/es/nif?value=12345678Z"

Validate a NIE:

curl -H "Authorization: Bearer YOUR_API_KEY" \
  "https://api.isvalid.dev/v0/es/nif?value=X1234567L"

8. Understanding the response

Valid DNI response:

{
  "valid": true,
  "type": "DNI",
  "number": "12345678",
  "letter": "Z"
}

Valid NIE response:

{
  "valid": true,
  "type": "NIE",
  "number": "X1234567",
  "letter": "L"
}

Invalid NIF:

{
  "valid": false
}

9. Edge cases

// Both inputs produce the same valid result
const a = await iv.es.nif('00123456Y');
const b = await iv.es.nif('123456Y');
// a.valid === true, b.valid === true
// a.number === '00123456', b.number === '00123456'