How I built a LEI checker for KYC compliance, from scratch!

Thanasis K — Mon, 06 Apr 2026 10:07:40 +0000

When you work in fintech or deal with corporate clients, KYC (Know Your Customer) isn't optional - it's a legal requirement. One piece of that puzzle is the LEI (Legal Entity Identifier): a 20-character ISO standard code assigned to every legal entity that participates in financial transactions.

The problem? Most developers don't know what LEI is, the official lookup tools are clunky, and integrating validation into your own stack requires stitching together a few public APIs with zero hand-holding. This is the build log of how I did it.

What is an LEI?
An LEI (ISO 17442) is a 20-character alphanumeric code that uniquely identifies legal entities in global financial markets. It's mandatory for reporting to ESMA, MiFID II, EMIR, and many other regulatory frameworks.

Why I built this

I was integrating a B2B onboarding flow where corporate clients had to submit their company details. Part of the compliance check required verifying their LEI against the GLEIF (Global Legal Entity Identifier Foundation) database. The existing options were:

Manual lookup on search.gleif.org, not scalable
Pay for a third-party KYC provider, expensive for early stage
Build a thin wrapper around the free GLEIF API — this is what I did

The GLEIF API

GLEIF provides a free, public REST API at api.gleif.org/api/v1. No auth required for basic lookups. Here are the two endpoints I used:

Endpoint	Purpose
`GET /lei-records/{lei}`	Fetch full entity data for a known LEI
`GET /lei-records?filter[entity.legalName]={name}`	Search by legal name
`GET /lei-records?filter[entity.status]=ACTIVE`	Filter by registration status

Step 1 — Validate the LEI format

Before hitting the API, validate the format locally. An LEI is exactly 20 characters: 18 alphanumeric chars + 2 numeric check digits (ISO 17442 checksum).

function validateLEIFormat(lei) {
  // Must be exactly 20 alphanumeric characters
  const LEI_REGEX = /^[A-Z0-9]{18}[0-9]{2}$/;

  if (!LEI_REGEX.test(lei.toUpperCase())) {
    return { valid: false, error: 'Invalid LEI format' };
  }

  // ISO 17442 checksum (mod 97)
  const padded = lei.toUpperCase().split('')
    .map(c => c >= 'A' ? c.charCodeAt(0) - 55 : c)
    .join('');

  const checksum = BigInt(padded) % 97n;

  return {
    valid: checksum === 1n,
    error: checksum !== 1n ? 'Checksum failed' : null
  };
}

💡 Pro tip: Always validate locally first. You save API calls and give users instant feedback without a round-trip.

Step 2 — Fetch entity data from GLEIF

async function fetchLEI(lei) {
  const BASE = 'https://api.gleif.org/api/v1';

  const res = await fetch(`${BASE}/lei-records/${lei}`, {
    headers: { 'Accept': 'application/vnd.api+json' }
  });

  if (res.status === 404) throw new Error('LEI not found');
  if (!res.ok) throw new Error(`GLEIF API error: ${res.status}`);

  const { data } = await res.json();
  const attrs = data.attributes;

  return {
    lei:         data.id,
    legalName:   attrs.entity.legalName.name,
    status:      attrs.entity.status,        // ACTIVE | INACTIVE
    leiStatus:   attrs.registration.status,  // ISSUED | LAPSED | RETIRED
    country:     attrs.entity.legalAddress.country,
    nextRenewal: attrs.registration.nextRenewalDate,
    managedBy:   attrs.registration.managingLou,
  };
}

Step 3 — The KYC decision logic

Not all valid LEIs are "good" from a compliance perspective. Here's the rule set I implemented based on ESMA guidance:

function assessKYCRisk(record) {
  const issues = [];

  if (record.status !== 'ACTIVE')
    issues.push({ level: 'block', msg: 'Entity is not ACTIVE' });

  if (record.leiStatus !== 'ISSUED')
    issues.push({ level: 'block', msg: `LEI registration: ${record.leiStatus}` });

  const daysToExpiry = (new Date(record.nextRenewal) - new Date()) / 86400000;
  if (daysToExpiry < 30)
    issues.push({ level: 'warn', msg: `LEI expires in ${Math.round(daysToExpiry)} days` });

  return {
    pass:   issues.filter(i => i.level === 'block').length === 0,
    issues: issues,
  };
}

Step 4 — Putting it all together

async function checkLEI(lei) {
  // 1. Format + checksum
  const fmt = validateLEIFormat(lei);
  if (!fmt.valid) return { ok: false, error: fmt.error };

  // 2. Live GLEIF lookup
  const record = await fetchLEI(lei);

  // 3. KYC assessment
  const kyc = assessKYCRisk(record);

  return {
    ok:     kyc.pass,
    record: record,
    issues: kyc.issues,
  };
}

// Usage
const result = await checkLEI('7LTWFZYICNSX8D621K86');
console.log(result.record.legalName); // Deutsche Bank AG
console.log(result.ok);               // true

Production considerations

Before shipping this to prod, a few things worth adding:

Caching — LEI records don't change hourly. I cache results in Redis with a 24h TTL, keyed by LEI string.
Rate limits — GLEIF's free tier is generous but not unlimited. Add a simple token bucket or exponential backoff.
Audit log — In regulated environments, you need a paper trail. Store every check with a timestamp, result, and the raw API response.
Sanctions screening — LEI validation alone is not full KYC. You still need to cross-reference against OFAC, EU sanctions, and UN lists. I used the OpenSanctions API for this.

⚠️ Regulatory note: This is a technical implementation guide, not legal advice. Whether LEI validation satisfies your specific KYC obligations depends on your jurisdiction and regulator. Always consult a compliance specialist.

What I'd do differently

Move the checksum logic to a Web Worker if validating bulk files, it can block the main thread on large batches
Use GLEIF's bulk data download (they publish daily snapshots) for offline validation if API latency is a concern
Expose this as a small internal npm package so other teams in the org can reuse it without copy-pasting

Conclusion

The GLEIF API is surprisingly well-designed and free. A basic LEI checker takes about 50 lines of JS, and you can extend it with proper KYC logic, caching, and audit trails within a day. If you're building anything B2B in the EU financial space, this is a tool you're likely going to need sooner or later.

The full working code is on my GitHub. Questions or corrections? Drop them in the comments.

Next up: Screening against OFAC + EU sanctions lists with OpenSanctions API

Hey everyone! Glad to finally be here!

Thanasis K — Mon, 06 Apr 2026 09:34:21 +0000

I'm a full-stack Software Developer, focused on fintech and compliance engineering — things like KYC pipelines, sanctions screening, and the kind of plumbing that makes regulated products actually work. I've spent the last couple of years building integrations around identity verification and entity data (GLEIF, LEIs, that sort of thing).

What brought me here: I wanted a place to write down the stuff I kept having to rediscover — underdocumented APIs, edge cases in compliance flows, the gap between "this is how it works in theory" and "this is what the response actually looks like at 2am." If even one person finds it useful, that's a win.

Fun fact: the first thing I ever automated was a script to track whether my train was late more than the operator admitted. Spoiler — it was. Some things never change.

Looking forward to reading and learning from everyone here.

DEV Community: Thanasis K