{"openapi":"3.0.0","info":{"title":"Spain Company API","version":"v1","contact":{"name":"SpainCompanyAPI support","url":"https://spaincompanyapi.com/","email":"soporte@apiempresas.es"},"description":"REST API with data on Spanish companies: identity, status, activity (CNAE code), registered address, directors and BORME filings, plus commercial score, risk profile and public contracts. All responses are JSON over HTTPS.\n\n## Data sources\n\n| Source | Updated |\n|---|---|\n| BORME (Spanish Commercial Registry Gazette) | Every business day |\n| Spanish Public Procurement Platform | Daily |\n| Calculated by APIEmpresas | With each load |\n\n- **BORME:** incorporations, appointments and removals, changes of address, corporate purpose or capital, dissolutions, insolvency proceedings and strike-offs.\n- **Public Procurement Platform:** awarded contracts, with contracting body, amounts and dates.\n- **Calculated by APIEmpresas:** registry status, commercial score and risk profile, based on those publications.\n\nCalculated data is not a Commercial Registry certificate.\n\n## Environments\n\n| Environment | Base URL | Usage |\n|---|---|---|\n| Production | `https://spaincompanyapi.com/api/v1` | Every 200 response uses requests from your plan |\n| Sandbox | `https://spaincompanyapi.com/api/sandbox/v1` | Free. Same API key and same paths |\n\nThe server selector on this page starts on **Sandbox**, so you can try the endpoints without using requests. Switch it to Production to see real data.\n\n## Authentication\n\nSend your API key in the `X-API-KEY` header (`Authorization: Bearer <your_api_key>` is also accepted). You'll find it in your [dashboard](https://spaincompanyapi.com/dashboard) as soon as you [sign up for free](https://spaincompanyapi.com/register?intent=api&source=api_reference_en).\n\n```\ncurl \"https://spaincompanyapi.com/api/v1/companies?cif=A46103834\" \\\n  -H \"X-API-KEY: YOUR_API_KEY\"\n```\n\n## Sandbox\n\nIt only accepts these CIFs (Spanish company tax IDs):\n\n- `A15075062`: company found (Inditex). All responses are samples, with fixed data and the same structure as production.\n- `B00000000`: company not found (404).\n\nThe Sandbox always answers with full data, without the Free plan cuts or quota limits: use it to check the format, not what you will get on your plan. Each response adds a `sandbox` block with the endpoint's minimum plan and the same request in production. `/webhooks` and `/usage` are not in the Sandbox.\n\n## Plans\n\n| Plan | Requests | Speed | Price |\n|---|---|---|---|\n| Free | 100 in total (not renewed) | 2 per second | Free, no card |\n| Pro | 3,000 per month | 20 per second | €19/month + VAT |\n| Business | 10,000 per month | 20 per second | €49/month + VAT |\n\nEach endpoint shows the plan it needs; on a lower plan it returns 403 with the plan you need in `required_plan` and a link to upgrade.\n\n## Usage and credits\n\n- Only 200 responses are charged. Errors cost nothing.\n- 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.\n- Free of charge: the Sandbox, `/usage`, `/catalog`, `/watchlist`, `/webhooks`, the `/companies/filter` count and previews (`/companies/score` on Free and `/companies/insights` on Pro).\n\nWhen your plan's requests run out, or with [prepaid credits](https://spaincompanyapi.com/buy-api-credits), each 200 response is paid with credits:\n\n| Credits | Endpoints |\n|---|---|\n| 1 | `/companies`, `/companies/search`; `/companies/batch`, `POST /companies/verify/batch` and `POST /companies/reconcile`, 1 per company found |\n| 2 | `/companies/verify` |\n| 3 | score, signals, insights, contact-prep, network, match, radar, borme, contracts and risk-profile |\n| 5 per row | `/companies/filter` rows |\n\n**Free plan with credits:** you get Pro access (full data, verify, verify/batch, reconcile, borme, score, signals, radar up to 100, insights preview and network), without batch, monitoring or Business endpoints. While you have credits, every request is paid with them even if you have free requests left, and speed stays at 2 per second.\n\n**Free plan:** the 100 requests count everything used since 28/05/2026, including usage on an earlier paid plan.\n\n**Previews:** what we show without charging (score on Free, insights on Pro, `business_preview` and the counts in some 403 responses) has a shared cap of 25 per day per account. Past the cap, score and insights return 429 `PREVIEW_LIMIT_EXCEEDED`.\n\n## Limits and headers\n\n| Header | Meaning |\n|---|---|\n| `X-RateLimit-Limit` / `X-RateLimit-Remaining` / `X-RateLimit-Reset` | Per-second limit, what is left in the current window and when it resets |\n| `X-Quota-Limit` / `X-Quota-Remaining` | Your plan's requests and how many are left, after this request |\n| `X-Quota-Reset` | Only on the quota-exceeded error of paid plans: when it renews |\n| `X-Request-Id` | Request identifier; include it if you contact support |\n\n## Errors\n\nErrors follow RFC 7807 (Problem Details) and keep `success`, `error` and `message`. In code, use `code`: it is stable. Messages are in Spanish.\n\n```json\n{\n  \"success\": false,\n  \"error\": \"COMPANY_NOT_FOUND\",\n  \"code\": \"COMPANY_NOT_FOUND\",\n  \"message\": \"Empresa no encontrada.\",\n  \"type\": \"https://apiempresas.es/docs/errors/company_not_found\",\n  \"title\": \"COMPANY_NOT_FOUND\",\n  \"status\": 404,\n  \"detail\": \"Empresa no encontrada.\",\n  \"instance\": \"req_8f73b1a2c9\"\n}\n```\n\n| HTTP | `code` | Meaning |\n|---|---|---|\n| 401 | `API_KEY_MISSING` | The `X-API-KEY` header is missing |\n| 401 | `API_KEY_INVALID` | The API key does not exist |\n| 403 | `API_KEY_INACTIVE` | The API key or the account is disabled |\n| 403 | `PLAN_RESTRICTION` | Your plan does not include this endpoint (the response includes the upgrade link) |\n| 429 | `TOO_MANY_REQUESTS` | Too many requests per second: wait as long as `Retry-After` says and retry |\n| 429 | `QUOTA_EXCEEDED` | Quota used up and no credits: don't retry, buy credits or upgrade |\n| 429 | `IP_LIMIT_EXCEEDED` | Free plan security limit per IP address |\n| 429 | `PREVIEW_LIMIT_EXCEEDED` | Daily cap of free previews reached |\n| 400 | `VALIDATION_ERROR` | A parameter is missing or not valid |\n| 400 | `INVALID_CIF_FORMAT` | The CIF format is not valid |\n| 400 | `FAKE_CIF_NOT_ALLOWED` | Test CIF in production: use the Sandbox |\n| 400 | `AUTONOMO_NOT_SUPPORTED` | DNI or NIE (individuals): we only provide data on companies |\n| 403 | `UPGRADE_REQUIRED` | Same as `PLAN_RESTRICTION`, on `/companies/borme` |\n| 403 | `TEST_MODE_RESTRICTION` | In the Sandbox, a CIF that is not a test CIF |\n| 404 | `COMPANY_NOT_FOUND` | No company with that CIF or name |\n| 404 | `RISK_PROFILE_NOT_AVAILABLE` | The company has no calculated risk profile |\n| 404 | `NOT_WATCHING` | You removed a company you were not monitoring |\n| 404 | `WEBHOOK_NOT_FOUND` | You have no webhook with that id |\n| 502 | `WEBHOOK_DELIVERY_FAILED` | On `/webhooks/{id}/test`, your server did not accept the test delivery |\n| 400 | `INVALID_EVENT` | When creating a webhook, an event that does not exist |\n\n## Pagination\n\n`/companies/search?multiple=true` and `/companies/filter` return `meta` with `has_more` and `next_cursor`: for the next page, send that value as is in `cursor`. `/watchlist` and `/watchlist/events` paginate with `page` and `limit` while `meta.has_more` is `true`.\n\n## Official SDKs\n\n```\nnpm install apiempresas\npip install apiempresas\ncomposer require apiempresas/apiempresas-php\n```\n\n## AI assistants (MCP)\n\nOfficial MCP server for Claude, Cursor, VS Code and other assistants: `npx -y apiempresas-mcp` with the `APIEMPRESAS_API_KEY` variable. Step-by-step setup in the [guide](https://spaincompanyapi.com/docs#mcp); source on [GitHub](https://github.com/abasmartinc/apiempresas-mcp).\n\nNothing to install: remote server at `https://apiempresas.es/api/mcp` (Claude, ChatGPT, Cursor), with the key in the `X-API-KEY` header or at the end of the URL. Without a key it also answers `search_companies` and `get_company`, with Free-plan data and a daily limit.\n\nService status: [status.apiempresas.es](https://status.apiempresas.es). Support: [soporte@apiempresas.es](mailto:soporte@apiempresas.es).\n"},"servers":[{"url":"https://spaincompanyapi.com/api/sandbox/v1","description":"Sandbox: does not use requests (test CIFs A15075062 and B00000000)"},{"url":"https://spaincompanyapi.com/api/v1","description":"Production: every 200 response uses requests"}],"security":[{"ApiKeyAuth":[]}],"tags":[{"name":"Companies","description":"Company data by CIF or by name, in bulk, KYB verification and name to CIF."},{"name":"Registry and BORME","description":"Filings published in the BORME, recent signals, corporate links and statistics by month and province."},{"name":"Risk and contracts","description":"Risk profile calculated from the BORME, awarded public contracts and grants received (BDNS)."},{"name":"Prospecting","description":"Commercial score, new companies, segments and AI sales tools."},{"name":"Monitoring","description":"Follow changes in your companies without using requests, or every change in the BORME with the changes feed (Business)."},{"name":"Webhooks","description":"Receive changes in monitored companies on your server."},{"name":"Account","description":"Your API key usage and valid filter values."}],"x-tagGroups":[{"name":"Company data","tags":["Companies","Registry and BORME","Risk and contracts"]},{"name":"Sales","tags":["Prospecting"]},{"name":"Alerts","tags":["Monitoring","Webhooks"]},{"name":"Account","tags":["Account"]}],"paths":{"/companies":{"get":{"tags":["Companies"],"summary":"Look up a company by CIF","description":"**Plan:** Free, Pro and Business (on Free, address masked and no directors)\n\nRetrieve the complete profile of a company by providing its CIF or NIF.\n\n#### Parameters\n\n| Field | Type | Description |\n| --- | --- | --- |\n| `cif` | string | **Required.** The company CIF/NIF (e.g. B12345678). |\n| `admin` | boolean | **Optional.** If `true`, includes current directors and officers (appointments minus the removals, resignations and revocations published in the BORME). Pro |\n\n\\* The `administrators` array is only included if you send `admin=true` and your plan supports it.\n\n#### Data Dictionary (Schema)\n\n| Field | Type | Description |\n| --- | --- | --- |\n| `cif` | string | The normalised Tax Identification Code (Spanish CIF/NIF). |\n| `name` | string | The official company name as registered in the BORME. |\n| `status` | enum | Status as it appears in the Registry, not normalised (e.g. `ACTIVA`, `Activa`, `Extinción`). May be empty. In your code, use `status_code`. |\n| `status_code` | enum | Normalised status: `ACTIVE` (active in the Registry), `PRESUMED_ACTIVE` (no status in the Registry, other Registry data present and no BORME event that closes it), `INSOLVENCY` (insolvency proceedings in progress), `IN_LIQUIDATION`, `DISSOLVED`, `REGISTRY_CLOSED` (registry sheet closed), `MERGED` (absorbed), `INACTIVE`, `EXTINCT` or `UNKNOWN` (not enough data to decide, e.g. UTE joint ventures or records with no Registry data). All plans. |\n| `status_source` | string | null | Where `status_code` comes from: `registry` (Registry status) or `borme_analysis` (reading of the BORME acts, which prevails when there is a more serious event than the registered status). |\n| `status_date` | date | null | Date of the status, when known. |\n| `status_confidence` | string | null | How much to trust `status_code` (new on 2026-11-03, all plans): `high`, `medium` or `low`; null when the status is `UNKNOWN`. It does not change the status: it flags when it may be out of date. The reasons are in `status_confidence_reasons`: `RECENT_REGISTRY_ACT` or `NO_RECENT_REGISTRY_ACT` (whether the company has published in the BORME in the last 5 years), `DATED_REGISTRY_EVENT`, `NO_STATUS_DATE`, `OLD_INSOLVENCY` (insolvency over 3 years old with no published conclusion), `ACTIVITY_AFTER_STATUS` (it kept filing acts more than a year later), `REVERSIBLE_STATUS` (registry sheet closed), `PRESUMED_STATUS` and `NOT_FROM_COMMERCIAL_REGISTRY` (`INACTIVE` comes from public sources, not the Commercial Registry). Measured status accuracy: [data sources](https://spaincompanyapi.com/data-sources#status-accuracy). |\n| `status_confidence_reasons` | array[string] | Reasons for `status_confidence` (see above). Empty when the status is `UNKNOWN`. |\n| `tax_id_revocation` | object | null | Revocation or reinstatement of the tax ID (NIF) by the Spanish Tax Agency, as published in the BOE (new on 2026-11-06, all plans). `status`: `REVOKED` (revoked: not valid for tax purposes, and banks cannot make payments to or from its accounts) or `REHABILITATED` (revoked and later reinstated); `date` (BOE date), `boe_id`, `boe_url` and `source` (`boe`). null if the BOE has never published anything about that NIF. In /companies/verify a revoked NIF raises the `TAX_ID_REVOKED` alert and `decision_hint: fail`; in /companies/verify/batch, `invoice_hint: no_facturar`. |\n| `financials` | object | Pro `size_band`: indicative revenue band (`LT_500K`, `500K_1M`, `GT_1M` or `NO_REVENUE`; null if unknown), with its label in `size_band_label`. `last_accounts_year`: latest financial year with filed accounts in our database (a later one may exist that we have not loaded yet). |\n| `identifiers` | object | The company's LEI from GLEIF (all plans). `lei` (null if it has none), `lei_status` as GLEIF gives it (`ISSUED` current, `LAPSED` not renewed, `RETIRED`…), `lei_next_renewal_date`, `lei_source` and `lei_as_of` (date of the GLEIF copy). Mostly held by mid-size and large companies and by those active in financial markets. |\n| `legal_form` | object | Legal form (all plans). `code` (`SL`, `SA`, `SLP`, `SLL`, `SCOOP`, `AIE`, `UTE`, `FUNDACION`…), `label` (in Spanish), `iso20275` (ISO 20275 ELF code, as used by GLEIF and KYB systems; null when the form has no code of its own, e.g. SLNE or UTE) and `source`: `name` (read from the company name) or `cif` (inferred from the CIF letter when the name does not say). |\n| `group` | object | null | Pro Direct parent (`direct_parent`) and ultimate parent (`ultimate_parent`) reported by the company to GLEIF, each with `lei`, `name`, `country` and `cif` (when it is a Spanish company in our database). null if the company has no LEI; both parents null if it has an LEI but reports no parent. |\n| `ownership` | object | Pro Sole shareholder according to the BORME. `unipersonal`: true, false or null (unknown). `sole_shareholder`: `name`, `type` (`company` or `person`), `since` and `url_pdf` (official BORME PDF), or null. `source`: `borme` (latest published single-member act) or `name` (only the name says SLU or SAU; the shareholder is not on record). In Spain only the shareholder of single-member companies is public: the shareholders of companies with several members and the beneficial owner are not published. |\n| `size` | object | null | Pro Headcount band (new on 2026-10-19). `employees_min` and `employees_max`, `label`, `category` (`micro` under 10, `small` 10 to 49, `medium` 50 to 249, `large` 250 or more; EU SME definition), `source` and `as_of`. Sources: `kit_digital` and `kit_consulting` (the band the company declared when it received the Red.es grant, as of the grant date) and `ted` or `placsp` (large company, \"not an SME\", according to its public contract awards; no headcount). null when there is no data: it is never estimated. |\n| `address_density` | object | null | Pro Shared registered address (new on 2026-10-19). `active_companies_at_address`: active companies with exactly the same address, floor and door included (this one counts if active). `level`: `normal`, `shared` (10 or more: an accountant or law firm that provides registered addresses) or `mass` (50 or more: a registered-address centre). `match`: `exact_address`. `as_of`: date of the count (rebuilt weekly). It is a conservative count: the same address written in very different ways counts separately, and office towers do not add up because each company has its own floor. null when the address cannot be compared (no street number, or no postcode or municipality). For KYB: a *mass* address is not fraud, but you should check where the company actually operates. |\n| `province` | string | Spanish province where the registered office is located. |\n| `cnae` / `cnae_label` | string | CNAE industry code for the primary economic activity and its full descriptive label. |\n| `sources` | object | Where each block comes from and how current it is (all plans; new on 2026-10-18). Each entry has `source` and `as_of`, and some have `url_pdf`. `registry`: legal name, incorporation and corporate purpose (`fields`), as of the company's latest BORME notice (`as_of`), with its official PDF in `url_pdf` (Pro, Business or credits); if the entity does not publish in the BORME (associations, foundations, public bodies…), `source` is `other_public_sources`. `status`, `identifiers`, `legal_form`, `group`, `ownership`, `size` and `address_density` repeat the source and date of their block. With `admin=true`, `administrators`: the list is the one in force per the BORME on that date. CNAE, address, coordinates and `financials` are compiled from several public sources and have no entry of their own (see [data sources](https://spaincompanyapi.com/data-sources)). It only adds information: no other field changes. |\n| `administrators[]` | array[object] | Current directors and officers: appointments and re-elections published in the BORME minus later removals, resignations and revocations (none for a dissolved-and-struck-off company). Each object contains `name`, the title (`position`; comma-separated if several), `since`, the date of the current appointment (null if it predates our BORME history), and `url_pdf`, the official BORME PDF of that appointment (null if not available). If the person holds several positions, `since` and `url_pdf` refer to their earliest current appointment. |\n\n#### Data on the Free plan\n\nOn the Free plan (without prepaid credit) the response has the same structure, with these cuts:\n\n- `address` contains the text `*** [ACTUALIZA A PRO PARA VER LA DIRECCION ]`.\n- `corporate_purpose` is cut to 100 characters when longer.\n- `lat` and `lng` are not included.\n- An `upsell_opportunities` object is added. If your code needs to know whether the response is trimmed, check for that field.\n- `financials` is not included. Inside `upsell_opportunities`, `datos_pro` says whether a revenue band and accounts year exist, and how many people currently hold a board position (excluding attorneys-in-fact; `admin=true` on Pro also returns the other posts).\n- `group` and `ownership` are not included. `datos_pro` says whether a sole shareholder is on record (`socio_unico`) and whether the company reports a parent to GLEIF (`grupo_empresarial`).\n- `size` and `address_density` are not included. `datos_pro` says whether a headcount band exists (`tamano_empresa`) and whether 10 or more active companies share the registered address (`domicilio_compartido`).\n- `status_code`, `status_source`, `status_date`, `status_confidence`, `identifiers` (LEI) and `legal_form` are returned as on paid plans.\n- `sources` is returned as well, except `registry.url_pdf` (null) and the `group`, `ownership`, `size` and `address_density` entries, which are not included.\n\nWith a Pro or Business plan, or with prepaid credit, you get the full data without changing your code.","operationId":"3306da725bbecc96cbd63f46540e56ae","parameters":[{"name":"cif","in":"query","description":"CIF of the company to look up","required":true,"schema":{"type":"string"}},{"name":"admin","in":"query","description":"Si es 'true', incluye los administradores y cargos vigentes: nombramientos y reelecciones del BORME menos los ceses, dimisiones y revocaciones publicados después (en una sociedad extinguida, ninguno). Cada uno lleva `since` (fecha del nombramiento vigente; null si es anterior a nuestro histórico) y `url_pdf` (PDF oficial del BORME de ese nombramiento; null si no consta). Exclusivo para planes Pro y Business.","required":false,"schema":{"type":"boolean"}}],"responses":{"200":{"description":"Company data","content":{"application/json":{"schema":{"properties":{"success":{"type":"boolean","example":true},"data":{"type":"object"}},"type":"object"},"example":{"success":true,"data":{"cif":"B12345678","name":"EMPRESA DE EJEMPLO SL","status":"ACTIVA","status_code":"ACTIVE","status_source":"registry","status_date":"2011-02-03","tax_id_revocation":null,"province":"MADRID","cnae":"6201","cnae_label":"Actividades de programación informática","financials":{"size_band":"GT_1M","size_band_label":"Más de 1 M€","last_accounts_year":2023},"identifiers":{"lei":"5493000EJEMPLO000000","lei_status":"ISSUED","lei_next_renewal_date":"2027-03-15","lei_source":"gleif","lei_as_of":"2026-10-15"},"legal_form":{"code":"SL","label":"Sociedad limitada","iso20275":"DP3Q","source":"name"},"group":{"direct_parent":{"lei":"5493000MATRIZ0000000","name":"GRUPO EJEMPLO SA","country":"ES","cif":"A12345674"},"ultimate_parent":{"lei":"5493000MATRIZ0000000","name":"GRUPO EJEMPLO SA","country":"ES","cif":"A12345674"},"source":"gleif","as_of":"2026-10-15"},"ownership":{"unipersonal":true,"sole_shareholder":{"name":"GRUPO EJEMPLO SA","type":"company","since":"2021-06-14","url_pdf":"https://www.boe.es/borme/dias/2021/06/14/pdfs/BORME-A-2021-111-28.pdf"},"source":"borme","as_of":"2021-06-14"},"size":{"employees_min":10,"employees_max":49,"label":"De 10 a 49 empleados","category":"small","source":"kit_digital","as_of":"2024-05-14"},"address_density":{"active_companies_at_address":63,"level":"mass","match":"exact_address","as_of":"2026-10-19"},"sources":{"registry":{"source":"borme","as_of":"2026-09-22","url_pdf":"https://www.boe.es/borme/dias/2026/09/22/pdfs/BORME-A-2026-180-28.pdf","fields":["name","founded","corporate_purpose"]},"status":{"source":"registry","as_of":"2011-02-03"},"identifiers":{"source":"gleif","as_of":"2026-10-15"},"legal_form":{"source":"name","as_of":null},"group":{"source":"gleif","as_of":"2026-10-15"},"ownership":{"source":"borme","as_of":"2021-06-14","url_pdf":"https://www.boe.es/borme/dias/2021/06/14/pdfs/BORME-A-2021-111-28.pdf"},"size":{"source":"kit_digital","as_of":"2024-05-14"},"address_density":{"source":"apiempresas","as_of":"2026-10-19"},"administrators":{"source":"borme","as_of":"2026-09-22"}},"administrators":[{"name":"JUAN PÉREZ GARCÍA","position":"Adm. Unico","since":"2019-03-01","url_pdf":"https://www.boe.es/borme/dias/2019/03/01/pdfs/BORME-A-2019-42-28.pdf"}]}}}}},"400":{"description":"Validation error or wrong CIF format","content":{"application/json":{"schema":{"properties":{"success":{"type":"boolean","example":false},"error":{"description":"Error code: 'VALIDATION_ERROR' or 'INVALID_CIF_FORMAT'","type":"string","example":"INVALID_CIF_FORMAT"},"message":{"type":"string","example":"El CIF proporcionado no tiene un formato válido (debe tener una letra, 7 dígitos y un dígito o letra de control)."}},"type":"object"}}}},"404":{"description":"Company not found","content":{"application/json":{"schema":{"properties":{"success":{"type":"boolean","example":false},"error":{"type":"string","example":"COMPANY_NOT_FOUND"},"message":{"type":"string"}},"type":"object"}}}}}}},"/companies/search":{"get":{"tags":["Companies"],"summary":"Search companies by name","description":"**Plan:** Free, Pro and Business\n\nSearch for companies matching a name or business name. Without `multiple` it returns the best match, favouring companies registered in the Registry over UTE joint ventures and records without data.\n\n#### Parameters\n\n| Field | Type | Description |\n| --- | --- | --- |\n| `name` | string | **Required.** The name or partial name to search for. (Alias: `q`) |\n| `multiple` | boolean | Optional. Without it (or with `false`) `data` is **a single object**: the best match. With `true`, `data` is a **list** and pagination goes in `meta`. |\n| `limit` | integer | Optional, only with `multiple=true`. Results per page (default 20, up to 100). |\n| `page` / `cursor` | integer / string | Optional, only with `multiple=true`. Page to request, or `meta.next_cursor` from the previous response. With `cursor`, send the same `limit` as in the first request too: otherwise 20 is used. |\n\n#### Data Dictionary (Search)\n\n| Field | Type | Description |\n| --- | --- | --- |\n| `data[]` | array[object] | List of matching companies, with the same fields as `/companies` (without directors): `cif`, `name`, `status`, `status_code`, `province`… |\n| `meta.page` | integer | Current page of search results. |\n| `meta.limit` | integer | Maximum number of results per page. |\n| `meta.has_more` | boolean | Indicates whether more results exist for the current search. |\n\n#### Data on the Free plan\n\nOn the Free plan (without credits), the same cuts as /companies: `address` hidden, `corporate_purpose` cut to 100 characters, no `lat`, `lng` or `financials`, and an `upsell_opportunities` object (`campos_ocultos`, `mensaje` and `upgrade_url`) on each company. On Pro, Business or with credits, full data.","operationId":"7505c6f7c5eb0d2af39a3177326b5617","parameters":[{"name":"q","in":"query","description":"Name or CIF of the company to search for","required":true,"schema":{"type":"string"}},{"name":"multiple","in":"query","description":"If true, returns a paginated list of matches. If false, returns the best match.","required":false,"schema":{"type":"boolean","default":false}},{"name":"cursor","in":"query","description":"Opaque pagination cursor (recommended for new integrations). If provided, it overrides `page`.","required":false,"schema":{"type":"string"}},{"name":"limit","in":"query","description":"Maximum results per page (only with multiple=true). Up to 100.","required":false,"schema":{"type":"integer","default":20}},{"name":"page","in":"query","description":"Page number (only with multiple=true).","required":false,"schema":{"type":"integer","default":1}}],"responses":{"200":{"description":"Search results","content":{"application/json":{"schema":{"properties":{"success":{"type":"boolean","example":true},"data":{"type":"array","items":{"type":"object"}}},"type":"object"},"example":{"success":true,"data":[{"cif":"B12345678","name":"EMPRESA DE EJEMPLO SL","status":"ACTIVA","province":"MADRID"}],"meta":{"page":1,"limit":20,"has_more":false}}}}}}}},"/companies/batch":{"post":{"tags":["Companies"],"summary":"Look up to 100 CIFs at once","description":"**Plan:** Pro and Business\n\nQuery up to 100 companies in a single request by sending an array of CIFs. The cost is variable: 1 credit from your monthly quota or wallet per company **found** (HTTP 200). If you don't have enough credits to cover the entire batch, the response will be automatically trimmed to the number of companies you can afford. Pro or Business plan only: Free with credits gets 403.\n\n| Field | Type | Description |\n| --- | --- | --- |\n| `meta.requested` | integer | Number of CIFs sent in the request. |\n| `meta.cost` | integer | Credits deducted from your plan for companies found. |","operationId":"ab63d5b004ffec1d0ccdeb1319290ed6","requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"cifs":{"description":"Array of CIFs to look up (max 100)","type":"array","items":{"type":"string"}},"admin":{"description":"If 'true', includes directors (Pro/Business only)","type":"boolean"}},"type":"object"},"example":{"cifs":["B12345678","A87654321","B00000000"],"admin":true}}}},"responses":{"200":{"description":"Companies found","content":{"application/json":{"schema":{"properties":{"success":{"type":"boolean","example":true},"data":{"type":"array","items":{"type":"object"}},"meta":{"properties":{"requested":{"type":"integer"},"found":{"type":"integer"},"cost":{"type":"integer"},"truncated":{"type":"boolean"}},"type":"object"}},"type":"object"},"example":{"success":true,"data":[{"cif":"B12345678","name":"EMPRESA DE EJEMPLO SL","status":"ACTIVA"},{"cif":"A87654321","name":"OTRA EMPRESA SA","status":"ACTIVA"}],"meta":{"requested":3,"found":2,"cost":2,"truncated":false}}}}}}}},"/companies/verify":{"get":{"tags":["Companies"],"summary":"KYB verification in one call","description":"**Plan:** Pro and Business\n\nIn a single call: whether the company exists and is operating, whether the name you were given matches the registered name, whether the signer is a current director and whether the VAT number is registered in VIES. Returns alerts and a recommendation (`decision_hint`) that you can use as is, or ignore and decide from the data. **Cost: 2 requests.**\n\n| Parameter | Description |\n| --- | --- |\n| `cif` | **Required.** Company CIF. |\n| `name` | Optional. The company name you were given. Compared without accents, punctuation or legal form (0-100; matches from 80). |\n| `person` | Optional. Full name of the signer. Looked up among the current directors, in any word order. |\n| `vat` | Optional. With `true`, checks the EU VAT number in VIES (European Commission). |\n| `eori` | Optional. With `true`, checks whether the company has an EORI number as a customs operator (it can import and export outside the EU), using the European Commission service. Informative: it does not change `decision_hint`. |\n| `iban` | Optional. The IBAN you were given to collect or pay (with or without spaces). Checks that it is well formed: country length, IBAN check digits and, for Spanish accounts, the national check digits. It does not tell who owns the account. |\n\n| decision\\_hint | When |\n| --- | --- |\n| `fail` | The company is not operating: extinct, dissolved, in liquidation, registry sheet closed, absorbed or inactive. Or the Spanish Tax Agency has revoked its tax ID (alert `TAX_ID_REVOKED`, critical). |\n| `review` | Insolvency proceedings, unknown status, name mismatch, signer is not a current director, VAT number not in VIES (if requested), invalid IBAN (if provided) or, on Business, high risk or a strong match on the sanctions lists. |\n| `pass` | None of the above. |\n\n- Each alert in `flags` has `code`, `severity` (critical, high, medium, low) and `message`.\n- If VIES does not respond, `checks.vat.checked` is `false` and the decision is not affected.\n- `checks.eori` (with `eori=true`): in Spain the EORI is `ES` + tax ID. `valid: true` means the company is registered as a customs operator in the EU. `name` and `address` are only returned if the company has agreed to publish them; otherwise `null`. Having no EORI is normal for companies that do not trade outside the EU, so it raises no flag and does not change the decision. If the service does not respond, `checked` is `false`.\n- `checks.iban` returns the masked IBAN, the country, whether it is SEPA and, for Spanish accounts, the bank (`bank_code`) and branch (`branch_code`) codes. If it is not valid, `reason` says why (`FORMAT`, `LENGTH`, `CHECKSUM` or `NATIONAL_CHECK_DIGITS`) and the `IBAN_INVALID` alert (medium) moves the decision to `review`. The IBAN is not stored.\n- `identifiers`, `legal_form`, `group` and `ownership` are the same blocks as in /companies. With `person`, `checks.person.is_sole_shareholder` also says whether the signer is the sole shareholder (a natural person). It is informational and does not change `decision_hint`.\n- `size` and `address_density` are the same as in /companies. When 10 or more active companies share the registered address the `SHARED_ADDRESS` alert (low) is added, and from 50, `MASS_ADDRESS` (medium). Both are informational: they do not change `decision_hint`.\n- `status_confidence` (`high`, `medium` or `low`; null when `UNKNOWN`) and `status_confidence_reasons`: the same as in /companies (since 2026-11-03). Informational: they do not change `decision_hint`.\n- `tax_id_revocation` (since 2026-11-06): the same block as in /companies, in `data`. With `status: REVOKED` you get the `TAX_ID_REVOKED` alert (critical) and `decision_hint: fail`: while the tax ID stays revoked it is not valid for tax purposes and banks cannot make payments to or from the company. `REHABILITATED` (revoked and later reinstated) raises no alert.\n- `sources`: the same as in /companies, plus the source and date of each check performed: `vat` (VIES, real time), `eori` (EOS, real time), `sanctions` (with the date of each list) and `risk` (Business, profile date). Use it to keep evidence of the decision.\n- The latest accounts year is informative: later filings may exist that we have not loaded yet.\n- **Business:** the response adds `risk` (`risk_level`, `risk_score`) and `checks.sanctions`: result on the EU, UN and OFAC sanctions lists for the company and its directors, with the matches (see 10.1).\n- Company not found: 404 `COMPANY_NOT_FOUND` with `decision_hint: \"fail\"` (not charged). Free plan without credit: 403 `PLAN_RESTRICTION`.","operationId":"2da67e1c20cd904deb2c1a7f950150e0","parameters":[{"name":"cif","in":"query","description":"Company CIF","required":true,"schema":{"type":"string"}},{"name":"name","in":"query","description":"Company name you were given, to compare with the official one.","required":false,"schema":{"type":"string"}},{"name":"person","in":"query","description":"Full name of the signatory, to check they are a current director.","required":false,"schema":{"type":"string"}},{"name":"vat","in":"query","description":"If true, checks the intra-EU VAT number in VIES.","required":false,"schema":{"type":"boolean"}},{"name":"eori","in":"query","description":"If true, checks whether the company has an EORI number (customs operator: it can import and export outside the EU) using the European Commission service. Informative: it does not change decision_hint.","required":false,"schema":{"type":"boolean"}},{"name":"iban","in":"query","description":"IBAN you were given to collect or pay: checks that it is well formed (IBAN check digits and, for Spanish accounts, the national ones). It does not tell who owns the account.","required":false,"schema":{"type":"string"}},{"name":"format","in":"query","description":"Con pdf, la respuesta es el expediente de evidencia en PDF (application/pdf) en vez de JSON.","required":false,"schema":{"type":"string","enum":["pdf"]}},{"name":"include_pdf","in":"query","description":"Si es true, el JSON incluye el expediente en PDF en evidence.pdf (base64).","required":false,"schema":{"type":"boolean"}}],"responses":{"200":{"description":"Verification result","content":{"application/json":{"example":{"success":true,"data":{"cif":"B12345678","exists":true,"name":"EMPRESA DE EJEMPLO SL","status":"ACTIVA","status_code":"ACTIVE","status_source":"registry","status_date":null,"tax_id_revocation":null,"identifiers":{"lei":null,"lei_status":null,"lei_next_renewal_date":null,"lei_source":null,"lei_as_of":null},"legal_form":{"code":"SL","label":"Sociedad limitada","iso20275":"DP3Q","source":"name"},"group":null,"ownership":{"unipersonal":true,"sole_shareholder":{"name":"PEREZ GARCIA JUAN","type":"person","since":"2019-03-01","url_pdf":"https://www.boe.es/borme/dias/2019/03/01/pdfs/BORME-A-2019-42-28.pdf"},"source":"borme","as_of":"2019-03-01"},"size":{"employees_min":3,"employees_max":9,"label":"De 3 a 9 empleados","category":"micro","source":"kit_digital","as_of":"2023-03-15"},"address_density":{"active_companies_at_address":1,"level":"normal","match":"exact_address","as_of":"2026-10-19"},"checks":{"name":{"provided":"Empresa de Ejemplo, S.L.","score":100,"match":true},"person":{"provided":"Juan Pérez García","is_current_admin":true,"matched_name":"PEREZ GARCIA JUAN","position":"Adm. Unico","since":"2019-03-01","is_sole_shareholder":true},"vat":{"vat_number":"ESB12345678","checked":true,"valid":true,"source":"VIES","error":null},"eori":{"eori_number":"ESB12345678","checked":true,"valid":true,"name":null,"address":null,"source":"EOS","error":null},"iban":{"provided":"ES91****************1332","valid":true,"country":"ES","sepa":true,"bank_code":"2100","branch_code":"0418","reason":null},"accounts":{"last_accounts_year":2023}},"flags":[],"decision_hint":"pass","checked_at":"2026-09-28T10:30:00+02:00"}}}}},"403":{"description":"Free plan without credits"},"404":{"description":"Company not found"}}}},"/companies/reconcile":{"post":{"tags":["Companies"],"summary":"Name to CIF (bulk)","description":"**Plan:** Pro and Business (and Free with credits)\n\nSend a list of company names and get each one's CIF with a confidence score. Useful to complete or clean customer and supplier databases that have the name but not the CIF. **Cost: 1 request per name with a match (`match`)**; ambiguous names, not-found names and matches to a company whose CIF we do not have yet (`cif: null`) are free.\n\n- Up to 100 names per request. `{\"names\": [\"...\", \"...\"]}` also works.\n- Names are compared without accents, punctuation or legal form. `match`: score 85 or higher and clearly ahead of the next candidate. `ambiguous`: plausible candidates (70 or higher), up to 3 returned. `no_match`: none reaches 70.\n- The province (`province`) is optional and breaks ties between companies with the same name.\n- If your quota runs out, the remaining names come back as `skipped_quota` and are not charged.\n- Pro and Business (and Free with credit). Free plan without credit: 403 `PLAN_RESTRICTION`.","operationId":"edfe0dea4333c3fb1a4aa9dbe2dff1af","requestBody":{"required":true,"content":{"application/json":{"schema":{},"example":{"items":[{"name":"Mercadona, S.A.","province":"Valencia"},{"name":"Talleres Pérez"},{"name":"Panadería Inventada del Norte"}]}}}},"responses":{"200":{"description":"Result per name","content":{"application/json":{"example":{"success":true,"data":[{"input":{"name":"Mercadona, S.A.","province":"Valencia"},"status":"match","score":100,"company":{"cif":"A46103834","name":"MERCADONA SA","province":"VALENCIA","status":"ACTIVA","status_code":"ACTIVE","score":100}},{"input":{"name":"Talleres Pérez","province":null},"status":"ambiguous","candidates":[{"cif":"B12345678","name":"TALLERES PEREZ SL","province":"MADRID","status":"ACTIVA","status_code":"ACTIVE","score":100},{"cif":"A12345674","name":"TALLERES PEREZ SA","province":"SEVILLA","status":"ACTIVA","status_code":"ACTIVE","score":100}]},{"input":{"name":"Panadería Inventada del Norte","province":null},"status":"no_match"}],"meta":{"requested":3,"matched":1,"ambiguous":1,"no_match":1,"invalid":0,"skipped_quota":0,"cost":1,"thresholds":{"match":85,"ambiguous":70}}}}}},"400":{"description":"Invalid input"},"403":{"description":"Free plan without credits"}}}},"/companies/verify/batch":{"post":{"tags":["Companies"],"summary":"Validate tax IDs before invoicing (up to 1,000)","description":"**Plan:** Pro and Business (and Free with credits)\n\nCheck up to 1,000 customer or supplier tax IDs (NIF) in one call before issuing invoices: whether the NIF is well formed, whether the company is registered, its legal name and registered address as recorded, its status and whether the name you have on file matches. Each row comes with a hint, `invoice_hint`: `ok`, `revisar` (review) or `no_facturar` (do not invoice). Built for invoicing and ERP software ahead of Verifactu (2027) and mandatory B2B e-invoicing in Spain (2027-2028). **Cost: 1 request per company found**; malformed NIFs, personal NIFs and NIFs not found are free.\n\n| Body field | Description |\n| --- | --- |\n| `items` | **Required** (or `cifs`). List of up to 1,000 objects `{cif, name, ref}`. `name` (optional): the legal name you have on file, compared with the official one. `ref` (optional): your customer ID, returned as is. |\n| `cifs` | Alternative to `items`: just the list of NIFs. |\n| `vat` | Optional. With `true` it also checks the EU VAT number in VIES. Only for batches of up to 20, because the European Commission service is slow. |\n\n| invoice\\_hint | When |\n| --- | --- |\n| `no_facturar` | Wrong check digit or letter, a sample NIF, a company that is extinct or was absorbed in a merger (invoice the absorbing company), or a tax ID revoked by the Spanish Tax Agency (alert `TAX_ID_REVOKED`). |\n| `revisar` | Insolvency proceedings, dissolved or in liquidation, registry sheet closed, inactive, the name on file does not match (use `legal_name`), the VAT number is not in VIES (if requested), a personal NIF, or a NIF not found as a registered company. |\n| `ok` | None of the above. If we have no data to state the status, you get `ok` with the `STATUS_UNKNOWN` flag (low): the company is registered. |\n\n- Results come in the same order as the request. `valid_format` checks the control digit or letter of CIF, DNI and NIE.\n- `exists: false` (not found) does not mean the NIF is fake: it may be an entity that is not registered in the Mercantile Registry (association, joint ownership, public body) or a typo. For personal NIFs, `exists` is `null`: we do not provide data on sole traders (GDPR).\n- `name_check` compares without accents, punctuation or legal form (0-100; matches from 80). A trade name (\"Inditex\") does not match the legal name (\"Industria de Diseño Textil SA\"): that is why `legal_name` gives you the name that must appear on the invoice.\n- `address` is the registered office according to the Registry and the BORME. It may differ from the tax address.\n- `status_confidence` (`high`, `medium` or `low`; null when `UNKNOWN`) and `status_confidence_reasons` on every company found: the same as in /companies (since 2026-11-03). Informational: they do not change `invoice_hint`.\n- `tax_id_revocation` on every company found (since 2026-11-06): the same block as in /companies. A revoked tax ID gives `invoice_hint: no_facturar` with the `TAX_ID_REVOKED` alert.\n- `meta.summary` counts the rows of each hint. A NIF repeated in the list is charged once.\n- If your quota runs out, the companies that do not fit come back with `processed: false` and the `NOT_PROCESSED_QUOTA` flag, and are not charged. No quota or credit left: 429 `QUOTA_EXCEEDED`.\n- **It does not check against the Tax Agency (AEAT) census** (only the taxpayer can use that service, with their own certificate). It helps fix errors before issuing; it does not guarantee that the AEAT accepts the record. Messages in `flags` are in Spanish; use `code` in your logic.\n- In the Sandbox, any NIF's format is checked, but only A15075062 is resolved; other valid CIFs come back with `processed: false`.\n- Pro and Business (and Free with credit). Free plan without credit: 403 `PLAN_RESTRICTION`. For a single company with more checks (signatory, IBAN, sanctions), use KYB verification.","operationId":"403b3c12fb46ef4ccae81f263c3b881a","requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"items":{"description":"List of {cif, name?, ref?} (max. 1,000). `name`: the legal name you have on file; `ref`: your own ID, returned as is.","type":"array","items":{"properties":{"cif":{"type":"string","example":"A15075062"},"name":{"type":"string","example":"Inditex"},"ref":{"type":"string","example":"cliente-0042"}},"type":"object"}},"cifs":{"description":"Alternative to items: just the NIFs.","type":"array","items":{"type":"string"}},"vat":{"description":"Check the EU VAT number in VIES (batches of up to 20 only).","type":"boolean"}},"type":"object"},"example":{"items":[{"cif":"A46103834","name":"Mercadona","ref":"cli-001"},{"cif":"A15075062","name":"Inditex","ref":"cli-002"},{"cif":"A46103835","ref":"cli-003"},{"cif":"12345678Z","ref":"cli-004"}]}}}},"responses":{"200":{"description":"One result per NIF, in the same order","content":{"application/json":{"example":{"success":true,"data":[{"input":"A46103834","cif":"A46103834","ref":"cli-001","valid_format":true,"processed":true,"exists":true,"legal_name":"MERCADONA SA","address":{"street":"CALLE VALENCIA 5","postal_code":"46016","municipality":"TAVERNES BLANQUES","province":"VALENCIA"},"status_code":"ACTIVE","status_date":null,"tax_id_revocation":null,"name_check":{"provided":"Mercadona","score":100,"match":true},"invoice_hint":"ok","flags":[]},{"input":"A15075062","cif":"A15075062","ref":"cli-002","valid_format":true,"processed":true,"exists":true,"legal_name":"INDUSTRIA DE DISENO TEXTIL SA","address":{"street":"AVENIDA DE LA DIPUTACION (ED INDITEX), S/N","postal_code":"15142","municipality":"ARTEIXO","province":"A CORUÑA"},"status_code":"ACTIVE","status_date":null,"tax_id_revocation":null,"name_check":{"provided":"Inditex","score":42,"match":false},"invoice_hint":"revisar","flags":[{"code":"NAME_MISMATCH","severity":"high","message":"El nombre que tienes guardado no coincide con la razón social: usa legal_name en la factura."}]},{"input":"A46103835","cif":"A46103835","ref":"cli-003","valid_format":false,"processed":true,"exists":null,"invoice_hint":"no_facturar","flags":[{"code":"INVALID_FORMAT","severity":"high","message":"El NIF no tiene un formato válido (dígito o letra de control incorrectos)."}]},{"input":"12345678Z","cif":"12345678Z","ref":"cli-004","valid_format":true,"processed":true,"exists":null,"invoice_hint":"revisar","flags":[{"code":"PERSON_NIF","severity":"info","message":"NIF de persona física (autónomo o particular): la letra de control es correcta, pero no damos datos de personas (RGPD)."}]}],"meta":{"requested":4,"found":2,"cost":2,"truncated":false,"summary":{"ok":1,"revisar":2,"no_facturar":1,"not_processed":0},"checked_at":"2026-10-25T10:00:00+02:00","note":"No sustituye la comprobación contra el censo de la AEAT. Razón social y domicilio según el Registro Mercantil y el BORME."}}}}},"400":{"description":"Malformed request"},"403":{"description":"Requires a Pro or Business plan, or credit"},"429":{"description":"No quota or credit left"}}}},"/companies/borme":{"get":{"tags":["Registry and BORME"],"summary":"BORME filing history","description":"**Plan:** Pro and Business\n\nGet the complete chronological history of publications in the Spanish Commercial Registry (BORME) for a company. Pro, Business and Free with credits. Free without credits: 403 `UPGRADE_REQUIRED`.\n\n#### Parameters\n\n| Field | Type | Description |\n| --- | --- | --- |\n| `cif` | string | **Required.** The company CIF/NIF (e.g. B12345678). |\n\n| Field | Type | Description |\n| --- | --- | --- |\n| `events[].date` | string | Official BORME publication date (YYYY-MM-DD format). |\n| `events[].act_types` | string | Categorised corporate act type (e.g. Appointments, Capital Increase). |\n| `events[].url_pdf` | string | Direct URL to the original PDF scan of the Official Gazette. |","operationId":"f655ee02cbbfc1cc1de85653490940b2","parameters":[{"name":"cif","in":"query","description":"CIF of the company to look up","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Company BORME history","content":{"application/json":{"schema":{"properties":{"success":{"type":"boolean","example":true},"data":{"properties":{"cif":{"type":"string","example":"B12345678"},"company_name":{"type":"string","example":"EMPRESA DE EJEMPLO SL"},"events":{"type":"array","items":{"properties":{"date":{"type":"string","format":"date","example":"2023-11-01"},"act_types":{"type":"string","example":"Nombramientos, Ceses"},"description":{"type":"string","example":"Ceses/Dimisiones. Administrador único: JUAN PEREZ..."},"url_pdf":{"type":"string","example":"https://www.boe.es/borme/dias/2023/11/01/pdfs/BORME-A-2023-100-28.pdf"}},"type":"object"}}},"type":"object"}},"type":"object"},"example":{"success":true,"data":{"cif":"B12345678","company_name":"EMPRESA DE EJEMPLO SL","events":[{"date":"2023-11-01","act_types":"Nombramientos, Ceses","description":"Ceses/Dimisiones. Administrador único: JUAN PEREZ...","url_pdf":"https://www.boe.es/borme/dias/2023/11/01/pdfs/BORME-A-2023-100-28.pdf"}]}}}}},"400":{"description":"Validation error","content":{"application/json":{"schema":{"properties":{"success":{"type":"boolean","example":false},"error":{"type":"string","example":"VALIDATION_ERROR"},"message":{"type":"string"}},"type":"object"}}}},"403":{"description":"Plan not sufficient","content":{"application/json":{"schema":{"properties":{"success":{"type":"boolean","example":false},"error":{"type":"string","example":"UPGRADE_REQUIRED"},"message":{"type":"string","example":"Este endpoint requiere un plan Pro o Business."}},"type":"object"}}}},"404":{"description":"Company not found","content":{"application/json":{"schema":{"properties":{"success":{"type":"boolean","example":false},"error":{"type":"string","example":"COMPANY_NOT_FOUND"},"message":{"type":"string"}},"type":"object"}}}}}}},"/stats":{"get":{"tags":["Registry and BORME"],"summary":"BORME statistics by month and province","description":"**Plan:** Free, Pro and Business\n\n> Not available in the Sandbox: this endpoint only works in production.\n\nHow many companies are incorporated, dissolved, struck off or enter insolvency each month or year, in all of Spain or in one province, according to the filings published in the BORME. Useful for market reports, dashboards and to put a risk analysis in context.\n\n| Parameter | Type | Required | Description |\n| --- | --- | --- | --- |\n| `metrics` | string | Optional | Comma-separated metrics (table below). Default: all. |\n| `province` | string | Optional | Commercial Registry province: the name from /catalog (e.g. `MADRID`) or the INE code (e.g. `28`). Without it, all of Spain. |\n| `from` | string | Optional | First month (`YYYY-MM`) or year (`YYYY`). Default: 11 months before `to`. Data since 2009. |\n| `to` | string | Optional | Last month or year. Default: the current month. |\n| `group` | string | Optional | `month` (default) or `year`. |\n\n| Metric | BORME filings |\n| --- | --- |\n| `incorporations` | Incorporations |\n| `dissolutions` | Dissolutions |\n| `extinctions` | Extinctions (struck off) |\n| `insolvencies` | Insolvency proceedings |\n| `capital_increases` | Capital increases |\n| `capital_reductions` | Capital reductions |\n| `address_changes` | Changes of registered address |\n| `mergers` | Mergers |\n\n#### Response (200 OK)\n\n- Counts filings in section A of the BORME by gazette date and Commercial Registry province. A filing with several types (e.g. \"Disolución, Extinción\") counts in each one.\n- The current month is incomplete; `meta.last_borme_date` is the latest day counted. Data is recalculated daily.\n- Months without filings return `0`, so the series has no gaps. `meta.notes` is in Spanish.\n- **Dissolutions and insolvencies cannot be compared between provinces.** Each Commercial Registry records these acts its own way: in September 2026 Barcelona published 36 dissolutions and 0 insolvencies, and Madrid 418 and 58, although Barcelona published 258 extinctions. Use them to follow the trend within one province. To measure closures, use `extinctions`; the full insolvency record is the Registro Público Concursal. If you request these metrics, `meta.metric_notes` carries the warning (in Spanish).\n- **Cost:** 1 request (3 credits from a top-up). All plans. Not available in the Sandbox.","operationId":"5cddf48714e0485ee422d9cfb0161d05","parameters":[{"name":"metrics","in":"query","description":"Comma-separated metrics: incorporations, dissolutions, extinctions, insolvencies, capital_increases, capital_reductions, address_changes, mergers. Default: all.","required":false,"schema":{"type":"string"}},{"name":"province","in":"query","description":"Commercial Registry province (name from /catalog, e.g. MADRID, or INE code, e.g. 28). Without it, all of Spain.","required":false,"schema":{"type":"string"}},{"name":"from","in":"query","description":"First month (YYYY-MM) or year (YYYY). Default: 11 months before to.","required":false,"schema":{"type":"string"}},{"name":"to","in":"query","description":"Last month (YYYY-MM) or year (YYYY). Default: the current month.","required":false,"schema":{"type":"string"}},{"name":"group","in":"query","description":"month (default) or year.","required":false,"schema":{"type":"string","default":"month"}}],"responses":{"200":{"description":"Series by period","content":{"application/json":{"example":{"success":true,"data":{"province":"MADRID","province_code":"28","group":"month","from":"2026-08","to":"2026-10","totals":{"incorporations":4210,"extinctions":1187},"series":[{"period":"2026-08","incorporations":1085,"extinctions":312},{"period":"2026-09","incorporations":1912,"extinctions":523},{"period":"2026-10","incorporations":1213,"extinctions":352}]},"meta":{"source":"borme","last_borme_date":"2026-10-16","computed_at":"2026-10-16 21:05:12","notes":"Actos publicados en el BORME (sección A) por la fecha del boletín y la provincia del Registro. El mes en curso está incompleto. Un acto con varios tipos cuenta en cada uno."}}}}},"400":{"description":"Invalid parameter"},"503":{"description":"Statistics not calculated yet"}},"servers":[{"url":"https://spaincompanyapi.com/api/v1","description":"Production"}]}},"/companies/signals":{"get":{"tags":["Registry and BORME"],"summary":"Recent corporate signals","description":"**Plan:** Pro and Business\n\nThe latest BORME act that counts towards the company's commercial score. The list has one item at most. Free plan: 403 `PLAN_RESTRICTION` with the number of events in `upsell_opportunities.eventos_ocultos`.\n\n| Field | Type | Description |\n| --- | --- | --- |\n| `signals[]` | array[object] | One item at most: `type` (always `borme_event`), `label` (type of act) and `date`. |\n| `signals[].probability` | string | The company's commercial priority, the same as `priority` on `/companies/score`: `muy_alta`, `alta`, `media`, `baja` or `muy_baja`. It is not the reliability of the event. |\n| `signals[].url_pdf` | string | null | Official BORME PDF for the day of the signal (`null` if not recorded). |","operationId":"03e9cb58fe9920dd2a821da49ddd7921","parameters":[{"name":"cif","in":"query","description":"Company CIF","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Company corporate signals","content":{"application/json":{"schema":{"properties":{"success":{"type":"boolean","example":true},"data":{"type":"object"}},"type":"object"},"example":{"success":true,"data":{"cif":"A46103834","signals":[{"type":"borme_event","label":"Ampliación de capital","date":"2026-09-15","probability":"muy_alta","url_pdf":"https://www.boe.es/borme/dias/2026/09/15/pdfs/BORME-A-2026-176-15.pdf"}]}}}}}}}},"/companies/network":{"get":{"tags":["Registry and BORME"],"summary":"Corporate network","description":"**Plan:** Pro and Business\n\nGets the corporate network linking companies through their directors. Requires the `cif` parameter. Pro, Business and Free with credits; on Free without credits, 403 `PLAN_RESTRICTION` with the counts in `data.stats`. If the company has no known directors, it returns 200 with only the company node, no `stats` and a `message` (charged like any other request).\n\n| Field | Type | Description |\n| --- | --- | --- |\n| `nodes[]` | array[object] | Graph nodes (companies or directors). |\n| `edges[]` | array[object] | Connections (links) between nodes. |","operationId":"b5b7a1477c590925db6c3751ca3660ec","parameters":[{"name":"cif","in":"query","description":"CIF of the base company","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Graph of nodes and links (companies and directors)","content":{"application/json":{"schema":{"properties":{"success":{"type":"boolean","example":true},"data":{"type":"object"}},"type":"object"},"example":{"success":true,"data":{"nodes":[{"id":"C_123","type":"company","label":"EMPRESA DE EJEMPLO SL","cif":"B12345678","root":true},{"id":"A_abc","type":"administrator","label":"JUAN PEREZ GARCIA"}],"edges":[{"source":"A_abc","target":"C_123","label":"Administrador"}],"stats":{"total_administrators":1,"total_linked_companies":1}}}}}}}}},"/companies/risk-profile":{"get":{"tags":["Risk and contracts"],"summary":"Risk and solvency profile","description":"**Plan:** Business\n\nReturns the corporate risk profile, registry compliance (annual accounts filing), governance stability, capital volatility, and official distress alerts associated with a company by CIF. Designed to automate credit scoring, solvency checks, and compliance in B2B onboarding workflows.\n\n| Parameter | Type | Required | Description |\n| --- | --- | --- | --- |\n| `cif` | string | Required | Company CIF/NIF to audit (e.g. `A01001411` or `A15075062` in Sandbox). |\n\n#### Plan restricted response (403 Forbidden - Free & Pro Plans)\n\n```\n{\n  \"success\": false,\n  \"error\": \"PLAN_RESTRICTION\",\n  \"message\": \"El acceso al perfil de riesgo corporativo requiere el plan Business.\",\n  \"upsell_opportunities\": {\n    \"mensaje\": \"Nivel de riesgo de esta empresa: MEDIO. Con el plan Business ves la puntuación, las seis dimensiones, el estado legal y cada evento del BORME que lo explica.\",\n    \"upgrade_url\": \"https://apiempresas.es/billing?plan=business&source=api_403_risk\",\n    \"perfil_disponible\": true,\n    \"nivel_riesgo\": \"MEDIO\"\n  }\n}\n```\n\n`nivel_riesgo` only appears on paid plans; on Free you only get whether a profile exists (`perfil_disponible`). Up to 25 responses with this summary per account per day.\n\n| Field | Type | Description |\n| --- | --- | --- |\n| `risk_score` | integer (0-100) | Consolidated algorithmic risk rating (higher values denote higher default or distress risk). |\n| `risk_level` | string | Qualitative risk grade: `BAJO`, `MEDIO`, `ALTO`, `CRITICO`. |\n| `dimensions` | object | Detailed breakdown of risk factors: legal distress, filing compliance, governance changes, capital instability and credit mitigation. |\n| `canonical_events[]` | array[object] | Chronological list of official corporate and mercantile registry events with severity assessment. |","operationId":"7b9f77b80bc5fc065e5157fe0cee8b54","parameters":[{"name":"cif","in":"query","description":"CIF of the company to look up","required":true,"schema":{"type":"string","example":"A01001411"}}],"responses":{"200":{"description":"Company risk profile","content":{"application/json":{"schema":{"properties":{"success":{"type":"boolean","example":true},"data":{"properties":{"cif":{"type":"string","example":"A01001411"},"company_name":{"type":"string","example":"RHEINMETALL EXPAL MUNITIONS SA"},"risk_score":{"type":"integer","example":62},"risk_level":{"type":"string","example":"ALTO"},"confidence_score":{"type":"integer","example":49,"nullable":true},"data_quality_score":{"type":"integer","example":70,"nullable":true},"summary_message":{"type":"string","example":"Atención: Constan indicadores de elevado riesgo financiero o corporativo.","nullable":true},"legal_state":{"type":"string","example":"REGISTRY_CLOSURE_GENERICO","nullable":true},"data_sources":{"properties":{"borme_status":{"type":"string","example":"CHECKED_WITH_RECORDS","nullable":true},"accounts_status":{"type":"string","example":"KNOWN_DELAYED","nullable":true},"official_status":{"type":"string","example":"KNOWN","nullable":true}},"type":"object"},"dimensions":{"properties":{"legal_distress":{"type":"integer","example":60},"filing_compliance":{"type":"integer","example":0},"governance_volatility":{"type":"integer","example":30},"capital_instability":{"type":"integer","example":0},"structural_volatility":{"type":"integer","example":0},"stabilizing_credit":{"type":"integer","example":0}},"type":"object"},"canonical_events":{"type":"array","items":{"properties":{"code":{"type":"string","example":"LEGAL_STATE_REGISTRY_CLOSURE_GENERICO","nullable":true},"dimension":{"type":"string","example":"legal_distress","nullable":true},"severity":{"type":"string","example":"high","nullable":true},"description":{"type":"string","example":"Consta publicación registral de cierre sin especificación de causa.","nullable":true},"event_date":{"type":"string","format":"date","example":"2026-08-24","nullable":true},"classification_confidence":{"type":"string","example":"LOW","nullable":true}},"type":"object"}},"model_version":{"type":"string","example":"2.0.0"},"calculated_at":{"type":"string","format":"date-time","example":"2026-08-24T00:00:00Z","nullable":true}},"type":"object"}},"type":"object"},"example":{"success":true,"data":{"cif":"A01001411","company_name":"RHEINMETALL EXPAL MUNITIONS SA","risk_score":62,"risk_level":"ALTO","confidence_score":49,"data_quality_score":70,"summary_message":"Atención: Constan indicadores de elevado riesgo financiero o corporativo.","legal_state":"REGISTRY_CLOSURE_GENERICO","data_sources":{"borme_status":"CHECKED_WITH_RECORDS","accounts_status":"KNOWN_DELAYED","official_status":"KNOWN"},"dimensions":{"legal_distress":60,"filing_compliance":0,"governance_volatility":30,"capital_instability":0,"structural_volatility":0,"stabilizing_credit":0},"canonical_events":[{"code":"LEGAL_STATE_REGISTRY_CLOSURE_GENERICO","dimension":"legal_distress","severity":"high","description":"Consta publicación registral de cierre sin especificación de causa.","event_date":"2026-08-24","classification_confidence":"LOW"}],"model_version":"2.0.0","calculated_at":"2026-08-24T00:00:00Z"}}}}},"400":{"description":"Parameter validation error","content":{"application/json":{"schema":{"properties":{"success":{"type":"boolean","example":false},"error":{"type":"string","example":"VALIDATION_ERROR"},"message":{"type":"string","example":"El parámetro \"cif\" es obligatorio."}},"type":"object"}}}},"401":{"description":"Unauthorized (invalid or inactive API key)","content":{"application/json":{"schema":{"properties":{"success":{"type":"boolean","example":false},"error":{"type":"string","example":"UNAUTHORIZED"},"message":{"type":"string","example":"API key inválida o inactiva."}},"type":"object"}}}},"403":{"description":"Plan restriction (Business only)","content":{"application/json":{"schema":{"properties":{"success":{"type":"boolean","example":false},"error":{"type":"string","example":"PLAN_RESTRICTION"},"message":{"type":"string","example":"El acceso al perfil de riesgo corporativo requiere el plan Business."}},"type":"object"}}}},"404":{"description":"Company not found or profile not available","content":{"application/json":{"schema":{"properties":{"success":{"type":"boolean","example":false},"error":{"type":"string","example":"COMPANY_NOT_FOUND"},"message":{"type":"string","example":"Empresa no encontrada."}},"type":"object"}}}},"429":{"description":"Rate limit exceeded","content":{"application/json":{"schema":{"properties":{"success":{"type":"boolean","example":false},"error":{"type":"string","example":"TOO_MANY_REQUESTS"},"message":{"type":"string","example":"Has superado el límite de peticiones."}},"type":"object"}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"properties":{"success":{"type":"boolean","example":false},"error":{"type":"string","example":"SERVER_ERROR"},"message":{"type":"string","example":"Se ha producido un error interno al consultar el perfil de riesgo."}},"type":"object"}}}}}}},"/companies/contracts":{"get":{"tags":["Risk and contracts"],"summary":"Public contracts and awards","description":"**Plan:** Business\n\nQuery public procurement contracts and awards associated with Spanish companies by CIF. Retrieve contracting authority details, award amounts, award dates, and official tender links.\n\n| Parameter | Type | Required | Description |\n| --- | --- | --- | --- |\n| `cif` | string | Required | Company CIF/NIF to query (e.g. `A01001411`). |\n| `page` | integer | Optional | Page number to retrieve. Default: `1`. |\n| `limit` | integer | Optional | Number of contracts per page. Default: `20` (maximum: `100`). |\n\n#### Plan restricted response (403 Forbidden - Free & Pro Plans)\n\n```\n{\n  \"success\": false,\n  \"error\": \"PLAN_RESTRICTION\",\n  \"message\": \"El acceso a contratos públicos requiere el plan Business.\",\n  \"upsell_opportunities\": {\n    \"mensaje\": \"Esta empresa tiene 14 contratos públicos adjudicados por 2.318.400 €. Con el plan Business ves cada contrato: órgano, título, fecha, importe y enlace a la licitación.\",\n    \"upgrade_url\": \"https://apiempresas.es/billing?plan=business&source=api_403_contracts\",\n    \"contratos_detectados\": 14,\n    \"importe_total\": 2318400.0,\n    \"currency\": \"EUR\",\n    \"ultima_adjudicacion\": \"2026-06-12\"\n  }\n}\n```\n\nThe `upsell_opportunities` summary is included in up to 25 403 responses per account per day; after that they only carry `mensaje` and `upgrade_url`.","operationId":"913bc49002ae09495216682d7892e506","parameters":[{"name":"cif","in":"query","description":"CIF of the company to look up","required":true,"schema":{"type":"string","example":"A10007516"}},{"name":"page","in":"query","description":"Page number (>= 1). Default: 1.","required":false,"schema":{"type":"integer","default":1}},{"name":"limit","in":"query","description":"Results per page (1 to 100). Default: 20.","required":false,"schema":{"type":"integer","default":20}}],"responses":{"200":{"description":"Company public contracts history","content":{"application/json":{"schema":{"properties":{"success":{"type":"boolean","example":true},"data":{"properties":{"cif":{"type":"string","example":"A10007516"},"company_name":{"type":"string","example":"CONSTRUCCIONES ALOR SA"},"summary":{"properties":{"total_contracts":{"type":"integer","example":14},"total_amount":{"type":"string","example":"311190.55"},"currency":{"type":"string","example":"EUR"}},"type":"object"},"contracts":{"type":"array","items":{"properties":{"tender_id":{"type":"string","example":"https://contrataciondelestado.es/sindicacion/licitacionesPerfilContratante/16026766","nullable":true},"title":{"type":"string","example":"Obras de Restauración de la Ermita de San Jorge de Alor en Cáceres","nullable":true},"contracting_authority":{"type":"string","example":"Consejería de Cultura, Turismo, Jóvenes y Deportes","nullable":true},"award_date":{"type":"string","format":"date","example":"2024-12-30","nullable":true},"amount":{"type":"string","example":"311190.55","nullable":true},"currency":{"type":"string","example":"EUR"},"tender_url":{"type":"string","example":"https://contrataciondelestado.es/wps/poc?uri=deeplink:detalle_licitacion&idEvl=T1rE11yqCklWhbmkna2nXQ%3D%3D","nullable":true}},"type":"object"}},"pagination":{"properties":{"total":{"type":"integer","example":14},"page":{"type":"integer","example":1},"limit":{"type":"integer","example":20},"total_pages":{"type":"integer","example":1},"has_more":{"type":"boolean","example":false}},"type":"object"}},"type":"object"}},"type":"object"},"example":{"success":true,"data":{"cif":"A01001411","company_name":"RHEINMETALL EXPAL MUNITIONS SA","summary":{"total_contracts":32,"total_amount":"617746086.47","currency":"EUR","by_year":[{"year":2026,"contracts":6,"amount":"48211904.10"},{"year":2025,"contracts":9,"amount":"201377410.52"}]},"contracts":[{"tender_id":"https://contrataciondelestado.es/sindicacion/licitacionesPerfilContratante/20344437","title":"Suministro de 27.000 granadas de mortero de 81 mm...","contracting_authority":"Jefatura de Asuntos Económicos del Mando de Apoyo Logístico","award_date":"2026-08-25","amount":"4395320.00","currency":"EUR","tender_url":"https://contrataciondelestado.es/wps/poc?uri=deeplink:detalle_licitacion&idEvl=B4EkDEGFvaA%2Bk2oCbDosIw%3D%3D"}],"pagination":{"total":32,"page":1,"limit":20,"total_pages":2,"has_more":true}}}}}},"400":{"description":"Parameter validation error","content":{"application/json":{"schema":{"properties":{"success":{"type":"boolean","example":false},"error":{"type":"string","example":"VALIDATION_ERROR"},"message":{"type":"string","example":"El parámetro \"cif\" es obligatorio."}},"type":"object"}}}},"401":{"description":"Unauthorized (invalid or inactive API key)","content":{"application/json":{"schema":{"properties":{"success":{"type":"boolean","example":false},"error":{"type":"string","example":"UNAUTHORIZED"},"message":{"type":"string","example":"API key inválida o inactiva."}},"type":"object"}}}},"403":{"description":"Plan restriction (Business only)","content":{"application/json":{"schema":{"properties":{"success":{"type":"boolean","example":false},"error":{"type":"string","example":"PLAN_RESTRICTION"},"message":{"type":"string","example":"El acceso a contratos públicos requiere el plan Business."}},"type":"object"}}}},"404":{"description":"Company not found","content":{"application/json":{"schema":{"properties":{"success":{"type":"boolean","example":false},"error":{"type":"string","example":"COMPANY_NOT_FOUND"},"message":{"type":"string","example":"Empresa no encontrada."}},"type":"object"}}}},"429":{"description":"Rate limit exceeded","content":{"application/json":{"schema":{"properties":{"success":{"type":"boolean","example":false},"error":{"type":"string","example":"TOO_MANY_REQUESTS"},"message":{"type":"string","example":"Has superado el límite de peticiones."}},"type":"object"}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"properties":{"success":{"type":"boolean","example":false},"error":{"type":"string","example":"SERVER_ERROR"},"message":{"type":"string","example":"Se ha producido un error interno al consultar los contratos públicos."}},"type":"object"}}}}}}},"/companies/subsidies":{"get":{"tags":["Risk and contracts"],"summary":"Public grants and subsidies","description":"**Plan:** Business\n\nGrants, loans, guarantees and tax benefits awarded to a company according to Spain's **National Grants Database (BDNS)**, since 2022, including the Kit Digital and Kit Consulting programmes. Returns a summary (total, by year, by instrument and the 10 calls with the largest amount) and the list of grants, newest first, paginated.\n\nUseful to know whether a customer or supplier depends on public funding, for due diligence and for prospecting (companies that have just received funds to digitalise or invest). Companies only: grants to individuals are not published here.\n\n| Parameter | Type | Required | Description |\n| --- | --- | --- | --- |\n| `cif` | string | Required | CIF of the company (e.g. `A38666897`). |\n| `year` | integer | Optional | Only grants awarded in that year (e.g. `2025`). The summary is computed for that year too. |\n| `page` | integer | Optional | Page number. Default: `1`. |\n| `limit` | integer | Optional | Grants per page. Default: `20` (max: `100`). |\n\n#### Restricted response (403 Forbidden - Free and Pro plans)\n\n```\n{\n  \"success\": false,\n  \"error\": \"PLAN_RESTRICTION\",\n  \"message\": \"Las subvenciones y ayudas públicas requieren el plan Business.\",\n  \"upsell_opportunities\": {\n    \"mensaje\": \"Esta empresa tiene 133 subvenciones o ayudas públicas por 181.848 €. Con el plan Business ves cada una: convocatoria, fecha, importe e instrumento.\",\n    \"upgrade_url\": \"https://apiempresas.es/billing?plan=business&source=api_403_subsidies\",\n    \"subvenciones_detectadas\": 133,\n    \"importe_total\": 181847.85,\n    \"currency\": \"EUR\",\n    \"ultima_concesion\": \"2025-01-08\"\n  }\n}\n```\n\nAmounts are strings with two decimals, as in Public Contracts. Call and instrument names are returned in Spanish, as published by the BDNS. `sources.subsidies.as_of` is the date of the last load from the BDNS. 403 responses do not use quota, and the `upsell_opportunities` summary is included in up to 25 403 responses per account per day. **Cost on Business:** 1 request per call.","operationId":"1bdd38c7e14ce52457c1080917f116f0","parameters":[{"name":"cif","in":"query","description":"CIF of the company to look up","required":true,"schema":{"type":"string","example":"A38666897"}},{"name":"year","in":"query","description":"Only grants awarded in that year (e.g. 2025).","required":false,"schema":{"type":"integer"}},{"name":"page","in":"query","description":"Page number (>= 1). Default: 1.","required":false,"schema":{"type":"integer","default":1}},{"name":"limit","in":"query","description":"Grants per page (1 to 100). Default: 20.","required":false,"schema":{"type":"integer","default":20}}],"responses":{"200":{"description":"Summary and grants of the company","content":{"application/json":{"example":{"success":true,"data":{"cif":"A38666897","company_name":"BINTER CANARIAS SA","year":null,"summary":{"total_grants":133,"total_amount":"181847.85","currency":"EUR","first_grant_date":"2024-12-26","last_grant_date":"2025-01-08","by_year":[{"year":2025,"grants":129,"amount":"179842.14"},{"year":2024,"grants":4,"amount":"2005.71"}],"by_instrument":[{"instrument":"SUBVENCIÓN y ENTREGA DINERARIA SIN CONTRAPRESTACIÓN","grants":133,"amount":"181847.85"}],"top_calls":[{"call":"Subvenciones al transporte aéreo para residentes en Canarias, Baleares, Ceuta y Melilla","grants":133,"amount":"181847.85","last_grant_date":"2025-01-08"}]},"grants":[{"grant_date":"2025-01-08","amount":"228.75","currency":"EUR","call":"Subvenciones al transporte aéreo para residentes en Canarias, Baleares, Ceuta y Melilla","instrument":"SUBVENCIÓN y ENTREGA DINERARIA SIN CONTRAPRESTACIÓN","grant_code":"SB123457636"}],"pagination":{"total":133,"page":1,"limit":20,"total_pages":7,"has_more":true},"sources":{"subsidies":{"source":"bdns","as_of":"2026-10-18","from":"2022-01-01"}}}}}}},"400":{"description":"Validation error"},"403":{"description":"Plan restriction (Business only)"},"404":{"description":"Company not found"}}}},"/tenders":{"get":{"tags":["Risk and contracts"],"summary":"Open public tenders","description":"**Plan:** Business (on Free and Pro, tender count and 3 samples)\n\n> Not available in the Sandbox: this endpoint only works in production.\n\nPublic tenders **open for bids today** across Spain: those on the Public Sector Procurement Platform and those of the regional platforms that publish there. For each one: title, contracting authority, province, type, procedure, amount, CPV, bid deadline, days left and a link to the notice to submit a bid. Updated daily.\n\nNot to be confused with Public Contracts: those are awards already decided (who won what); these are tenders still accepting bids.\n\n| Parameter | Type | Required | Description |\n| --- | --- | --- | --- |\n| `q` | string | Optional | Words in the title; all must appear (min. 3 letters). E.g. `limpieza colegios`. |\n| `cpv` | string | Optional | One or more CPV codes or their prefix, comma-separated (up to 20). E.g. `72,48` (IT) or `90911200`. |\n| `province` | string | Optional | Province of the contracting authority. Variants accepted: `Bizkaia`, `Gerona`, `Baleares`... |\n| `type` | string | Optional | `supplies`, `services` or `works`. |\n| `procedure` | string | Optional | Procedure code: `1` open, `9` simplified open, `2` restricted, `4` negotiated with notice, `13` competitive procedure with negotiation... |\n| `min_amount / max_amount` | number | Optional | Amount excluding VAT, in euros. |\n| `deadline_from / deadline_to` | date | Optional | Bid deadline between these dates (YYYY-MM-DD). |\n| `published_from` | date | Optional | Published since (YYYY-MM-DD). |\n| `cif` | string | Optional | Company CIF: open tenders similar to the contracts it has already won (see below). |\n| `status` | string | Optional | `open` (accepting bids, default), `prior_notice` or `all` (also recently closed). |\n| `sort` | string | Optional | `deadline` (closing soonest, default), `published`, `amount` or `relevance` (default with `cif`). |\n| `page / limit` | integer | Optional | Pagination. `limit` defaults to 20, max 100. |\n\n```\ncurl \"https://apiempresas.es/api/v1/tenders?q=limpieza&province=Madrid&type=services\" \\\n  -H \"X-API-KEY: your_api_key\"\n```\n\n- `status`: `open` (accepting bids), `prior_notice` (no bids yet) or, with `status=all`, `deadline_passed` (deadline expired and the Platform has not updated its status yet), `under_evaluation`, `awarded`, `cancelled`...\n- `deadline` is in mainland Spain time with its offset; `days_left` are calendar days until the deadline date (0 = closes today).\n- `submission_platform` says where to submit the bid: the State Platform or the relevant regional platform.\n- Amounts in euros excluding and including VAT; `estimated_value` includes planned extensions and modifications.\n\n### Tenders for a company\n\nWith `cif`, the API looks at the titles of the public contracts that company has won in the last 5 years, extracts the words that define what it does and returns the most similar open tenders, ranked by similarity (`match_score`). It can be combined with the other filters (e.g. `province`). If the company has no awarded contracts, `company.note` says so and there are no results.\n\n```\ncurl \"https://apiempresas.es/api/v1/tenders?cif=A82018474\" -H \"X-API-KEY: your_api_key\"\n```\n\n```\n{\n  \"success\": true,\n  \"data\": {\n    \"company\": {\n      \"cif\": \"A82018474\",\n      \"name\": \"TELEFONICA DE ESPAÑA SAU\",\n      \"contracts_used\": 60,\n      \"keywords\": [\"telecomunicaciones\", \"datos\", \"internet\", \"telefonía\", \"comunicaciones\", \"fija\", \"infraestructuras\", \"móvil\"]\n    },\n    \"tenders\": [\n      {\n        \"title\": \"Servicios e infraestructura telefonia fija, datos y enlaces especiales de la i3d\",\n        \"match_score\": 19.31,\n        \"...\": \"same fields as above\"\n      }\n    ],\n    \"pagination\": { \"total\": 6, \"page\": 1, \"limit\": 20, \"total_pages\": 1, \"has_more\": false }\n  }\n}\n```\n\n#### Restricted response (403 Forbidden - Free and Pro plans)\n\n```\n{\n  \"success\": false,\n  \"error\": \"PLAN_RESTRICTION\",\n  \"message\": \"Las licitaciones públicas abiertas requieren el plan Business.\",\n  \"required_plan\": \"business\",\n  \"upsell_opportunities\": {\n    \"mensaje\": \"Hay 45 licitaciones que cumplen tu búsqueda. Con el plan Business las ves todas, con importe, plazo, CPV y enlace para presentarte.\",\n    \"upgrade_url\": \"https://apiempresas.es/billing?plan=business&source=api_403_tenders\",\n    \"licitaciones_encontradas\": 45,\n    \"muestra\": [\n      {\n        \"title\": \"Servicio de limpieza para centros y establecimientos del Área de Atención...\",\n        \"contracting_authority\": \"...\",\n        \"province\": \"Ceuta\",\n        \"amount_excl_vat\": 11963978.09,\n        \"deadline\": \"2026-10-20T23:59:00+02:00\"\n      }\n    ]\n  }\n}\n```\n\nThe 403 does not use queries. The tender count and sample are included in up to 25 403 responses per day per account. **Cost on Business:** 1 query per call.","operationId":"0a8b86cb3634e5f120a576cedb9d2003","parameters":[{"name":"q","in":"query","description":"Words in the title (all must appear). E.g.: limpieza colegios","required":false,"schema":{"type":"string"}},{"name":"cpv","in":"query","description":"One or more CPV codes (or their prefix), comma-separated. E.g.: 72,48 (IT) or 90911200","required":false,"schema":{"type":"string"}},{"name":"province","in":"query","description":"Province of the contracting authority. E.g.: Madrid, Barcelona, Bizkaia","required":false,"schema":{"type":"string"}},{"name":"type","in":"query","description":"supplies, services or works","required":false,"schema":{"type":"string","enum":["supplies","services","works"]}},{"name":"procedure","in":"query","description":"Procedure code: 1 open, 9 simplified open, 2 restricted, 4 negotiated with prior notice...","required":false,"schema":{"type":"string"}},{"name":"min_amount","in":"query","description":"Minimum amount excluding VAT (euros)","required":false,"schema":{"type":"number"}},{"name":"max_amount","in":"query","description":"Maximum amount excluding VAT (euros)","required":false,"schema":{"type":"number"}},{"name":"deadline_from","in":"query","description":"Bid deadline from (YYYY-MM-DD)","required":false,"schema":{"type":"string","format":"date"}},{"name":"deadline_to","in":"query","description":"Bid deadline to (YYYY-MM-DD)","required":false,"schema":{"type":"string","format":"date"}},{"name":"published_from","in":"query","description":"Published since (YYYY-MM-DD)","required":false,"schema":{"type":"string","format":"date"}},{"name":"cif","in":"query","description":"Company CIF: open tenders similar to the contracts it has already won","required":false,"schema":{"type":"string"}},{"name":"status","in":"query","description":"open (accepting bids, default), prior_notice or all (also recently closed)","required":false,"schema":{"type":"string","enum":["open","prior_notice","all"]}},{"name":"sort","in":"query","description":"deadline (closing soonest, default), published, amount or relevance (with cif)","required":false,"schema":{"type":"string"}},{"name":"page","in":"query","required":false,"schema":{"type":"integer","default":1}},{"name":"limit","in":"query","description":"Results per page (max. 100)","required":false,"schema":{"type":"integer","default":20}}],"responses":{"200":{"description":"Tenders","content":{"application/json":{"example":{"success":true,"data":{"tenders":[{"tender_id":"https://contrataciondelestado.es/sindicacion/licitacionesPerfilContratante/20705710","file_number":"002317/2026","title":"Servicio de Mantenimiento de la Red de Comunicaciones, Telefonía IP y Cableado.","status":"open","contracting_authority":{"name":"Comité de Dirección de Equipos Nucleares S.A.","nif":"A28325520","city":"Maliaño","province":"Cantabria"},"contract_type":"services","procedure":"Abierto","procedure_code":"1","amount_excl_vat":48000,"amount_incl_vat":58080,"estimated_value":48000,"currency":"EUR","lots":null,"main_cpv":"50330000","cpv_codes":["50330000"],"execution_place":"Cantabria","published_date":"2026-10-16","deadline":"2026-10-26T13:00:00+01:00","days_left":9,"submission_platform":"Plataforma de Contratación del Estado","url":"https://contrataciondelestado.es/wps/poc?uri=deeplink:detalle_licitacion&idEvl=AtvacxRpmXcmMOlAXxDEjw%3D%3D","last_updated":"2026-10-16T12:29:02+02:00"}],"pagination":{"total":7,"page":1,"limit":20,"total_pages":1,"has_more":false}},"meta":{"source":"Plataforma de Contratación del Sector Público (incluye plataformas autonómicas agregadas)","data_updated_at":"2026-10-17T08:56:50+00:00","status_filter":"open"}}}}},"400":{"description":"Invalid parameter"},"403":{"description":"Free or Pro plan: tender count and 3 samples"}},"servers":[{"url":"https://spaincompanyapi.com/api/v1","description":"Production"}]}},"/sanctions/screen":{"get":{"tags":["Risk and contracts"],"summary":"Sanctions screening (EU, UN, OFAC)","description":"**Plan:** Business (on Free and Pro, 403 without the result)\n\n> Not available in the Sandbox: this endpoint only works in production.\n\nChecks whether a Spanish company and its current directors, or any name, appear on the sanctions lists of the **European Union** (consolidated financial sanctions list, binding in Spain), the **United Nations** (Security Council consolidated list) and **OFAC** (US SDN list). The lists are updated daily.\n\nEach match has a similarity level: `strong` (0.92 or more: same name, possibly in another order or transliteration) or `possible` (0.85 or more: similar, or the searched name is contained in the listed one). To confirm or rule it out, compare the date of birth, country and documents included in the list.\n\n| Parameter | Type | Required | Description |\n| --- | --- | --- | --- |\n| `cif` | string | One of the two | Company CIF: checks the legal name and its current directors (excluding auditors and attorneys, up to 40). |\n| `name` | string | One of the two | Name of a person or entity, instead of `cif` (3-200 characters). |\n| `type` | string | Optional | With `name`: `person`, `entity` or `any` (default). |\n| `directors` | boolean | Optional | With `cif`: `false` to check only the company. Default `true`. |\n\n```\ncurl \"https://apiempresas.es/api/v1/sanctions/screen?name=Vladimir%20Putin&type=person\" -H \"X-API-KEY: your_api_key\"\n```\n\n#### Response for a name (200 OK - Business plan)\n\n#### Response for a CIF\n\n```\ncurl \"https://apiempresas.es/api/v1/sanctions/screen?cif=A46103834\" -H \"X-API-KEY: your_api_key\"\n```\n\n```\n{\n  \"success\": true,\n  \"data\": {\n    \"company\": { \"cif\": \"A46103834\", \"name\": \"MERCADONA SA\", \"matches\": [] },\n    \"directors\": [],\n    \"summary\": { \"directors_checked\": 9, \"strong_matches\": 0, \"possible_matches\": 0, \"result\": \"clear\", \"directors_included\": true },\n    \"lists\": [ \"...\" ],\n    \"checked_at\": \"2026-10-18T11:55:45+00:00\"\n  }\n}\n```\n\n- `summary.result`: `clear` (no matches), `possible_match` (only possible ones) or `match` (at least one strong).\n- With `cif`, `directors` only lists directors with a match: `name`, `position` and `matches`, with the same fields as above.\n- It is also included in KYB verification on Business, under `checks.sanctions`: a strong match for the company or a director sets `decision_hint` to `review`.\n- It supports due diligence; it is not a certificate. The final decision and identity check are yours.\n\n#### Restricted response (403 Forbidden - Free and Pro plans)\n\n```\n{\n  \"success\": false,\n  \"error\": \"PLAN_RESTRICTION\",\n  \"message\": \"La comprobación en listas de sanciones requiere el plan Business.\",\n  \"required_plan\": \"business\",\n  \"upsell_opportunities\": {\n    \"mensaje\": \"Con el plan Business ves cada coincidencia en las listas de la UE, la ONU y OFAC, con su grado de parecido, programa de sanciones, fecha, país y fecha de nacimiento, también para los administradores.\",\n    \"upgrade_url\": \"https://apiempresas.es/billing?plan=business&source=api_403_sanctions\",\n    \"listas\": [\"EU (6234 entradas, lista del 2026-10-15)\", \"OFAC (19457 entradas, lista del 2026-10-15)\", \"UN (1010 entradas, lista del 2026-10-17)\"]\n  }\n}\n```\n\nThe 403 does not use queries or reveal the result. **Cost on Business:** 1 query per call.","operationId":"4aaa0e78a2f60ba1a49a0624939ccc9b","parameters":[{"name":"cif","in":"query","description":"Company CIF: checks the legal name and the current directors","required":false,"schema":{"type":"string"}},{"name":"name","in":"query","description":"Name of a person or entity (instead of cif)","required":false,"schema":{"type":"string"}},{"name":"type","in":"query","description":"With name: person, entity or any (default)","required":false,"schema":{"type":"string","enum":["person","entity","any"]}},{"name":"directors","in":"query","description":"With cif: false to skip the directors (default true)","required":false,"schema":{"type":"boolean"}}],"responses":{"200":{"description":"Screening result","content":{"application/json":{"example":{"success":true,"data":{"query":{"name":"Vladimir Putin","type":"person"},"matches":[{"level":"strong","score":1,"list":"OFAC","matched_name":"Vladimir PUTIN","listed_name":"Vladimir Vladimirovich PUTIN","entry_type":"person","programs":["RUSSIA-EO14024"],"listed_on":null,"countries":["Russia"],"birth_dates":["07 Oct 1952"],"identifiers":[],"reference":"35096","url":"https://sanctionssearch.ofac.treas.gov/Details.aspx?id=35096"}],"summary":{"strong_matches":2,"possible_matches":0,"result":"match"},"lists":[{"list":"EU","description":"Unión Europea: lista consolidada de sanciones financieras","entries":6234,"list_date":"2026-10-15","loaded_at":"2026-10-18T11:52:34+00:00"},{"list":"OFAC","description":"EE. UU. (OFAC): Specially Designated Nationals (SDN)","entries":19457,"list_date":"2026-10-15","loaded_at":"2026-10-18T11:53:07+00:00"},{"list":"UN","description":"Naciones Unidas: lista consolidada del Consejo de Seguridad","entries":1010,"list_date":"2026-10-17","loaded_at":"2026-10-18T11:53:01+00:00"}],"checked_at":"2026-10-18T11:55:44+00:00","note":"Una coincidencia por nombre no confirma que sea la misma persona o entidad: compara la fecha de nacimiento, el país y los documentos de la lista antes de decidir."}}}}},"400":{"description":"Invalid parameter"},"403":{"description":"Free or Pro plan"},"404":{"description":"Company not found"}},"servers":[{"url":"https://spaincompanyapi.com/api/v1","description":"Production"}]}},"/companies/score":{"get":{"tags":["Prospecting"],"summary":"Commercial score (0-100)","description":"**Plan:** Free, Pro and Business (on Free, the number only)\n\nPower your prospecting with enriched data and real-time business signals.\n\nCommercial score from 0 to 100 for a company: its recent BORME activity, how complete its record is and whether it has a phone, email or website. It does not measure solvency (use `/companies/risk-profile` for that). On Free it returns the number only, without using requests (within the cap of 25 previews a day); `priority`, `reasons` and `last_signal` come back locked.\n\n| Field | Type | Description |\n| --- | --- | --- |\n| `data.score` | integer | Commercial score from 0 to 100. |\n| `data.priority` | enum | Prospecting priority from the score: `muy_alta` (75 or more), `alta` (60), `media` (40), `baja` (20) or `muy_baja`. |\n| `data.reasons` | array | List of reasons behind the score. |\n| `data.last_signal` | object | Latest BORME act that counts towards the score: `type`, `date` and `url_pdf` (official BORME PDF for that day; `null` if not recorded). |","operationId":"9b4661101275cf401d165674ea348e66","parameters":[{"name":"cif","in":"query","description":"Company CIF","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Commercial score data","content":{"application/json":{"schema":{"properties":{"success":{"type":"boolean","example":true},"data":{"type":"object"}},"type":"object"},"example":{"success":true,"data":{"cif":"B12345678","score":82,"priority":"muy_alta","reasons":["OPP:95|QUAL:80|CONT:60 · Ampliación de capital"],"last_signal":{"type":"Ampliación de capital","date":"2026-09-15","url_pdf":"https://www.boe.es/borme/dias/2026/09/15/pdfs/BORME-A-2026-176-15.pdf"},"source":"radar"}}}}}}}},"/companies/radar":{"get":{"tags":["Prospecting"],"summary":"Newly incorporated companies","description":"**Plan:** Free, Pro and Business (10, 100 or 1,000 results per request)\n\nCompanies incorporated in the period you ask for (today by default), sorted by commercial score, highest first.\n\n- Free: 10 results with name and CIF hidden. Uses 1 request.\n- Pro and Free with credits: up to 100 results. Business: up to 1,000.\n- If there are more companies than fit, `meta.oportunidades_ocultas` says how many are missing.\n- All filters work on every plan.\n\n#### Optional parameters\n\n| Field | Description |\n| --- | --- |\n| `province` | Filter by Spanish province (e.g. MADRID). |\n| `range` | Time window. Accepts `hoy` (today, the default) or an integer for **days back** (e.g. `7`, `30`). |\n| `priority` | Commercial priority: `muy_alta`, `alta`, `media`, `baja` or `muy_baja` (very high to very low). |\n| `cnae` | One or more comma-separated CNAE prefixes (e.g. `62` or `4711,4719`). |\n| `min_score` | Minimum opportunity score, 0 to 100. |\n| `main_act_type` | Type of the latest relevant BORME act (e.g. `Constitución`, `Ampliación de capital`). |\n| `has_phone` | With `true`, only companies with a phone number. |\n\n| Field | Type | Description |\n| --- | --- | --- |\n| `data[].fecha_constitucion` | string | Date the company was incorporated. |\n| `data[].score_total` | integer | null | Commercial score (0-100). With `priority_level` and `main_act_type`, the latest relevant BORME act. |\n| `meta.plan` | string | Your current plan. |\n| `meta.total_disponibles` | integer | Total companies in the Radar. If your plan is capped at `limit`, you'll see the real total here. |","operationId":"b31701f7df831631439af15c6b6ed8f8","parameters":[{"name":"province","in":"query","description":"Filter by province","required":false,"schema":{"type":"string"}},{"name":"range","in":"query","description":"Time range: 'hoy' (today), '7' days or '30' days","required":false,"schema":{"type":"string","default":"hoy"}},{"name":"priority","in":"query","description":"Calculated commercial priority (priority_level value, e.g. alta, media or baja).","required":false,"schema":{"type":"string"}},{"name":"cnae","in":"query","description":"One or more comma-separated CNAE prefixes (e.g. 62 or 4711,4719).","required":false,"schema":{"type":"string"}},{"name":"min_score","in":"query","description":"Minimum opportunity score (0-100).","required":false,"schema":{"type":"integer"}},{"name":"main_act_type","in":"query","description":"Type of the latest relevant BORME act (e.g. Constitución or Ampliación de capital).","required":false,"schema":{"type":"string"}},{"name":"has_phone","in":"query","description":"If true, only companies with a phone number.","required":false,"schema":{"type":"boolean"}}],"responses":{"200":{"description":"Companies found","content":{"application/json":{"schema":{"properties":{"success":{"type":"boolean","example":true},"meta":{"type":"object"},"data":{"type":"array","items":{"type":"object"}}},"type":"object"},"example":{"success":true,"meta":{"plan":"business","count":50,"limit":1000,"total_disponibles":50},"data":[{"id":4812345,"company_name":"NUEVA EMPRESA SL","cif":"B12345678","fecha_constitucion":"2026-10-13","cnae":"6201","cnae_label":"Actividades de programación informática","registro_mercantil":"MADRID","municipality":"MADRID","score_total":78,"priority_level":"alta","main_act_type":"Constitución"}]}}}}}}},"/companies/filter":{"get":{"tags":["Prospecting"],"summary":"Company segments","description":"**Plan:** Business (the count is free on every plan)\n\nFilter companies by activity, area, size and other criteria. **Counting is free on every plan** (`count_only=true`): you see how many companies match before paying anything. Downloading the rows is a Business feature and costs **5 requests per returned row**.\n\n| Parameter | Description |\n| --- | --- |\n| `cnae` | Comma-separated CNAE prefixes (e.g. `62` or `4711,4719`). |\n| `province` | Mercantile Registry province (e.g. `MADRID`). |\n| `municipality` | Municipality (e.g. `GETAFE`). |\n| `status` | `active` (default: active in the Registry), `active_or_unknown` (also those with no registered status) or `any`. |\n| `founded_from / founded_to` | Incorporation date, `YYYY-MM-DD`. |\n| `has_phone` | With `true`, only companies with a phone number. The number is not returned. |\n| `size_band` | Comma-separated revenue bands: `NO_REVENUE`, `LT_500K`, `500K_1M`, `GT_1M`. |\n| `size_category` | Headcount size, comma-separated: `micro` (under 10 employees), `small` (10-49), `medium` (50-249) or `large` (250 or more, or a large company according to its contract awards). Only returns companies with this data (Kit Digital, Kit Consulting, TED or PLACSP); it is never estimated. Each row includes the `size` block. |\n| `min_accounts_year` | Latest filed accounts year equal or later (e.g. `2023`). |\n| `count_only` | With `true`, only the count. Free. |\n| `limit / cursor` | Rows per page (1-1000, default 100) and `meta.next_cursor` from the previous page. |\n\nAt least one of `cnae`, `province` or `municipality` is required.\n\n#### Count only (all plans, free)\n\n#### Rows (Business)\n\n```\n// GET /companies/filter?cnae=62&province=MADRID&has_phone=true&limit=100\n{\n  \"success\": true,\n  \"data\": [\n    {\n      \"cif\": \"B12345678\",\n      \"name\": \"EMPRESA DE EJEMPLO SL\",\n      \"cnae\": \"6201\",\n      \"cnae_label\": \"Actividades de programación informática\",\n      \"province\": \"MADRID\",\n      \"municipality\": \"MADRID\",\n      \"founded\": \"2019-03-01\",\n      \"status\": \"ACTIVA\",\n      \"status_code\": \"ACTIVE\",\n      \"status_source\": \"registry\",\n      \"financials\": { \"size_band\": \"GT_1M\", \"size_band_label\": \"Más de 1 M€\", \"last_accounts_year\": 2023 },\n      \"size\": { \"employees_min\": 10, \"employees_max\": 49, \"label\": \"De 10 a 49 empleados\", \"category\": \"small\", \"source\": \"kit_digital\", \"as_of\": \"2024-05-14\" },\n      \"has_phone\": true\n    }\n  ],\n  \"meta\": {\n    \"total\": 3412,\n    \"returned\": 100,\n    \"limit\": 100,\n    \"has_more\": true,\n    \"next_cursor\": \"eyJpZCI6ODgxMjM0NX0\",\n    \"cost\": 500,\n    \"cost_per_row\": 5,\n    \"truncated\": false,\n    \"filters\": { \"cnae\": [\"62\"], \"province\": \"MADRID\", \"status\": \"active\", \"has_phone\": true }\n  }\n}\n```\n\n- Only returned rows are charged: `meta.cost` = rows × 5. If your quota is not enough, the page is cut (`truncated: true`) to the rows you can pay for.\n- For the next page, pass `meta.next_cursor` as `cursor` with the same filters.\n- Counts are cached for 6 hours: repeating the same search is not recalculated.\n- Without a Business plan, asking for rows returns 403 `PLAN_RESTRICTION` with the count in `upsell_opportunities.total`.\n- Phone numbers and emails are never returned: only `has_phone`.","operationId":"4a2297c1f54968df341b945005cccb45","parameters":[{"name":"cnae","in":"query","description":"Comma-separated CNAE prefixes (e.g. 62 or 4711,4719). cnae, province or municipality is required.","required":false,"schema":{"type":"string"}},{"name":"province","in":"query","description":"Commercial Registry province (e.g. MADRID).","required":false,"schema":{"type":"string"}},{"name":"municipality","in":"query","description":"Municipality (e.g. GETAFE).","required":false,"schema":{"type":"string"}},{"name":"status","in":"query","description":"active (default: active in the Registry), active_or_unknown (also those with no status) or any.","required":false,"schema":{"type":"string","default":"active"}},{"name":"founded_from","in":"query","description":"Incorporated on or after this date (YYYY-MM-DD).","required":false,"schema":{"type":"string","format":"date"}},{"name":"founded_to","in":"query","description":"Incorporated on or before this date (YYYY-MM-DD).","required":false,"schema":{"type":"string","format":"date"}},{"name":"has_phone","in":"query","description":"true: only companies with a phone number (the number is not returned).","required":false,"schema":{"type":"boolean"}},{"name":"size_band","in":"query","description":"Comma-separated revenue bands: NO_REVENUE, LT_500K, 500K_1M, GT_1M.","required":false,"schema":{"type":"string"}},{"name":"size_category","in":"query","description":"Headcount size, comma-separated: micro (under 10 employees), small (10-49), medium (50-249), large (250 or more, or not an SME according to its contract awards). Only companies with this data (Kit Digital, Kit Consulting, TED or PLACSP); it is never estimated.","required":false,"schema":{"type":"string"}},{"name":"min_accounts_year","in":"query","description":"Latest filed accounts year equal to or later than this.","required":false,"schema":{"type":"integer"}},{"name":"count_only","in":"query","description":"true: count only (free, every plan).","required":false,"schema":{"type":"boolean"}},{"name":"limit","in":"query","description":"Rows per page (1-1000). Default: 100.","required":false,"schema":{"type":"integer","default":100}},{"name":"cursor","in":"query","description":"meta.next_cursor from the previous page.","required":false,"schema":{"type":"string"}}],"responses":{"200":{"description":"Count or rows","content":{"application/json":{"example":{"success":true,"data":{"total":3412},"meta":{"filters":{"cnae":["62"],"province":"MADRID","status":"active","has_phone":true},"cost":0,"counted_at":"2026-09-29T09:30:00+02:00"}}}}},"400":{"description":"Invalid filters"},"403":{"description":"Rows without Business plan (includes the count)"}}}},"/companies/insights":{"get":{"tags":["Prospecting"],"summary":"AI commercial analysis","description":"**Plan:** Business (preview on Pro)\n\nAI-powered analysis of the commercial profile and probable needs of a company. On Pro (or Free with credits) there is a preview that does not use requests, within the cap of 25 a day: only `profile` and `conversion_probability`; `pain_points`, `buyer_persona` and `sales_arguments` come back locked, with `message` and `checkout_url`. Free plan: 403 `PLAN_RESTRICTION`.\n\n| Field | Type | Description |\n| --- | --- | --- |\n| `needs[]` | array[string] | List of software needs detected through AI inference. |\n| `conversion_probability` | string | Estimated B2B cross-selling probability. |","operationId":"18786d5e2d8d8be91882f39936c5756d","parameters":[{"name":"cif","in":"query","description":"Company CIF","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"AI-generated insights","content":{"application/json":{"schema":{"properties":{"success":{"type":"boolean","example":true},"data":{"type":"object"}},"type":"object"},"example":{"success":true,"data":{"profile":"Servicios de Tecnología","summary":"Empresa enfocada en desarrollo software...","needs":["Presencia Web","Gestión Cloud"],"conversion_probability":"Alta","estimated_ticket":"Medio-Alto"}}}}}}}},"/companies/contact-prep":{"get":{"tags":["Prospecting"],"summary":"AI contact preparation","description":"**Plan:** Business\n\nAI-generated sales pitch and objection handling for a target company.\n\n| Field | Type | Description |\n| --- | --- | --- |\n| `sales_approach` | string | Suggested commercial outreach strategy. |\n| `likely_objection` | string | Most likely objection from the prospect. |","operationId":"85cf72fa9acdc26beeb7147ec1e768b3","parameters":[{"name":"cif","in":"query","description":"Company CIF","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Preparation tactics","content":{"application/json":{"schema":{"properties":{"success":{"type":"boolean","example":true},"data":{"type":"object"}},"type":"object"},"example":{"success":true,"data":{"sales_approach":"Consultative and direct approach...","suggested_message":"Hi, I noticed the recent growth of...","likely_objection":"Temporary budget constraints","attack_angle":"Demonstrate immediate ROI..."}}}}}}}},"/companies/match":{"get":{"tags":["Prospecting"],"summary":"Fit with your sector (B2B match)","description":"**Plan:** Business\n\nB2B Match calculator. Requires `cif` and `seller_sector` parameters. Returns the commercial fit level and a personalised sales argument.\n\n| Field | Type | Description |\n| --- | --- | --- |\n| `match_score` | integer | B2B fit level (0–100). |\n| `sales_argument` | string | Sales argument tailored to the match. |","operationId":"428873cb6ca45cc2398f1735bfe78ef1","parameters":[{"name":"cif","in":"query","description":"CIF of the prospect company","required":true,"schema":{"type":"string"}},{"name":"seller_sector","in":"query","description":"Seller's sector (e.g. Software, Marketing, Consulting)","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Match score and sales pitch","content":{"application/json":{"schema":{"properties":{"success":{"type":"boolean","example":true},"data":{"type":"object"}},"type":"object"},"example":{"success":true,"data":{"match_score":85,"fit_level":"Alto","pain_points_addressed":["Ineficiencia operativa","Falta de digitalización"],"sales_argument":"Our software eliminates manual work...","recommendation":"Contact immediately."}}}}}}}},"/watchlist":{"get":{"tags":["Monitoring"],"summary":"List monitored companies","description":"**Plan:** Pro and Business\n\nLists your watched companies (`page`, `limit` up to 500).","operationId":"dd6f7698727f31a6be34b2156248fcdc","parameters":[{"name":"page","in":"query","description":"Page (>= 1).","required":false,"schema":{"type":"integer","default":1}},{"name":"limit","in":"query","description":"Results per page (1-500).","required":false,"schema":{"type":"integer","default":100}}],"responses":{"200":{"description":"List of monitored companies","content":{"application/json":{"example":{"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}}}}}}},"post":{"tags":["Monitoring"],"summary":"Add companies to monitoring","description":"**Plan:** Pro and Business (100 companies on Pro, 1,000 on Business)\n\nAdd 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.\n\nAdd up to 500 CIFs per request. The response says what happened to each one.","operationId":"d00dfb1037ef1da2693eb233aad23522","responses":{"200":{"description":"Result per CIF","content":{"application/json":{"example":{"success":true,"data":{"added":["A46103834"],"already_watching":["A15075062"],"not_found":[],"invalid":[],"rejected_over_limit":[]},"meta":{"total":2,"watch_limit":100}}}}}},"requestBody":{"required":true,"content":{"application/json":{"example":{"cifs":["A46103834","A15075062"]}}}}}},"/watchlist/{cif}":{"delete":{"tags":["Monitoring"],"summary":"Stop monitoring a company","description":"**Plan:** Pro and Business\n\nRemoves a company. If it was not on your watchlist, returns 404 `NOT_WATCHING`.","operationId":"9f0c0491682af32e7f4be91941b43aae","parameters":[{"name":"cif","in":"path","description":"Company CIF","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Removed","content":{"application/json":{"example":{"success":true,"data":{"cif":"A46103834","removed":true},"meta":{"total":1,"watch_limit":100}}}}},"404":{"description":"It was not on your watchlist"}}}},"/watchlist/events":{"get":{"tags":["Monitoring"],"summary":"Changes in monitored companies","description":"**Plan:** Pro and Business\n\n| Parameter | Description |\n| --- | --- |\n| `since` | Date `YYYY-MM-DD`, inclusive. Default: 7 days ago; at most 90 days back. |\n| `types` | Optional. `borme_act`, `status_change`, `risk_level_change`, `insolvency`, comma-separated. |\n| `cif` | Optional. Only the events of that company. |\n| `page` / `limit` | Pagination (up to 500 per page). |\n\n- Events are returned oldest first. The `id` is stable: use it to avoid processing the same event twice.\n- `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).\n- `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.\n- Recommended use: one call a day with `since` = the date of your last call.\n- Free plan (also with credits): 403 `PLAN_RESTRICTION`. On Business you can receive these same events on your server with webhooks.","operationId":"d390d199944f4742139af2667c5a64c2","parameters":[{"name":"since","in":"query","description":"Date YYYY-MM-DD (inclusive). Default: 7 days ago. Up to 90 days back.","required":false,"schema":{"type":"string","format":"date"}},{"name":"types","in":"query","description":"Comma-separated types: borme_act, status_change, risk_level_change, insolvency. Default: all.","required":false,"schema":{"type":"string"}},{"name":"cif","in":"query","description":"Only events for this company (it must be on your watchlist).","required":false,"schema":{"type":"string"}},{"name":"page","in":"query","description":"Page (>= 1).","required":false,"schema":{"type":"integer","default":1}},{"name":"limit","in":"query","description":"Events per page (1-500).","required":false,"schema":{"type":"integer","default":100}}],"responses":{"200":{"description":"Events","content":{"application/json":{"example":{"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}}}}}}}},"/companies/changes":{"get":{"tags":["Monitoring"],"summary":"Changes feed (all companies)","description":"**Plan:** Business\n\nEvery company with a filing published in the BORME since a given date, oldest first: to keep a CRM, an ERP or a customer database up to date without adding each company to the watchlist. Each row says what changed (`change_types`) and the company's current status. For the details (new directors, address...), look the company up in `/companies`.\n\n| Parameter | Type | Required | Description |\n| --- | --- | --- | --- |\n| `since` | date | Optional | Filings published on or after this date (`YYYY-MM-DD`). Default: yesterday. Up to 30 days back. |\n| `until` | date | Optional | Filings published on or before this date. |\n| `types` | string | Optional | Comma-separated change types (table below). E.g. `address,dissolution,insolvency`. |\n| `province` | string | Optional | Commercial Registry province (e.g. `MADRID`). |\n| `cnae` | string | Optional | Comma-separated CNAE prefixes (e.g. `62` or `4711,4719`). |\n| `limit` | integer | Optional | Rows per page (1-1000). Default: `500`. |\n| `cursor` | string | Optional | `meta.next_cursor` from the previous page, with the same filters. |\n\n#### Change types\n\n| change\\_types | What the BORME published |\n| --- | --- |\n| `incorporation` | Incorporation |\n| `officers` | Appointments, resignations, revocations and re-elections of officers |\n| `address` | Change of registered address |\n| `name` | Change of company name |\n| `purpose` | Change of corporate purpose |\n| `capital` | Capital increase or reduction |\n| `sole_shareholder` | Sole-shareholder declaration or loss, change of sole shareholder |\n| `dissolution` | Dissolution, extinction or reactivation |\n| `insolvency` | Insolvency proceedings |\n| `enforcement_insolvency` | Insolvency declared by a court in an enforcement proceeding (usually a labour court: no assets were found to pay a debt). Not insolvency proceedings; the row also carries `insolvency`. Since 26-10-2026 |\n| `structural` | Merger, demerger, conversion or absorption |\n| `registry_closure` | Provisional closure of the registry sheet or revoked tax ID |\n| `other` | Other filings |\n\n#### Restricted response (403 Forbidden - Free and Pro plans)\n\n```\n{\n  \"success\": false,\n  \"error\": \"PLAN_RESTRICTION\",\n  \"message\": \"El feed de cambios requiere el plan Business.\",\n  \"upsell_opportunities\": {\n    \"mensaje\": \"Desde el 01/10/2026 hay 4.812 cambios publicados en el BORME que encajan con tu búsqueda. Con el plan Business los recibes por API para mantener al día tu base de clientes.\",\n    \"upgrade_url\": \"https://apiempresas.es/billing?plan=business&source=api_403_changes\",\n    \"total\": 4812,\n    \"since\": \"2026-10-01\"\n  }\n}\n```\n\n- **Companies with a CIF only.** Newly incorporated companies rarely appear on their incorporation day, because they do not have a CIF yet (we find it a few days later). To learn about new companies, use the `company.created` webhook, which notifies on the same day with province, CNAE and capital filters.\n- One row per filing: a company with two filings on the same day appears twice. `id` is stable: use it to avoid processing the same change twice.\n- Recommended: one call a day with `since` = the day of your last call. The BORME is published Monday to Friday; `meta.last_borme_date` is the latest day loaded.\n- Page with `meta.next_cursor` until `has_more` is `false`. With `types`, a page may hold fewer rows than `limit` while more remain.\n- `act_types` are returned in Spanish, as published by the BORME. The filing text and people's names are not included: use /companies/borme for that.\n- **Cost:** 1 request per page (up to 1,000 rows). 403 responses do not use quota; the count is included in up to 25 403 responses per account per day.","operationId":"6262ff38a4f1ad6b1cd81b4890e24b9a","parameters":[{"name":"since","in":"query","description":"Filings published on or after this date (YYYY-MM-DD). Default: yesterday. Up to 30 days back.","required":false,"schema":{"type":"string","format":"date"}},{"name":"until","in":"query","description":"Filings published on or before this date (YYYY-MM-DD).","required":false,"schema":{"type":"string","format":"date"}},{"name":"types","in":"query","description":"Comma-separated change types: incorporation, officers, address, name, purpose, capital, sole_shareholder, dissolution, insolvency, enforcement_insolvency, structural, registry_closure, other.","required":false,"schema":{"type":"string"}},{"name":"province","in":"query","description":"Commercial Registry province (e.g. MADRID).","required":false,"schema":{"type":"string"}},{"name":"cnae","in":"query","description":"Comma-separated CNAE prefixes (e.g. 62 or 4711,4719).","required":false,"schema":{"type":"string"}},{"name":"limit","in":"query","description":"Rows per page (1-1000). Default: 500.","required":false,"schema":{"type":"integer","default":500}},{"name":"cursor","in":"query","description":"meta.next_cursor from the previous page.","required":false,"schema":{"type":"string"}}],"responses":{"200":{"description":"Changes","content":{"application/json":{"example":{"success":true,"data":[{"id":"borme_act:11494608","date":"2026-10-08","cif":"B93867240","company_name":"BIOLIQUID DIAGNOSTICS S.L","change_types":["address"],"act_types":["Cambio de domicilio social"],"status_code":"ACTIVE","province":"Barcelona","cnae":null,"borme_pdf":"https://www.boe.es/borme/dias/2026/10/08/pdfs/BORME-A-2026-195-08.pdf"},{"id":"borme_act:11494733","date":"2026-10-08","cif":"B93867604","company_name":"TITANIA INMO S.L","change_types":["officers","dissolution"],"act_types":["Nombramientos","Revocaciones","Extinción"],"status_code":"EXTINCT","province":"Barcelona","cnae":null,"borme_pdf":"https://www.boe.es/borme/dias/2026/10/08/pdfs/BORME-A-2026-195-08.pdf"}],"meta":{"since":"2026-10-08","until":null,"filters":{"since":"2026-10-08","province":"BARCELONA"},"count":2,"limit":500,"has_more":true,"next_cursor":"eyJkIjoiMjAyNi0xMC0wOCIsImlkIjoxMTQ5NDczM30","last_borme_date":"2026-10-09"}}}}},"400":{"description":"Invalid parameter"},"403":{"description":"Free or Pro plan: number of changes"}}}},"/webhooks":{"get":{"tags":["Webhooks"],"summary":"List your webhooks","description":"**Plan:** Business\n\n> Not available in the Sandbox: this endpoint only works in production.\n\nReceive 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.\n\nLists 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`.","operationId":"d29beef27f3b961d8b638f50e5f41291","responses":{"200":{"description":"List of webhooks","content":{"application/json":{"schema":{"properties":{"success":{"type":"boolean","example":true},"data":{"type":"array","items":{"type":"object"}}},"type":"object"},"example":{"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"}]}}}}},"servers":[{"url":"https://spaincompanyapi.com/api/v1","description":"Production"}]},"post":{"tags":["Webhooks"],"summary":"Create a webhook","description":"**Plan:** Business\n\n> Not available in the Sandbox: this endpoint only works in production.\n\n#### Create a webhook\n\nKeep the `secret`: it lets you check that each delivery comes from us. If you send one in the request, yours is used.\n\n| Event | When it arrives |\n| --- | --- |\n| `company.created` | A company is incorporated that matches the webhook `filters` (see new companies). It does not depend on the watchlist. |\n| `company.borme_act` | An act is published in the BORME for a watched company. |\n| `company.status_changed` | The Registry changes the status of a watched company. |\n| `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`. |\n| `company.risk_level_changed` | Its risk level changes (`model_change: true` if caused by a recalculation of our model). |\n| `watchlist.*` | All watchlist events (all of the above except `company.created`). |\n| `test.ping` | Only when calling `/webhooks/{id}/test`. |\n\n#### New companies (`company.created`)\n\nSome 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.\n\n```\n// Request\n{\n  \"url\": \"https://yourdomain.com/webhooks/empresas-nuevas\",\n  \"event\": \"company.created\",\n  \"filters\": { \"province\": [\"VIZCAYA\", \"GUIPUZCOA\"], \"keywords\": [\"instalaciones\", \"eléctric\"], \"min_capital\": 3000 }\n}\n\n// Response (201)\n{\n  \"success\": true,\n  \"message\": \"Webhook creado correctamente\",\n  \"id\": 13,\n  \"event\": \"company.created\",\n  \"secret\": \"8b1e0c4f2a...\",\n  \"filters\": { \"province\": [\"VIZCAYA\", \"GUIPUZCOA\"], \"keywords\": [\"INSTALACIONES\", \"ELÉCTRIC\"], \"min_capital\": 3000 }\n}\n```\n\n| Filter | What it does |\n| --- | --- |\n| `province` | Commercial Registry provinces (up to 10). Values in /catalog. |\n| `municipality` | Municipalities (up to 20). |\n| `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. |\n| `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. |\n| `min_capital` | Minimum share capital in euros (95 % have it). |\n| `legal_form` | Legal forms: `SL`, `SA`, `SLP`, `SLL`, `SCOOP`… |\n\nWithout filters you get all of them. An invalid filter returns 400 `VALIDATION_ERROR`. To change the filters, delete the webhook and create it again.\n\nEach delivery carries one company:\n\n```\n{\n  \"id\": \"51057088-7127-103b-3c57-8c8e824456d3\",\n  \"event\": \"company.created\",\n  \"created_at\": \"2026-10-08T19:00:02+02:00\",\n  \"data\": {\n    \"id\": \"company_created:8573551\",\n    \"type\": \"company_created\",\n    \"date\": \"2026-10-08\",\n    \"cif\": null,\n    \"company_name\": \"PERICIALES HERRERO SOCIEDAD LIMITADA\",\n    \"data\": {\n      \"legal_form\": { \"code\": \"SL\", \"label\": \"Sociedad limitada\", \"iso20275\": \"DP3Q\", \"source\": \"name\" },\n      \"founded\": \"2026-10-01\",\n      \"province\": \"Vizcaya\",\n      \"municipality\": \"BILBAO\",\n      \"address\": \"AVDA MONTEVIDEO 4 3 (BILBAO)\",\n      \"postal_code\": null,\n      \"share_capital_eur\": 3000,\n      \"corporate_purpose\": \"Evaluación de riesgos y daños\",\n      \"cnae\": null,\n      \"cnae_label\": null,\n      \"administrators\": [\n        { \"name\": \"HERRERO TASCON AITOR\", \"position\": \"Adm. Solidario\", \"since\": \"2026-10-08\" }\n      ],\n      \"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\" },\n      \"detected_at\": \"2026-10-08T20:21:27+02:00\"\n    }\n  }\n}\n```\n\n- `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.\n- `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.\n- `administrators`: those appointed at incorporation, same as `admin=true` in /companies.\n- No phone or website: a newly incorporated company does not have them in any source yet.\n\n#### What your server receives\n\nA JSON `POST` with these headers: `X-ApiEmpresas-Event`, `X-ApiEmpresas-Delivery` (unique delivery id) and `X-ApiEmpresas-Signature`.\n\n```\n{\n  \"id\": \"5d41402a-bc4b-2a76-b971-9d911017c592\",\n  \"event\": \"company.borme_act\",\n  \"created_at\": \"2026-09-28T10:15:00+02:00\",\n  \"data\": {\n    \"id\": \"borme_act:8812345\",\n    \"type\": \"borme_act\",\n    \"date\": \"2026-09-28\",\n    \"cif\": \"B12345678\",\n    \"company_name\": \"EMPRESA DE EJEMPLO SL\",\n    \"data\": { \"act_types\": \"Nombramientos\", \"description\": \"Nombramientos. Adm. Unico: ...\", \"url_pdf\": \"https://www.boe.es/borme/...\" }\n  }\n}\n```\n\n#### Verify the signature\n\n`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.\n\n```\n[$t, $v1] = array_map(fn($p) => explode('=', $p, 2)[1], explode(',', $_SERVER['HTTP_X_APIEMPRESAS_SIGNATURE']));\n$body = file_get_contents('php://input');\n$ok = hash_equals(hash_hmac('sha256', $t . '.' . $body, $secret), $v1) && abs(time() - (int) $t) < 300;\n```\n\n#### Retries\n\n- 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.\n- Use `X-ApiEmpresas-Delivery` to avoid processing the same delivery twice.\n- 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.\n- The URL must be HTTPS (port 443) and public. We do not follow redirects.","operationId":"9f3b040ea012169a4f2fea1c1551f351","requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"url":{"type":"string","format":"uri"},"event":{"type":"string"}},"type":"object"},"example":{"url":"https://yourdomain.com/webhooks/apiempresas","event":"watchlist.*"}}}},"responses":{"201":{"description":"Webhook created","content":{"application/json":{"schema":{"properties":{"success":{"type":"boolean","example":true},"message":{"type":"string"},"id":{"type":"integer"}},"type":"object"},"example":{"success":true,"message":"Webhook creado correctamente","id":12,"event":"watchlist.*","secret":"3f9c1b2a7d..."}}}}},"servers":[{"url":"https://spaincompanyapi.com/api/v1","description":"Production"}]}},"/webhooks/{id}/test":{"post":{"responses":{"200":{"description":"OK","content":{"application/json":{"example":{"success":true,"data":{"delivered":true,"http_status":200,"duration_ms":143,"error":null,"delivery_id":"5d41402a-bc4b-2a76-b971-9d911017c592"}}}}}},"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"tags":["Webhooks"],"summary":"Send a test event","description":"**Plan:** Business\n\n> Not available in the Sandbox: this endpoint only works in production.\n\nSends 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.","servers":[{"url":"https://spaincompanyapi.com/api/v1","description":"Production"}]}},"/webhooks/{id}/deliveries":{"get":{"tags":["Webhooks"],"summary":"Delivery history","description":"**Plan:** Business\n\n> Not available in the Sandbox: this endpoint only works in production.\n\nLatest 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.","operationId":"bd8eb0a560078f7b3e1067fe2214eb77","parameters":[{"name":"id","in":"path","description":"Webhook ID","required":true,"schema":{"type":"integer"}},{"name":"status","in":"query","description":"Filter by status: pending, processing, retry, delivered or dead.","required":false,"schema":{"type":"string"}},{"name":"page","in":"query","description":"Page (>= 1).","required":false,"schema":{"type":"integer","default":1}},{"name":"limit","in":"query","description":"Deliveries per page (1-100). Default: 50.","required":false,"schema":{"type":"integer","default":50}}],"responses":{"200":{"description":"Webhook deliveries","content":{"application/json":{"example":{"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}}}}},"404":{"description":"Webhook not found"}},"servers":[{"url":"https://spaincompanyapi.com/api/v1","description":"Production"}]}},"/webhooks/{id}":{"delete":{"tags":["Webhooks"],"summary":"Delete a webhook","description":"**Plan:** Business\n\n> Not available in the Sandbox: this endpoint only works in production.\n\nDeletes a webhook. You stop receiving deliveries from that moment. If it does not exist, 404 `WEBHOOK_NOT_FOUND`.","operationId":"84f636f336a23bc8cc89aa63f8fc601b","parameters":[{"name":"id","in":"path","description":"ID of the webhook to delete","required":true,"schema":{"type":"integer"}}],"responses":{"200":{"description":"Webhook deleted","content":{"application/json":{"schema":{"properties":{"success":{"type":"boolean","example":true},"message":{"type":"string"}},"type":"object"},"example":{"success":true,"message":"Webhook eliminado"}}}}},"servers":[{"url":"https://spaincompanyapi.com/api/v1","description":"Production"}]}},"/usage":{"get":{"tags":["Account"],"summary":"Your API key usage","description":"**Plan:** Free, Pro and Business\n\n> Not available in the Sandbox: this endpoint only works in production.\n\nGet the request count for the current month and the history of companies queried associated with your API Key. Does not use requests.\n\n| Field | Type | Description |\n| --- | --- | --- |\n| `stats.monthly_queries` | integer | Requests charged in the quota period: the current month on Pro and Business; since 28/05/2026 on Free (or since sign-up, if later), including usage on an earlier paid plan. |\n| `stats.monthly_quota` | integer | Requests included in your plan (per month, or 100 in total on Free). |\n| `stats.remaining_calls` | integer | Plan requests left before credits are used. |\n| `stats.total_queries` | integer | Plan requests charged since sign-up (credits not included). |\n| `stats.wallet_balance` | integer | Credits left in your wallet. |\n| `history[]` | array[object] | The last 20 companies, by CIF, that you queried in production with a 200 response: each company record (cut on Free), `query_count`, `last_query` and `found`. |","operationId":"3ef076df3688a1cc1a57b1e02a840df6","responses":{"200":{"description":"Statistics and history","content":{"application/json":{"schema":{"properties":{"success":{"type":"boolean","example":true},"data":{"type":"object"}},"type":"object"},"example":{"success":true,"data":{"stats":{"monthly_queries":150,"total_queries":1250},"history":[{"cif":"A46103834","name":"MERCADONA SA","province":"VALENCIA","query_count":3,"last_query":"2026-10-12 17:40:02","found":true}]}}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"properties":{"success":{"type":"boolean","example":false},"error":{"type":"string"}},"type":"object"}}}}},"servers":[{"url":"https://spaincompanyapi.com/api/v1","description":"Production"}]}},"/catalog":{"get":{"tags":["Account"],"summary":"Valid filter values","description":"**Plan:** Free, Pro and Business\n\nValid values for the filters: `province` (radar and segments), `size_band` and `status` (segments), `range`, `priority` and `main_act_type` (radar), the score priority, webhook events and monitoring event types. Every plan. **Does not use requests.** Also in the Sandbox.\n\nThere is no CNAE list: use CNAE-2009 (INE) prefixes of 1 to 4 digits and check how many companies match with `/companies/filter?cnae=62&count_only=true`, which is free. Labels are in Spanish.","operationId":"b6bcfa2d29a0781f934d7e1095aa95d3","responses":{"200":{"description":"Catalog","content":{"application/json":{"example":{"success":true,"data":{"province":["A CORUÑA","ÁLAVA","ALBACETE","…","ZARAGOZA"],"cnae":{"format":"Prefijos de la CNAE-2009 (INE) de 1 a 4 dígitos, separados por comas: 62 o 4711,4719.","count":"/companies/filter?cnae=62&count_only=true (gratis) dice cuántas empresas hay."},"size_band":[{"value":"NO_REVENUE","label":"Sin ventas"},{"value":"LT_500K","label":"Menos de 0,5 M€"},{"value":"500K_1M","label":"Entre 0,5 y 1 M€"},{"value":"GT_1M","label":"Más de 1 M€"}],"status":["active","active_or_unknown","any"],"radar":{"range":["hoy","7","30"],"range_note":"'hoy' o cualquier número de días atrás","priority":["muy_alta","alta","media","baja","muy_baja"],"main_act_type":["Constitución","Nombramientos","Ampliación de Capital","…"]},"score_priority":["muy_alta","alta","media","baja","muy_baja"],"webhook_events":["test.ping","company.created","company.borme_act","company.status_changed","company.risk_level_changed","company.insolvency","watchlist.*"],"watchlist_event_types":["borme_act","status_change","risk_level_change","insolvency"]},"meta":{"updated_at":"2026-10-13","cost":0}}}}}}}}},"components":{"securitySchemes":{"ApiKeyAuth":{"type":"apiKey","description":"Enter your private API key here to authenticate and try the endpoints live.","name":"X-API-KEY","in":"header"}}},"externalDocs":{"description":"Guide with examples in curl, PHP, Node.js and Python","url":"https://spaincompanyapi.com/docs"}}