DEV Community: isvalid.dev

KYC Onboarding Validation Checklist — IBAN, LEI & VAT in One Flow (Python)

isvalid.dev — Sun, 22 Mar 2026 09:51:22 +0000

Three identifiers, three API calls, one onboarding flow. Here's how to validate a counterparty's IBAN, LEI, and VAT number before opening an account — and why skipping any of them is a compliance risk.

What is KYC and why validation matters
The three identifiers
Step 1: Validate the IBAN
Step 2: Validate the LEI
Step 3: Validate the VAT number
Putting it all together — parallel validation
cURL examples
Handling failures gracefully
Summary checklist

1. What is KYC and why validation matters

KYC (Know Your Customer) is the process of verifying the identity of a counterparty before entering a business relationship. Regulations like AML4/AML5 (EU Anti-Money Laundering Directives), the Bank Secrecy Act (US), and MiFID II require financial institutions to verify key identifiers at onboarding — not as a formality, but as a legal obligation with real consequences for non-compliance.

Three identifiers form the backbone of entity KYC in Europe:

IBAN — confirms the bank account is structurally valid and identifies the bank
LEI — confirms the legal entity is registered and active in the GLEIF database
VAT — confirms the tax registration is valid via the EU VIES system

Failing to validate these at onboarding leads to: rejected payments, regulatory fines, delayed settlements, and exposure to fraud. A single invalid identifier can block a wire transfer, trigger a compliance review, or — in the worst case — result in facilitating transactions with a sanctioned entity.

ℹ️ KYC is not a one-time check. Identifiers can change — IBANs get closed, LEIs lapse, VAT registrations get revoked. Periodic re-validation is part of ongoing due diligence.

2. The three identifiers

Each identifier serves a different purpose in the KYC chain. Together, they verify the counterparty's bank account, legal existence, and tax status:

Identifier	Standard	What it proves	API endpoint
IBAN	ISO 13616	The bank account is structurally valid and the bank exists	`GET /v0/iban`
LEI	ISO 17442	The legal entity is registered with GLEIF and its status is current	`GET /v0/lei`
VAT	EU VIES	The tax registration is active in the EU VIES database	`GET /v0/vat`

⚠️ Not every counterparty has all three. Non-EU entities won't have an EU VAT number. Non-financial entities may not have a LEI. Design your flow to require only the identifiers relevant to your use case.

3. Step 1: Validate the IBAN

The IBAN endpoint performs a multi-layer validation:

MOD-97 checksum — the ISO 13616 algorithm that catches transcription errors
Country code + BBAN extraction — validates the country-specific length and format
Bank identification — looks up the bank code in the iban_bank_codes table to return bankCode, bankName, and bankBic
EU/SEPA membership flag — tells you whether the account is in a SEPA country

Example response

{
  "valid": true,
  "countryCode": "DE",
  "countryName": "Germany",
  "bban": "210501700012345678",
  "isEU": true,
  "isSEPA": true,
  "bankCode": "21050170",
  "bankName": "Hamburger Sparkasse",
  "bankBic": "HASPDEHHXXX"
}

What to check in your code

valid === true — the IBAN passes format, length, and mod-97 checksum
bankName exists — the bank code was identified in the national registry
countryCode matches expectations — the counterparty claims to be in Germany, and the IBAN confirms it

4. Step 2: Validate the LEI

The LEI endpoint performs a deep verification chain:

ISO 17442 MOD-97 checksum — identical algorithm to IBAN, applied to the 20-character code
Entity lookup in GLEIF database — 2.3 million records synced from the GLEIF Golden Copy, with live API fallback
Registration status and entity status — distinguishes between ACTIVE/INACTIVE entities and ISSUED/LAPSED registrations

Example response

{
  "valid": true,
  "lei": "7LTWFZYICNSX8D621K86",
  "louCode": "7LTW",
  "checkDigits": "86",
  "found": true,
  "dataSource": "gleif-db",
  "entity": {
    "legalName": "DEUTSCHE BANK AKTIENGESELLSCHAFT",
    "country": "DE",
    "entityStatus": "ACTIVE",
    "registrationStatus": "ISSUED",
    "category": null,
    "initialRegistrationDate": "2012-06-06",
    "lastUpdate": "2024-03-15",
    "nextRenewal": "2025-03-15",
    "managingLou": "EVK05KS7XY1DEII3R011"
  },
  "lou": null
}

What to check in your code

valid === true — the LEI passes format and MOD-97 checksum
found === true — the entity exists in the GLEIF database
entity.entityStatus === "ACTIVE" — the entity is currently active
entity.registrationStatus === "ISSUED" — the LEI is current, not LAPSED

⚠️ A LAPSED LEI means the entity failed to renew. Regulators may reject transactions with lapsed LEIs. Always check registrationStatus.

5. Step 3: Validate the VAT number

The VAT endpoint combines two layers of validation:

Country-specific checksum validation — each EU country has its own format and check digit algorithm (Germany uses MOD-11, Poland uses weighted sum, etc.)
VIES lookup — queries the EU VAT Information Exchange System to confirm the number is actively registered

Example response

{
  "valid": true,
  "countryCode": "DE",
  "vatNumber": "123456789",
  "normalized": "DE123456789",
  "vies": {
    "checked": true,
    "valid": true,
    "name": "DEUTSCHE BANK AG",
    "address": "TAUNUSANLAGE 12, 60325 FRANKFURT AM MAIN"
  }
}

What to check in your code

valid === true — the VAT number passes format and checksum validation
vies.checked === true — VIES was reachable and the query succeeded
vies.valid === true — the number is confirmed active in the EU VIES registry

6. Putting it all together — parallel validation

The following Python example validates all three identifiers in parallel using asyncio.gather (SDK) or ThreadPoolExecutor (requests). Install with pip install isvalid-sdk or pip install requests.

Using the SDK

import asyncio
import os
from isvalid_sdk import IsValidConfig, create_client

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


async def kyc_check(iban: str, lei: str, vat: str) -> dict:
    iban_result, lei_result, vat_result = await asyncio.gather(
        iv.iban(iban),
        iv.lei(lei),
        iv.vat(vat, check_vies=True),
    )

    return {
        "iban": {
            "valid": iban_result["valid"],
            "bank": iban_result.get("bankName"),
            "country": iban_result.get("countryCode"),
        },
        "lei": {
            "valid": lei_result["valid"],
            "found": lei_result.get("found"),
            "name": (lei_result.get("entity") or {}).get("legalName"),
            "status": (lei_result.get("entity") or {}).get("registrationStatus"),
        },
        "vat": {
            "valid": vat_result["valid"],
            "confirmed": (vat_result.get("vies") or {}).get("valid"),
            "name": (vat_result.get("vies") or {}).get("name"),
        },
    }


# ── Example usage ────────────────────────────────────────────────────────────
result = asyncio.run(kyc_check(
    iban="DE89370400440532013000",
    lei="7LTWFZYICNSX8D621K86",
    vat="DE123456789",
))

print("IBAN:", f"✓ {result['iban']['bank']}" if result["iban"]["valid"] else "✗ invalid")
print("LEI :", f"✓ {result['lei']['name']}" if result["lei"]["found"] else "✗ not found")
print("VAT :", f"✓ {result['vat']['name']}" if result["vat"]["confirmed"] else "✗ not confirmed")

approved = (
    result["iban"]["valid"]
    and result["lei"]["found"]
    and result["lei"]["status"] == "ISSUED"
    and result["vat"]["confirmed"]
)
print("KYC :", "APPROVED" if approved else "REJECTED")

Using requests

# kyc_validator.py
import os
from concurrent.futures import ThreadPoolExecutor
import requests

API_KEY = os.environ["ISVALID_API_KEY"]
BASE_URL = "https://api.isvalid.dev"
HEADERS = {"Authorization": f"Bearer {API_KEY}"}


def call_api(path: str, params: dict) -> dict:
    response = requests.get(f"{BASE_URL}{path}", params=params, headers=HEADERS)
    response.raise_for_status()
    return response.json()


def kyc_check(iban: str, lei: str, vat: str) -> dict:
    with ThreadPoolExecutor(max_workers=3) as pool:
        iban_future = pool.submit(call_api, "/v0/iban", {"value": iban})
        lei_future = pool.submit(call_api, "/v0/lei", {"value": lei})
        vat_future = pool.submit(call_api, "/v0/vat", {"value": vat})

    iban_result = iban_future.result()
    lei_result = lei_future.result()
    vat_result = vat_future.result()

    return {
        "iban": {
            "valid": iban_result["valid"],
            "bank": iban_result.get("bankName"),
            "country": iban_result.get("countryCode"),
        },
        "lei": {
            "valid": lei_result["valid"],
            "found": lei_result.get("found"),
            "name": (lei_result.get("entity") or {}).get("legalName"),
            "status": (lei_result.get("entity") or {}).get("registrationStatus"),
        },
        "vat": {
            "valid": vat_result["valid"],
            "confirmed": (vat_result.get("vies") or {}).get("valid"),
            "name": (vat_result.get("vies") or {}).get("name"),
        },
    }


# ── Example usage ────────────────────────────────────────────────────────────
result = kyc_check(
    iban="DE89370400440532013000",
    lei="7LTWFZYICNSX8D621K86",
    vat="DE123456789",
)

print("IBAN:", f"✓ {result['iban']['bank']}" if result["iban"]["valid"] else "✗ invalid")
print("LEI :", f"✓ {result['lei']['name']}" if result["lei"]["found"] else "✗ not found")
print("VAT :", f"✓ {result['vat']['name']}" if result["vat"]["confirmed"] else "✗ not confirmed")

# All three must pass for KYC approval
approved = (
    result["iban"]["valid"]
    and result["lei"]["found"]
    and result["lei"]["status"] == "ISSUED"
    and result["vat"]["confirmed"]
)
print("KYC :", "APPROVED" if approved else "REJECTED")

✅ All three API calls run in parallel via asyncio.gather (SDK) or ThreadPoolExecutor (requests). The total latency is the slowest single call, not the sum of all three.

7. cURL examples

Validate an IBAN (German account):

curl -H "Authorization: Bearer YOUR_API_KEY" \
  "https://api.isvalid.dev/v0/iban?value=DE89370400440532013000"

Validate a LEI (Deutsche Bank):

curl -H "Authorization: Bearer YOUR_API_KEY" \
  "https://api.isvalid.dev/v0/lei?value=7LTWFZYICNSX8D621K86"

Validate a VAT number with VIES check:

curl -H "Authorization: Bearer YOUR_API_KEY" \
  "https://api.isvalid.dev/v0/vat?value=DE123456789&checkVies=true"

8. Handling failures gracefully

Real-world KYC flows encounter partial failures, stale data, and edge cases. Here are the most common scenarios and how to handle them:

VIES unavailable

The EU VIES service has regular downtimes — each of the 27 member states runs its own node. When vies.checked is false, the VAT number passed local checksum validation but VIES confirmation is unavailable. Decide whether to accept provisionally and re-check later, or block the onboarding until VIES responds.

if vat_result["valid"] and vat_result.get("vies") and not vat_result["vies"]["checked"]:
    # VIES is down — format is valid, but registration unconfirmed
    # Option A: accept provisionally, schedule re-check
    schedule_recheck(vat_result["normalized"], delay="24h")
    return {"status": "provisional", "reason": "vies_unavailable"}

LEI found but LAPSED

An entity whose LEI registration has lapsed still exists in GLEIF but is not current. For regulated transactions (EMIR, MiFID II), only "ISSUED" status is acceptable. A "LAPSED" LEI is a compliance red flag — the entity has not renewed, and regulators may reject reports that reference it.

entity = lei_result.get("entity") or {}
if lei_result.get("found") and entity.get("registrationStatus") != "ISSUED":
    # LEI exists but is not current — reject for regulated transactions
    return {
        "status": "rejected",
        "reason": f"LEI registration is {entity['registrationStatus']}",
    }

IBAN valid but bank unknown

The mod-97 checksum passed but the bank code is not in the database. This happens with small banks, new entrants, or countries where the national registry is incomplete. The IBAN is still structurally valid — the bank just is not identified by name. This is not a rejection reason, but it reduces the information available for due diligence.

if iban_result["valid"] and not iban_result.get("bankName"):
    # IBAN is structurally valid, but bank is not identified
    # Log for manual review — do not reject
    logger.warning(f"IBAN valid but bank unknown: {iban_result['countryCode']}")

Partial KYC — not all identifiers available

Not every entity has all three identifiers. Design a tiered approach: IBAN is always required for payment-related onboarding, LEI is required for regulated entities under MiFID II or EMIR, and VAT is required for EU B2B entities. Use a flexible config pattern to adapt requirements per counterparty type.

REQUIREMENTS = {
    "regulated_eu":       {"iban": True, "lei": True, "vat": True},
    "regulated_non_eu":   {"iban": True, "lei": True, "vat": False},
    "unregulated_eu":     {"iban": True, "lei": False, "vat": True},
    "unregulated_non_eu": {"iban": True, "lei": False, "vat": False},
}


def get_requirements(counterparty_type: str) -> dict:
    return REQUIREMENTS.get(counterparty_type, REQUIREMENTS["unregulated_non_eu"])


# Only validate required identifiers
reqs = get_requirements("regulated_eu")
calls = []
if reqs["iban"]:
    calls.append(pool.submit(call_api, "/v0/iban", {"value": iban}))
if reqs["lei"]:
    calls.append(pool.submit(call_api, "/v0/lei", {"value": lei}))
if reqs["vat"]:
    calls.append(pool.submit(call_api, "/v0/vat", {"value": vat}))

results = [f.result() for f in calls]

9. Summary checklist

❌ Do not skip LEI registration status — a LAPSED LEI is a compliance red flag
❌ Do not treat VIES downtime as a VAT rejection — re-check later
❌ Do not assume all counterparties have all three identifiers — tier your requirements
✅ Run all validations in parallel — reduces onboarding latency
✅ Check registrationStatus for LEI and vies.valid for VAT — not just the checksum
✅ Log and store validation results — auditors need the paper trail

Built with IsValid API — free tier includes 100 API calls per day, no credit card required.

LEI Validation in JavaScript — GLEIF Lookup Without Rate Limits

isvalid.dev — Thu, 05 Mar 2026 11:40:55 +0000

If you work in finance, compliance, or regulatory reporting, you've seen LEIs everywhere. Every MiFID II transaction report, every EMIR derivative trade, every SEC filing — they all require a valid Legal Entity Identifier.

Yet most developers treat LEI validation as a simple format check. It's not. A syntactically valid LEI can belong to an entity that merged, dissolved, or had its registration lapsed years ago. If you're not checking against the GLEIF database, you're not really validating.

This guide covers the full stack: format validation, mod-97 checksum, and live entity lookup — with code you can use today.

What Is an LEI?

An LEI (ISO 17442) is a 20-character alphanumeric code that uniquely identifies legal entities participating in financial transactions. It was introduced after the 2008 crisis because regulators couldn't trace exposure across institutions — nobody had a universal ID for companies.

7 L T W F Z Y I C N S X 8 D 6 2 1 K 8 6
├─────┤ ├─┤ ├─────────────────────┤ ├─┤
LOU     Reserved    Entity          Check
prefix  (2 chars)   identifier      digits
(4 chars)           (12 chars)      (2 chars)

The first 4 characters identify the Local Operating Unit (LOU) that issued the LEI. Characters 5–6 are reserved (always digits). Characters 7–18 are the entity-specific part. Characters 19–20 are check digits computed using the same mod-97 algorithm as IBANs.

Step 1: Format Validation

An LEI must be exactly 20 alphanumeric characters:

function isValidLEIFormat(lei) {
  return /^[A-Z0-9]{20}$/.test(lei.toUpperCase().trim());
}

This catches typos and garbage input, but tells you nothing about whether the LEI actually exists.

Step 2: Mod-97 Checksum

The check digit algorithm is identical to IBAN's ISO 7064 mod-97:

Move the last two digits (check digits) to the front
Convert all letters to numbers (A=10, B=11, ..., Z=35)
Compute the remainder when divided by 97
If the remainder is 1, the checksum is valid

function verifyLEIChecksum(lei) {
  const upper = lei.toUpperCase().trim();
  if (!/^[A-Z0-9]{20}$/.test(upper)) return false;

  // Move check digits (last 2) to front
  const rearranged = upper.slice(2) + upper.slice(0, 2);

  // Convert letters to numbers
  let numericString = '';
  for (const char of rearranged) {
    const code = char.charCodeAt(0);
    if (code >= 65 && code <= 90) {
      numericString += (code - 55).toString();
    } else {
      numericString += char;
    }
  }

  // Mod-97 using chunk method (avoids BigInt)
  let remainder = 0;
  for (let i = 0; i < numericString.length; i += 7) {
    const chunk = remainder + numericString.slice(i, i + 7);
    remainder = parseInt(chunk, 10) % 97;
  }

  return remainder === 1;
}

// Test with Deutsche Bank's LEI
verifyLEIChecksum('7LTWFZYICNSX8D621K86'); // true
verifyLEIChecksum('7LTWFZYICNSX8D621K87'); // false — one digit off

This is the same chunk-based approach used for IBAN validation. parseInt can't handle the full numeric string (it exceeds 2^53), so we process it in chunks of 7 digits, carrying the remainder forward.

Step 3: The Hard Part — Entity Lookup

Here's where it gets interesting. A valid checksum doesn't mean the entity exists or is active. The Global LEI Foundation (GLEIF) maintains the authoritative database of all ~2.3 million LEIs worldwide.

Option A: GLEIF API Directly

GLEIF provides a free public API:

async function lookupGLEIF(lei) {
  const res = await fetch(
    `https://api.gleif.org/api/v1/lei-records/${lei}`
  );

  if (res.status === 404) return null;
  const data = await res.json();

  return {
    legalName: data.data.attributes.entity.legalName.name,
    country: data.data.attributes.entity.legalAddress.country,
    status: data.data.attributes.entity.status,
    registrationStatus: data.data.attributes.registration.status,
  };
}

This works, but has practical limitations:

Rate limits — the public API is rate-limited, which is a problem if you're validating batches
Latency — each request is a round-trip to GLEIF's servers
No search by name — you need the LEI upfront; you can't search "Deutsche Bank" and get back LEIs
Response structure — deeply nested JSON that requires careful extraction

Option B: Use a Local GLEIF Database

IsValid maintains a local copy of the GLEIF Golden Copy database (~2.3 million entities), updated regularly. No rate limits, no external API calls from your perspective, and full-text name search built in.

// Validate + enrich in one call
const res = await fetch(
  'https://isvalid.dev/v0/lei?value=7LTWFZYICNSX8D621K86',
  { headers: { 'Authorization': 'Bearer YOUR_API_KEY' } }
);
const data = await res.json();

{
  "valid": true,
  "lei": "7LTWFZYICNSX8D621K86",
  "found": true,
  "dataSource": "gleif-db",
  "entity.legalName": "Deutsche Bank AG",
  "entity.country": "DE",
  "entity.entityStatus": "ACTIVE",
  "entity.registrationStatus": "ISSUED",
  "lou.name": "SWIFT"
}

One request: format validation, mod-97 checksum, entity lookup, registration status, and LOU info.

With the SDK

npm install @isvalid-dev/sdk

import { IsValid } from '@isvalid-dev/sdk';

const client = new IsValid({ apiKey: 'YOUR_API_KEY' });

const result = await client.lei('7LTWFZYICNSX8D621K86');
console.log(result.entity.legalName);         // "Deutsche Bank AG"
console.log(result.entity.entityStatus);       // "ACTIVE"
console.log(result.entity.registrationStatus); // "ISSUED"

Search by Name

Don't have the LEI? Search by entity name using trigram similarity:

const res = await fetch(
  'https://isvalid.dev/v0/lei?search=deutsche%20bank',
  { headers: { 'Authorization': 'Bearer YOUR_API_KEY' } }
);

This returns matching entities ranked by similarity — useful for onboarding flows where users type a company name and you need to resolve it to an LEI.

Why Checksum-Only Validation Isn't Enough

Consider these real scenarios:

Merged entities — After an acquisition, the acquired company's LEI may still pass checksum validation but its status changes to MERGED. Using it in a regulatory filing would be incorrect.

Lapsed registrations — LEIs must be renewed annually. A lapsed LEI (registrationStatus: LAPSED) might indicate an entity that hasn't updated its reference data — a compliance red flag.

Duplicate detection — Some entities have multiple LEIs (they shouldn't, but it happens). Checking against the GLEIF database lets you flag this.

KYC/AML workflows — When onboarding a counterparty, validating the LEI format is step 1. Confirming the entity is active and the registration is current is step 2. Both are required for MiFID II, EMIR, and Dodd-Frank compliance.

Production Patterns

Validation Middleware (Express)

import { IsValid } from '@isvalid-dev/sdk';

const isvalid = new IsValid({ apiKey: process.env.ISVALID_API_KEY });

async function validateLEI(req, res, next) {
  const { lei } = req.body;

  if (!lei) {
    return res.status(400).json({ error: 'LEI is required' });
  }

  const result = await isvalid.lei(lei);

  if (!result.valid) {
    return res.status(400).json({
      error: 'Invalid LEI format or checksum',
    });
  }

  if (!result.found) {
    return res.status(400).json({
      error: 'LEI not found in GLEIF database',
    });
  }

  if (result.entity.registrationStatus !== 'ISSUED') {
    return res.status(400).json({
      error: `LEI registration status: ${result.entity.registrationStatus}`,
    });
  }

  req.leiData = result;
  next();
}

Batch Validation

Processing a CSV of counterparties? Validate all LEIs in parallel:

async function validateBatch(leis) {
  const results = await Promise.all(
    leis.map(async (lei) => {
      const result = await isvalid.lei(lei);
      return {
        lei,
        valid: result.valid,
        found: result.found,
        name: result.entity?.legalName ?? null,
        status: result.entity?.registrationStatus ?? null,
      };
    })
  );

  const invalid = results.filter(
    (r) => !r.valid || !r.found || r.status !== 'ISSUED'
  );

  return { total: results.length, invalid: invalid.length, issues: invalid };
}

Caching Strategy

LEI entity data doesn't change frequently. Cache lookups for 24 hours to reduce API calls:

const cache = new Map();
const TTL = 24 * 60 * 60 * 1000; // 24 hours

async function cachedLEILookup(lei) {
  const cached = cache.get(lei);
  if (cached && Date.now() - cached.timestamp < TTL) {
    return cached.data;
  }

  const result = await isvalid.lei(lei);
  cache.set(lei, { data: result, timestamp: Date.now() });
  return result;
}

Comparison: DIY vs. API

	DIY (regex + mod-97)	GLEIF API	IsValid
Format check	✅	✅	✅
Mod-97 checksum	✅	✅	✅
Entity lookup	❌	✅	✅
Registration status	❌	✅	✅
Name search	❌	Limited	✅ (trigram)
Rate limits	N/A	Yes	No*
Latency	<1ms	200-500ms	<50ms

* Within your plan's quota.

Wrapping Up

LEI validation has three layers: format, checksum, and entity verification. Most implementations stop at the first two, which is fine for catching typos but insufficient for compliance workflows.

If you're building anything that touches regulatory reporting — MiFID II, EMIR, SFTR, Dodd-Frank — you need all three. The mod-97 code above handles format and checksum. For entity verification and name search across 2.3 million records, IsValid gives you that in a single API call.

50+ validators. IBAN, ISIN, LEI, VAT, BIC, email, phone, and more.
Try it free → isvalid.dev

DEV Community: isvalid.dev

KYC Onboarding Validation Checklist — IBAN, LEI & VAT in One Flow (Python)

Table of contents

1. What is KYC and why validation matters

2. The three identifiers

3. Step 1: Validate the IBAN

Example response

What to check in your code

4. Step 2: Validate the LEI

Example response

What to check in your code

5. Step 3: Validate the VAT number

Example response

What to check in your code

6. Putting it all together — parallel validation

Using the SDK

Using requests

7. cURL examples

8. Handling failures gracefully

VIES unavailable

LEI found but LAPSED

IBAN valid but bank unknown

Partial KYC — not all identifiers available

9. Summary checklist

LEI Validation in JavaScript — GLEIF Lookup Without Rate Limits

What Is an LEI?

Step 1: Format Validation

Step 2: Mod-97 Checksum

Step 3: The Hard Part — Entity Lookup

Option A: GLEIF API Directly

Option B: Use a Local GLEIF Database

With the SDK

Search by Name

Why Checksum-Only Validation Isn't Enough

Production Patterns

Validation Middleware (Express)

Batch Validation

Caching Strategy

Comparison: DIY vs. API

Wrapping Up