NIFScout: Spanish Company CIF/NIF Lookup API

NIFScout turns a company website URL into a Spanish legal name, corporate NIF (historically called CIF), and an explicitly stated fiscal address when available. Use the structured result for CRM enrichment or supplier onboarding. The Actor checks the root, /aviso-legal and up to two additional legal/contact pages and returns one dataset row per lookup.

Each result includes the source path in found_at. A corporate tax identifier must pass its check-character validation and appear in context with a compatible legal name. Missing, invalid or conflicting evidence produces an explicit negative result; the Actor does not fill gaps with guessed company details. An address is returned as fiscal only when labelled as such.

Input

{"url":"https://www.cliente.es"}

Use a real public company website. The example is an input illustration, not a claim that this domain contains the sample company below. Paths and query strings are normalized to the website root. Only HTTPS pages on the same domain or its www counterpart are followed.

The input form is prefilled with https://www.futuroinformatica.com, a public company website used in the recorded smoke test. Replace it with your target website before running. The prefilled input is processed through the same live extraction as every other lookup; results are not prerecorded, and the website can change. No user-supplied secret or paid external subscription is required. Empty input remains invalid. NIF validation checks the structure and control character, not a tax registry.

Output

Illustrative result using a fictional company and a checksum-valid sample identifier:

{
  "success": true,
  "domain": "cliente.es",
  "legal_name": "Comercial Horizonte S.L.",
  "tax_id": "B12345674",
  "tax_id_valid": true,
  "tax_address": "Calle Mayor 12, 28001 Madrid",
  "found_at": "/aviso-legal"
}

Missing or conflicting evidence produces success: false, null identity fields, and an error object. Examples include not_found, ambiguous, invalid_tax_id, upstream_unavailable and timeout. Results are available in the default dataset as JSON or CSV; the Actor does not create a second copy in a key-value store.

Validation and scope

• Corporate Spanish NIF structure and control character are validated. Personal DNI/NIE is excluded.
• A tax identifier must appear with an explicit label and a nearby supported legal company name. Conflicting candidates are rejected.
• tax_id_valid means formal validation. It does not confirm registry existence, current activity, VAT registration, or legal ownership of the website.
• An address is returned only when explicitly described as fiscal. A registered office is not automatically relabelled a fiscal address.
• Static HTML and plain text are supported. No browser JavaScript, CAPTCHAs, authenticated pages, PDF parsing, or proxy services are used.
• The extraction budget is five seconds. Actor startup and Apify storage operations add time; the complete run is not a five-second latency promise.
• Conservative matching reduces false positives but cannot guarantee perfect attribution for arbitrary or misleading web content.

Billing

The configured pricing is USD 0.01 per dataset row, including negative lookup results, plus USD 0.00005 per Actor start. Platform usage is billed separately to the consumer. Invalid or inaccessible websites can still consume resources and produce a billed error row. No external API subscription or Cloudflare credential is required. Consult the plan displayed in Apify before running.

The Actor is published at apify.com/dekaz/spanish-company-tax-data, with monetization active (Actor ID t2kCzBw6tUhde0GfB). Publication was confirmed on October 16, 2026. Payout eligibility is separate from Store availability and is not confirmed here.

Local development

Requires Node.js 24+. Runtime dependencies: none.

cd E:\api-datos-fiscales\apify
npm run sync-core
npm test
npm start -- --url https://company.es

sync-core copies four shared modules from the parent project's src/ directory into src/core/. The packaged Actor already includes these copies and runs independently. Run this command after changing the parent extractor, then run both test suites.

On Apify the Actor reads its runtime input and writes its default dataset through the native fetch API. The Apify runtime token is sent only to https://api.apify.com; it is never forwarded to scanned websites. The Node HTTPS transport validates DNS at socket lookup and connects to that checked public IP. Each run handles one URL and writes at most one row. Resurrected runs first check for an existing result to avoid repeating a completed lookup. Uncertain dataset POST responses are not automatically retried.

Deployment settings

Build the contents of this directory as a Docker Actor. Use the supplied .actor/actor.json, input schema and dataset schema. Select limited permissions, disable Standby, keep the memory at 128 MB, and set the platform run timeout to 30 seconds. The process also stops itself at 25 seconds. Test with one website before enabling public monetization.

Configured monetization: pay per event; apify-default-dataset-item at $0.01 per saved row and apify-actor-start at $0.00005, with Pay per event + usage enabled so the consumer pays platform usage separately. These prices are Apify deployment settings, not prices enforced by this source code. A run budget must cover the events and any separately billed platform usage; the event subtotal alone is $0.01005 for one start and one row.

Apify is a metered platform. A Free account has a finite credit allowance; builds and the owner's own test runs consume it. Do not upgrade the account or enable extra spend for this project. Free infrastructure is therefore bounded, not unlimited. If platform usage is included in the event price instead, the creator's net payout is calculated after the platform's share and running costs. Payout eligibility requires the billing, payment and verification steps requested by Apify.

Recorded remote smoke test

deployment/smoke-result.json records a successful remote run against https://www.futuroinformatica.com: it completed with status SUCCEEDED in 4.642 seconds and returned Futuro Informática Profesional, S.L. with tax ID B92588243. The fiscal address remained null because the source labelled its address as a registered office. Observed platform usage at completion was approximately USD 0.00008542, covered by existing Free-plan credits without a plan change. This is one measured test, not a latency or coverage guarantee, and it does not verify tax-registry status.

Official references checked for this package: Actor definition, pay-per-event and automatic dataset events, costs and payouts, monetization setup, and current plans.