CNPJ Validation in Python

1. What is a CNPJ?

CNPJ (Cadastro Nacional da Pessoa Jurídica) is the Brazilian National Registry of Legal Entities. It is the mandatory identification number for every company, association, foundation, or any other legal entity operating in Brazil. The CNPJ is issued and managed by the Receita Federal (Brazilian Federal Revenue Service).

A CNPJ is required for:

• Opening bank accounts and obtaining credit
• Issuing invoices (notas fiscais)
• Signing contracts and participating in public procurement
• Tax filings and social security obligations
• Registering with state and municipal authorities

2. CNPJ anatomy

A CNPJ is a 14-digit number. When formatted, it uses the pattern XX.XXX.XXX/XXXX-XX. Internally, it consists of three parts:

3. The check digit algorithm

CNPJ uses two consecutive weighted MOD-11 sums. The first pass computes check digit 1 (position 13) from digits 1–12. The second pass computes check digit 2 (position 14) from digits 1–13 (including the freshly computed check digit 1).

First check digit (position 13)

1. Multiply each of the first 12 digits by the weight sequence: [5, 4, 3, 2, 9, 8, 7, 6, 5, 4, 3, 2]
2. Sum all products
3. Calculate remainder = sum mod 11
4. If the remainder is less than 2, the check digit is 0; otherwise the check digit is 11 − remainder

Second check digit (position 14)

1. Multiply each of the first 13 digits (including check digit 1) by the weight sequence: [6, 5, 4, 3, 2, 9, 8, 7, 6, 5, 4, 3, 2]
2. Sum all products
3. Calculate remainder = sum mod 11
4. Same rule: if the remainder is less than 2, the check digit is 0; otherwise 11 − remainder

Here is a step-by-step worked example for the CNPJ 11222333000181:

Here is a Python implementation:

import re


def validate_cnpj(cnpj: str) -> bool:
    """Validate a Brazilian CNPJ using the two-pass MOD-11 algorithm."""
    # Strip formatting
    digits = re.sub(r"[^\d]", "", cnpj)
    if len(digits) != 14:
        return False

    # Reject known invalid patterns (all same digit)
    if len(set(digits)) == 1:
        return False

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

    # First check digit (position 13)
    w1 = [5, 4, 3, 2, 9, 8, 7, 6, 5, 4, 3, 2]
    sum1 = sum(d[i] * w1[i] for i in range(12))
    rem1 = sum1 % 11
    check1 = 0 if rem1 < 2 else 11 - rem1
    if check1 != d[12]:
        return False

    # Second check digit (position 14)
    w2 = [6, 5, 4, 3, 2, 9, 8, 7, 6, 5, 4, 3, 2]
    sum2 = sum(d[i] * w2[i] for i in range(13))
    rem2 = sum2 % 11
    check2 = 0 if rem2 < 2 else 11 - rem2
    return check2 == d[13]


# Example usage
print(validate_cnpj("11.222.333/0001-81"))  # True
print(validate_cnpj("11222333000181"))       # True
print(validate_cnpj("00000000000000"))       # False

4. Why manual validation isn't enough

5. The right solution: one API call

The IsValid CNPJ API handles the full validation stack 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: CNPJ Validation API docs →

6. Python code example

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

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

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

# -- Basic validation --------------------------------------------------------
result = iv.br.cnpj("11.222.333/0001-81")

if not result["valid"]:
    print("Invalid CNPJ")
else:
    print("Formatted:", result["formatted"])       # "11.222.333/0001-81"
    print("HQ?      :", result["isHeadquarters"])   # True

# -- With company lookup -----------------------------------------------------
detailed = iv.br.cnpj("11222333000181", lookup=True)

if detailed["valid"] and detailed.get("found"):
    print("Company  :", detailed["razaoSocial"])
    print("Trade    :", detailed["nomeFantasia"])
    print("Status   :", detailed["situacao"])
    print("CNAE     :", detailed["cnaeFiscal"], detailed["cnaeDescricao"])
    print("State    :", detailed["uf"])

# views.py (Django / Flask pattern)
from django.http import JsonResponse
import requests


def validate_company(request):
    cnpj = request.GET.get("cnpj", "").strip()
    if not cnpj:
        return JsonResponse({"error": "cnpj parameter required"}, status=400)

    try:
        result = validate_cnpj(cnpj, lookup=True)
    except requests.Timeout:
        return JsonResponse({"error": "validation service timeout"}, status=502)
    except requests.HTTPError as exc:
        return JsonResponse({"error": str(exc)}, status=502)

    if not result["valid"]:
        return JsonResponse({"error": "Invalid CNPJ"}, status=422)

    if result.get("found") and result.get("situacao") != "Ativa":
        return JsonResponse({
            "error": f"Company is not active (status: {result['situacao']})"
        }, status=422)

    return JsonResponse({
        "cnpj": result["formatted"],
        "company": result.get("razaoSocial"),
        "tradeName": result.get("nomeFantasia"),
        "status": result.get("situacao"),
        "state": result.get("uf"),
    })

7. cURL examples

Basic CNPJ validation:

curl -H "Authorization: Bearer YOUR_API_KEY" \
  "https://api.isvalid.dev/v0/br/cnpj?value=11.222.333/0001-81"

With company lookup via BrasilAPI:

curl -H "Authorization: Bearer YOUR_API_KEY" \
  "https://api.isvalid.dev/v0/br/cnpj?value=11222333000181&lookup=true"

8. Understanding the response

Valid CNPJ (basic)

{
  "valid": true,
  "formatted": "11.222.333/0001-81",
  "base": "11222333",
  "branch": "0001",
  "checkDigits": "81",
  "isHeadquarters": true
}

Valid CNPJ (with lookup)

{
  "valid": true,
  "formatted": "11.222.333/0001-81",
  "base": "11222333",
  "branch": "0001",
  "checkDigits": "81",
  "isHeadquarters": true,
  "found": true,
  "razaoSocial": "EMPRESA EXEMPLO LTDA",
  "nomeFantasia": "EXEMPLO",
  "situacao": "Ativa",
  "dataInicioAtividade": "2010-05-15",
  "cnaeFiscal": "6201501",
  "cnaeDescricao": "Desenvolvimento de programas de computador sob encomenda",
  "naturezaJuridica": "206-2 - Sociedade Empresaria Limitada",
  "porte": "ME",
  "capitalSocial": 50000,
  "uf": "SP",
  "municipio": "SAO PAULO",
  "cep": "01310100",
  "dataSource": "brasilapi"
}

Invalid CNPJ

{ "valid": false }

9. Edge cases to handle

result = validate_cnpj("11222333000262")

if result["valid"] and not result["isHeadquarters"]:
    print("This is a branch office (filial)")
    print("Branch number:", result["branch"])  # "0002"
    # Consider requesting the headquarters CNPJ instead

result = validate_cnpj("11222333000181", lookup=True)

if result["valid"] and result.get("found"):
    if result["situacao"] != "Ativa":
        print(f"Company is not active: {result['situacao']}")
        # "Baixada" = deregistered, "Inapta" = unfit, "Suspensa" = suspended
    else:
        print("Company is active")

import re

# Both produce the same result:
a = validate_cnpj("11.222.333/0001-81")
b = validate_cnpj("11222333000181")

# Always store the raw form
cnpj_for_db = re.sub(r"[^\d]", "", result["formatted"])

# Use the formatted version for display
print("Display:", result["formatted"])  # "11.222.333/0001-81"

result = validate_cnpj("11222333000181", lookup=True)

if result["valid"] and result.get("found"):
    porte = result.get("porte", "")
    labels = {
        "MEI": "Sole proprietor (MEI)",
        "ME": "Micro enterprise",
        "EPP": "Small enterprise",
    }
    print(labels.get(porte, f"Company size: {porte}"))