CPF Validation in Python

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 Python implementation of the algorithm:

import re


def validate_cpf(cpf: str) -> bool:
    """Validate a Brazilian CPF number using the two-step MOD-11 checksum.

    Args:
        cpf: A CPF string (formatted or unformatted).

    Returns:
        True if both check digits are valid, False otherwise.
    """
    # Strip formatting characters
    digits = re.sub(r"\D", "", cpf)
    if len(digits) != 11:
        return False

    d = [int(c) for c in digits]

    # First check digit (D1): weights 10..2 over digits 0..8
    sum1 = sum(d[i] * (10 - i) for i in range(9))
    rem1 = sum1 % 11
    d1 = 0 if rem1 < 2 else 11 - rem1
    if d1 != d[9]:
        return False

    # Second check digit (D2): weights 11..2 over digits 0..9
    sum2 = sum(d[i] * (11 - i) for i in range(10))
    rem2 = sum2 % 11
    d2 = 0 if rem2 < 2 else 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. Python code example

Using the isvalid-sdk Python SDK or the requests library. Install with pip install isvalid-sdk or pip install requests.

# cpf_validator.py
import os
from isvalid_sdk import IsValidConfig, create_client

iv = create_client(IsValidConfig(api_key=os.environ["ISVALID_API_KEY"]))

# ── Validate a CPF number ────────────────────────────────────────────────
result = iv.br.cpf("529.982.247-25")

if not result["valid"]:
    print("Invalid CPF")
else:
    print(f"Formatted    : {result['formatted']}")     # "529.982.247-25"
    print(f"Check digits : {result['checkDigits']}")    # "25"

# app.py (Flask)
import os
from flask import Flask, request, jsonify
from isvalid_sdk import IsValidConfig, create_client

app = Flask(__name__)
iv = create_client(IsValidConfig(api_key=os.environ["ISVALID_API_KEY"]))


@app.post("/verify-cpf")
def verify_cpf():
    data = request.get_json()
    cpf = data.get("cpf")

    if not cpf:
        return jsonify(error="CPF is required"), 400

    try:
        result = iv.br.cpf(cpf)
    except Exception:
        return jsonify(error="CPF validation service unavailable"), 502

    if not result["valid"]:
        return jsonify(error="Invalid CPF number"), 400

    return jsonify(
        valid=True,
        formatted=result["formatted"],
        checkDigits=result["checkDigits"],
    )

7. cURL example

Validate a CPF number from the command line:

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
result = iv.br.cpf("111.111.111-11")
print(result["valid"])  # False

# The API catches what the math alone cannot
result2 = iv.br.cpf("000.000.000-00")
print(result2["valid"])  # False

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

# All return: {"valid": True, "formatted": "529.982.247-25", "checkDigits": "25"}

# Individual taxpayer — use the CPF endpoint
cpf_result = iv.br.cpf("529.982.247-25")

# Business taxpayer — use the CNPJ endpoint (different weights and length)
# cnpj_result = iv.br.cnpj("11.222.333/0001-81")

import os
from concurrent.futures import ThreadPoolExecutor, as_completed
from isvalid_sdk import IsValidConfig, create_client

iv = create_client(IsValidConfig(api_key=os.environ["ISVALID_API_KEY"]))

cpf_numbers = ["529.982.247-25", "111.111.111-11", "305.384.210-47"]

with ThreadPoolExecutor(max_workers=5) as pool:
    futures = {pool.submit(iv.br.cpf, c): c for c in cpf_numbers}

    for future in as_completed(futures):
        cpf = futures[future]
        result = future.result()
        status = "valid" if result["valid"] else "invalid"
        print(f"{cpf}: {status}")