Authentication, plans and limits

Everything that applies to every endpoint: how to send your API key, how requests are counted on each plan, the rate limits, the error format and how to page through results.

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

2. Authentication

To access the endpoints you must include your X-API-KEY in the request header. You can generate and copy your key from your control panel.

GET /api/v1/companies?cif=A15075062 HTTP/1.1
Host: spaincompanyapi.com
X-API-KEY: your_api_key_here
Accept: application/json

The Authorization: Bearer your_api_key_here header is also accepted.

Test environment (Sandbox)

To test your integration without using requests, use the same API key with the base URL https://spaincompanyapi.com/api/sandbox/v1 (same paths as production: /companies, /companies/search, /companies/score…). The Sandbox does not use requests and only accepts these CIFs (all responses are samples, with fixed data and the same structure as production):

  • A15075062: company found (Inditex).
  • B00000000: company not found (404).

Any other CIF returns an error. The Sandbox always answers with the full data, without the Free plan truncation or quota limits: use it to check the response format, not what you will see on your plan.

Every successful Sandbox response adds a sandbox block: plan_required (minimum plan for the endpoint), production_url (the same request in production, ready to copy), cost (always 0) and, on /companies, /companies/search and /companies/batch, fields_by_plan with the fields that only come complete on Pro.

/companies/verify, POST /companies/verify/batch (only A15075062 is resolved; any NIF's format is checked), /companies/contracts, /companies/filter, POST /companies/reconcile ("Inditex" gives match, a name containing "Ejemplo" gives ambiguous and anything else no_match) and monitoring (/watchlist and /watchlist/events, nothing is saved: it answers as if you were already watching A15075062) are also in the Sandbox, along with every other /companies path. /webhooks and /usage are not.

2.1 Plans, usage and credits

PlanRequestsSpeed
Free100 in total (not renewed)2 per second
Pro3,000 per month20 per second
Business10,000 per month20 per second

Each endpoint shows the plan it needs. On a lower plan it returns 403 with the plan you need in required_plan and the upgrade link in upsell_opportunities.checkout_url.

What uses a request

  • Only 200 responses are charged. Errors cost nothing.
  • While your plan has requests left, every 200 response uses 1, whatever the endpoint. Exceptions: /companies/verify uses 2; /companies/batch, POST /companies/verify/batch and POST /companies/reconcile, 1 per company found; /companies/filter rows, 5 per row.
  • Free of charge: the Sandbox, /usage, /catalog, /watchlist, /webhooks, the /companies/filter count (count_only=true) and previews (/companies/score on Free and /companies/insights on Pro).

Credits

When your plan's requests run out, or if you use prepaid credits without a subscription, each 200 response is paid from your wallet. Endpoints do not all cost the same:

CreditsEndpoints
1/companies and /companies/search; /companies/batch, POST /companies/verify/batch and POST /companies/reconcile, 1 per company found
2/companies/verify
3/companies/score, /signals, /insights, /contact-prep, /network, /match, /radar, /borme, /contracts and /risk-profile
5 per row/companies/filter rows

Free plan with credits

  • You get Pro access: full data on /companies and /companies/search, plus /companies/verify, POST /companies/verify/batch, POST /companies/reconcile, /companies/borme, full /companies/score, /companies/signals, /companies/radar (up to 100 results), /companies/insights (preview) and /companies/network.
  • It does not include /companies/batch, monitoring (/watchlist) or Business endpoints.
  • While you have credits, every request is paid with them, even if you have free requests left. Speed stays at 2 per second.

Free plan

  • The 100 requests count everything used since 28/05/2026, including usage on an earlier paid plan.
  • The /companies/score preview does not use requests, but you need at least one left: with no requests and no credits it returns 429 QUOTA_EXCEEDED.

Previews

What we show without charging has a shared cap of 25 per day per account: the /companies/score preview (Free), the /companies/insights preview (Pro), business_preview (Pro) and the counts included in some 403 responses (for example eventos_ocultos on /companies/signals). Past the cap, score and insights return 429 PREVIEW_LIMIT_EXCEEDED, with Retry-After until the next day, and 403 responses come without counts.

13. Rate Limiting

To protect the API's stability and help you monitor your consumption, we return standard HTTP headers in every response that inform you in real time of your monthly quota and per-second speed limit.

HTTP Response Headers

HTTP Header Description
X-RateLimit-Limit Maximum requests allowed per second (2 on Free, 20 on paid plans).
X-RateLimit-Remaining Requests per second remaining in the current time window.
X-RateLimit-Reset Unix timestamp indicating when the speed limit resets.
X-Quota-Limit Requests included in your plan: per month on Pro and Business; on Free, 100 in total (not renewed).
X-Quota-Remaining Plan requests left, after this request, before credits are used.
X-Request-Id Unique traceability identifier for the request. Useful for fast technical support.

If you exceed the per-second limit, you will receive a 429 Too Many Requests error along with the Retry-After: 1 header indicating to wait 1 second. If you need to process many companies at once, we recommend using the Batch endpoint.

What each limit applies to

  • Rate (requests per second): per API key. Two keys on the same account each have their own limit.
  • Request quota and balance: per account. All keys on the account draw from the same quota.
  • Free previews and the Free plan safety limit: per account and per IP.

Per-request caps

EndpointCap
POST /companies/verify/batch1,000 tax IDs per call.
POST /watchlist500 tax IDs per call. Watched companies: 100 on Pro and 1,000 on Business.
GET /watchlistUp to 500 per page (limit).
WebhooksYour server has 10 seconds to reply to each delivery.
Other list endpointsThe maximum limit or number of items is stated on each endpoint.

Enterprise

On Enterprise contracts the rate, the quota and the number of watched companies are set in the contract according to the expected volume. Headers and error codes are the same.

12. Error Handling (RFC 7807)

API error responses include legacy fields (success, error, message) and also implement the modern RFC 7807 (Problem Details) standard. If there is an error, the HTTP status code will be different from 200 and you will receive a detailed JSON.

{
  "success": false,
  "error": "COMPANY_NOT_FOUND",
  "message": "Empresa no encontrada.",
  "code": "COMPANY_NOT_FOUND",
  "type": "https://apiempresas.es/docs/errors/company_not_found",
  "title": "COMPANY_NOT_FOUND",
  "status": 404,
  "detail": "Empresa no encontrada.",
  "instance": "req_8f73b1a2c9"
}

The instance field is unique per request and is very useful if you need to report a problem to support.

To handle errors in code, use the code field: it is a stable identifier and does not change within version 1. The legacy fields (error, message) vary from one endpoint to another: do not code against them. These are the codes the API can return:

HTTPcodeMeaning
401API_KEY_MISSINGThe X-API-KEY header was not sent.
401API_KEY_INVALIDThe API key does not exist.
403API_KEY_INACTIVEThe API key or the account is disabled.
403COUNTRY_NOT_ALLOWEDThe request comes from a country not allowed for your API key.
429TOO_MANY_REQUESTSToo many requests per second. Wait as long as Retry-After says and retry.
429QUOTA_EXCEEDEDYour plan's requests are used up and you have no credits. Retrying does not help: buy credits or upgrade.
429IP_LIMIT_EXCEEDEDFree plan security limit per IP address.
429PREVIEW_LIMIT_EXCEEDEDYou passed the cap of 25 free previews a day (see Plans and usage). Retry-After says when they are available again.
400VALIDATION_ERRORA required parameter is missing or not valid.
400INVALID_CIF_FORMATThe CIF format is not valid.
400FAKE_CIF_NOT_ALLOWEDA test CIF (for example B12345678 or B00000000) in production. To test, use the Sandbox.
400AUTONOMO_NOT_SUPPORTEDA DNI or NIE: we only provide data on companies.
403PLAN_RESTRICTIONYour plan does not include this endpoint. required_plan says which one does and upsell_opportunities.checkout_url links to the upgrade.
403UPGRADE_REQUIREDThe same, on /companies/borme.
403TEST_MODE_RESTRICTIONIn the Sandbox, a CIF that is not a test CIF.
404COMPANY_NOT_FOUNDNo company with that CIF or name.
404RISK_PROFILE_NOT_AVAILABLEThe company has no calculated risk profile.
404NOT_WATCHINGYou removed a company you were not monitoring.
404WEBHOOK_NOT_FOUNDYou have no webhook with that id.
502WEBHOOK_DELIVERY_FAILEDOn /webhooks/{id}/test: your server did not accept the test delivery.
400INVALID_EVENTWhen creating a webhook, an event that does not exist.
429CONCURRENT_BILLINGAnother request from the same account is being charged at that instant (batches and requests paid from the wallet). Wait for Retry-After (1 second) and retry.
500 / 503SERVER_ERROR / SERVICE_UNAVAILABLEOur error. Retry later and, if it persists, write to us with the instance.

What to retry, and how

ResponseRetry?How
429 TOO_MANY_REQUESTS, CONCURRENT_BILLINGYesWait the seconds in Retry-After and repeat the same request.
500, 502, 503, 504 or no responseYesUp to 3 attempts with growing waits (for example 1, 4 and 15 seconds). If the response carries Retry-After, honour it.
429 QUOTA_EXCEEDED, IP_LIMIT_EXCEEDED, PREVIEW_LIMIT_EXCEEDEDNoWaiting a few seconds does not fix it: you need quota, balance, or to wait until the date given.
400, 401, 403, 404NoThe result will not change. Fix the input, the key or the plan.
  • Recommended client timeout: 10 seconds for single-company requests and 60 seconds for batch requests.
  • Repeating a lookup is safe. GET requests change nothing. Errors never use up requests.
  • Repeating a request that already returned 200 is charged again. There are no idempotency keys. If a batch times out on your side, check /usage before repeating it, or split it into smaller batches.
  • When asking for support, send the instance value (or the X-Request-Id header) and the time of the request.

14. Cursor-based Pagination

In the multiple search endpoint (/api/v1/companies/search?multiple=true), you can use the traditional page parameter or the cursor parameter to paginate results more safely.

If the response contains more pages, the meta object will include a next_cursor. Simply send that exact value in your next request to automatically get the next page of results:

"meta": {
  "page": 1,
  "limit": 20,
  "has_more": true,
  "next_cursor": "eyJwIjoyfQ=="
}

/companies/filter also paginates with meta.next_cursor. /watchlist and /watchlist/events paginate with page and limit: request the next page while meta.has_more is true.

🚀 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?