{"openapi":"3.1.0","info":{"title":"Sisoco One API","version":"2026-11-14","description":"Counterparty early warning for apps and AI agents — watch UK and EU companies and get webhooks the moment official records show risk. One key, one schema, source on every event, self-serve from £0\n\nGet a free read-only preview key with `POST https://api.sisoco.co.uk/v1/preview/keys` (no sign-up), then send it as `Authorization: Bearer <key>`. MCP endpoint: https://api.sisoco.co.uk/mcp. Terms: https://api.sisoco.co.uk/terms. Start with `GET /v1/check`."},"components":{"schemas":{},"securitySchemes":{"bearer":{"type":"http","scheme":"bearer","description":"API key: Authorization: Bearer sisk_live_…"}}},"paths":{"/v1/health":{"get":{"summary":"Service health","tags":["platform"],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"status":{"type":"string","enum":["ok"]},"service":{"type":"string"},"version":{"type":"string"},"commit":{"type":"string"},"api_version":{"type":"string"},"packs":{"type":"integer","minimum":0,"maximum":9007199254740991}},"required":["status","service","version","commit","api_version","packs"],"additionalProperties":false},"meta":{"type":"object","properties":{"request_id":{"type":"string"}},"required":["request_id"],"additionalProperties":false}},"required":["data","meta"],"additionalProperties":false}}}}},"security":[]}},"/v1/account":{"get":{"summary":"The account that owns this API key","tags":["account"],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"id":{"type":"string"},"email":{"type":"string"},"plan":{"type":"string"},"tier":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"status":{"type":"string"},"api_version":{"type":"string","description":"API version this account is pinned to; used when no Sisoco-Version header is sent"},"created_at":{"type":"string"},"entitlements":{"type":"object","propertyNames":{"type":"string"},"additionalProperties":{"type":["number","boolean","string"]}}},"required":["id","email","plan","tier","status","api_version","created_at","entitlements"],"additionalProperties":false},"meta":{"type":"object","properties":{"request_id":{"type":"string"}},"required":["request_id"],"additionalProperties":false}},"required":["data","meta"],"additionalProperties":false}}}}}}},"/v1/keys":{"get":{"summary":"List this account's API keys","tags":["account"],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"display":{"type":"string","description":"Key prefix for display, e.g. sisk_live_AbCd…; the full key is shown only once, at creation"},"created_at":{"type":"string"},"last_used_at":{"type":["string","null"]},"revoked_at":{"type":["string","null"]},"scope":{"type":"string","enum":["read_write","read_only"]},"allowed_ips":{"anyOf":[{"type":"array","items":{"type":"string"}},{"type":"null"}],"description":"Client IPs/CIDRs this key may be used from; null = any"},"expires_at":{"description":"After this time the key stops working (preview keys); null = no expiry","type":["string","null"]}},"required":["id","name","display","created_at","last_used_at","revoked_at","scope","allowed_ips","expires_at"],"additionalProperties":false}},"meta":{"type":"object","properties":{"request_id":{"type":"string"}},"required":["request_id"],"additionalProperties":false}},"required":["data","meta"],"additionalProperties":false}}}}}}},"/v1/keys/{key_id}":{"get":{"summary":"One API key of this account","tags":["account"],"parameters":[{"schema":{"type":"string","maxLength":64},"in":"path","name":"key_id","required":true}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"display":{"type":"string","description":"Key prefix for display, e.g. sisk_live_AbCd…; the full key is shown only once, at creation"},"created_at":{"type":"string"},"last_used_at":{"type":["string","null"]},"revoked_at":{"type":["string","null"]},"scope":{"type":"string","enum":["read_write","read_only"]},"allowed_ips":{"anyOf":[{"type":"array","items":{"type":"string"}},{"type":"null"}],"description":"Client IPs/CIDRs this key may be used from; null = any"},"expires_at":{"description":"After this time the key stops working (preview keys); null = no expiry","type":["string","null"]}},"required":["id","name","display","created_at","last_used_at","revoked_at","scope","allowed_ips","expires_at"],"additionalProperties":false},"meta":{"type":"object","properties":{"request_id":{"type":"string"}},"required":["request_id"],"additionalProperties":false}},"required":["data","meta"],"additionalProperties":false}}}}}}},"/v1/preview/keys":{"post":{"summary":"Get a free preview API key (read-only, no sign-up)","tags":["preview"],"description":"Issues one read-only API key on the Preview plan: 100 lookups per month, no watching, expires after 30 days. At most 3 keys per client IP per UTC day. The key is shown once. Send an Idempotency-Key header to retry safely: a retry within 10 minutes returns the same key. Use it as \"Authorization: Bearer <key>\" on /v1 routes and on the MCP endpoint /mcp.","requestBody":{"required":true,"content":{"application/json":{"schema":{"anyOf":[{"type":"object","properties":{"source":{"default":"direct","description":"Where you found Sisoco One","type":"string","enum":["mcp_registry","smithery","glama","pulsemcp","mcp_so","llms_txt","openapi","github","direct","other"]},"ref":{"description":"Free text: the listing URL, campaign or agent name","type":"string","maxLength":200},"contact_email":{"description":"Optional; stored unverified, never mailed during the preview","type":"string","maxLength":320,"format":"email","pattern":"^(?:[A-Za-z0-9_'+\\-]+\\.)*[A-Za-z0-9_'+\\-]*[A-Za-z0-9_+-]@(?:[A-Za-z0-9][A-Za-z0-9\\-]*\\.)+[A-Za-z]{2,}$"}},"additionalProperties":false},{"type":"null"}]}}}},"responses":{"201":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"key":{"type":"string","description":"The API key. Shown once; it is not stored and cannot be shown again."},"key_id":{"type":"string"},"display":{"type":"string"},"account_id":{"type":"string"},"plan":{"type":"string"},"scope":{"type":"string","enum":["read_only","read_write"]},"expires_at":{"type":"string"},"lookups_per_month":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"mcp_url":{"type":"string"},"openapi_url":{"type":"string"},"terms_url":{"type":"string"}},"required":["key","key_id","display","account_id","plan","scope","expires_at","lookups_per_month","mcp_url","openapi_url","terms_url"],"additionalProperties":false},"meta":{"type":"object","properties":{"request_id":{"type":"string"}},"required":["request_id"],"additionalProperties":false}},"required":["data","meta"],"additionalProperties":false}}}}},"security":[]}},"/v1/usage":{"get":{"summary":"This account's usage, limits and usage tier","tags":["account"],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"period":{"type":"object","properties":{"id":{"type":"string","description":"Calendar month (UTC), YYYY-MM"},"start":{"type":"string"},"end":{"type":"string"}},"required":["id","start","end"],"additionalProperties":false},"plan":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"}},"required":["id","name"],"additionalProperties":false},"lookups":{"type":"object","properties":{"used":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"limit":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"remaining":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991}},"required":["used","limit","remaining"],"additionalProperties":false,"description":"Lookups charged this period against the plan quota (1 per lookup request, cached or not)"},"watched_entities":{"type":"object","properties":{"used":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"limit":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"remaining":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991}},"required":["used","limit","remaining"],"additionalProperties":false,"description":"Active watched entities against the plan limit"},"rate_limit":{"type":"object","properties":{"requests_per_minute":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"per":{"type":"string","enum":["api_key"]}},"required":["requests_per_minute","per"],"additionalProperties":false},"tier":{"type":"object","properties":{"current":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991,"description":"Usage tier (rises with payment history; sets the rate limit)"},"progress":{"type":"object","properties":{"cumulative_paid_pence":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"account_age_days":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991}},"required":["cumulative_paid_pence","account_age_days"],"additionalProperties":false},"next":{"anyOf":[{"type":"object","properties":{"tier":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"requests_per_minute":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"criteria":{"type":"object","properties":{"min_cumulative_paid_pence":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"min_account_age_days":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991}},"required":["min_cumulative_paid_pence","min_account_age_days"],"additionalProperties":false}},"required":["tier","requests_per_minute","criteria"],"additionalProperties":false},{"type":"null"}],"description":"Next usage tier and what reaching it takes; null at the top tier"}},"required":["current","progress","next"],"additionalProperties":false}},"required":["period","plan","lookups","watched_entities","rate_limit","tier"],"additionalProperties":false},"meta":{"type":"object","properties":{"request_id":{"type":"string"}},"required":["request_id"],"additionalProperties":false}},"required":["data","meta"],"additionalProperties":false}}}}}}},"/v1/check":{"get":{"summary":"Check a company in one call: matched entity, signals and recent events","tags":["check"],"parameters":[{"schema":{"type":"string","minLength":1,"maxLength":200},"in":"query","name":"company","required":true,"description":"Registry number (e.g. 00445790, SIREN 552032534), LEI, or a company name"},{"schema":{"type":"string","pattern":"^[A-Za-z]{2}$"},"in":"query","name":"country","required":false,"description":"ISO 3166-1 alpha-2 (GB, FR); needed for name searches"}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"entity":{"type":"object","properties":{"id":{"type":"string"},"kind":{"type":"string"},"country":{"type":["string","null"]},"registry":{"type":"string"},"registry_id":{"type":"string"},"name":{"type":"string"},"status":{"type":["string","null"]},"lei":{"type":["string","null"]}},"required":["id","kind","country","registry","registry_id","name","status","lei"],"additionalProperties":false},"match":{"type":"object","properties":{"resolver":{"type":"string","description":"Which resolver matched, e.g. gb-company-number"},"kind":{"type":"string","enum":["identifier","name"]},"confidence":{"type":"number","description":"1 for an exact identifier or name match"}},"required":["resolver","kind","confidence"],"additionalProperties":false},"signals":{"type":"array","items":{"type":"object","properties":{"type":{"type":"string"},"severity":{"type":"string","enum":["info","warning","critical"]},"since":{"type":["string","null"]},"source_url":{"type":["string","null"]},"source":{"type":"string"},"event_id":{"type":["string","null"]},"details":{"type":"object","propertyNames":{"type":"string"},"additionalProperties":{}}},"required":["type","severity","since","source_url","source","event_id","details"],"additionalProperties":false},"description":"Conditions true now (e.g. accounts overdue, a sanctions possible match), newest first"},"recent_events":{"type":"array","items":{"type":"object","properties":{"api_version":{"type":"string"},"event_id":{"type":"string"},"type":{"type":"string"},"vertical":{"description":"Pack id for vertical events; null for the core product pack","type":["string","null"]},"severity":{"type":"string","enum":["info","warning","critical"],"description":"Default severity of the type (profiles may change it from M5c)"},"entity":{"type":"object","properties":{"id":{"type":"string"},"kind":{"type":"string"},"country":{"type":["string","null"]},"registry":{"type":"string"},"registry_id":{"type":"string"},"name":{"type":"string"},"status":{"type":["string","null"]},"lei":{"type":["string","null"]}},"required":["id","kind","country","registry","registry_id","name","status","lei"],"additionalProperties":false},"related":{"type":"array","items":{"type":"object","properties":{"entity_id":{"type":"string"},"relationship":{"type":"string"}},"required":["entity_id","relationship"],"additionalProperties":false}},"effective_at":{"type":["string","null"]},"observed_at":{"type":"string"},"source":{"type":"object","properties":{"id":{"type":"string"},"url":{"type":["string","null"]},"attribution":{"type":["string","null"]}},"required":["id","url","attribution"],"additionalProperties":false},"data":{"type":"object","propertyNames":{"type":"string"},"additionalProperties":{}}},"required":["api_version","event_id","type","vertical","severity","entity","related","effective_at","observed_at","source","data"],"additionalProperties":false},"description":"Events in the last 90 days, newest first (max 20)"},"watching":{"type":"boolean","description":"Whether this account watches the entity on any of its watchlists"},"sources":{"type":"array","items":{"type":"object","properties":{"fields":{"type":"array","items":{"type":"string"},"description":"Fields of entity this source backs, e.g. [\"name\",\"status\",\"registry_id\"]"},"source":{"type":"string","description":"The official source, e.g. Companies House"},"url":{"type":"string","description":"Link to the record at the source"}},"required":["fields","source","url"],"additionalProperties":false},"description":"Where each core fact comes from, with a link to the official record. Signals and events carry their own source_url."}},"required":["entity","match","signals","recent_events","watching","sources"],"additionalProperties":false},"meta":{"type":"object","properties":{"request_id":{"type":"string"},"retrieved_at":{"type":"string"},"cached":{"type":"boolean"},"sources":{"type":"array","items":{"type":"string"}}},"required":["request_id","retrieved_at","cached","sources"],"additionalProperties":false}},"required":["data","meta"],"additionalProperties":false}}}}}}},"/v1/catalog":{"get":{"summary":"Catalog of packs and lookup providers","tags":["platform"],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"packs":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"version":{"type":"string"},"providers":{"type":"array","items":{"type":"string"}},"check_resolvers":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"kind":{"type":"string","enum":["identifier","name"]},"description":{"type":"string"}},"required":["id","kind","description"],"additionalProperties":false}}},"required":["id","name","version","providers","check_resolvers"],"additionalProperties":false}},"providers":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"pack":{"type":"string"},"status":{"type":"string","enum":["live","beta","unavailable"],"description":"live: answering; beta: in a beta pack; unavailable: installed but switched off (licence or configuration)"},"licence":{"type":"object","properties":{"status":{"type":"string"},"attribution":{"type":["string","null"]},"source_url":{"type":"string"}},"required":["status","attribution","source_url"],"additionalProperties":false},"limits":{"type":"object","properties":{"requests_per_window":{"type":"number"},"window_seconds":{"type":"number"}},"required":["requests_per_window","window_seconds"],"additionalProperties":false,"description":"The provider's published upstream limit, shared by all Sisoco One accounts"},"operations":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"units":{"type":"number"},"cache_ttl_seconds":{"type":["number","null"]}},"required":["id","units","cache_ttl_seconds"],"additionalProperties":false}}},"required":["id","name","pack","status","licence","limits","operations"],"additionalProperties":false}}},"required":["packs","providers"],"additionalProperties":false},"meta":{"type":"object","properties":{"request_id":{"type":"string"}},"required":["request_id"],"additionalProperties":false}},"required":["data","meta"],"additionalProperties":false}}}}},"security":[]}},"/v1/catalog/providers/{id}":{"get":{"summary":"One lookup provider","tags":["platform"],"parameters":[{"schema":{"type":"string","maxLength":64},"in":"path","name":"id","required":true}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"pack":{"type":"string"},"status":{"type":"string","enum":["live","beta","unavailable"],"description":"live: answering; beta: in a beta pack; unavailable: installed but switched off (licence or configuration)"},"licence":{"type":"object","properties":{"status":{"type":"string"},"attribution":{"type":["string","null"]},"source_url":{"type":"string"}},"required":["status","attribution","source_url"],"additionalProperties":false},"limits":{"type":"object","properties":{"requests_per_window":{"type":"number"},"window_seconds":{"type":"number"}},"required":["requests_per_window","window_seconds"],"additionalProperties":false,"description":"The provider's published upstream limit, shared by all Sisoco One accounts"},"operations":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"units":{"type":"number"},"cache_ttl_seconds":{"type":["number","null"]}},"required":["id","units","cache_ttl_seconds"],"additionalProperties":false}}},"required":["id","name","pack","status","licence","limits","operations"],"additionalProperties":false},"meta":{"type":"object","properties":{"request_id":{"type":"string"}},"required":["request_id"],"additionalProperties":false}},"required":["data","meta"],"additionalProperties":false}}}}},"security":[]}},"/v1/profiles":{"get":{"summary":"Watchlist profiles available to this account","tags":["watchlists"],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"pack":{"type":["string","null"]},"description":{"type":"string"},"default":{"type":"boolean"},"types":{"anyOf":[{"type":"string","enum":["*"]},{"type":"array","items":{"type":"string"}}]},"severity":{"type":"object","propertyNames":{"type":"string"},"additionalProperties":{"type":"string","enum":["info","warning","critical"]}},"min_severity":{"anyOf":[{"type":"string","enum":["info","warning","critical"]},{"type":"null"}]}},"required":["id","pack","description","default","types","severity","min_severity"],"additionalProperties":false}},"meta":{"type":"object","properties":{"request_id":{"type":"string"}},"required":["request_id"],"additionalProperties":false}},"required":["data","meta"],"additionalProperties":false}}}}}}},"/v1/watchlists":{"post":{"summary":"Create a watchlist","tags":["watchlists"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string","minLength":1,"maxLength":100},"profile":{"description":"Default: core-default","type":"string","minLength":1,"maxLength":64}},"required":["name"],"additionalProperties":false}}}},"responses":{"201":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"profile":{"type":"string","description":"Profile applied to events of this watchlist (GET /v1/profiles)"},"entity_count":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"created_at":{"type":"string"}},"required":["id","name","profile","entity_count","created_at"],"additionalProperties":false},"meta":{"type":"object","properties":{"request_id":{"type":"string"}},"required":["request_id"],"additionalProperties":false}},"required":["data","meta"],"additionalProperties":false}}}}}},"get":{"summary":"This account's watchlists","tags":["watchlists"],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"profile":{"type":"string","description":"Profile applied to events of this watchlist (GET /v1/profiles)"},"entity_count":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"created_at":{"type":"string"}},"required":["id","name","profile","entity_count","created_at"],"additionalProperties":false}},"meta":{"type":"object","properties":{"request_id":{"type":"string"}},"required":["request_id"],"additionalProperties":false}},"required":["data","meta"],"additionalProperties":false}}}}}}},"/v1/watchlists/{id}":{"get":{"summary":"One watchlist","tags":["watchlists"],"parameters":[{"schema":{"type":"string","minLength":1,"maxLength":64},"in":"path","name":"id","required":true}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"profile":{"type":"string","description":"Profile applied to events of this watchlist (GET /v1/profiles)"},"entity_count":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"created_at":{"type":"string"}},"required":["id","name","profile","entity_count","created_at"],"additionalProperties":false},"meta":{"type":"object","properties":{"request_id":{"type":"string"}},"required":["request_id"],"additionalProperties":false}},"required":["data","meta"],"additionalProperties":false}}}}}},"delete":{"summary":"Delete a watchlist (its entities stop being watched; feed history is kept)","tags":["watchlists"],"parameters":[{"schema":{"type":"string","minLength":1,"maxLength":64},"in":"path","name":"id","required":true}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"id":{"type":"string"},"deleted":{"type":"boolean","enum":[true]}},"required":["id","deleted"],"additionalProperties":false},"meta":{"type":"object","properties":{"request_id":{"type":"string"}},"required":["request_id"],"additionalProperties":false}},"required":["data","meta"],"additionalProperties":false}}}}}}},"/v1/watchlists/{id}/entities":{"get":{"summary":"Entities on a watchlist","tags":["watchlists"],"parameters":[{"schema":{"default":100,"type":"integer","minimum":1,"maximum":500},"in":"query","name":"limit","required":false},{"schema":{"type":"string","maxLength":64},"in":"query","name":"cursor","required":false,"description":"entity_id of the last item of the previous page"},{"schema":{"type":"string","minLength":1,"maxLength":64},"in":"path","name":"id","required":true}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"entity":{"type":"object","properties":{"id":{"type":"string"},"kind":{"type":"string"},"country":{"type":["string","null"]},"registry":{"type":"string"},"registry_id":{"type":"string"},"name":{"type":"string"},"status":{"type":["string","null"]},"lei":{"type":["string","null"]}},"required":["id","kind","country","registry","registry_id","name","status","lei"],"additionalProperties":false},"client_reference":{"type":["string","null"]},"added_at":{"type":"string"}},"required":["entity","client_reference","added_at"],"additionalProperties":false}},"meta":{"type":"object","properties":{"request_id":{"type":"string"},"next_cursor":{"type":["string","null"]}},"required":["request_id","next_cursor"],"additionalProperties":false}},"required":["data","meta"],"additionalProperties":false}}}}}},"post":{"summary":"Watch entities: up to 1000 per call by entity_id or identifier; name + country returns a GET /v1/match URL","tags":["watchlists"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"entities":{"minItems":1,"maxItems":1000,"type":"array","items":{"type":"object","properties":{"entity_id":{"type":"string","minLength":1,"maxLength":64},"identifier":{"description":"Registry number or LEI, read offline by the packs’ identifier parsers","type":"string","minLength":1,"maxLength":64},"country":{"type":"string","pattern":"^[A-Za-z]{2}$"},"name":{"description":"With country: answered needs_match with a GET /v1/match URL","type":"string","minLength":2,"maxLength":200},"client_reference":{"description":"Your own id; echoed on feed items and webhooks","type":"string","maxLength":200}},"additionalProperties":false,"description":"One of: entity_id; identifier (+ country); name + country"}}},"required":["entities"],"additionalProperties":false}}}},"parameters":[{"schema":{"type":"string","minLength":1,"maxLength":64},"in":"path","name":"id","required":true}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"added":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"watched_entities":{"type":"object","properties":{"used":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"limit":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"remaining":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991}},"required":["used","limit","remaining"],"additionalProperties":false},"results":{"type":"array","items":{"type":"object","properties":{"index":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"status":{"type":"string","enum":["added","already_watching","needs_match","invalid","not_entitled","not_found"]},"entity":{"anyOf":[{"type":"object","properties":{"id":{"type":"string"},"kind":{"type":"string"},"country":{"type":["string","null"]},"registry":{"type":"string"},"registry_id":{"type":"string"},"name":{"type":"string"},"status":{"type":["string","null"]},"lei":{"type":["string","null"]}},"required":["id","kind","country","registry","registry_id","name","status","lei"],"additionalProperties":false},{"type":"null"}]},"parser":{"type":["string","null"]},"message":{"type":["string","null"]},"match_url":{"type":["string","null"]}},"required":["index","status","entity","parser","message","match_url"],"additionalProperties":false}}},"required":["added","watched_entities","results"],"additionalProperties":false},"meta":{"type":"object","properties":{"request_id":{"type":"string"}},"required":["request_id"],"additionalProperties":false}},"required":["data","meta"],"additionalProperties":false}}}}}}},"/v1/watchlists/{id}/entities/{entity_id}":{"delete":{"summary":"Stop watching an entity on this watchlist","tags":["watchlists"],"parameters":[{"schema":{"type":"string","minLength":1,"maxLength":64},"in":"path","name":"id","required":true},{"schema":{"type":"string","minLength":1,"maxLength":64},"in":"path","name":"entity_id","required":true}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"watchlist_id":{"type":"string"},"entity_id":{"type":"string"},"removed":{"type":"boolean","enum":[true]}},"required":["watchlist_id","entity_id","removed"],"additionalProperties":false},"meta":{"type":"object","properties":{"request_id":{"type":"string"}},"required":["request_id"],"additionalProperties":false}},"required":["data","meta"],"additionalProperties":false}}}}}}},"/v1/events":{"get":{"summary":"Event feed for watched entities (polling, with cursor)","tags":["events"],"parameters":[{"schema":{"type":"string","maxLength":64},"in":"query","name":"watchlist_id","required":false},{"schema":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$"},"in":"query","name":"since","required":false,"description":"Only items that reached the feed at or after this time (ignored with cursor)"},{"schema":{"type":"string","maxLength":64},"in":"query","name":"cursor","required":false,"description":"next_cursor from the previous page"},{"schema":{"type":"string","maxLength":2000},"in":"query","name":"types","required":false,"description":"Comma-separated event types"},{"schema":{"type":"string","maxLength":2000},"in":"query","name":"severity","required":false,"description":"Comma-separated severities (after the watchlist profile)"},{"schema":{"default":50,"type":"integer","minimum":1,"maximum":100},"in":"query","name":"limit","required":false}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"api_version":{"type":"string"},"event_id":{"type":"string"},"type":{"type":"string"},"vertical":{"description":"Pack id for vertical events; null for the core product pack","type":["string","null"]},"severity":{"type":"string","enum":["info","warning","critical"],"description":"Default severity of the type (profiles may change it from M5c)"},"entity":{"type":"object","properties":{"id":{"type":"string"},"kind":{"type":"string"},"country":{"type":["string","null"]},"registry":{"type":"string"},"registry_id":{"type":"string"},"name":{"type":"string"},"status":{"type":["string","null"]},"lei":{"type":["string","null"]}},"required":["id","kind","country","registry","registry_id","name","status","lei"],"additionalProperties":false},"related":{"type":"array","items":{"type":"object","properties":{"entity_id":{"type":"string"},"relationship":{"type":"string"}},"required":["entity_id","relationship"],"additionalProperties":false}},"effective_at":{"type":["string","null"]},"observed_at":{"type":"string"},"source":{"type":"object","properties":{"id":{"type":"string"},"url":{"type":["string","null"]},"attribution":{"type":["string","null"]}},"required":["id","url","attribution"],"additionalProperties":false},"data":{"type":"object","propertyNames":{"type":"string"},"additionalProperties":{}},"watchlist_id":{"type":"string"},"client_reference":{"type":["string","null"]}},"required":["api_version","event_id","type","vertical","severity","entity","related","effective_at","observed_at","source","data","watchlist_id","client_reference"],"additionalProperties":false}},"meta":{"type":"object","properties":{"request_id":{"type":"string"},"next_cursor":{"type":["string","null"]},"has_more":{"type":"boolean"}},"required":["request_id","next_cursor","has_more"],"additionalProperties":false}},"required":["data","meta"],"additionalProperties":false}}}}}}},"/v1/webhooks":{"post":{"summary":"Register a webhook endpoint (the signing secret is shown once)","tags":["webhooks"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"url":{"type":"string","maxLength":2000,"description":"https:// URL on port 443 with a public DNS name"},"event_types":{"default":[],"description":"Empty = every event type","maxItems":100,"type":"array","items":{"type":"string","pattern":"^[a-z][a-z0-9_]*\\.[a-z][a-z0-9_]*$"}},"description":{"type":"string","maxLength":200}},"required":["url"],"additionalProperties":false}}}},"responses":{"201":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"id":{"type":"string"},"url":{"type":"string"},"description":{"type":["string","null"]},"event_types":{"type":"array","items":{"type":"string"},"description":"Event types delivered; empty = every type"},"status":{"type":"string","enum":["active","disabled"]},"secret_prefix":{"type":"string","description":"First characters of the signing secret, to tell secrets apart"},"created_at":{"type":"string"},"disabled_at":{"type":["string","null"]},"disabled_reason":{"type":["string","null"]},"secret":{"type":"string","description":"whsec_… — shown only now; store it to verify Sisoco-Signature"}},"required":["id","url","description","event_types","status","secret_prefix","created_at","disabled_at","disabled_reason","secret"],"additionalProperties":false},"meta":{"type":"object","properties":{"request_id":{"type":"string"}},"required":["request_id"],"additionalProperties":false}},"required":["data","meta"],"additionalProperties":false}}}}}},"get":{"summary":"This account's webhook endpoints","tags":["webhooks"],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"url":{"type":"string"},"description":{"type":["string","null"]},"event_types":{"type":"array","items":{"type":"string"},"description":"Event types delivered; empty = every type"},"status":{"type":"string","enum":["active","disabled"]},"secret_prefix":{"type":"string","description":"First characters of the signing secret, to tell secrets apart"},"created_at":{"type":"string"},"disabled_at":{"type":["string","null"]},"disabled_reason":{"type":["string","null"]}},"required":["id","url","description","event_types","status","secret_prefix","created_at","disabled_at","disabled_reason"],"additionalProperties":false}},"meta":{"type":"object","properties":{"request_id":{"type":"string"}},"required":["request_id"],"additionalProperties":false}},"required":["data","meta"],"additionalProperties":false}}}}}}},"/v1/webhooks/{id}":{"get":{"summary":"One webhook endpoint","tags":["webhooks"],"parameters":[{"schema":{"type":"string","minLength":1,"maxLength":64},"in":"path","name":"id","required":true}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"id":{"type":"string"},"url":{"type":"string"},"description":{"type":["string","null"]},"event_types":{"type":"array","items":{"type":"string"},"description":"Event types delivered; empty = every type"},"status":{"type":"string","enum":["active","disabled"]},"secret_prefix":{"type":"string","description":"First characters of the signing secret, to tell secrets apart"},"created_at":{"type":"string"},"disabled_at":{"type":["string","null"]},"disabled_reason":{"type":["string","null"]}},"required":["id","url","description","event_types","status","secret_prefix","created_at","disabled_at","disabled_reason"],"additionalProperties":false},"meta":{"type":"object","properties":{"request_id":{"type":"string"}},"required":["request_id"],"additionalProperties":false}},"required":["data","meta"],"additionalProperties":false}}}}}},"delete":{"summary":"Delete a webhook endpoint (pending deliveries stop)","tags":["webhooks"],"parameters":[{"schema":{"type":"string","minLength":1,"maxLength":64},"in":"path","name":"id","required":true}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"id":{"type":"string"},"deleted":{"type":"boolean","enum":[true]}},"required":["id","deleted"],"additionalProperties":false},"meta":{"type":"object","properties":{"request_id":{"type":"string"}},"required":["request_id"],"additionalProperties":false}},"required":["data","meta"],"additionalProperties":false}}}}}}},"/v1/webhooks/{id}/deliveries":{"get":{"summary":"Delivery log of a webhook endpoint, newest first","tags":["webhooks"],"parameters":[{"schema":{"default":50,"type":"integer","minimum":1,"maximum":100},"in":"query","name":"limit","required":false},{"schema":{"type":"string","maxLength":64},"in":"query","name":"cursor","required":false,"description":"id of the last delivery of the previous page"},{"schema":{"type":"string","enum":["pending","succeeded","failed"]},"in":"query","name":"status","required":false},{"schema":{"type":"string","minLength":1,"maxLength":64},"in":"path","name":"id","required":true}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"event_id":{"type":"string"},"test":{"type":"boolean"},"status":{"type":"string","enum":["pending","succeeded","failed"]},"attempts":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"last_status_code":{"anyOf":[{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},{"type":"null"}]},"last_error":{"type":["string","null"]},"last_attempt_at":{"type":["string","null"]},"next_attempt_at":{"type":["string","null"]},"delivered_at":{"type":["string","null"]},"created_at":{"type":"string"}},"required":["id","event_id","test","status","attempts","last_status_code","last_error","last_attempt_at","next_attempt_at","delivered_at","created_at"],"additionalProperties":false}},"meta":{"type":"object","properties":{"request_id":{"type":"string"},"next_cursor":{"type":["string","null"]}},"required":["request_id","next_cursor"],"additionalProperties":false}},"required":["data","meta"],"additionalProperties":false}}}}}}},"/v1/webhooks/{id}/test":{"post":{"summary":"Send one signed sample event to the endpoint now and return the delivery result","tags":["webhooks"],"parameters":[{"schema":{"type":"string","minLength":1,"maxLength":64},"in":"path","name":"id","required":true}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"id":{"type":"string"},"event_id":{"type":"string"},"test":{"type":"boolean"},"status":{"type":"string","enum":["pending","succeeded","failed"]},"attempts":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"last_status_code":{"anyOf":[{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},{"type":"null"}]},"last_error":{"type":["string","null"]},"last_attempt_at":{"type":["string","null"]},"next_attempt_at":{"type":["string","null"]},"delivered_at":{"type":["string","null"]},"created_at":{"type":"string"}},"required":["id","event_id","test","status","attempts","last_status_code","last_error","last_attempt_at","next_attempt_at","delivered_at","created_at"],"additionalProperties":false},"meta":{"type":"object","properties":{"request_id":{"type":"string"}},"required":["request_id"],"additionalProperties":false}},"required":["data","meta"],"additionalProperties":false}}}}}}},"/v1/match":{"get":{"summary":"Candidates for a company name + country (to choose what to watch)","tags":["watchlists"],"parameters":[{"schema":{"type":"string","minLength":2,"maxLength":200},"in":"query","name":"name","required":true},{"schema":{"type":"string","pattern":"^[A-Za-z]{2}$"},"in":"query","name":"country","required":true}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"candidates":{"type":"array","items":{"type":"object","properties":{"entity":{"anyOf":[{"type":"object","properties":{"id":{"type":"string"},"kind":{"type":"string"},"country":{"type":["string","null"]},"registry":{"type":"string"},"registry_id":{"type":"string"},"name":{"type":"string"},"status":{"type":["string","null"]},"lei":{"type":["string","null"]}},"required":["id","kind","country","registry","registry_id","name","status","lei"],"additionalProperties":false},{"type":"null"}],"description":"The candidate as an entity, when the graph already holds it"},"name":{"type":"string"},"country":{"type":["string","null"]},"registry":{"type":"string"},"registry_id":{"type":"string"},"status":{"type":["string","null"]},"confidence":{"type":"number","minimum":0,"maximum":1,"description":"Name similarity to the query (0–1); not a judgement about the company"},"resolver":{"type":"string"},"watch_item":{"type":"object","properties":{"identifier":{"type":"string"},"country":{"type":["string","null"]}},"required":["identifier","country"],"additionalProperties":false,"description":"Send this item to POST /v1/watchlists/{id}/entities to watch the candidate"}},"required":["entity","name","country","registry","registry_id","status","confidence","resolver","watch_item"],"additionalProperties":false}}},"required":["candidates"],"additionalProperties":false},"meta":{"type":"object","properties":{"request_id":{"type":"string"},"sources":{"type":"array","items":{"type":"string"}}},"required":["request_id","sources"],"additionalProperties":false}},"required":["data","meta"],"additionalProperties":false}}}}}}},"/v1/entities/{entity_id}/events":{"get":{"summary":"Recent events stored for one entity (newest first)","tags":["events"],"parameters":[{"schema":{"default":20,"type":"integer","minimum":1,"maximum":100},"in":"query","name":"limit","required":false,"description":"Most recent events to return (1–100)"},{"schema":{"default":90,"type":"integer","minimum":1,"maximum":365},"in":"query","name":"since_days","required":false,"description":"Look back this many days (1–365)"},{"schema":{"type":"string","pattern":"^ent_[A-Za-z0-9_-]{1,64}$"},"in":"path","name":"entity_id","required":true,"description":"Entity id (ent_…) as returned by check or a lookup"}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"entity":{"type":"object","properties":{"id":{"type":"string"},"kind":{"type":"string"},"country":{"type":["string","null"]},"registry":{"type":"string"},"registry_id":{"type":"string"},"name":{"type":"string"},"status":{"type":["string","null"]},"lei":{"type":["string","null"]}},"required":["id","kind","country","registry","registry_id","name","status","lei"],"additionalProperties":false},"events":{"type":"array","items":{"type":"object","properties":{"api_version":{"type":"string"},"event_id":{"type":"string"},"type":{"type":"string"},"vertical":{"description":"Pack id for vertical events; null for the core product pack","type":["string","null"]},"severity":{"type":"string","enum":["info","warning","critical"],"description":"Default severity of the type (profiles may change it from M5c)"},"entity":{"type":"object","properties":{"id":{"type":"string"},"kind":{"type":"string"},"country":{"type":["string","null"]},"registry":{"type":"string"},"registry_id":{"type":"string"},"name":{"type":"string"},"status":{"type":["string","null"]},"lei":{"type":["string","null"]}},"required":["id","kind","country","registry","registry_id","name","status","lei"],"additionalProperties":false},"related":{"type":"array","items":{"type":"object","properties":{"entity_id":{"type":"string"},"relationship":{"type":"string"}},"required":["entity_id","relationship"],"additionalProperties":false}},"effective_at":{"type":["string","null"]},"observed_at":{"type":"string"},"source":{"type":"object","properties":{"id":{"type":"string"},"url":{"type":["string","null"]},"attribution":{"type":["string","null"]}},"required":["id","url","attribution"],"additionalProperties":false},"data":{"type":"object","propertyNames":{"type":"string"},"additionalProperties":{}}},"required":["api_version","event_id","type","vertical","severity","entity","related","effective_at","observed_at","source","data"],"additionalProperties":false},"description":"Newest first"}},"required":["entity","events"],"additionalProperties":false},"meta":{"type":"object","properties":{"request_id":{"type":"string"},"retrieved_at":{"type":"string"}},"required":["request_id","retrieved_at"],"additionalProperties":false}},"required":["data","meta"],"additionalProperties":false}}}}}}},"/v1/companies/uk/search":{"get":{"summary":"Search UK companies by name or number (Companies House)","tags":["companies (UK)"],"parameters":[{"schema":{"type":"string","minLength":1,"maxLength":200},"in":"query","name":"q","required":true,"description":"Company name or number"},{"schema":{"type":"integer","minimum":1,"maximum":100},"in":"query","name":"items_per_page","required":false,"description":"Results per page (1–100, default 20)"},{"schema":{"type":"integer","minimum":0,"maximum":9007199254740991},"in":"query","name":"start_index","required":false,"description":"Offset of the first result"}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"query":{"type":"string"},"total_results":{"type":"number"},"items_per_page":{"type":"number"},"start_index":{"type":"number"},"items":{"type":"array","items":{"type":"object","properties":{"company_number":{"type":"string"},"company_name":{"type":"string"},"company_status":{"type":["string","null"]},"company_type":{"type":["string","null"]},"date_of_creation":{"type":["string","null"]},"date_of_cessation":{"type":["string","null"]},"address_snippet":{"type":["string","null"]}},"required":["company_number","company_name","company_status","company_type","date_of_creation","date_of_cessation","address_snippet"],"additionalProperties":false}}},"required":["query","total_results","items_per_page","start_index","items"],"additionalProperties":false},"meta":{"type":"object","properties":{"provider":{"type":"string"},"operation":{"type":"string"},"source_url":{"type":"string"},"retrieved_at":{"type":"string"},"cached":{"type":"boolean"},"transformed":{"type":"boolean"},"attribution":{"type":"string"},"request_id":{"type":"string"}},"required":["provider","operation","source_url","retrieved_at","cached","transformed","request_id"],"additionalProperties":false}},"required":["data","meta"],"additionalProperties":false}}}}}}},"/v1/companies/uk/{company_number}/ownership-chain":{"get":{"summary":"Ownership and control chain from the PSC register (Companies House), walked upwards","tags":["companies (UK)"],"parameters":[{"schema":{"default":10,"type":"integer","minimum":1,"maximum":25},"in":"query","name":"max_depth","required":false,"description":"Levels of owners to walk (1–25)"},{"schema":{"type":"string","maxLength":16},"in":"path","name":"company_number","required":true,"description":"Companies House number, e.g. 00445790 or SC123456; short numbers are zero-padded"}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"root":{"type":"object","properties":{"id":{"type":"string"},"kind":{"type":"string"},"country":{"type":["string","null"]},"registry":{"type":"string"},"registry_id":{"type":"string"},"name":{"type":"string"},"status":{"type":["string","null"]},"lei":{"type":["string","null"]}},"required":["id","kind","country","registry","registry_id","name","status","lei"],"additionalProperties":false},"links":{"type":"array","items":{"type":"object","properties":{"depth":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991,"description":"1 = direct owner of the company"},"owner_id":{"type":"string"},"owned_id":{"type":"string"},"types":{"type":"array","items":{"type":"string"},"description":"owns (shares or surplus assets) and/or controls (votes, appointments, influence), from the PSC register"},"cycle":{"type":"boolean","description":"The owner already appears lower in the chain; it is not walked again"},"natures_of_control":{"type":"array","items":{"type":"string"},"description":"Companies House codes for the kind of ownership or control, e.g. ownership-of-shares-75-to-100-percent"},"control":{"type":"array","items":{"type":"string"},"description":"The same in plain words, e.g. \"owns 75% or more of the shares\""}},"required":["depth","owner_id","owned_id","types","cycle","natures_of_control","control"],"additionalProperties":false}},"entities":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"kind":{"type":"string"},"country":{"type":["string","null"]},"registry":{"type":"string"},"registry_id":{"type":"string"},"name":{"type":"string"},"status":{"type":["string","null"]},"lei":{"type":["string","null"]}},"required":["id","kind","country","registry","registry_id","name","status","lei"],"additionalProperties":false},"description":"Every owner in links"},"truncated":{"type":"boolean","description":"More owners exist beyond max_depth, or some owners' registers could not be read in this call (see unread_owner_ids)"},"registers_read":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991,"description":"Companies House PSC registers read for this answer (the company's own and its UK corporate owners')"},"unread_owner_ids":{"type":"array","items":{"type":"string"},"description":"UK corporate owners whose own register was not read in this call (read limit or upstream error); call again with their company number to go further"},"no_owners_reason":{"anyOf":[{"type":"object","properties":{"summary":{"type":"string","description":"Why the register lists no current owner, in plain words"},"statements":{"type":"array","items":{"type":"object","properties":{"statement":{"type":"string"},"description":{"type":"string"},"notified_on":{"type":["string","null"]}},"required":["statement","description","notified_on"],"additionalProperties":false},"description":"Current PSC statements filed by the company"},"exemptions":{"type":"array","items":{"type":"object","properties":{"type":{"type":"string"},"description":{"type":"string"},"exempt_from":{"type":["string","null"]}},"required":["type","description","exempt_from"],"additionalProperties":false},"description":"Current exemptions from keeping a PSC register"}},"required":["summary","statements","exemptions"],"additionalProperties":false},{"type":"null"}],"description":"Set only when the company has no current owner on its PSC register: the statements and exemptions it has filed instead"}},"required":["root","links","entities","truncated","registers_read","unread_owner_ids","no_owners_reason"],"additionalProperties":false},"meta":{"type":"object","properties":{"provider":{"type":"string"},"operation":{"type":"string"},"source_url":{"type":"string"},"retrieved_at":{"type":"string"},"cached":{"type":"boolean"},"transformed":{"type":"boolean"},"attribution":{"type":"string"},"request_id":{"type":"string"}},"required":["provider","operation","source_url","retrieved_at","cached","transformed","request_id"],"additionalProperties":false}},"required":["data","meta"],"additionalProperties":false}}}}}}},"/v1/companies/uk/{company_number}":{"get":{"summary":"UK company profile (Companies House), with its LEI (GLEIF)","tags":["companies (UK)"],"parameters":[{"schema":{"type":"string","maxLength":16},"in":"path","name":"company_number","required":true,"description":"Companies House number, e.g. 00445790 or SC123456; short numbers are zero-padded"}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"entity":{"type":"object","properties":{"id":{"type":"string"},"kind":{"type":"string"},"country":{"type":["string","null"]},"registry":{"type":"string"},"registry_id":{"type":"string"},"name":{"type":"string"},"status":{"type":["string","null"]},"lei":{"type":["string","null"]}},"required":["id","kind","country","registry","registry_id","name","status","lei"],"additionalProperties":false},"company_number":{"type":"string"},"company_name":{"type":"string"},"company_status":{"type":["string","null"]},"company_status_detail":{"type":["string","null"]},"type":{"type":"string"},"subtype":{"type":["string","null"]},"jurisdiction":{"type":["string","null"]},"date_of_creation":{"type":["string","null"]},"date_of_cessation":{"type":["string","null"]},"sic_codes":{"type":"array","items":{"type":"string"}},"registered_office_address":{"anyOf":[{"type":"object","propertyNames":{"type":"string"},"additionalProperties":{}},{"type":"null"}]},"has_charges":{"type":["boolean","null"]},"has_insolvency_history":{"type":["boolean","null"]},"has_been_liquidated":{"type":["boolean","null"]},"accounts":{"anyOf":[{"type":"object","properties":{"next_due":{"type":["string","null"]},"next_made_up_to":{"type":["string","null"]},"overdue":{"type":["boolean","null"]},"last_made_up_to":{"type":["string","null"]},"last_accounts_type":{"type":["string","null"]}},"required":["next_due","next_made_up_to","overdue","last_made_up_to","last_accounts_type"],"additionalProperties":false},{"type":"null"}]},"confirmation_statement":{"anyOf":[{"type":"object","properties":{"next_due":{"type":["string","null"]},"next_made_up_to":{"type":["string","null"]},"last_made_up_to":{"type":["string","null"]},"overdue":{"type":["boolean","null"]}},"required":["next_due","next_made_up_to","last_made_up_to","overdue"],"additionalProperties":false},{"type":"null"}]},"previous_company_names":{"type":"array","items":{"type":"object","properties":{"name":{"type":"string"},"effective_from":{"type":["string","null"]},"ceased_on":{"type":["string","null"]}},"required":["name","effective_from","ceased_on"],"additionalProperties":false}},"lei":{"description":"LEI from the GLEIF crosswalk, or null (see lei_match)","type":["string","null"]},"lei_match":{"type":"object","properties":{"status":{"type":"string","enum":["matched","none","multiple","unavailable"],"description":"matched: one LEI; none: GLEIF has no LEI for this number; multiple: several (lei null); unavailable: GLEIF could not be asked"},"provider":{"type":"string","enum":["gleif"]},"source_url":{"type":["string","null"]},"retrieved_at":{"type":["string","null"]},"cached":{"type":["boolean","null"]},"reason":{"description":"Error code when status is unavailable","type":["string","null"]}},"required":["status","provider","source_url","retrieved_at","cached","reason"],"additionalProperties":false,"description":"How `lei` was found"}},"required":["entity","company_number","company_name","company_status","company_status_detail","type","subtype","jurisdiction","date_of_creation","date_of_cessation","sic_codes","registered_office_address","has_charges","has_insolvency_history","has_been_liquidated","accounts","confirmation_statement","previous_company_names","lei","lei_match"],"additionalProperties":false},"meta":{"type":"object","properties":{"provider":{"type":"string"},"operation":{"type":"string"},"source_url":{"type":"string"},"retrieved_at":{"type":"string"},"cached":{"type":"boolean"},"transformed":{"type":"boolean"},"attribution":{"type":"string"},"request_id":{"type":"string"}},"required":["provider","operation","source_url","retrieved_at","cached","transformed","request_id"],"additionalProperties":false}},"required":["data","meta"],"additionalProperties":false}}}}}}},"/v1/companies/uk/{company_number}/officers":{"get":{"summary":"Officers (directors, secretaries, LLP members) as published (Companies House)","tags":["companies (UK)"],"parameters":[{"schema":{"type":"integer","minimum":1,"maximum":100},"in":"query","name":"items_per_page","required":false},{"schema":{"type":"integer","minimum":0,"maximum":9007199254740991},"in":"query","name":"start_index","required":false},{"schema":{"type":"string","maxLength":16},"in":"path","name":"company_number","required":true,"description":"Companies House number, e.g. 00445790 or SC123456; short numbers are zero-padded"}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"company_number":{"type":"string"},"entity_id":{"type":"string"},"items_per_page":{"type":"number"},"start_index":{"type":"number"},"total_results":{"type":"number"},"active_count":{"type":["number","null"]},"resigned_count":{"type":["number","null"]},"items":{"type":"array","items":{"type":"object","properties":{"entity_id":{"type":"string"},"name":{"type":"string"},"officer_role":{"type":"string"},"appointed_on":{"type":["string","null"]},"appointed_before":{"type":["string","null"]},"resigned_on":{"type":["string","null"]},"nationality":{"type":["string","null"]},"occupation":{"type":["string","null"]},"country_of_residence":{"type":["string","null"]},"date_of_birth":{"anyOf":[{"type":"object","properties":{"month":{"type":"number"},"year":{"type":"number"}},"required":["month","year"],"additionalProperties":false},{"type":"null"}]},"address":{"anyOf":[{"type":"object","propertyNames":{"type":"string"},"additionalProperties":{}},{"type":"null"}]},"identification":{"anyOf":[{"type":"object","propertyNames":{"type":"string"},"additionalProperties":{}},{"type":"null"}]}},"required":["entity_id","name","officer_role","appointed_on","appointed_before","resigned_on","nationality","occupation","country_of_residence","date_of_birth","address","identification"],"additionalProperties":false}}},"required":["company_number","entity_id","items_per_page","start_index","total_results","active_count","resigned_count","items"],"additionalProperties":false},"meta":{"type":"object","properties":{"provider":{"type":"string"},"operation":{"type":"string"},"source_url":{"type":"string"},"retrieved_at":{"type":"string"},"cached":{"type":"boolean"},"transformed":{"type":"boolean"},"attribution":{"type":"string"},"request_id":{"type":"string"}},"required":["provider","operation","source_url","retrieved_at","cached","transformed","request_id"],"additionalProperties":false}},"required":["data","meta"],"additionalProperties":false}}}}}}},"/v1/companies/uk/{company_number}/psc":{"get":{"summary":"Persons with significant control as published (Companies House)","tags":["companies (UK)"],"parameters":[{"schema":{"type":"integer","minimum":1,"maximum":100},"in":"query","name":"items_per_page","required":false},{"schema":{"type":"integer","minimum":0,"maximum":9007199254740991},"in":"query","name":"start_index","required":false},{"schema":{"type":"string","maxLength":16},"in":"path","name":"company_number","required":true,"description":"Companies House number, e.g. 00445790 or SC123456; short numbers are zero-padded"}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"company_number":{"type":"string"},"entity_id":{"type":"string"},"items_per_page":{"type":"number"},"start_index":{"type":"number"},"total_results":{"type":"number"},"active_count":{"type":["number","null"]},"ceased_count":{"type":["number","null"]},"items":{"type":"array","items":{"type":"object","properties":{"entity_id":{"description":"null for super-secure PSCs, whose identity is not published","type":["string","null"]},"kind":{"type":"string"},"name":{"type":["string","null"]},"description":{"type":["string","null"]},"natures_of_control":{"type":"array","items":{"type":"string"}},"notified_on":{"type":["string","null"]},"ceased_on":{"type":["string","null"]},"nationality":{"type":["string","null"]},"country_of_residence":{"type":["string","null"]},"date_of_birth":{"anyOf":[{"type":"object","properties":{"month":{"type":"number"},"year":{"type":"number"}},"required":["month","year"],"additionalProperties":false},{"type":"null"}]},"address":{"anyOf":[{"type":"object","propertyNames":{"type":"string"},"additionalProperties":{}},{"type":"null"}]},"identification":{"anyOf":[{"type":"object","propertyNames":{"type":"string"},"additionalProperties":{}},{"type":"null"}]}},"required":["entity_id","kind","name","description","natures_of_control","notified_on","ceased_on","nationality","country_of_residence","date_of_birth","address","identification"],"additionalProperties":false}}},"required":["company_number","entity_id","items_per_page","start_index","total_results","active_count","ceased_count","items"],"additionalProperties":false},"meta":{"type":"object","properties":{"provider":{"type":"string"},"operation":{"type":"string"},"source_url":{"type":"string"},"retrieved_at":{"type":"string"},"cached":{"type":"boolean"},"transformed":{"type":"boolean"},"attribution":{"type":"string"},"request_id":{"type":"string"}},"required":["provider","operation","source_url","retrieved_at","cached","transformed","request_id"],"additionalProperties":false}},"required":["data","meta"],"additionalProperties":false}}}}}}},"/v1/companies/uk/{company_number}/charges":{"get":{"summary":"Registered charges and the persons entitled (Companies House)","tags":["companies (UK)"],"parameters":[{"schema":{"type":"integer","minimum":1,"maximum":100},"in":"query","name":"items_per_page","required":false},{"schema":{"type":"integer","minimum":0,"maximum":9007199254740991},"in":"query","name":"start_index","required":false},{"schema":{"type":"string","maxLength":16},"in":"path","name":"company_number","required":true,"description":"Companies House number, e.g. 00445790 or SC123456; short numbers are zero-padded"}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"company_number":{"type":"string"},"entity_id":{"type":"string"},"items_per_page":{"type":"number"},"start_index":{"type":"number"},"total_count":{"type":["number","null"]},"satisfied_count":{"type":["number","null"]},"part_satisfied_count":{"type":["number","null"]},"items":{"type":"array","items":{"type":"object","properties":{"charge_id":{"type":["string","null"]},"charge_code":{"type":["string","null"]},"charge_number":{"type":"number"},"status":{"type":"string"},"classification":{"anyOf":[{"type":"object","properties":{"type":{"type":["string","null"]},"description":{"type":["string","null"]}},"required":["type","description"],"additionalProperties":false},{"type":"null"}]},"created_on":{"type":["string","null"]},"delivered_on":{"type":["string","null"]},"satisfied_on":{"type":["string","null"]},"persons_entitled":{"type":"array","items":{"type":"object","properties":{"name":{"type":"string"},"entity_id":{"type":"string"}},"required":["name","entity_id"],"additionalProperties":false}},"particulars":{"anyOf":[{"type":"object","properties":{"type":{"type":["string","null"]},"description":{"type":["string","null"]}},"required":["type","description"],"additionalProperties":false},{"type":"null"}]}},"required":["charge_id","charge_code","charge_number","status","classification","created_on","delivered_on","satisfied_on","persons_entitled","particulars"],"additionalProperties":false}}},"required":["company_number","entity_id","items_per_page","start_index","total_count","satisfied_count","part_satisfied_count","items"],"additionalProperties":false},"meta":{"type":"object","properties":{"provider":{"type":"string"},"operation":{"type":"string"},"source_url":{"type":"string"},"retrieved_at":{"type":"string"},"cached":{"type":"boolean"},"transformed":{"type":"boolean"},"attribution":{"type":"string"},"request_id":{"type":"string"}},"required":["provider","operation","source_url","retrieved_at","cached","transformed","request_id"],"additionalProperties":false}},"required":["data","meta"],"additionalProperties":false}}}}}}},"/v1/companies/uk/{company_number}/filings":{"get":{"summary":"Filing history (Companies House)","tags":["companies (UK)"],"parameters":[{"schema":{"type":"integer","minimum":1,"maximum":100},"in":"query","name":"items_per_page","required":false},{"schema":{"type":"integer","minimum":0,"maximum":9007199254740991},"in":"query","name":"start_index","required":false},{"schema":{"type":"string","maxLength":16},"in":"path","name":"company_number","required":true,"description":"Companies House number, e.g. 00445790 or SC123456; short numbers are zero-padded"}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"company_number":{"type":"string"},"entity_id":{"type":"string"},"items_per_page":{"type":"number"},"start_index":{"type":"number"},"total_count":{"type":"number"},"items":{"type":"array","items":{"type":"object","properties":{"transaction_id":{"type":"string"},"category":{"type":"string"},"subcategory":{"anyOf":[{"anyOf":[{"type":"string"},{"type":"array","items":{"type":"string"}}]},{"type":"null"}]},"type":{"type":"string"},"date":{"type":"string"},"description":{"type":"string","description":"Companies House description code, e.g. accounts-with-accounts-type-full"},"description_values":{"anyOf":[{"type":"object","propertyNames":{"type":"string"},"additionalProperties":{}},{"type":"null"}]},"action_date":{"type":["string","null"]},"pages":{"type":["number","null"]},"paper_filed":{"type":["boolean","null"]},"document_metadata_url":{"type":["string","null"]}},"required":["transaction_id","category","subcategory","type","date","description","description_values","action_date","pages","paper_filed","document_metadata_url"],"additionalProperties":false}}},"required":["company_number","entity_id","items_per_page","start_index","total_count","items"],"additionalProperties":false},"meta":{"type":"object","properties":{"provider":{"type":"string"},"operation":{"type":"string"},"source_url":{"type":"string"},"retrieved_at":{"type":"string"},"cached":{"type":"boolean"},"transformed":{"type":"boolean"},"attribution":{"type":"string"},"request_id":{"type":"string"}},"required":["provider","operation","source_url","retrieved_at","cached","transformed","request_id"],"additionalProperties":false}},"required":["data","meta"],"additionalProperties":false}}}}}}},"/v1/entities/lei":{"get":{"summary":"LEIs for a registration number in a country (GLEIF crosswalk)","tags":["entities (LEI)"],"parameters":[{"schema":{"type":"string","minLength":1,"maxLength":40},"in":"query","name":"registration_number","required":true,"description":"Number at the national register, e.g. 00445790 (GB) or 552032534 (FR)"},{"schema":{"type":"string","minLength":2,"maxLength":2},"in":"query","name":"country","required":true,"description":"ISO 3166-1 alpha-2 country of the register"}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"registration_number":{"type":"string"},"country":{"type":"string"},"total":{"type":"number"},"items":{"type":"array","items":{"type":"object","properties":{"lei":{"type":"string"},"legal_name":{"type":"string"},"entity_id":{"type":"string"},"entity_status":{"type":"string"},"registration_status":{"type":"string"},"registration_authority":{"type":"object","properties":{"id":{"type":["string","null"]},"registered_as":{"type":["string","null"]}},"required":["id","registered_as"],"additionalProperties":false},"jurisdiction":{"type":["string","null"]}},"required":["lei","legal_name","entity_id","entity_status","registration_status","registration_authority","jurisdiction"],"additionalProperties":false}}},"required":["registration_number","country","total","items"],"additionalProperties":false},"meta":{"type":"object","properties":{"provider":{"type":"string"},"operation":{"type":"string"},"source_url":{"type":"string"},"retrieved_at":{"type":"string"},"cached":{"type":"boolean"},"transformed":{"type":"boolean"},"attribution":{"type":"string"},"request_id":{"type":"string"}},"required":["provider","operation","source_url","retrieved_at","cached","transformed","request_id"],"additionalProperties":false}},"required":["data","meta"],"additionalProperties":false}}}}}}},"/v1/entities/lei/{lei}":{"get":{"summary":"LEI record (GLEIF)","tags":["entities (LEI)"],"parameters":[{"schema":{"type":"string","maxLength":32},"in":"path","name":"lei","required":true,"description":"Legal Entity Identifier (20 characters), e.g. 2138002P5RNKC5W2JZ46"}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"entity":{"type":"object","properties":{"id":{"type":"string"},"kind":{"type":"string"},"country":{"type":["string","null"]},"registry":{"type":"string"},"registry_id":{"type":"string"},"name":{"type":"string"},"status":{"type":["string","null"]},"lei":{"type":["string","null"]}},"required":["id","kind","country","registry","registry_id","name","status","lei"],"additionalProperties":false},"lei":{"type":"string"},"legal_name":{"type":"string"},"other_names":{"type":"array","items":{"type":"string"}},"legal_address":{"anyOf":[{"type":"object","properties":{"lines":{"type":"array","items":{"type":"string"}},"city":{"type":["string","null"]},"region":{"type":["string","null"]},"country":{"type":["string","null"]},"postal_code":{"type":["string","null"]}},"required":["lines","city","region","country","postal_code"],"additionalProperties":false},{"type":"null"}]},"headquarters_address":{"anyOf":[{"type":"object","properties":{"lines":{"type":"array","items":{"type":"string"}},"city":{"type":["string","null"]},"region":{"type":["string","null"]},"country":{"type":["string","null"]},"postal_code":{"type":["string","null"]}},"required":["lines","city","region","country","postal_code"],"additionalProperties":false},{"type":"null"}]},"jurisdiction":{"type":["string","null"]},"registration_authority":{"type":"object","properties":{"id":{"type":["string","null"]},"registered_as":{"type":["string","null"]}},"required":["id","registered_as"],"additionalProperties":false,"description":"Where the entity is registered (GLEIF RA code) and its number there"},"legal_form":{"type":"object","properties":{"elf_code":{"type":["string","null"]},"other":{"type":["string","null"]}},"required":["elf_code","other"],"additionalProperties":false},"entity_status":{"type":"string","description":"GLEIF entity status, e.g. ACTIVE, INACTIVE"},"entity_category":{"type":["string","null"]},"creation_date":{"type":["string","null"]},"successor_lei":{"type":["string","null"]},"registration":{"type":"object","properties":{"status":{"type":"string","description":"LEI registration status, e.g. ISSUED, LAPSED, RETIRED"},"initial_registration_date":{"type":["string","null"]},"last_update_date":{"type":["string","null"]},"next_renewal_date":{"type":["string","null"]},"managing_lou":{"type":["string","null"]},"corroboration_level":{"type":["string","null"]}},"required":["status","initial_registration_date","last_update_date","next_renewal_date","managing_lou","corroboration_level"],"additionalProperties":false},"bic":{"type":"array","items":{"type":"string"}}},"required":["entity","lei","legal_name","other_names","legal_address","headquarters_address","jurisdiction","registration_authority","legal_form","entity_status","entity_category","creation_date","successor_lei","registration","bic"],"additionalProperties":false},"meta":{"type":"object","properties":{"provider":{"type":"string"},"operation":{"type":"string"},"source_url":{"type":"string"},"retrieved_at":{"type":"string"},"cached":{"type":"boolean"},"transformed":{"type":"boolean"},"attribution":{"type":"string"},"request_id":{"type":"string"}},"required":["provider","operation","source_url","retrieved_at","cached","transformed","request_id"],"additionalProperties":false}},"required":["data","meta"],"additionalProperties":false}}}}}}},"/v1/entities/lei/{lei}/parents":{"get":{"summary":"Direct and ultimate accounting-consolidation parents (GLEIF Level 2)","tags":["entities (LEI)"],"parameters":[{"schema":{"type":"string","maxLength":32},"in":"path","name":"lei","required":true,"description":"Legal Entity Identifier (20 characters)"}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"lei":{"type":"string"},"entity_id":{"type":"string"},"direct_parent":{"anyOf":[{"type":"object","properties":{"lei":{"type":"string"},"legal_name":{"type":"string"},"entity":{"type":"object","properties":{"id":{"type":"string"},"kind":{"type":"string"},"country":{"type":["string","null"]},"registry":{"type":"string"},"registry_id":{"type":"string"},"name":{"type":"string"},"status":{"type":["string","null"]},"lei":{"type":["string","null"]}},"required":["id","kind","country","registry","registry_id","name","status","lei"],"additionalProperties":false},"relationship":{"type":"object","properties":{"type":{"type":"string","description":"GLEIF relationship type, e.g. IS_DIRECTLY_CONSOLIDATED_BY"},"status":{"type":"string"},"start_date":{"type":["string","null"]},"end_date":{"type":["string","null"]},"corroboration_level":{"type":["string","null"]}},"required":["type","status","start_date","end_date","corroboration_level"],"additionalProperties":false}},"required":["lei","legal_name","entity","relationship"],"additionalProperties":false},{"type":"null"}]},"ultimate_parent":{"anyOf":[{"type":"object","properties":{"lei":{"type":"string"},"legal_name":{"type":"string"},"entity":{"type":"object","properties":{"id":{"type":"string"},"kind":{"type":"string"},"country":{"type":["string","null"]},"registry":{"type":"string"},"registry_id":{"type":"string"},"name":{"type":"string"},"status":{"type":["string","null"]},"lei":{"type":["string","null"]}},"required":["id","kind","country","registry","registry_id","name","status","lei"],"additionalProperties":false},"relationship":{"type":"object","properties":{"type":{"type":"string","description":"GLEIF relationship type, e.g. IS_DIRECTLY_CONSOLIDATED_BY"},"status":{"type":"string"},"start_date":{"type":["string","null"]},"end_date":{"type":["string","null"]},"corroboration_level":{"type":["string","null"]}},"required":["type","status","start_date","end_date","corroboration_level"],"additionalProperties":false}},"required":["lei","legal_name","entity","relationship"],"additionalProperties":false},{"type":"null"}]},"direct_parent_exception":{"anyOf":[{"type":"object","properties":{"category":{"type":"string"},"reason":{"type":"string","description":"Why no parent is reported, e.g. NON_CONSOLIDATING, NATURAL_PERSONS"}},"required":["category","reason"],"additionalProperties":false},{"type":"null"}]},"ultimate_parent_exception":{"anyOf":[{"type":"object","properties":{"category":{"type":"string"},"reason":{"type":"string","description":"Why no parent is reported, e.g. NON_CONSOLIDATING, NATURAL_PERSONS"}},"required":["category","reason"],"additionalProperties":false},{"type":"null"}]}},"required":["lei","entity_id","direct_parent","ultimate_parent","direct_parent_exception","ultimate_parent_exception"],"additionalProperties":false},"meta":{"type":"object","properties":{"provider":{"type":"string"},"operation":{"type":"string"},"source_url":{"type":"string"},"retrieved_at":{"type":"string"},"cached":{"type":"boolean"},"transformed":{"type":"boolean"},"attribution":{"type":"string"},"request_id":{"type":"string"}},"required":["provider","operation","source_url","retrieved_at","cached","transformed","request_id"],"additionalProperties":false}},"required":["data","meta"],"additionalProperties":false}}}}}}},"/v1/companies/fr/search":{"get":{"summary":"Search French companies by name, address or officer (API Recherche d'entreprises)","tags":["companies (FR)"],"parameters":[{"schema":{"type":"string","minLength":3,"maxLength":200},"in":"query","name":"q","required":true},{"schema":{"type":"integer","minimum":1,"maximum":1000},"in":"query","name":"page","required":false},{"schema":{"type":"integer","minimum":1,"maximum":25},"in":"query","name":"per_page","required":false}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"query":{"type":"string"},"total_results":{"type":"number","description":"Upstream total (diffusible units only; the API holds no others)"},"page":{"type":"number"},"per_page":{"type":"number"},"items":{"type":"array","items":{"type":"object","properties":{"siren":{"type":"string"},"name":{"type":"string"},"status":{"type":["string","null"]},"legal_form_code":{"type":["string","null"]},"activity_code":{"type":["string","null"]},"date_of_creation":{"type":["string","null"]},"head_office_postcode":{"type":["string","null"]},"head_office_city":{"type":["string","null"]},"sole_trader":{"type":["boolean","null"]}},"required":["siren","name","status","legal_form_code","activity_code","date_of_creation","head_office_postcode","head_office_city","sole_trader"],"additionalProperties":false}}},"required":["query","total_results","page","per_page","items"],"additionalProperties":false},"meta":{"type":"object","properties":{"provider":{"type":"string"},"operation":{"type":"string"},"source_url":{"type":"string"},"retrieved_at":{"type":"string"},"cached":{"type":"boolean"},"transformed":{"type":"boolean"},"attribution":{"type":"string"},"request_id":{"type":"string"}},"required":["provider","operation","source_url","retrieved_at","cached","transformed","request_id"],"additionalProperties":false}},"required":["data","meta"],"additionalProperties":false}}}}}}},"/v1/companies/fr/{siren}":{"get":{"summary":"French company by SIREN (API Recherche d'entreprises), with its LEI (GLEIF)","tags":["companies (FR)"],"parameters":[{"schema":{"type":"string","maxLength":16},"in":"path","name":"siren","required":true,"description":"SIREN, 9 digits"}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"entity":{"type":"object","properties":{"id":{"type":"string"},"kind":{"type":"string"},"country":{"type":["string","null"]},"registry":{"type":"string"},"registry_id":{"type":"string"},"name":{"type":"string"},"status":{"type":["string","null"]},"lei":{"type":["string","null"]}},"required":["id","kind","country","registry","registry_id","name","status","lei"],"additionalProperties":false},"siren":{"type":"string"},"name":{"type":"string","description":"nom_complet: the full name as the register builds it"},"legal_name":{"type":["string","null"]},"acronym":{"type":["string","null"]},"status":{"description":"active | ceased (from etat_administratif)","type":["string","null"]},"etat_administratif":{"type":["string","null"]},"legal_form_code":{"description":"INSEE nature juridique code","type":["string","null"]},"activity_code":{"description":"NAF code","type":["string","null"]},"company_category":{"description":"PME | ETI | GE","type":["string","null"]},"headcount_band":{"type":["string","null"]},"date_of_creation":{"type":["string","null"]},"date_of_cessation":{"type":["string","null"]},"establishments":{"type":"object","properties":{"total":{"type":["number","null"]},"open":{"type":["number","null"]}},"required":["total","open"],"additionalProperties":false},"head_office":{"anyOf":[{"type":"object","properties":{"siret":{"type":["string","null"]},"address":{"type":["string","null"]},"postcode":{"type":["string","null"]},"city":{"type":["string","null"]},"etat_administratif":{"type":["string","null"]}},"required":["siret","address","postcode","city","etat_administratif"],"additionalProperties":false},{"type":"null"}]},"officers":{"type":"array","items":{"oneOf":[{"type":"object","properties":{"type":{"type":"string","enum":["natural_person"]},"entity_id":{"type":"null"},"last_name":{"type":["string","null"]},"first_names":{"type":["string","null"]},"birth_year":{"type":["string","null"]},"birth_month":{"description":"YYYY-MM, as published","type":["string","null"]},"role":{"type":["string","null"]},"nationality":{"type":["string","null"]}},"required":["type","entity_id","last_name","first_names","birth_year","birth_month","role","nationality"],"additionalProperties":false},{"type":"object","properties":{"type":{"type":"string","enum":["legal_person"]},"entity_id":{"type":["string","null"]},"siren":{"type":["string","null"]},"name":{"type":["string","null"]},"role":{"type":["string","null"]}},"required":["type","entity_id","siren","name","role"],"additionalProperties":false}]}},"finances":{"type":"array","items":{"type":"object","properties":{"year":{"type":"string"},"revenue":{"type":["number","null"]},"net_income":{"type":["number","null"]},"currency":{"type":"string","enum":["EUR"]}},"required":["year","revenue","net_income","currency"],"additionalProperties":false}},"vat_numbers":{"type":"array","items":{"type":"string"}},"opposition_diffusion_commerciale":{"description":"Unit has opposed use of its data for commercial prospecting, as published","type":["boolean","null"]},"lei":{"description":"LEI from the GLEIF crosswalk, or null (see lei_match)","type":["string","null"]},"lei_match":{"type":"object","properties":{"status":{"type":"string","enum":["matched","none","multiple","unavailable"],"description":"matched: one LEI; none: GLEIF has no LEI for this number; multiple: several (lei null); unavailable: GLEIF could not be asked"},"provider":{"type":"string","enum":["gleif"]},"source_url":{"type":["string","null"]},"retrieved_at":{"type":["string","null"]},"cached":{"type":["boolean","null"]},"reason":{"description":"Error code when status is unavailable","type":["string","null"]}},"required":["status","provider","source_url","retrieved_at","cached","reason"],"additionalProperties":false,"description":"How `lei` was found"}},"required":["entity","siren","name","legal_name","acronym","status","etat_administratif","legal_form_code","activity_code","company_category","headcount_band","date_of_creation","date_of_cessation","establishments","head_office","officers","finances","vat_numbers","opposition_diffusion_commerciale","lei","lei_match"],"additionalProperties":false},"meta":{"type":"object","properties":{"provider":{"type":"string"},"operation":{"type":"string"},"source_url":{"type":"string"},"retrieved_at":{"type":"string"},"cached":{"type":"boolean"},"transformed":{"type":"boolean"},"attribution":{"type":"string"},"request_id":{"type":"string"}},"required":["provider","operation","source_url","retrieved_at","cached","transformed","request_id"],"additionalProperties":false}},"required":["data","meta"],"additionalProperties":false}}}}}}}},"servers":[{"url":"https://api.sisoco.co.uk"}],"security":[{"bearer":[]}]}