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
Plan
Requests
Speed
Free
100 in total (not renewed)
2 per second
Pro
3,000 per month
20 per second
Business
10,000 per month
20 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:
Credits
Endpoints
1
/companies and /companies/search; /companies/batch, POST /companies/verify/batch and POST /companies/reconcile, 1 per company found
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
Endpoint
Cap
POST /companies/verify/batch
1,000 tax IDs per call.
POST /watchlist
500 tax IDs per call. Watched companies: 100 on Pro and 1,000 on Business.
GET /watchlist
Up to 500 per page (limit).
Webhooks
Your server has 10 seconds to reply to each delivery.
Other list endpoints
The 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.
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:
HTTP
code
Meaning
401
API_KEY_MISSING
The X-API-KEY header was not sent.
401
API_KEY_INVALID
The API key does not exist.
403
API_KEY_INACTIVE
The API key or the account is disabled.
403
COUNTRY_NOT_ALLOWED
The request comes from a country not allowed for your API key.
429
TOO_MANY_REQUESTS
Too many requests per second. Wait as long as Retry-After says and retry.
429
QUOTA_EXCEEDED
Your plan's requests are used up and you have no credits. Retrying does not help: buy credits or upgrade.
429
IP_LIMIT_EXCEEDED
Free plan security limit per IP address.
429
PREVIEW_LIMIT_EXCEEDED
You passed the cap of 25 free previews a day (see Plans and usage). Retry-After says when they are available again.
400
VALIDATION_ERROR
A required parameter is missing or not valid.
400
INVALID_CIF_FORMAT
The CIF format is not valid.
400
FAKE_CIF_NOT_ALLOWED
A test CIF (for example B12345678 or B00000000) in production. To test, use the Sandbox.
400
AUTONOMO_NOT_SUPPORTED
A DNI or NIE: we only provide data on companies.
403
PLAN_RESTRICTION
Your plan does not include this endpoint. required_plan says which one does and upsell_opportunities.checkout_url links to the upgrade.
403
UPGRADE_REQUIRED
The same, on /companies/borme.
403
TEST_MODE_RESTRICTION
In the Sandbox, a CIF that is not a test CIF.
404
COMPANY_NOT_FOUND
No company with that CIF or name.
404
RISK_PROFILE_NOT_AVAILABLE
The company has no calculated risk profile.
404
NOT_WATCHING
You removed a company you were not monitoring.
404
WEBHOOK_NOT_FOUND
You have no webhook with that id.
502
WEBHOOK_DELIVERY_FAILED
On /webhooks/{id}/test: your server did not accept the test delivery.
400
INVALID_EVENT
When creating a webhook, an event that does not exist.
429
CONCURRENT_BILLING
Another 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 / 503
SERVER_ERROR / SERVICE_UNAVAILABLE
Our error. Retry later and, if it persists, write to us with the instance.
What to retry, and how
Response
Retry?
How
429 TOO_MANY_REQUESTS, CONCURRENT_BILLING
Yes
Wait the seconds in Retry-After and repeat the same request.
500, 502, 503, 504 or no response
Yes
Up to 3 attempts with growing waits (for example 1, 4 and 15 seconds). If the response carries Retry-After, honour it.
Waiting a few seconds does not fix it: you need quota, balance, or to wait until the date given.
400, 401, 403, 404
No
The 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:
/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.
¡Hola! Soy el asistente de APIEmpresas. ¿En qué puedo ayudarte hoy?
Consultando...
Legal
Privacy Policy
How we collect, use, and protect your information.
1. Identity of the Data Controller
The data controller of the personal data collected on this platform is Ariel Martinez Hernandez (hereinafter, "SpainCompanyAPI"), with NIF 54994158P and address at República Dominicana 40, Bajo E, 28983, Parla (Madrid). You can contact us at soporte@apiempresas.es.
2. Purposes and Legal Basis
We process your personal data for the following purposes and legal bases:
Provision of the service and account management: Necessary for the performance of the contract (Terms of Use) upon registration.
Billing and collections: Compliance with legal and tax obligations.
Fraud prevention and security: Based on our legitimate interest to keep the platform secure.
Commercial communications and marketing: We rely on our legitimate interest to send you information about products or services similar to those contracted. You can object to this processing by checking the corresponding box during registration or unsubscribing at any time.
3. Data Retention
The data will be kept as long as you maintain your account active and it is necessary to provide the service. Once canceled, they will be kept duly blocked for the period required by applicable legislation (generally up to 5 years for tax and legal reasons).
4. Recipients and International Transfers
We do not sell your data to third parties. We may transfer them to strictly necessary providers (hosting, analytics, payment gateway such as Stripe). Some of these providers (e.g., Google, GitHub) may transfer data outside the EEA. We ensure they comply with the GDPR through standard contractual clauses or equivalent agreements.
Cloudflare Turnstile: We use Cloudflare Turnstile to protect our forms against spam and automated abuse. The use of Turnstile is subject to the Cloudflare Privacy Policy and Terms.
5. Your Rights (ARCO-POL)
You have the right to obtain confirmation as to whether we are processing your data. You also have the right to:
Access your personal data.
Request its rectification if it is inaccurate.
Request its deletion when it is no longer necessary.
Request the limitation or object to its processing.
Request data portability.
You can exercise them by sending an email to soporte@apiempresas.es. Likewise, if you consider that your data has not been properly processed, you have the right to file a claim with the Spanish Data Protection Agency (AEPD).
Last updated: 11/16/2026
Legal
Legal Notice & Terms of Use
Legal conditions for accessing and using the platform.
1. General Information (LSSI-CE)
In compliance with Law 34/2002 on Information Society Services and Electronic Commerce (LSSI-CE), it is reported that the owner of the SpainCompanyAPI web platform is:
Owner: Ariel Martinez Hernandez
NIF: 54994158P
Address: República Dominicana 40, Bajo E, 28983, Parla (Madrid)
Contact: soporte@apiempresas.es
2. Acceptance
By accessing or registering on the service, you acquire the status of User and accept these terms of use in their entirety. If you do not agree, do not use the platform.
3. Permitted Use Conditions
You agree to make appropriate and lawful use of the service. It is strictly prohibited to:
Attempt to access systems or data without authorization.
Interfere with operation by abusing rate limits, malicious scraping, or cyber attacks.
Use the service for illegal purposes or those that harm the rights of third parties.
4. Account and Security
You are solely responsible for maintaining the confidentiality of your credentials (password, API keys) and for all activity that occurs under your account.
5. Intellectual Property
All content on the platform (design, code, structure, and databases) is the exclusive property of Ariel Martinez Hernandez or has the corresponding licenses. Reproduction, distribution, or modification is not allowed without express authorization.
6. Limitation of Liability
The platform is provided "as is." Within the applicable legal framework, SpainCompanyAPI is not liable for direct or indirect damages derived from the use of information obtained through the API, nor for potential service interruptions due to external causes.
7. Jurisdiction and Applicable Law
These conditions are governed by Spanish law. For the resolution of any dispute derived from the use of the service, the parties submit to the courts and tribunals of the city of Madrid, expressly waiving any other jurisdiction that may apply.