Validate Spanish NIF and CIF via API in Seconds: AEAT Registry Verification

#An invoice with an incorrect NIF is an invoice with problems

It seems like a minor detail: a 9-character field in a form. But an incorrect NIF on a Spanish invoice can mean:

• Fiscally invalid invoice — not deductible for your client
• VeriFactu rejection — AEAT registration fails
• Mandatory corrective invoice — extra work to fix it
• Penalties — in cases of repeated negligence

Most applications validate the NIF format (regex + check letter). That confirms B12345678 has the correct structure. It doesn’t confirm it exists in the AEAT or corresponds to an active entity.

The BeeL. API includes NIF validation against the Tax Agency registry. One call, response in milliseconds.

#NIF, CIF, NIE: what’s what

Before validating, let’s clarify the terminology:

Since 2008, CIF was integrated into the NIF system. All are “NIF” for tax purposes, but the structure varies. The BeeL. API validates all three formats.

#Validation with the SDK (3 lines)

import { BeeL } from '@beel_es/sdk';
 
const beel = new BeeL({ apiKey: process.env.BEEL_API_KEY! });
 
const result = await beel.nif.validate('B12345678');
 
console.log(result.valid); // true
console.log(result.name);  // "EMPRESA EJEMPLO SL"

That’s it. The API checks the AEAT registry and returns whether the NIF is registered and the associated fiscal name.

#Validation with fetch (no SDK)

If you don’t use Node.js or prefer not to install the SDK:

const response = await fetch('https://app.beel.es/api/v1/nif/validate', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer beel_sk_live_your_api_key',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({ nif: 'B12345678' }),
});
 
const { data } = await response.json();
console.log(data.valid, data.name);

#With curl

curl -X POST https://app.beel.es/api/v1/nif/validate \
  -H "Authorization: Bearer beel_sk_live_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{"nif": "B12345678"}'

#Why local validation isn’t enough

A NIF has a check letter calculated from the digits. It’s trivial to verify the letter is correct:

// This only validates the FORMAT, not the existence
function isValidNifFormat(nif: string): boolean {
  const letters = 'TRWAGMYFPDXBNJZSQVHLCKE';
  const number = parseInt(nif.slice(0, -1), 10);
  return nif.charAt(nif.length - 1) === letters[number % 23];
}
 
isValidNifFormat('00000000T'); // true — correct format
// But does it exist in the AEAT? Is it an active entity? You don't know.

Local validation catches obvious errors (typos, wrong length). But to confirm a NIF is real and active, you need to check with the AEAT.

#Integration in a customer registration form

The most common pattern: validate the NIF when the user enters it in the form.

// Backend: your API endpoint that validates before saving
app.post('/api/customers', async (req, res) => {
  const { nif, name, email, address } = req.body;
 
  // 1. Validate NIF against the AEAT
  const nifResult = await beel.nif.validate(nif);
 
  if (!nifResult.valid) {
    return res.status(422).json({
      error: 'NIF_INVALID',
      message: 'NIF is not registered with the AEAT',
    });
  }
 
  // 2. Optional: compare fiscal name
  if (nifResult.name && nifResult.name !== name.toUpperCase()) {
    // Warn but don't block — could be a trade name
    console.warn(`Fiscal name differs: ${nifResult.name} vs ${name}`);
  }
 
  // 3. Create customer in BeeL. + your database
  const customer = await beel.customers.create({
    legal_name: nifResult.name || name,
    nif,
    email,
    address,
  });
 
  // 4. Save in your DB with BeeL. reference
  await db.customers.insert({
    ...req.body,
    beel_id: customer.id,
    nif_verified: true,
  });
 
  res.json({ customer });
});

#Use cases

#B2B e-commerce checkout

In a B2B e-commerce, the customer enters their NIF during checkout. Validate it in real time to prevent completing the purchase with incorrect data — and needing a corrective invoice later.

#Supplier onboarding

If you manage a supplier network, validate their NIFs when registering them. An invalid NIF means received invoices that aren’t deductible.

#Data migration

When migrating customers from a legacy system, run all NIFs through the API to identify which ones are outdated or incorrect before importing.

#Fraud prevention

A valid NIF that returns a different fiscal name than the one provided may indicate impersonation. Useful as a signal in fraud detection systems.

#Frequently asked questions

#What’s the difference between format validation and AEAT validation?

Format validation (regex + check letter) confirms the NIF has the correct structure. AEAT validation confirms it’s registered as an active taxpayer. They’re complementary: the first is instant and local, the second requires an external query.

#Does validation have an additional cost?

No. NIF validation is included in all BeeL. plans at no additional cost per query.

#What does the API return if the NIF doesn’t exist?

It returns { valid: false }. No name or additional data is returned if the NIF isn’t registered.

#Can I validate NIFs from other EU countries?

Currently the API validates Spanish NIFs (NIF, CIF, NIE) against the AEAT. For intra-community NIFs (VIES validation), it’s on the roadmap.

#Is there a query limit?

BeeL. plans include a generous volume of validations. If you need bulk validation (thousands per day), contact us to ensure your plan covers it.

Want to integrate NIF validation in your application? Install the TypeScript SDK (source code on GitHub), check the API documentation, or the SDKs page for quickstarts in other languages. You can also automate validation with n8n or integrate it into your CRM.