Company monitoring: watchlist and webhooks
Keep track of your customers and suppliers: add companies to a watchlist and get notified by webhook when something is published about them.
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
7.1 Company Watchlist
Add the companies you care about and fetch their changes since a date: new BORME acts, Registry status changes and risk level changes. Does not consume requests. Pro: up to 100 companies. Business: up to 1,000.
/watchlist
Pro
Add up to 500 CIFs per request. The response says what happened to each one.
// Request
{ "cifs": ["A46103834", "A15075062"] }
// Response
{
"success": true,
"data": {
"added": ["A46103834"],
"already_watching": ["A15075062"],
"not_found": [],
"invalid": [],
"rejected_over_limit": []
},
"meta": { "total": 2, "watch_limit": 100 }
}
/watchlist
Lists your watched companies (page, limit up to 500).
{
"success": true,
"data": [
{ "cif": "A46103834", "name": "MERCADONA SA", "added_at": "2026-09-27 10:12:04" },
{ "cif": "A15075062", "name": "INDUSTRIA DE DISENO TEXTIL SA", "added_at": "2026-09-28 08:30:51" }
],
"meta": { "total": 2, "watch_limit": 100, "page": 1, "limit": 100, "has_more": false }
}
/watchlist/{cif}
Removes a company. If it was not on your watchlist, returns 404 NOT_WATCHING.
{
"success": true,
"data": { "cif": "A46103834", "removed": true },
"meta": { "total": 1, "watch_limit": 100 }
}
/watchlist/events
| Parameter | Description |
|---|---|
since | Date YYYY-MM-DD, inclusive. Default: 7 days ago; at most 90 days back. |
types | Optional. borme_act, status_change, risk_level_change, insolvency, comma-separated. |
cif | Optional. Only the events of that company. |
page / limit | Pagination (up to 500 per page). |
{
"success": true,
"data": [
{
"id": "borme_act:8812345",
"type": "borme_act",
"date": "2026-09-22",
"cif": "B12345678",
"company_name": "EMPRESA DE EJEMPLO SL",
"data": {
"act_types": "Nombramientos, Ceses/Dimisiones",
"description": "Ceses/Dimisiones. Adm. Unico: ...",
"url_pdf": "https://www.boe.es/borme/dias/2026/09/22/pdfs/BORME-A-2026-181-28.pdf"
}
},
{
"id": "risk_level_change:B12345678:2026-09-25",
"type": "risk_level_change",
"date": "2026-09-25",
"cif": "B12345678",
"company_name": "EMPRESA DE EJEMPLO SL",
"data": { "from": "BAJO", "to": "MEDIO", "model_change": null }
}
],
"meta": { "since": "2026-09-20", "types": ["borme_act", "status_change", "risk_level_change", "insolvency"], "total": 2, "page": 1, "limit": 100, "has_more": false }
}
- Events are returned oldest first. The
idis stable: use it to avoid processing the same event twice. model_change: truemeans the level changed because we recalculated our model, not because of anything new at the company, andfalsethat it did not.nullif the model version used for the calculation is not recorded (older profiles).insolvency(since 26-10-2026): the company publishes an insolvency notice in the BORME. The same act is also returned asborme_act; this event adds the stage (stage) and the company's current status (status_code) indata, plusact_types,descriptionandurl_pdf. Insolvency proceedings stages:filed(petition),declared(declaration, including the opening of the special micro-enterprise procedure),restructuring(restructuring plan or pre-insolvency),agreement(creditors' agreement),liquidation,classification(culpable or fortuitous),concludedandreopened.enforcement_insolvencyis not insolvency proceedings: a court, usually an employment court, declares the company insolvent in an enforcement because it has no assets to pay a debt (for example, wages).other: other insolvency notices, such as the appointment of the insolvency administrator.- Recommended use: one call a day with
since= the date of your last call. - Free plan (also with credits): 403
PLAN_RESTRICTION. On Business you can receive these same events on your server with webhooks.
8. Webhooks (Business only)
Receive the changes of the companies on your watchlist on your server, without polling the API: new BORME acts, status changes and risk level changes. Also the new companies incorporated every day that match your filters (company.created). Events are generated every 15 minutes.
/webhooks
Business
Lists your webhooks with their status: is_active, failure_count (failed attempts in a row), last_status_code and the dates of the last delivery. It includes each webhook's secret.
{
"success": true,
"data": [
{
"id": 12,
"user_id": 229,
"url": "https://tu-dominio.com/webhooks/apiempresas",
"event": "watchlist.*",
"secret": "3f9c1b2a7d...",
"filters": "[]",
"is_active": 1,
"failure_count": 0,
"last_delivery_at": "2026-10-13 09:15:02",
"last_success_at": "2026-10-13 09:15:02",
"last_status_code": 200,
"disabled_at": null,
"created_at": "2026-09-28 10:00:00",
"updated_at": "2026-10-13 09:15:02"
}
]
}
/webhooks
Business
Create a webhook
// Request
{ "url": "https://yourdomain.com/webhooks/apiempresas", "event": "watchlist.*" }
// Response (201)
{
"success": true,
"message": "Webhook creado correctamente",
"id": 12,
"event": "watchlist.*",
"secret": "3f9c1b2a7d..."
}
Keep the secret: it lets you check that each delivery comes from us. If you send one in the request, yours is used.
| Event | When it arrives |
|---|---|
company.created | A company is incorporated that matches the webhook filters (see new companies). It does not depend on the watchlist. |
company.borme_act | An act is published in the BORME for a watched company. |
company.status_changed | The Registry changes the status of a watched company. |
company.insolvency | An insolvency notice is published for a watched company: a stage of its insolvency proceedings (declaration, agreement, liquidation, conclusion…) or a court declaration of insolvency. The stage is in stage. |
company.risk_level_changed | Its risk level changes (model_change: true if caused by a recalculation of our model). |
watchlist.* | All watchlist events (all of the above except company.created). |
test.ping | Only when calling /webhooks/{id}/test. |
New companies (company.created)
Some 400-600 companies are incorporated in Spain every working day. With this event, the ones that match your filters reach your server as soon as they appear in the BORME (in the 15-minute run after the daily load, with a 30-minute margin so the record is complete). Only companies detected after you create the webhook. Cost: 0, like every webhook.
// Request
{
"url": "https://yourdomain.com/webhooks/empresas-nuevas",
"event": "company.created",
"filters": { "province": ["VIZCAYA", "GUIPUZCOA"], "keywords": ["instalaciones", "eléctric"], "min_capital": 3000 }
}
// Response (201)
{
"success": true,
"message": "Webhook creado correctamente",
"id": 13,
"event": "company.created",
"secret": "8b1e0c4f2a...",
"filters": { "province": ["VIZCAYA", "GUIPUZCOA"], "keywords": ["INSTALACIONES", "ELÉCTRIC"], "min_capital": 3000 }
}
| Filter | What it does |
|---|---|
province | Commercial Registry provinces (up to 10). Values in /catalog. |
municipality | Municipalities (up to 20). |
keywords | Words that must appear in the corporate purpose or the name; one is enough (up to 20, 3 characters or more; Spanish text). It is the best activity filter for new companies: 92 % have it. |
cnae | CNAE prefixes (up to 20). Note: a newly incorporated company almost never has a CNAE code yet (around 6 %), so this filter lets very few through. Use keywords instead. |
min_capital | Minimum share capital in euros (95 % have it). |
legal_form | Legal forms: SL, SA, SLP, SLL, SCOOP… |
Without filters you get all of them. An invalid filter returns 400 VALIDATION_ERROR. To change the filters, delete the webhook and create it again.
Each delivery carries one company:
{
"id": "51057088-7127-103b-3c57-8c8e824456d3",
"event": "company.created",
"created_at": "2026-10-08T19:00:02+02:00",
"data": {
"id": "company_created:8573551",
"type": "company_created",
"date": "2026-10-08",
"cif": null,
"company_name": "PERICIALES HERRERO SOCIEDAD LIMITADA",
"data": {
"legal_form": { "code": "SL", "label": "Sociedad limitada", "iso20275": "DP3Q", "source": "name" },
"founded": "2026-10-01",
"province": "Vizcaya",
"municipality": "BILBAO",
"address": "AVDA MONTEVIDEO 4 3 (BILBAO)",
"postal_code": null,
"share_capital_eur": 3000,
"corporate_purpose": "Evaluación de riesgos y daños",
"cnae": null,
"cnae_label": null,
"administrators": [
{ "name": "HERRERO TASCON AITOR", "position": "Adm. Solidario", "since": "2026-10-08" }
],
"borme": { "date": "2026-10-08", "act_types": "Constitución, Nombramientos", "url_pdf": "https://www.boe.es/borme/dias/2026/10/08/pdfs/BORME-A-2026-195-48.pdf" },
"detected_at": "2026-10-08T20:21:27+02:00"
}
}
}
cifis almost alwaysnull: the Tax Agency assigns the CIF and it takes days or weeks to appear in public sources. To link it in your CRM, usedata.idor search by name later with /companies/search.dateandborme: the incorporation notice in the BORME (with its official PDF).founded: the incorporation date stated in the notice.detected_at: when we added it.administrators: those appointed at incorporation, same asadmin=truein /companies.- No phone or website: a newly incorporated company does not have them in any source yet.
What your server receives
A JSON POST with these headers: X-ApiEmpresas-Event, X-ApiEmpresas-Delivery (unique delivery id) and X-ApiEmpresas-Signature.
{
"id": "5d41402a-bc4b-2a76-b971-9d911017c592",
"event": "company.borme_act",
"created_at": "2026-09-28T10:15:00+02:00",
"data": {
"id": "borme_act:8812345",
"type": "borme_act",
"date": "2026-09-28",
"cif": "B12345678",
"company_name": "EMPRESA DE EJEMPLO SL",
"data": { "act_types": "Nombramientos", "description": "Nombramientos. Adm. Unico: ...", "url_pdf": "https://www.boe.es/borme/..." }
}
}
Verify the signature
X-ApiEmpresas-Signature looks like t=1790000000,v1=<signature>. The signature is the hex HMAC-SHA256 of t + "." + body with your secret. Reject the delivery if it does not match or if t is more than 5 minutes old. The SDKs include a helper that does this.
[$t, $v1] = array_map(fn($p) => explode('=', $p, 2)[1], explode(',', $_SERVER['HTTP_X_APIEMPRESAS_SIGNATURE']));
$body = file_get_contents('php://input');
$ok = hash_equals(hash_hmac('sha256', $t . '.' . $body, $secret), $v1) && abs(time() - (int) $t) < 300;
const crypto = require('crypto');
// rawBody: the body exactly as received, before JSON.parse
const { t, v1 } = Object.fromEntries(req.headers['x-apiempresas-signature'].split(',').map(p => p.split('=')));
const expected = crypto.createHmac('sha256', secret).update(t + '.' + rawBody).digest('hex');
const ok = expected.length === v1.length
&& crypto.timingSafeEqual(Buffer.from(expected), Buffer.from(v1))
&& Math.abs(Date.now() / 1000 - Number(t)) < 300;
import hmac, hashlib, time
# raw_body: the body bytes exactly as received
parts = dict(p.split('=', 1) for p in request.headers['X-ApiEmpresas-Signature'].split(','))
expected = hmac.new(secret.encode(), parts['t'].encode() + b'.' + raw_body, hashlib.sha256).hexdigest()
ok = hmac.compare_digest(expected, parts['v1']) and abs(time.time() - int(parts['t'])) < 300
Rotating the secret without losing events
Create a second webhook with the same URL, the same event and the new secret. While both exist, accept either signature and drop duplicates by the event content. Once your server validates the new one, delete the old webhook.
Where deliveries come from
If your firewall filters by origin, allow these addresses: 185.50.47.159 (IPv4) and 2a01:71c1:47::/48 (IPv6). Deliveries carry User-Agent: APIEmpresas-Webhooks/1.0. If they change, we will announce it in the changelog at least 30 days in advance. The signature remains the main check: do not rely on the IP alone.
Retries
- Reply with a 2xx code within 10 seconds. Otherwise we retry with growing waits: 1, 5 and 30 minutes, 2 and 6 hours. Deliveries go out every 15 minutes, so each retry arrives on the first run after that wait. After 6 attempts the delivery is dropped.
- Use
X-ApiEmpresas-Deliveryto avoid processing the same delivery twice. - At-least-once delivery. The same delivery can reach you more than once (for example, if you replied late and we retried): the
X-ApiEmpresas-Deliveryid is the same on every attempt. - Order is not guaranteed. A retry can arrive after a more recent event. Sort by the event date, not by arrival time.
- A webhook is disabled after 50 failed attempts in a row, counting all its deliveries; a successful delivery resets the count. Create it again once your server responds.
- The URL must be HTTPS (port 443) and public. We do not follow redirects.
/webhooks/{id}/test
Business
Sends a test.ping event to the webhook to check that your server receives it and validates the signature. If your server does not reply with a 2xx, the response is 502 WEBHOOK_DELIVERY_FAILED with the same data (the HTTP status your server returned and the error): the failure is on your server, not the API.
{
"success": true,
"data": {
"delivered": true,
"http_status": 200,
"duration_ms": 143,
"error": null,
"delivery_id": "5d41402a-bc4b-2a76-b971-9d911017c592"
}
}
/webhooks/{id}/deliveries
Business
Latest deliveries of the webhook, newest first: status (pending, processing, retry, delivered or dead), attempts, HTTP status your server returned, duration and error. next_attempt_at only appears on pending or retrying deliveries. Optional parameters: status, page and limit (1-100, default 50). Does not use requests. 404 WEBHOOK_NOT_FOUND if the webhook is not yours.
{
"success": true,
"data": [
{
"delivery_id": "5d41402a-bc4b-2a76-b971-9d911017c592",
"event": "company.borme_act",
"event_id": "borme_act:8812345",
"status": "delivered",
"attempts": 1,
"http_status": 200,
"duration_ms": 143,
"error": null,
"created_at": "2026-10-13 09:15:00",
"last_attempt_at": "2026-10-13 09:15:02",
"next_attempt_at": null,
"completed_at": "2026-10-13 09:15:02"
}
],
"meta": { "webhook_id": 12, "total": 1, "page": 1, "limit": 50, "has_more": false }
}
/webhooks/{id}
Business
Deletes a webhook. You stop receiving deliveries from that moment. If it does not exist, 404 WEBHOOK_NOT_FOUND.
{ "success": true, "message": "Webhook eliminado" }
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