Spanish NIF and NIE Validation in Python

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. Python code example

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

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

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

# DNI (Spanish citizen)
dni = iv.es.nif("12345678Z")
print(dni["valid"])    # True
print(dni["type"])     # 'DNI'
print(dni["number"])   # '12345678'
print(dni["letter"])   # 'Z'

# NIE (Foreign resident)
nie = iv.es.nif("X1234567L")
print(nie["valid"])    # True
print(nie["type"])     # 'NIE'

# Invalid control letter
bad = iv.es.nif("12345678A")
print(bad["valid"])    # False

# app.py (Flask)
import os
import requests
from flask import Flask, request, jsonify

app = Flask(__name__)

API_KEY = os.environ["ISVALID_API_KEY"]
BASE_URL = "https://api.isvalid.dev"


def validate_nif(nif: str) -> dict:
    resp = requests.get(
        f"{BASE_URL}/v0/es/nif",
        params={"value": nif},
        headers={"Authorization": f"Bearer {API_KEY}"},
    )
    resp.raise_for_status()
    return resp.json()


@app.post("/onboard")
def onboard():
    data = request.get_json()

    try:
        result = validate_nif(data["nif"])
    except requests.RequestException:
        return jsonify(error="NIF validation service unavailable"), 502

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

    # Optionally check the type matches your expectations
    if result["type"] == "NIE":
        # Foreign resident — may need additional documentation
        print("NIE detected — foreign resident onboarding")

    # Store the parsed components
    user = create_user(
        nif_type=result["type"],
        nif_number=result["number"],
        nif_letter=result["letter"],
        raw_nif=data["nif"],
    )

    return jsonify(success=True, user_id=user["id"])

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
a = iv.es.nif("00123456Y")
b = iv.es.nif("123456Y")
# a["valid"] == True, b["valid"] == True
# a["number"] == "00123456", b["number"] == "00123456"