{ "openapi": "3.1.0", "info": { "title": "filings.es · Spanish company data API", "version": "1.0.0", "description": "REST API over the Spanish commercial register (Registro Mercantil / BORME): company identity, tax IDs, directors, ownership, insolvency proceedings and official filings for more than 3.9 million companies.", "termsOfService": "https://filings.es/aviso-legal", "contact": { "name": "filings", "url": "https://filings.es/contact" }, "license": { "name": "Commercial · see plan terms", "url": "https://filings.es/precios" } }, "servers": [ { "url": "https://api.filings.es", "description": "Production" } ], "externalDocs": { "description": "Documentation", "url": "https://filings.es/developers" }, "tags": [ { "name": "Search", "description": "Search companies · Autocomplete" }, { "name": "Companies", "description": "Company profile · Company directors · Ownership · Relationship graph · Company insolvency · BORME history" }, { "name": "Directors", "description": "Search directors · Person profile" }, { "name": "Compliance (KYB)", "description": "Validate a VAT number (VIES)" }, { "name": "Prospecting", "description": "Newly incorporated companies · Directory by sector · Activity codes (CNAE) · Provinces" }, { "name": "Insolvency", "description": "Search insolvency filings · Full notice" }, { "name": "Screener", "description": "Screen BORME events" } ], "paths": { "/api/public/v1/es/search": { "get": { "operationId": "search", "summary": "Search companies", "description": "Search by company name, NIF/CIF or registry sheet.", "tags": [ "Search" ], "parameters": [ { "name": "query", "in": "query", "required": true, "description": "Search term (min. 2 characters).", "schema": { "type": "string" } }, { "name": "limit", "in": "query", "required": false, "description": "Results per page (default 20, max 100).", "schema": { "type": "string" } }, { "name": "page", "in": "query", "required": false, "description": "Page number, from 1 (max 20). The response carries has_more and next: a ready-to-use URL for the following page.", "schema": { "type": "string" }, "example": "2" } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object" } } } }, "401": { "description": "Missing or invalid API key" }, "404": { "description": "Not found" }, "429": { "description": "Monthly call quota exhausted" } } } }, "/api/public/v1/es/autocomplete": { "get": { "operationId": "autocomplete", "summary": "Autocomplete", "description": "Real-time suggestions (companies and directors).", "tags": [ "Search" ], "parameters": [ { "name": "query", "in": "query", "required": true, "description": "Prefix (min. 2 characters).", "schema": { "type": "string" } }, { "name": "limit", "in": "query", "required": false, "description": "Suggestions (default 15, max 100). No paging: refine as you type.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object" } } } }, "401": { "description": "Missing or invalid API key" }, "404": { "description": "Not found" }, "429": { "description": "Monthly call quota exhausted" } } } }, "/api/public/v1/es/company/{id}": { "get": { "operationId": "company", "summary": "Company profile", "description": "Every data point on a company, by NIF, CIF or registry sheet number: identity, legal form, share capital, registered office, CNAE code, status, directors, ownership and insolvency proceedings.", "tags": [ "Companies" ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "NIF/CIF or registry sheet. Returned by Search companies or Autocomplete (e.g. B54226691 or A105993).", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object" } } } }, "401": { "description": "Missing or invalid API key" }, "404": { "description": "Not found" }, "429": { "description": "Monthly call quota exhausted" } } } }, "/api/public/v1/es/company/{id}/directors": { "get": { "operationId": "company-directors", "summary": "Company directors", "description": "Directors and authorised representatives (current and former), rebuilt from BORME appointments and terminations.", "tags": [ "Companies" ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "NIF, CIF or registry sheet.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object" } } } }, "401": { "description": "Missing or invalid API key" }, "404": { "description": "Not found" }, "429": { "description": "Monthly call quota exhausted" } } } }, "/api/public/v1/es/company/{id}/owners": { "get": { "operationId": "company-owners", "summary": "Ownership", "description": "Sole shareholder, cap table and beneficial owner where the BORME discloses them.", "tags": [ "Companies" ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "NIF, CIF or registry sheet.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object" } } } }, "401": { "description": "Missing or invalid API key" }, "404": { "description": "Not found" }, "429": { "description": "Monthly call quota exhausted" } } } }, "/api/public/v1/es/company/{id}/network": { "get": { "operationId": "company-network", "summary": "Relationship graph", "description": "Nodes and edges linking the company to its directors and the other companies they run.", "tags": [ "Companies" ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "NIF, CIF or registry sheet.", "schema": { "type": "string" } }, { "name": "status", "in": "query", "required": false, "description": "Time filter: active (current roles, default), former (ended roles), all (both).", "schema": { "type": "string" }, "example": "former" }, { "name": "depth", "in": "query", "required": false, "description": "1 = board only · 2 = + members' network (default) · 3 = + their boards · 4 = + subsidiaries' boards.", "schema": { "type": "string" }, "example": "3" }, { "name": "kind", "in": "query", "required": false, "description": "dirigeants (default), associes or beneficiaires.", "schema": { "type": "string" }, "example": "associes" } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object" } } } }, "401": { "description": "Missing or invalid API key" }, "404": { "description": "Not found" }, "429": { "description": "Monthly call quota exhausted" } } } }, "/api/public/v1/es/company/{id}/insolvency": { "get": { "operationId": "company-insolvency", "summary": "Company insolvency", "description": "Insolvency proceedings linked to the company.", "tags": [ "Companies" ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "NIF, CIF or registry sheet.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object" } } } }, "401": { "description": "Missing or invalid API key" }, "404": { "description": "Not found" }, "429": { "description": "Monthly call quota exhausted" } } } }, "/api/public/v1/es/company/{id}/announcements": { "get": { "operationId": "company-announcements", "summary": "BORME history", "description": "Timeline of the company's official gazette filings.", "tags": [ "Companies" ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "NIF, CIF or registry sheet.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object" } } } }, "401": { "description": "Missing or invalid API key" }, "404": { "description": "Not found" }, "429": { "description": "Monthly call quota exhausted" } } } }, "/api/public/v1/es/directors/search": { "get": { "operationId": "directors-search", "summary": "Search directors", "description": "Search people by name.", "tags": [ "Directors" ], "parameters": [ { "name": "query", "in": "query", "required": true, "description": "First name or surname.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object" } } } }, "401": { "description": "Missing or invalid API key" }, "404": { "description": "Not found" }, "429": { "description": "Monthly call quota exhausted" } } } }, "/api/public/v1/es/director/{name}": { "get": { "operationId": "director", "summary": "Person profile", "description": "Every mandate, current and former, held by a person.", "tags": [ "Directors" ], "parameters": [ { "name": "name", "in": "path", "required": true, "description": "Full name, as spelled in the BORME.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object" } } } }, "401": { "description": "Missing or invalid API key" }, "404": { "description": "Not found" }, "429": { "description": "Monthly call quota exhausted" } } } }, "/api/public/v1/es/vat/{nif}": { "get": { "operationId": "vat", "summary": "Validate a VAT number (VIES)", "description": "Checks the intra-EU VAT number against VIES, the European Commission's official service, and joins it to our register data. This is the check required before invoicing an EU customer without VAT. Returns valid, invalid or unavailable, an outage at the tax administration is never reported as invalid.", "tags": [ "Compliance (KYB)" ], "parameters": [ { "name": "nif", "in": "path", "required": true, "description": "Spanish NIF/CIF, with or without the ES prefix.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object" } } } }, "401": { "description": "Missing or invalid API key" }, "404": { "description": "Not found" }, "429": { "description": "Monthly call quota exhausted" } } } }, "/api/public/v1/es/new-companies": { "get": { "operationId": "new-companies", "summary": "Newly incorporated companies", "description": "Recently incorporated companies, filtered by province, sector (CNAE code) and capital. Returns address and phone where known. Defaults to the last 30 days.", "tags": [ "Prospecting" ], "parameters": [ { "name": "since", "in": "query", "required": false, "description": "Incorporated on or after this date (YYYY-MM-DD). Default: 30 days ago.", "schema": { "type": "string" } }, { "name": "provincia", "in": "query", "required": false, "description": "INE province code (29 = Málaga). See /provinces.", "schema": { "type": "string" } }, { "name": "cnae", "in": "query", "required": false, "description": "Activity code as a PREFIX: “64” covers all finance, “6920” accountancy firms. See /cnae.", "schema": { "type": "string" }, "example": "6920" }, { "name": "min_capital", "in": "query", "required": false, "description": "Minimum share capital, in euros.", "schema": { "type": "string" }, "example": "3000" }, { "name": "limit", "in": "query", "required": false, "description": "Results per page (default 50, max 100).", "schema": { "type": "string" } }, { "name": "page", "in": "query", "required": false, "description": "Page, from 1 (max 20).", "schema": { "type": "string" }, "example": "2" } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object" } } } }, "401": { "description": "Missing or invalid API key" }, "404": { "description": "Not found" }, "429": { "description": "Monthly call quota exhausted" } } } }, "/api/public/v1/es/directory": { "get": { "operationId": "directory", "summary": "Directory by sector", "description": "Every company in a sector and province, not just new ones. “I'm an accountant, list the firms in Málaga.” At least one filter is required: province or sector.", "tags": [ "Prospecting" ], "parameters": [ { "name": "cnae", "in": "query", "required": false, "description": "Activity code prefix. Required when provincia is absent.", "schema": { "type": "string" } }, { "name": "provincia", "in": "query", "required": false, "description": "INE province code. Required when cnae is absent.", "schema": { "type": "string" } }, { "name": "active_only", "in": "query", "required": false, "description": "Excludes dissolved companies (default true).", "schema": { "type": "string" }, "example": "false" }, { "name": "min_capital", "in": "query", "required": false, "description": "Minimum share capital, in euros.", "schema": { "type": "string" }, "example": "60000" } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object" } } } }, "401": { "description": "Missing or invalid API key" }, "404": { "description": "Not found" }, "429": { "description": "Monthly call quota exhausted" } } } }, "/api/public/v1/es/cnae": { "get": { "operationId": "cnae", "summary": "Activity codes (CNAE)", "description": "The full nomenclature, with the NUMBER of companies per code, so you can size a target immediately. Search by label (“agricultura”, “software”) to find a code you don't know.", "tags": [ "Prospecting" ], "parameters": [ { "name": "query", "in": "query", "required": false, "description": "Filters on code or label.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object" } } } }, "401": { "description": "Missing or invalid API key" }, "404": { "description": "Not found" }, "429": { "description": "Monthly call quota exhausted" } } } }, "/api/public/v1/es/provinces": { "get": { "operationId": "provinces", "summary": "Provinces", "description": "INE province codes with their name and company count. This is the key behind the provincia parameter elsewhere.", "tags": [ "Prospecting" ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object" } } } }, "401": { "description": "Missing or invalid API key" }, "404": { "description": "Not found" }, "429": { "description": "Monthly call quota exhausted" } } } }, "/api/public/v1/es/insolvency/search": { "get": { "operationId": "insolvency-search", "summary": "Search insolvency filings", "description": "Insolvency notices by company name or CIF (BOE Section IV and RPC).", "tags": [ "Insolvency" ], "parameters": [ { "name": "query", "in": "query", "required": true, "description": "Company name or CIF.", "schema": { "type": "string" } }, { "name": "limit", "in": "query", "required": false, "description": "Results (default 50, max 100).", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object" } } } }, "401": { "description": "Missing or invalid API key" }, "404": { "description": "Not found" }, "429": { "description": "Monthly call quota exhausted" } } } }, "/api/public/v1/es/insolvency/{boe_id}": { "get": { "operationId": "insolvency", "summary": "Full notice", "description": "Full text of an insolvency notice. The identifier is not guessable: it comes from Search insolvency filings (boe_id field) · RPC-N from the Registro Público Concursal, BOE-B-YYYY-N from BOE notices.", "tags": [ "Insolvency" ], "parameters": [ { "name": "boe_id", "in": "path", "required": true, "description": "boe_id returned by Search insolvency filings (e.g. RPC-455662).", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object" } } } }, "401": { "description": "Missing or invalid API key" }, "404": { "description": "Not found" }, "429": { "description": "Monthly call quota exhausted" } } } }, "/api/public/v1/es/screener": { "get": { "operationId": "screener", "summary": "Screen BORME events", "description": "Filter BORME filings by act type, province and date.", "tags": [ "Screener" ], "parameters": [ { "name": "acto", "in": "query", "required": false, "description": "Act type.", "schema": { "type": "string" } }, { "name": "provincia", "in": "query", "required": false, "description": "INE province code (e.g. 28).", "schema": { "type": "string" } }, { "name": "since", "in": "query", "required": false, "description": "From date (YYYY-MM-DD).", "schema": { "type": "string" }, "example": "2026-01-01" }, { "name": "limit", "in": "query", "required": false, "description": "Results (default 50, max 100).", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object" } } } }, "401": { "description": "Missing or invalid API key" }, "404": { "description": "Not found" }, "429": { "description": "Monthly call quota exhausted" } } } } }, "components": { "securitySchemes": { "ApiKeyHeader": { "type": "apiKey", "in": "header", "name": "X-Api-Key" }, "ApiKeyQuery": { "type": "apiKey", "in": "query", "name": "apikey" } } }, "security": [ { "ApiKeyHeader": [] }, { "ApiKeyQuery": [] } ] }