CPF Validation in Node.js

1. What is a CPF?

CPF (Cadastro de Pessoas Fisicas) is the Brazilian individual taxpayer identification number. It is issued by the Receita Federal (the Brazilian Federal Revenue Service) and assigned to every Brazilian citizen and resident foreigner who needs to interact with the tax system. The CPF is an 11-digit number that serves as the primary identifier across virtually every public and private system in Brazil:

• Banking and financial services — required for opening accounts, applying for credit cards, and processing loans
• Tax filings — used as the individual taxpayer ID for annual income tax declarations
• Healthcare — identifies patients in the SUS (Sistema Unico de Saude) public health system
• E-commerce — required for purchases, invoice generation (nota fiscal), and marketplace registration
• Government services — needed for voter registration, passport applications, and social programs like Bolsa Familia
• Employment — mandatory for formal employment contracts and payroll processing

Unlike some national IDs, the CPF does not encode personal data like date of birth or gender. It is a registration number with two check digits that guard against transcription errors. However, the 9th digit does encode the fiscal region where the CPF was originally issued.

2. CPF anatomy

A CPF number is always exactly 11 digits. When formatted, it follows the pattern XXX.XXX.XXX-XX, where dots separate groups of three digits and a hyphen precedes the two check digits.

For example, the CPF 529.982.247-25 breaks down as: registration number 52998224, fiscal region 7 (Rio de Janeiro and Espirito Santo), first check digit 2, second check digit 5.

Fiscal region codes

The 9th digit indicates the fiscal region where the CPF was originally registered. This does not change if the person moves to a different state:

3. The check digit algorithm

The CPF uses two weighted MOD-11 sums to compute its check digits. The first check digit is computed from the first 9 digits, and the second check digit is computed from all 10 digits (the original 9 plus the first check digit).

First check digit (D1)

1. Take the first 9 digits of the CPF
2. Multiply each digit by descending weights: 10, 9, 8, 7, 6, 5, 4, 3, 2
3. Sum all products
4. Compute the remainder: remainder = sum mod 11
5. If remainder < 2, the check digit is 0; otherwise, the check digit is 11 − remainder

Second check digit (D2)

1. Take the first 9 digits plus the first check digit (10 digits total)
2. Multiply each digit by descending weights: 11, 10, 9, 8, 7, 6, 5, 4, 3, 2
3. Sum all products
4. Compute the remainder: remainder = sum mod 11
5. If remainder < 2, the check digit is 0; otherwise, the check digit is 11 − remainder

Step-by-step example

Let's validate 529.982.247-25 (digits: 5 2 9 9 8 2 2 4 7 2 5):

First check digit (D1) — weights 10 down to 2:

Second check digit (D2) — weights 11 down to 2, including D1:

The computed check digits are 2 and 5, which match the last two digits of 529.982.247-25. This CPF passes the checksum.

Here is a JavaScript implementation of the algorithm:

function validateCpfChecksum(cpf) {
  const d = cpf.replace(/\D/g, '').split('').map(Number);
  if (d.length !== 11) return false;

  // First check digit (D1): weights 10..2 over digits 0..8
  const sum1 = d.slice(0, 9).reduce((acc, v, i) => acc + v * (10 - i), 0);
  const rem1 = sum1 % 11;
  const d1 = rem1 < 2 ? 0 : 11 - rem1;
  if (d1 !== d[9]) return false;

  // Second check digit (D2): weights 11..2 over digits 0..9
  const sum2 = d.slice(0, 10).reduce((acc, v, i) => acc + v * (11 - i), 0);
  const rem2 = sum2 % 11;
  const d2 = rem2 < 2 ? 0 : 11 - rem2;
  return d2 === d[10];
}

4. Why manual validation isn't enough

5. The right solution: one API call

The IsValid CPF API handles the complete validation pipeline 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: CPF Validation API docs →

6. Node.js code example

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

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

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

// ── Validate a CPF number ─────────────────────────────────────────────────
const result = await iv.br.cpf('529.982.247-25');

if (!result.valid) {
  console.log('Invalid CPF');
} else {
  console.log('Formatted   :', result.formatted);    // "529.982.247-25"
  console.log('Check digits:', result.checkDigits);   // "25"
}

7. cURL example

Validate a CPF number directly from the terminal:

curl -H "Authorization: Bearer YOUR_API_KEY" \
  "https://api.isvalid.dev/v0/br/cpf?value=529.982.247-25"

A successful response includes the formatted CPF and its check digits:

{
  "valid": true,
  "formatted": "529.982.247-25",
  "checkDigits": "25"
}

8. Understanding the response

Valid CPF

{
  "valid": true,
  "formatted": "529.982.247-25",
  "checkDigits": "25"
}

Invalid CPF

{ "valid": false }

9. Edge cases

// All-same-digits — passes checksum but is NOT a valid CPF
const result = await iv.br.cpf('111.111.111-11');
console.log(result.valid); // false

// The API catches what the math alone cannot
const result2 = await iv.br.cpf('000.000.000-00');
console.log(result2.valid); // false

// All of these are equivalent — the API normalizes the input
const r1 = await iv.br.cpf('529.982.247-25');  // formatted
const r2 = await iv.br.cpf('52998224725');      // raw digits
const r3 = await iv.br.cpf('529982247-25');     // partial formatting

// All return: { valid: true, formatted: "529.982.247-25", checkDigits: "25" }

// Individual taxpayer — use the CPF endpoint
const cpfResult = await iv.br.cpf('529.982.247-25');

// Business taxpayer — use the CNPJ endpoint (different weights and length)
// const cnpjResult = await iv.br.cnpj('11.222.333/0001-81');