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.
/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.
| Parameter | Description |
|---|---|
cif | Required. Company CIF. |
name | Optional. The company name you were given. Compared without accents, punctuation or legal form (0-100; matches from 80). |
person | Optional. Full name of the signer. Looked up among the current directors, in any word order. |
vat | Optional. With true, checks the EU VAT number in VIES (European Commission). |
eori | Optional. 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. |
iban | Optional. 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_hint | When |
|---|---|
fail | The 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). |
review | Insolvency 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. |
pass | None of the above. |
- Each alert in
flagshascode,severity(critical, high, medium, low) andmessage. - If VIES does not respond,
checks.vat.checkedisfalseand the decision is not affected. tax_id_revocation(2026-11-06): the same block as in/companies, indata. Withstatus: REVOKEDyou get theTAX_ID_REVOKEDalert (critical) anddecision_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(witheori=true): in Spain the EORI isES+ tax ID.valid: truemeans the company is registered as a customs operator in the EU.nameandaddressare only returned if the company has agreed to publish them; otherwisenull. 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,checkedisfalse.checks.ibanreturns 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,reasonsays why (FORMAT,LENGTH,CHECKSUMorNATIONAL_CHECK_DIGITS) and theIBAN_INVALIDalert (medium) moves the decision toreview. The IBAN is not stored.identifiers,legal_form,groupandownershipare the same blocks as in /companies. Withperson,checks.person.is_sole_shareholderalso says whether the signer is the sole shareholder (a natural person). It is informational and does not changedecision_hint.sizeandaddress_densityare the same as in /companies. When 10 or more active companies share the registered address theSHARED_ADDRESSalert (low) is added, and from 50,MASS_ADDRESS(medium). Both are informational: they do not changedecision_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) andrisk(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 theX-Request-Idheader),checked_at,sha256(hash ofdatawithoutevidence, 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(alwaysfalse) anddisclaimer. To get it as a PDF: withformat=pdfthe response is the PDF itself (application/pdf, with theX-Evidence-Id,X-Evidence-Sha256andX-Decision-Hintheaders); withinclude_pdf=trueyou get the usual JSON plus the PDF inevidence.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) andchecks.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_FOUNDwithdecision_hint: "fail"(not charged). Free plan without credit: 403PLAN_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.
/companies/verify/batch
Pro
| Body field | Description |
|---|---|
items | Required (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. |
cifs | Alternative to items: just the list of NIFs. |
vat | Optional. 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_hint | When |
|---|---|
no_facturar | Wrong 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). |
revisar | Insolvency 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. |
ok | None 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_formatchecks 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,existsisnull: we do not provide data on sole traders (GDPR).name_checkcompares 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 whylegal_namegives you the name that must appear on the invoice.addressis the registered office according to the Registry and the BORME. It may differ from the tax address.meta.summarycounts 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: falseand theNOT_PROCESSED_QUOTAflag, and are not charged. No quota or credit left: 429QUOTA_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
flagsare in Spanish; usecodein 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.
/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_quotaand are not charged. - Pro and Business (and Free with credit). Free plan without credit: 403
PLAN_RESTRICTION.
More API documentation
- Authentication, plans and limits
- Spanish company lookup by CIF or name
- KYB verification and tax ID checks
- BORME API: registry filings as JSON
- Company monitoring: watchlist and webhooks
- Prospecting: new companies and segments
- Public contracts, tenders and grants
- Sanctions screening and risk profile
- MCP server for AI assistants
- SDKs, code examples and Postman
🚀 Ready to get started?
Get your API Key in seconds and start integrating real data into your applications.
Go to Control Panel