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.

POST /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 }
}
GET /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 }
}
DELETE /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 }
}
GET /watchlist/events
ParameterDescription
sinceDate YYYY-MM-DD, inclusive. Default: 7 days ago; at most 90 days back.
typesOptional. borme_act, status_change, risk_level_change, insolvency, comma-separated.
cifOptional. Only the events of that company.
page / limitPagination (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 id is stable: use it to avoid processing the same event twice.
  • model_change: true means the level changed because we recalculated our model, not because of anything new at the company, and false that it did not. null if 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 as borme_act; this event adds the stage (stage) and the company's current status (status_code) in data, plus act_types, description and url_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), concluded and reopened. enforcement_insolvency is 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.

GET /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"
    }
  ]
}
POST /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.

EventWhen it arrives
company.createdA company is incorporated that matches the webhook filters (see new companies). It does not depend on the watchlist.
company.borme_actAn act is published in the BORME for a watched company.
company.status_changedThe Registry changes the status of a watched company.
company.insolvencyAn 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_changedIts 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.pingOnly 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 }
}
FilterWhat it does
provinceCommercial Registry provinces (up to 10). Values in /catalog.
municipalityMunicipalities (up to 20).
keywordsWords 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.
cnaeCNAE 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_capitalMinimum share capital in euros (95 % have it).
legal_formLegal 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"
    }
  }
}
  • cif is almost always null: the Tax Agency assigns the CIF and it takes days or weeks to appear in public sources. To link it in your CRM, use data.id or search by name later with /companies/search.
  • date and borme: 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 as admin=true in /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-Delivery to 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-Delivery id 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.
POST /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"
  }
}
GET /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 }
}
DELETE /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" }

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