KYB verification and tax ID checks

Endpoints for onboarding and invoicing: a single KYB verdict for a company, batch checks of customer tax IDs before you invoice, and name-to-CIF reconciliation.

Base URL: https://spaincompanyapi.com/api/v1 · API key in the X-API-KEY header · Get a free API key (100 requests, no card) · Full documentation

3.1 KYB Verification

In a single call: whether the company exists and is operating, whether the name you were given matches the registered name, whether the signer is a current director and whether the VAT number is registered in VIES. Returns alerts and a recommendation (decision_hint) that you can use as is, or ignore and decide from the data. Cost: 2 requests.

GET /companies/verify Pro

Personal data: send it in the body. The same parameters can be sent with POST /companies/verify and a JSON body ({"cif": "…", "person": "…", "iban": "…"}). This is recommended whenever you send person or iban: a request body is not written to the server access logs, while the URL is. Cost and response are the same.

ParameterDescription
cifRequired. Company CIF.
nameOptional. The company name you were given. Compared without accents, punctuation or legal form (0-100; matches from 80).
personOptional. Full name of the signer. Looked up among the current directors, in any word order.
vatOptional. With true, checks the EU VAT number in VIES (European Commission).
eoriOptional. With true, checks whether the company has an EORI number as a customs operator (it can import and export outside the EU), using the European Commission service. Informative: it does not change decision_hint.
ibanOptional. The IBAN you were given to collect or pay (with or without spaces). Checks that it is well formed: country length, IBAN check digits and, for Spanish accounts, the national check digits. It does not tell who owns the account.
{
  "success": true,
  "data": {
    "cif": "B12345678",
    "exists": true,
    "name": "EMPRESA DE EJEMPLO SL",
    "status": "ACTIVA",
    "status_code": "ACTIVE",
    "status_source": "registry",
    "status_date": null,
    "status_confidence": "high",
    "status_confidence_reasons": ["RECENT_REGISTRY_ACT"],
    "tax_id_revocation": null,
    "identifiers": { "lei": null, "lei_status": null, "lei_next_renewal_date": null, "lei_source": null, "lei_as_of": null },
    "legal_form": { "code": "SL", "label": "Sociedad limitada", "iso20275": "DP3Q", "source": "name" },
    "group": null,
    "ownership": {
      "unipersonal": true,
      "sole_shareholder": { "name": "PEREZ GARCIA JUAN", "type": "person", "since": "2019-03-01", "url_pdf": "https://www.boe.es/borme/dias/2019/03/01/pdfs/BORME-A-2019-42-28.pdf" },
      "source": "borme",
      "as_of": "2019-03-01"
    },
    "size": { "employees_min": 3, "employees_max": 9, "label": "De 3 a 9 empleados", "category": "micro", "source": "kit_digital", "as_of": "2023-03-15" },
    "address_density": { "active_companies_at_address": 1, "level": "normal", "match": "exact_address", "as_of": "2026-10-19" },
    "checks": {
      "name": { "provided": "Empresa de Ejemplo, S.L.", "score": 100, "match": true },
      "person": { "provided": "Juan Pérez García", "is_current_admin": true, "matched_name": "PEREZ GARCIA JUAN", "position": "Adm. Unico", "since": "2019-03-01", "is_sole_shareholder": true },
      "vat": { "vat_number": "ESB12345678", "checked": true, "valid": true, "source": "VIES", "error": null },
      "eori": { "eori_number": "ESB12345678", "checked": true, "valid": true, "name": null, "address": null, "source": "EOS", "error": null },
      "iban": { "provided": "ES91****************1332", "valid": true, "country": "ES", "sepa": true, "bank_code": "2100", "branch_code": "0418", "reason": null },
      "accounts": { "last_accounts_year": 2023 }
    },
    "flags": [],
    "decision_hint": "pass",
    "checked_at": "2026-09-28T10:30:00+02:00",
    "evidence": {
      "evidence_id": "3f9a1c0be27d4e5fa6b7c8d9e0f1a2b3",
      "version": "1",
      "checked_at": "2026-09-28T10:30:00+02:00",
      "issuer": "APIEmpresas (apiempresas.es)",
      "sha256": "616f1a6375637ebfe25d29a193a8dd580e03c87dae128b077794725f80b46643",
      "is_registry_certificate": false,
      "disclaimer": "Este expediente recoge el resultado de una comprobación automática… No es una certificación registral…"
    }
  }
}
decision_hintWhen
failThe company is not operating: extinct, dissolved, in liquidation, registry sheet closed, absorbed or inactive. Or the Spanish Tax Agency has revoked its tax ID (alert TAX_ID_REVOKED, critical).
reviewInsolvency proceedings, unknown status, name mismatch, signer is not a current director, VAT number not in VIES (if requested), invalid IBAN (if provided) or, on Business, high risk or a strong match on the sanctions lists.
passNone of the above.
  • Each alert in flags has code, severity (critical, high, medium, low) and message.
  • If VIES does not respond, checks.vat.checked is false and the decision is not affected.
  • tax_id_revocation (2026-11-06): the same block as in /companies, in data. With status: REVOKED you get the TAX_ID_REVOKED alert (critical) and decision_hint: fail: while the tax ID stays revoked it is not valid for tax purposes and banks cannot make payments to or from the company. REHABILITATED (revoked and later reinstated) raises no alert.
  • checks.eori (with eori=true): in Spain the EORI is ES + tax ID. valid: true means the company is registered as a customs operator in the EU. name and address are only returned if the company has agreed to publish them; otherwise null. Having no EORI is normal for companies that do not trade outside the EU, so it raises no flag and does not change the decision. If the service does not respond, checked is false.
  • checks.iban returns the masked IBAN, the country, whether it is SEPA and, for Spanish accounts, the bank (bank_code) and branch (branch_code) codes. If it is not valid, reason says why (FORMAT, LENGTH, CHECKSUM or NATIONAL_CHECK_DIGITS) and the IBAN_INVALID alert (medium) moves the decision to review. The IBAN is not stored.
  • identifiers, legal_form, group and ownership are the same blocks as in /companies. With person, checks.person.is_sole_shareholder also says whether the signer is the sole shareholder (a natural person). It is informational and does not change decision_hint.
  • size and address_density are the same as in /companies. When 10 or more active companies share the registered address the SHARED_ADDRESS alert (low) is added, and from 50, MASS_ADDRESS (medium). Both are informational: they do not change decision_hint.
  • sources: the same as in /companies, plus the source and date of each check performed: vat (VIES, real time), eori (EOS, real time), sanctions (with the date of each list) and risk (Business, profile date). Use it to keep evidence of the decision.
  • Downloadable evidence (16 Nov 2026): the response includes evidence, the record of the check for your files: evidence_id (the same value as the X-Request-Id header), checked_at, sha256 (hash of data without evidence, as JSON with sorted keys, no spaces and no escaping of Unicode or slashes; in Python, json.dumps(data, sort_keys=True, ensure_ascii=False, separators=(",", ":"))), is_registry_certificate (always false) and disclaimer. To get it as a PDF: with format=pdf the response is the PDF itself (application/pdf, with the X-Evidence-Id, X-Evidence-Sha256 and X-Decision-Hint headers); with include_pdf=true you get the usual JSON plus the PDF in evidence.pdf.base64. It costs the same as a normal call. The PDF is in Spanish. It is not a certificate from the Mercantile Registry and does not establish the beneficial owner, and we keep no copy: store it yourself. The hash lets you check that the JSON has not been altered; it is not a signature.
  • The latest accounts year is informative: later filings may exist that we have not loaded yet.
  • Business: the response adds risk (risk_level, risk_score) and checks.sanctions: result on the EU, UN and OFAC sanctions lists for the company and its directors, with the matches (see 10.1).
  • Company not found: 404 COMPANY_NOT_FOUND with decision_hint: "fail" (not charged). Free plan without credit: 403 PLAN_RESTRICTION.

3.3 Validate tax IDs before invoicing (batch)

Check up to 1,000 customer or supplier tax IDs (NIF) in one call before issuing invoices: whether the NIF is well formed, whether the company is registered, its legal name and registered address as recorded, its status and whether the name you have on file matches. Each row comes with a hint, invoice_hint: ok, revisar (review) or no_facturar (do not invoice). Built for invoicing and ERP software ahead of Verifactu (2027) and mandatory B2B e-invoicing in Spain (2027-2028). Cost: 1 request per company found; malformed NIFs, personal NIFs and NIFs not found are free.

POST /companies/verify/batch Pro
Body fieldDescription
itemsRequired (or cifs). List of up to 1,000 objects {cif, name, ref}. name (optional): the legal name you have on file, compared with the official one. ref (optional): your customer ID, returned as is.
cifsAlternative to items: just the list of NIFs.
vatOptional. With true it also checks the EU VAT number in VIES. Only for batches of up to 20, because the European Commission service is slow.
// Request
{
  "items": [
    { "cif": "A46103834", "name": "Mercadona", "ref": "cli-001" },
    { "cif": "A15075062", "name": "Inditex", "ref": "cli-002" },
    { "cif": "A46103835", "ref": "cli-003" },
    { "cif": "12345678Z", "ref": "cli-004" }
  ]
}

// Response
{
  "success": true,
  "data": [
    {
      "input": "A46103834", "cif": "A46103834", "ref": "cli-001", "valid_format": true, "processed": true, "exists": true,
      "legal_name": "MERCADONA SA",
      "address": { "street": "CALLE VALENCIA 5", "postal_code": "46016", "municipality": "TAVERNES BLANQUES", "province": "VALENCIA" },
      "status_code": "ACTIVE", "status_date": null, "status_confidence": "high", "status_confidence_reasons": ["RECENT_REGISTRY_ACT"], "tax_id_revocation": null,
      "name_check": { "provided": "Mercadona", "score": 100, "match": true },
      "invoice_hint": "ok", "flags": []
    },
    {
      "input": "A15075062", "cif": "A15075062", "ref": "cli-002", "valid_format": true, "processed": true, "exists": true,
      "legal_name": "INDUSTRIA DE DISENO TEXTIL SA",
      "address": { "street": "AVENIDA DE LA DIPUTACION (ED INDITEX), S/N", "postal_code": "15142", "municipality": "ARTEIXO", "province": "A CORUÑA" },
      "status_code": "ACTIVE", "status_date": null,
      "name_check": { "provided": "Inditex", "score": 42, "match": false },
      "invoice_hint": "revisar",
      "flags": [ { "code": "NAME_MISMATCH", "severity": "high", "message": "El nombre que tienes guardado no coincide con la razón social: usa legal_name en la factura." } ]
    },
    {
      "input": "A46103835", "cif": "A46103835", "ref": "cli-003", "valid_format": false, "processed": true, "exists": null,
      "invoice_hint": "no_facturar",
      "flags": [ { "code": "INVALID_FORMAT", "severity": "high", "message": "El NIF no tiene un formato válido (dígito o letra de control incorrectos)." } ]
    },
    {
      "input": "12345678Z", "cif": "12345678Z", "ref": "cli-004", "valid_format": true, "processed": true, "exists": null,
      "invoice_hint": "revisar",
      "flags": [ { "code": "PERSON_NIF", "severity": "info", "message": "NIF de persona física (autónomo o particular): la letra de control es correcta, pero no damos datos de personas (RGPD)." } ]
    }
  ],
  "meta": {
    "requested": 4, "found": 2, "cost": 2, "truncated": false,
    "summary": { "ok": 1, "revisar": 2, "no_facturar": 1, "not_processed": 0 },
    "checked_at": "2026-10-25T10:00:00+02:00",
    "note": "No sustituye la comprobación contra el censo de la AEAT. Razón social y domicilio según el Registro Mercantil y el BORME."
  }
}
invoice_hintWhen
no_facturarWrong check digit or letter, a sample NIF, a company that is extinct or was absorbed in a merger (invoice the absorbing company), or a tax ID revoked by the Spanish Tax Agency (alert TAX_ID_REVOKED; see tax_id_revocation on each row).
revisarInsolvency proceedings, dissolved or in liquidation, registry sheet closed, inactive, the name on file does not match (use legal_name), the VAT number is not in VIES (if requested), a personal NIF, or a NIF not found as a registered company.
okNone of the above. If we have no data to state the status, you get ok with the STATUS_UNKNOWN flag (low): the company is registered.
  • Results come in the same order as the request. valid_format checks the control digit or letter of CIF, DNI and NIE.
  • exists: false (not found) does not mean the NIF is fake: it may be an entity that is not registered in the Mercantile Registry (association, joint ownership, public body) or a typo. For personal NIFs, exists is null: we do not provide data on sole traders (GDPR).
  • name_check compares without accents, punctuation or legal form (0-100; matches from 80). A trade name ("Inditex") does not match the legal name ("Industria de Diseño Textil SA"): that is why legal_name gives you the name that must appear on the invoice.
  • address is the registered office according to the Registry and the BORME. It may differ from the tax address.
  • meta.summary counts the rows of each hint. A NIF repeated in the list is charged once.
  • If your quota runs out, the companies that do not fit come back with processed: false and the NOT_PROCESSED_QUOTA flag, and are not charged. No quota or credit left: 429 QUOTA_EXCEEDED.
  • It does not check against the Tax Agency (AEAT) census (only the taxpayer can use that service, with their own certificate). It helps fix errors before issuing; it does not guarantee that the AEAT accepts the record. Messages in flags are in Spanish; use code in your logic.
  • In the Sandbox, any NIF's format is checked, but only A15075062 is resolved; other valid CIFs come back with processed: false.
  • Pro and Business (and Free with credit). Free plan without credit: 403 PLAN_RESTRICTION. For a single company with more checks (signatory, IBAN, sanctions), use KYB verification.

3.2 Name to CIF (reconciliation)

Send a list of company names and get each one's CIF with a confidence score. Useful to complete or clean customer and supplier databases that have the name but not the CIF. Cost: 1 request per name with a match (match); ambiguous names, not-found names and matches to a company whose CIF we do not have yet (cif: null) are free.

POST /companies/reconcile Pro
// Request
{
  "items": [
    { "name": "Mercadona, S.A.", "province": "Valencia" },
    { "name": "Talleres Pérez" },
    { "name": "Panadería Inventada del Norte" }
  ]
}

// Response
{
  "success": true,
  "data": [
    {
      "input": { "name": "Mercadona, S.A.", "province": "Valencia" },
      "status": "match",
      "score": 100,
      "company": { "cif": "A46103834", "name": "MERCADONA SA", "province": "VALENCIA", "status": "ACTIVA", "status_code": "ACTIVE", "score": 100 }
    },
    {
      "input": { "name": "Talleres Pérez", "province": null },
      "status": "ambiguous",
      "candidates": [
        { "cif": "B12345678", "name": "TALLERES PEREZ SL", "province": "MADRID", "status": "ACTIVA", "status_code": "ACTIVE", "score": 100 },
        { "cif": "A12345674", "name": "TALLERES PEREZ SA", "province": "SEVILLA", "status": "ACTIVA", "status_code": "ACTIVE", "score": 100 }
      ]
    },
    { "input": { "name": "Panadería Inventada del Norte", "province": null }, "status": "no_match" }
  ],
  "meta": { "requested": 3, "matched": 1, "ambiguous": 1, "no_match": 1, "invalid": 0, "skipped_quota": 0, "cost": 1, "thresholds": { "match": 85, "ambiguous": 70 } }
}
  • Up to 100 names per request. {"names": ["...", "..."]} also works.
  • Names are compared without accents, punctuation or legal form. match: score 85 or higher and clearly ahead of the next candidate. ambiguous: plausible candidates (70 or higher), up to 3 returned. no_match: none reaches 70.
  • The province (province) is optional and breaks ties between companies with the same name.
  • If your quota runs out, the remaining names come back as skipped_quota and are not charged.
  • Pro and Business (and Free with credit). Free plan without credit: 403 PLAN_RESTRICTION.

🚀 Ready to get started?

Get your API Key in seconds and start integrating real data into your applications.

Go to Control Panel
🤖
Asistente IA En línea
¡Hola! Soy el asistente de APIEmpresas. ¿En qué puedo ayudarte hoy?