{"openapi":"3.1.0","info":{"title":"Company Directory","version":"1","description":"Find a company by name, Spanish CIF or EU VAT number, and get its record."},"components":{"securitySchemes":{"apiKey":{"type":"http","scheme":"bearer","description":"One API key per consumer, sent as `Authorization: Bearer <key>`."}},"schemas":{"Health":{"type":"object","properties":{"status":{"type":"string","enum":["ok","unavailable"]}},"required":["status"]},"Coverage":{"type":"object","properties":{"coverage":{"$ref":"#/components/schemas/CoverageMap"}},"required":["coverage"]},"CoverageMap":{"type":"object","properties":{"spanishCompanies":{"type":"boolean","description":"Spanish CIFs"},"spanishCompanyNames":{"type":"boolean","description":"Spanish company names"},"euVatNumbers":{"type":"boolean","description":"EU VAT numbers outside Spain"}},"required":["spanishCompanies","spanishCompanyNames","euVatNumbers"]},"Error":{"type":"object","properties":{"code":{"type":"string","enum":["E_INVALID_REQUEST","E_UNAUTHORIZED","E_PERSONAL_ID","E_NOT_FOUND","E_RATE_LIMITED","E_INTERNAL","E_PROVIDER"]},"message":{"type":"string"},"reason":{"type":"string","enum":["timeout","quota","auth","upstream","malformed"],"description":"E_PROVIDER only: why the source failed."}},"required":["code","message"]},"CompanyProfile":{"type":"object","properties":{"id":{"type":"string"},"website":{"type":["object","null"],"properties":{"url":{"type":"string"},"source":{"type":"string","enum":["consumer","source","guess"]},"verified":{"type":"boolean","description":"The site shows the company's CIF or exact legal name (guessed sites always do)."}},"required":["url","source","verified"]},"logo":{"type":["string","null"],"description":"URL on the company's site."},"commercialName":{"type":["string","null"]},"address":{"type":["object","null"],"properties":{"street":{"type":["string","null"]},"postalCode":{"type":["string","null"]},"city":{"type":["string","null"]},"province":{"type":["string","null"]},"region":{"type":["string","null"]},"country":{"type":["string","null"]}},"required":["street","postalCode","city","province","region","country"],"description":"As the site publishes it (often the operating address, not the registered office)."},"taxId":{"type":["string","null"],"description":"A CIF the verified site publishes for itself."},"fetchedAt":{"type":"string"},"cached":{"type":"boolean"}},"required":["id","website","logo","commercialName","address","taxId","fetchedAt","cached"]},"CompanySearchResult":{"type":"object","properties":{"results":{"type":"array","items":{"$ref":"#/components/schemas/CompanySummary"}},"attribution":{"type":["string","null"],"description":"Show it where you display BORME-sourced data.","example":"Fuente: BORME / BOE"}},"required":["results","attribution"]},"CompanySummary":{"type":"object","properties":{"id":{"type":"string","example":"ES-28-M898483"},"idType":{"type":"string","enum":["register","nif","lei"],"description":"register: a commercial register id (ES-<province>-<sheet>); nif: a Spanish CIF or a prefixed EU VAT number; lei: an LEI."},"name":{"type":"string"},"city":{"type":["string","null"]},"province":{"type":["string","null"]},"status":{"type":["string","null"],"enum":["active","dissolved","extinguished","closed",null],"description":"From register acts: dissolved (in liquidation), extinguished, closed (register sheet provisionally closed). Null when the source does not say."},"source":{"type":"string","enum":["borme","gleif","einforma","vies"]}},"required":["id","idType","name","city","province","status","source"]},"CompanyRecord":{"type":"object","properties":{"id":{"type":"string"},"idType":{"type":"string","enum":["register","nif","lei"],"description":"register: a commercial register id (ES-<province>-<sheet>); nif: a Spanish CIF or a prefixed EU VAT number; lei: an LEI."},"legalName":{"type":"string"},"commercialName":{"type":["string","null"]},"taxId":{"type":["string","null"],"description":"Spanish CIF or prefixed EU VAT number. The BORME does not publish CIFs; present once a source that knows it has answered."},"lei":{"type":["string","null"]},"legalForm":{"type":["string","null"]},"status":{"type":["string","null"],"enum":["active","dissolved","extinguished","closed",null],"description":"From register acts: dissolved (in liquidation), extinguished, closed (register sheet provisionally closed). Null when the source does not say."},"address":{"type":"object","properties":{"line1":{"type":["string","null"]},"line2":{"type":["string","null"]},"postalCode":{"type":["string","null"]},"city":{"type":["string","null"]},"province":{"type":["string","null"]},"region":{"type":["string","null"],"description":"ISO 3166-2 (a Spanish province when known)."},"country":{"type":"string"}},"required":["line1","line2","postalCode","city","province","region","country"]},"incorporatedOn":{"type":["string","null"]},"formerNames":{"type":"array","items":{"type":"string"}},"cnae":{"type":["string","null"]},"phone":{"type":["string","null"]},"website":{"type":["string","null"]},"asOf":{"type":["string","null"],"description":"BORME: date of the latest register act reflected."},"source":{"type":"string","enum":["borme","gleif","einforma","vies"]},"attribution":{"type":["string","null"]}},"required":["id","idType","legalName","commercialName","taxId","lei","legalForm","status","address","incorporatedOn","formerNames","cnae","phone","website","asOf","source","attribution"]}},"parameters":{}},"paths":{"/v1/health":{"get":{"tags":["Service"],"summary":"Liveness, including the database","description":"Public, for uptime monitors. The `Server-Timing` header carries the database round trip (`db`).","responses":{"200":{"description":"Up","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Health"}}}},"503":{"description":"The database is unreachable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Health"}}}}}}},"/v1/coverage":{"get":{"tags":["Companies"],"summary":"Which query kinds this deployment answers","security":[{"apiKey":[]}],"responses":{"200":{"description":"Coverage","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Coverage"}}}},"401":{"description":"Missing, unknown or revoked API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit for this API key exceeded","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/companies/{id}/profile":{"get":{"tags":["Companies"],"summary":"A company's website, logo, commercial name and address","description":"From the company's own website, found through `website` (a hint you already have), a source that knows it, or a guessed domain the site must confirm. Built on first request (allow ~10 s) and kept for later ones.","security":[{"apiKey":[]}],"parameters":[{"schema":{"type":"string","minLength":1,"maxLength":40,"example":"ES-28-M213180"},"required":true,"name":"id","in":"path"},{"schema":{"type":"string","minLength":4,"maxLength":200,"description":"The company website, if you know it (e.g. typed by the user)."},"required":false,"description":"The company website, if you know it (e.g. typed by the user).","name":"website","in":"query"}],"responses":{"200":{"description":"The profile (fields are null when the site does not say)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CompanyProfile"}}}},"400":{"description":"Invalid query, or a natural person's id","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing, unknown or revoked API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Unknown company","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit for this API key exceeded","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"502":{"description":"A company source failed (fixed message per reason)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/companies/search":{"get":{"tags":["Companies"],"summary":"Find companies by name, Spanish CIF or EU VAT number","description":"Names: prefix- and typo-tolerant over every company in the commercial register (BORME), current and former names, then GLEIF and eInforma when the register finds nothing. CIFs: the index, then eInforma. Prefixed EU VAT numbers: VIES. Natural persons' ids are refused.","security":[{"apiKey":[]}],"parameters":[{"schema":{"type":"string","minLength":1,"maxLength":120,"example":"recargas punto"},"required":true,"name":"q","in":"query"},{"schema":{"type":"string","pattern":"^[A-Za-z]{2}$","description":"ISO 3166-1 alpha-2 of the billing country; lets a bare EU VAT number be read for that country."},"required":false,"description":"ISO 3166-1 alpha-2 of the billing country; lets a bare EU VAT number be read for that country.","name":"country","in":"query"},{"schema":{"type":"integer","minimum":1,"maximum":20,"default":10},"required":false,"name":"limit","in":"query"}],"responses":{"200":{"description":"Matches, best first","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CompanySearchResult"}}}},"400":{"description":"Invalid query, or a natural person's id","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing, unknown or revoked API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit for this API key exceeded","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"502":{"description":"A company source failed (fixed message per reason)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/companies/{id}":{"get":{"tags":["Companies"],"summary":"Get a company record","description":"By the id a search returned: a register id, a Spanish CIF, a prefixed EU VAT number or an LEI.","security":[{"apiKey":[]}],"parameters":[{"schema":{"type":"string","minLength":1,"maxLength":40,"example":"ES-28-M898483"},"required":true,"name":"id","in":"path"}],"responses":{"200":{"description":"The record","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CompanyRecord"}}}},"400":{"description":"Invalid query, or a natural person's id","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing, unknown or revoked API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Unknown company","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit for this API key exceeded","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"502":{"description":"A company source failed (fixed message per reason)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}}},"webhooks":{}}