{ "openapi": "3.1.1", "info": { "title": "Fortuna", "description": "UK company accounts, parsed from Companies House bulk XBRL filings and served\nover JSON.\n\nEighteen years of accounts back to 2008, the full live register of around 5.7\nmillion companies, and postcode-level geocoding, all held against one company\nregistration number.\n\n## Conventions\n\nEvery response field is `snake_case`, matching the column names the data has.\nQuery parameters are camelCase, because they bind to the framework's own names.\n\nFiling and area responses wrap their results in an envelope:\n\n```json\n{ \"items\": [], \"total\": 37, \"limit\": 50, \"offset\": 0, \"has_more\": false }\n```\n\nThe four simple search routes return a bare array. All of them take `limit`\n(1 to 200, default 50) and `offset`.\n\nMoney is in the filing's own currency, reported by `currency_used_in_report`.\nA figure a filing did not report, or reported only as a breakdown with no total,\nis `null` rather than a guess.\n\n## Keys and quotas\n\nEverything under `/api` needs an `X-Api-Key` header. `/health` and `/progress`\ndo not, so a probe never needs a credential.\n\nKeys carry a daily and a monthly allowance. Every response reports usage in\n`X-RateLimit-Limit-Day`, `X-RateLimit-Used-Day`, their monthly equivalents and\n`X-RateLimit-Remaining`. A `429` carries `Retry-After`, the seconds until the\nexceeded window rolls over. A separate burst limit caps the instantaneous rate.", "contact": { "name": "Mythic Software", "url": "https://mythic.software" }, "version": "1.0.0" }, "servers": [ { "url": "http://api.fortunadata.io/" } ], "paths": { "/api/company/{id}/logo": { "get": { "tags": [ "Company brand" ], "summary": "The company's logo, as an image.\n\nServed from here rather than from the storage account directly. These are other\ncompanies' trademarks, published on their own sites and reproduced to identify them;\na public container with an immutable cache header would leave no way to honour a\nrequest to stop, and no way to stop anyone else embedding the URLs at our expense.\nThrough the API a takedown is one UPDATE.", "parameters": [ { "name": "id", "in": "path", "description": "Company registration number, for example 13449176.", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "content": { "image/png": { }, "image/jpeg": { }, "image/svg+xml": { }, "image/webp": { }, "image/gif": { } } }, "404": { "description": "Not Found", "content": { "image/png": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } }, "image/jpeg": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } }, "image/svg+xml": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } }, "image/webp": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } }, "image/gif": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } }, "security": [ { "ApiKey": [ ] } ] } }, "/api/company/{id}/brand": { "get": { "tags": [ "Company brand" ], "summary": "Everything the company's website said about itself, without the image bytes.", "parameters": [ { "name": "id", "in": "path", "description": "Company registration number, for example 13449176.", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CompanyBrandResponse" } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } }, "security": [ { "ApiKey": [ ] } ] } }, "/api/company/{id}": { "get": { "tags": [ "Company" ], "summary": "Everything held about a company in one call: status and SIC codes from the register,\naccounts dates, the verified website and its contact details, where it is, the latest\naccounts, who owns it, its current officers, and financial health indicators.\n\nHealth is a set of flags rather than a score. Each flag has a stable code -- the same\ncodes monitoring webhooks report -- a severity of info, warning or serious, and a\nsentence saying what was found.", "parameters": [ { "name": "id", "in": "path", "description": "Company registration number, for example 08810260. Leading zeros may be dropped.", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CompanyProfile" } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } }, "security": [ { "ApiKey": [ ] } ] } }, "/api/companyfiling/{id}": { "get": { "tags": [ "Company filings" ], "summary": "All filings held for a company registration number.", "parameters": [ { "name": "id", "in": "path", "description": "Company registration number, for example 00005775.", "required": true, "schema": { "type": "string" } }, { "name": "limit", "in": "query", "description": "Page size, 1 to 200. Defaults to 50.", "schema": { "pattern": "^-?(?:0|[1-9]\\d*)$", "type": [ "integer", "string" ], "format": "int32" } }, { "name": "offset", "in": "query", "description": "How many filings to skip.", "schema": { "pattern": "^-?(?:0|[1-9]\\d*)$", "type": [ "integer", "string" ], "format": "int32" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FilingPage" } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } }, "security": [ { "ApiKey": [ ] } ] } }, "/api/companyfiling/{id}/from/{from}": { "get": { "tags": [ "Company filings" ], "summary": "Filings for a company whose period ends on or after a date.", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "from", "in": "path", "required": true, "schema": { "type": "string", "format": "date-time" } }, { "name": "limit", "in": "query", "schema": { "pattern": "^-?(?:0|[1-9]\\d*)$", "type": [ "integer", "string" ], "format": "int32" } }, { "name": "offset", "in": "query", "schema": { "pattern": "^-?(?:0|[1-9]\\d*)$", "type": [ "integer", "string" ], "format": "int32" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FilingPage" } } } } }, "security": [ { "ApiKey": [ ] } ] } }, "/api/companyfiling/{id}/to/{to}": { "get": { "tags": [ "Company filings" ], "summary": "Filings for a company whose period ends on or before a date.", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "to", "in": "path", "required": true, "schema": { "type": "string", "format": "date-time" } }, { "name": "limit", "in": "query", "schema": { "pattern": "^-?(?:0|[1-9]\\d*)$", "type": [ "integer", "string" ], "format": "int32" } }, { "name": "offset", "in": "query", "schema": { "pattern": "^-?(?:0|[1-9]\\d*)$", "type": [ "integer", "string" ], "format": "int32" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FilingPage" } } } } }, "security": [ { "ApiKey": [ ] } ] } }, "/api/companyfiling/{id}/between/{from}/{to}": { "get": { "tags": [ "Company filings" ], "summary": "Filings for a company whose period ends within a range.", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "from", "in": "path", "required": true, "schema": { "type": "string", "format": "date-time" } }, { "name": "to", "in": "path", "required": true, "schema": { "type": "string", "format": "date-time" } }, { "name": "limit", "in": "query", "schema": { "pattern": "^-?(?:0|[1-9]\\d*)$", "type": [ "integer", "string" ], "format": "int32" } }, { "name": "offset", "in": "query", "schema": { "pattern": "^-?(?:0|[1-9]\\d*)$", "type": [ "integer", "string" ], "format": "int32" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FilingPage" } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } }, "security": [ { "ApiKey": [ ] } ] } }, "/api/company/{id}/psc": { "get": { "tags": [ "Company ownership" ], "summary": "The company's persons with significant control: anyone holding more than 25% of its\nshares or votes, able to appoint its board, or otherwise in control.\n\nOwnership is a band -- 25 to 50, 50 to 75 or 75 to 100 percent -- because that is all\nthe register publishes. An empty list can mean nobody holds more than 25%.", "parameters": [ { "name": "id", "in": "path", "description": "Company registration number, for example 08810260.", "required": true, "schema": { "type": "string" } }, { "name": "include_ceased", "in": "query", "schema": { "type": "boolean" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/PscResponse" } } } } } }, "security": [ { "ApiKey": [ ] } ] } }, "/health": { "get": { "tags": [ "Health" ], "summary": "Reports that the service is up.", "responses": { "200": { "description": "OK", "content": { "application/json": { } } } } } }, "/api/match": { "get": { "tags": [ "Match" ], "summary": "The companies a name, postcode, website, email address or number could be, most likely\nfirst, each with a confidence and the evidence for it.\n\nmatch is set only when the best candidate is confident enough to act on without a\nperson looking: 0.85 or more, and at least 0.1 ahead of the next. A website or email\ndomain counts only where the company's own registered number was found on that site,\nand free-mail addresses (gmail.com and the like) are ignored.", "parameters": [ { "name": "number", "in": "query", "description": "A registration number.", "schema": { "type": "string" } }, { "name": "name", "in": "query", "description": "A company name, as the caller has it.", "schema": { "type": "string" } }, { "name": "postcode", "in": "query", "description": "A postcode, which separates companies sharing a name.", "schema": { "type": "string" } }, { "name": "domain", "in": "query", "description": "A website or domain, for example acme.co.uk.", "schema": { "type": "string" } }, { "name": "email", "in": "query", "description": "An email address.", "schema": { "type": "string" } }, { "name": "limit", "in": "query", "description": "Candidates to return, 1 to 20. Defaults to 5.", "schema": { "pattern": "^-?(?:0|[1-9]\\d*)$", "type": [ "integer", "string" ], "format": "int32" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MatchResult" } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } }, "security": [ { "ApiKey": [ ] } ] } }, "/api/match/batch": { "post": { "tags": [ "Match" ], "summary": "Up to 100 matches in one request, for enriching a list. Each item takes the same fields\nas a single match, plus a reference that is echoed back to line results up with input.\nEach result carries its three best candidates.", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MatchBatchRequest" } }, "application/*+json": { "schema": { "$ref": "#/components/schemas/MatchBatchRequest" } } }, "required": true }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/MatchResult" } } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } }, "security": [ { "ApiKey": [ ] } ] } }, "/progress": { "get": { "tags": [ "Progress" ], "summary": "What the ingest and domain pipelines are doing right now.", "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/IngestProgress" } } } } } } }, "/api/search/name/{name}": { "get": { "tags": [ "Search" ], "summary": "Companies whose registered name contains the given text.", "parameters": [ { "name": "name", "in": "path", "description": "Name, or part of one, for example 'Lost Level Studios'.", "required": true, "schema": { "type": "string" } }, { "name": "limit", "in": "query", "description": "Page size, 1 to 200. Defaults to 50.", "schema": { "pattern": "^-?(?:0|[1-9]\\d*)$", "type": [ "integer", "string" ], "format": "int32" } }, { "name": "offset", "in": "query", "description": "How many results to skip.", "schema": { "pattern": "^-?(?:0|[1-9]\\d*)$", "type": [ "integer", "string" ], "format": "int32" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/CompanySearchResult" } } } } } }, "security": [ { "ApiKey": [ ] } ] } }, "/api/search/postcode/{postcode}": { "get": { "tags": [ "Search" ], "summary": "Companies whose postcode contains the given text.", "parameters": [ { "name": "postcode", "in": "path", "description": "Postcode, or part of one, for example 'DT11 7RF'.", "required": true, "schema": { "type": "string" } }, { "name": "limit", "in": "query", "schema": { "pattern": "^-?(?:0|[1-9]\\d*)$", "type": [ "integer", "string" ], "format": "int32" } }, { "name": "offset", "in": "query", "schema": { "pattern": "^-?(?:0|[1-9]\\d*)$", "type": [ "integer", "string" ], "format": "int32" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/CompanySearchResult" } } } } } }, "security": [ { "ApiKey": [ ] } ] } }, "/api/search/director/{director}": { "get": { "tags": [ "Search" ], "summary": "Companies with an officer whose name contains the given text.", "parameters": [ { "name": "director", "in": "path", "description": "Officer name, or part of one.", "required": true, "schema": { "type": "string" } }, { "name": "limit", "in": "query", "schema": { "pattern": "^-?(?:0|[1-9]\\d*)$", "type": [ "integer", "string" ], "format": "int32" } }, { "name": "offset", "in": "query", "schema": { "pattern": "^-?(?:0|[1-9]\\d*)$", "type": [ "integer", "string" ], "format": "int32" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/CompanySearchResult" } } } } } }, "security": [ { "ApiKey": [ ] } ] } }, "/api/search/area": { "get": { "tags": [ "Search" ], "summary": "Companies in an area, optionally filtered on their most recent financials.\n\nEither a postcode with a radius, or a named area, is required. Supplying both narrows\nto the intersection.", "parameters": [ { "name": "postcode", "in": "query", "description": "Origin postcode to measure a radius from, e.g. 'DT1 1XJ'.", "schema": { "type": "string" } }, { "name": "radius_miles", "in": "query", "schema": { "pattern": "^-?(?:0|[1-9]\\d*)(?:\\.\\d+)?(?:[eE][+-]?\\d+)?$", "type": [ "number", "string" ], "format": "double" } }, { "name": "area", "in": "query", "description": "District or county, e.g. 'Dorset'. Either is matched, because which of the two holds\na given place is an accident of local government reorganisation: Dorset is a unitary\nauthority and so has no county at all.", "schema": { "type": "string" } }, { "name": "status", "in": "query", "description": "Companies House status, e.g. 'active'.", "schema": { "type": "string" } }, { "name": "min_net_assets", "in": "query", "schema": { "pattern": "^-?(?:0|[1-9]\\d*)(?:\\.\\d+)?$", "type": [ "number", "string" ], "format": "double" } }, { "name": "min_employees", "in": "query", "schema": { "pattern": "^-?(?:0|[1-9]\\d*)(?:\\.\\d+)?$", "type": [ "number", "string" ], "format": "double" } }, { "name": "sic_code", "in": "query", "schema": { "type": "string" } }, { "name": "limit", "in": "query", "schema": { "pattern": "^-?(?:0|[1-9]\\d*)$", "type": [ "integer", "string" ], "format": "int32" } }, { "name": "offset", "in": "query", "schema": { "pattern": "^-?(?:0|[1-9]\\d*)$", "type": [ "integer", "string" ], "format": "int32" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AreaSearchPage" } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } }, "security": [ { "ApiKey": [ ] } ] } }, "/api/search/radius/postcodes": { "get": { "tags": [ "Search" ], "summary": "Every postcode inside a circle with a count of the matching companies at it: the\nnumbered pins for a map.\n\nThe circle is a coordinate and a radius, so a pin dropped anywhere works. Coordinates\nare the postcode's centroid, which is where the companies are plotted -- rough, as a\npostcode is, and the registered office rather than wherever the company trades.", "parameters": [ { "name": "latitude", "in": "query", "description": "Latitude of the circle's centre, WGS84.", "schema": { "pattern": "^-?(?:0|[1-9]\\d*)(?:\\.\\d+)?(?:[eE][+-]?\\d+)?$", "type": [ "number", "string" ], "format": "double" } }, { "name": "longitude", "in": "query", "description": "Longitude of the circle's centre, WGS84.", "schema": { "pattern": "^-?(?:0|[1-9]\\d*)(?:\\.\\d+)?(?:[eE][+-]?\\d+)?$", "type": [ "number", "string" ], "format": "double" } }, { "name": "radius_miles", "in": "query", "schema": { "pattern": "^-?(?:0|[1-9]\\d*)(?:\\.\\d+)?(?:[eE][+-]?\\d+)?$", "type": [ "number", "string" ], "format": "double" } }, { "name": "status", "in": "query", "schema": { "type": "string" } }, { "name": "sic_code", "in": "query", "schema": { "type": "string" } }, { "name": "min_turnover", "in": "query", "schema": { "pattern": "^-?(?:0|[1-9]\\d*)(?:\\.\\d+)?$", "type": [ "number", "string" ], "format": "double" } }, { "name": "max_turnover", "in": "query", "schema": { "pattern": "^-?(?:0|[1-9]\\d*)(?:\\.\\d+)?$", "type": [ "number", "string" ], "format": "double" } }, { "name": "min_employees", "in": "query", "schema": { "pattern": "^-?(?:0|[1-9]\\d*)(?:\\.\\d+)?$", "type": [ "number", "string" ], "format": "double" } }, { "name": "max_employees", "in": "query", "schema": { "pattern": "^-?(?:0|[1-9]\\d*)(?:\\.\\d+)?$", "type": [ "number", "string" ], "format": "double" } }, { "name": "min_net_assets", "in": "query", "schema": { "pattern": "^-?(?:0|[1-9]\\d*)(?:\\.\\d+)?$", "type": [ "number", "string" ], "format": "double" } }, { "name": "max_net_assets", "in": "query", "schema": { "pattern": "^-?(?:0|[1-9]\\d*)(?:\\.\\d+)?$", "type": [ "number", "string" ], "format": "double" } }, { "name": "min_owner_percent", "in": "query", "schema": { "pattern": "^-?(?:0|[1-9]\\d*)$", "type": [ "integer", "string" ], "format": "int32" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RadiusPostcodes" } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } }, "security": [ { "ApiKey": [ ] } ] } }, "/api/search/radius": { "get": { "tags": [ "Search" ], "summary": "The matching companies inside a circle, nearest first, a page at a time -- or, with\npost_code, just those at the postcode a caller clicked.", "parameters": [ { "name": "latitude", "in": "query", "description": "Latitude of the circle's centre, WGS84.", "schema": { "pattern": "^-?(?:0|[1-9]\\d*)(?:\\.\\d+)?(?:[eE][+-]?\\d+)?$", "type": [ "number", "string" ], "format": "double" } }, { "name": "longitude", "in": "query", "description": "Longitude of the circle's centre, WGS84.", "schema": { "pattern": "^-?(?:0|[1-9]\\d*)(?:\\.\\d+)?(?:[eE][+-]?\\d+)?$", "type": [ "number", "string" ], "format": "double" } }, { "name": "radius_miles", "in": "query", "schema": { "pattern": "^-?(?:0|[1-9]\\d*)(?:\\.\\d+)?(?:[eE][+-]?\\d+)?$", "type": [ "number", "string" ], "format": "double" } }, { "name": "post_code", "in": "query", "schema": { "type": "string" } }, { "name": "status", "in": "query", "schema": { "type": "string" } }, { "name": "sic_code", "in": "query", "schema": { "type": "string" } }, { "name": "min_turnover", "in": "query", "schema": { "pattern": "^-?(?:0|[1-9]\\d*)(?:\\.\\d+)?$", "type": [ "number", "string" ], "format": "double" } }, { "name": "max_turnover", "in": "query", "schema": { "pattern": "^-?(?:0|[1-9]\\d*)(?:\\.\\d+)?$", "type": [ "number", "string" ], "format": "double" } }, { "name": "min_employees", "in": "query", "schema": { "pattern": "^-?(?:0|[1-9]\\d*)(?:\\.\\d+)?$", "type": [ "number", "string" ], "format": "double" } }, { "name": "max_employees", "in": "query", "schema": { "pattern": "^-?(?:0|[1-9]\\d*)(?:\\.\\d+)?$", "type": [ "number", "string" ], "format": "double" } }, { "name": "min_net_assets", "in": "query", "schema": { "pattern": "^-?(?:0|[1-9]\\d*)(?:\\.\\d+)?$", "type": [ "number", "string" ], "format": "double" } }, { "name": "max_net_assets", "in": "query", "schema": { "pattern": "^-?(?:0|[1-9]\\d*)(?:\\.\\d+)?$", "type": [ "number", "string" ], "format": "double" } }, { "name": "min_owner_percent", "in": "query", "schema": { "pattern": "^-?(?:0|[1-9]\\d*)$", "type": [ "integer", "string" ], "format": "int32" } }, { "name": "limit", "in": "query", "description": "Page size, 1 to 200. Defaults to 50.", "schema": { "pattern": "^-?(?:0|[1-9]\\d*)$", "type": [ "integer", "string" ], "format": "int32" } }, { "name": "offset", "in": "query", "description": "How many results to skip.", "schema": { "pattern": "^-?(?:0|[1-9]\\d*)$", "type": [ "integer", "string" ], "format": "int32" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RadiusCompanyPage" } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } }, "security": [ { "ApiKey": [ ] } ] } }, "/api/search/radius/registrations": { "get": { "tags": [ "Search" ], "summary": "The registration number of every matching company inside a circle, nearest first, for\nimporting them. At most 50,000; truncated says whether there were more.", "parameters": [ { "name": "latitude", "in": "query", "description": "Latitude of the circle's centre, WGS84.", "schema": { "pattern": "^-?(?:0|[1-9]\\d*)(?:\\.\\d+)?(?:[eE][+-]?\\d+)?$", "type": [ "number", "string" ], "format": "double" } }, { "name": "longitude", "in": "query", "description": "Longitude of the circle's centre, WGS84.", "schema": { "pattern": "^-?(?:0|[1-9]\\d*)(?:\\.\\d+)?(?:[eE][+-]?\\d+)?$", "type": [ "number", "string" ], "format": "double" } }, { "name": "radius_miles", "in": "query", "schema": { "pattern": "^-?(?:0|[1-9]\\d*)(?:\\.\\d+)?(?:[eE][+-]?\\d+)?$", "type": [ "number", "string" ], "format": "double" } }, { "name": "post_code", "in": "query", "schema": { "type": "string" } }, { "name": "status", "in": "query", "schema": { "type": "string" } }, { "name": "sic_code", "in": "query", "schema": { "type": "string" } }, { "name": "min_turnover", "in": "query", "schema": { "pattern": "^-?(?:0|[1-9]\\d*)(?:\\.\\d+)?$", "type": [ "number", "string" ], "format": "double" } }, { "name": "max_turnover", "in": "query", "schema": { "pattern": "^-?(?:0|[1-9]\\d*)(?:\\.\\d+)?$", "type": [ "number", "string" ], "format": "double" } }, { "name": "min_employees", "in": "query", "schema": { "pattern": "^-?(?:0|[1-9]\\d*)(?:\\.\\d+)?$", "type": [ "number", "string" ], "format": "double" } }, { "name": "max_employees", "in": "query", "schema": { "pattern": "^-?(?:0|[1-9]\\d*)(?:\\.\\d+)?$", "type": [ "number", "string" ], "format": "double" } }, { "name": "min_net_assets", "in": "query", "schema": { "pattern": "^-?(?:0|[1-9]\\d*)(?:\\.\\d+)?$", "type": [ "number", "string" ], "format": "double" } }, { "name": "max_net_assets", "in": "query", "schema": { "pattern": "^-?(?:0|[1-9]\\d*)(?:\\.\\d+)?$", "type": [ "number", "string" ], "format": "double" } }, { "name": "min_owner_percent", "in": "query", "schema": { "pattern": "^-?(?:0|[1-9]\\d*)$", "type": [ "integer", "string" ], "format": "int32" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RadiusRegistrations" } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } }, "security": [ { "ApiKey": [ ] } ] } }, "/api/search/id/{id}": { "get": { "tags": [ "Search" ], "summary": "Companies whose registration number starts with the given text.", "parameters": [ { "name": "id", "in": "path", "description": "Registration number, or the start of one, for example '0955'.", "required": true, "schema": { "type": "string" } }, { "name": "limit", "in": "query", "schema": { "pattern": "^-?(?:0|[1-9]\\d*)$", "type": [ "integer", "string" ], "format": "int32" } }, { "name": "offset", "in": "query", "schema": { "pattern": "^-?(?:0|[1-9]\\d*)$", "type": [ "integer", "string" ], "format": "int32" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/CompanySearchResult" } } } } } }, "security": [ { "ApiKey": [ ] } ] } }, "/api/watchlist": { "get": { "tags": [ "Monitoring" ], "summary": "The watched companies, by registration number.", "parameters": [ { "name": "limit", "in": "query", "description": "Page size, 1 to 1000. Defaults to 100.", "schema": { "pattern": "^-?(?:0|[1-9]\\d*)$", "type": [ "integer", "string" ], "format": "int32" } }, { "name": "offset", "in": "query", "description": "How many to skip.", "schema": { "pattern": "^-?(?:0|[1-9]\\d*)$", "type": [ "integer", "string" ], "format": "int32" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WatchlistPage" } } } } }, "security": [ { "ApiKey": [ ] } ] }, "post": { "tags": [ "Monitoring" ], "summary": "Watches up to 1000 companies at once.", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WatchRequest" } }, "application/*+json": { "schema": { "$ref": "#/components/schemas/WatchRequest" } } }, "required": true }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WatchResult" } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } }, "security": [ { "ApiKey": [ ] } ] } }, "/api/watchlist/{id}": { "put": { "tags": [ "Monitoring" ], "summary": "Watches one company.", "parameters": [ { "name": "id", "in": "path", "description": "Company registration number.", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WatchResult" } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } }, "security": [ { "ApiKey": [ ] } ] }, "delete": { "tags": [ "Monitoring" ], "summary": "Stops watching a company.", "parameters": [ { "name": "id", "in": "path", "description": "Company registration number.", "required": true, "schema": { "type": "string" } } ], "responses": { "204": { "description": "No Content", "content": { "application/json": { } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } }, "security": [ { "ApiKey": [ ] } ] } }, "/api/webhooks": { "post": { "tags": [ "Monitoring" ], "summary": "Registers a webhook. The response carries its signing secret, once.", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateWebhookRequest" } }, "application/*+json": { "schema": { "$ref": "#/components/schemas/CreateWebhookRequest" } } }, "required": true }, "responses": { "201": { "description": "Created", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreatedWebhook" } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } }, "security": [ { "ApiKey": [ ] } ] }, "get": { "tags": [ "Monitoring" ], "summary": "This key's webhooks, without their secrets.", "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/WebhookSubscription" } } } } } }, "security": [ { "ApiKey": [ ] } ] } }, "/api/webhooks/{id}": { "delete": { "tags": [ "Monitoring" ], "summary": "Deletes a webhook. Deliveries not yet made are dropped.", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "204": { "description": "No Content", "content": { "application/json": { } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } }, "security": [ { "ApiKey": [ ] } ] } }, "/api/webhooks/{id}/deliveries": { "get": { "tags": [ "Monitoring" ], "summary": "A webhook's most recent deliveries and how each went, for debugging a receiver.", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "limit", "in": "query", "description": "How many, 1 to 200. Defaults to 50.", "schema": { "pattern": "^-?(?:0|[1-9]\\d*)$", "type": [ "integer", "string" ], "format": "int32" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/WebhookDeliveryRecord" } } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } }, "security": [ { "ApiKey": [ ] } ] } } }, "components": { "schemas": { "AreaSearchPage": { "required": [ "items", "total", "limit", "offset" ], "type": "object", "properties": { "items": { "type": "array", "items": { "$ref": "#/components/schemas/AreaSearchResult" } }, "total": { "pattern": "^-?(?:0|[1-9]\\d*)$", "type": [ "integer", "string" ], "format": "int32" }, "limit": { "pattern": "^-?(?:0|[1-9]\\d*)$", "type": [ "integer", "string" ], "format": "int32" }, "offset": { "pattern": "^-?(?:0|[1-9]\\d*)$", "type": [ "integer", "string" ], "format": "int32" }, "has_more": { "type": "boolean" } }, "description": "One page of area search results." }, "AreaSearchResult": { "required": [ "company_registration", "name", "company_status", "status_code", "post_code", "admin_district", "admin_county", "distance_miles", "net_assets", "employees", "period_end", "sic_codes", "domain", "logo_url", "theme_colour", "strapline" ], "type": "object", "properties": { "company_registration": { "type": "string" }, "name": { "type": [ "null", "string" ] }, "company_status": { "type": [ "null", "string" ] }, "status_code": { "pattern": "^-?(?:0|[1-9]\\d*)$", "type": [ "null", "integer", "string" ], "format": "int16" }, "post_code": { "type": [ "null", "string" ] }, "admin_district": { "type": [ "null", "string" ] }, "admin_county": { "type": [ "null", "string" ] }, "distance_miles": { "pattern": "^-?(?:0|[1-9]\\d*)(?:\\.\\d+)?(?:[eE][+-]?\\d+)?$", "type": [ "null", "number", "string" ], "format": "double" }, "net_assets": { "pattern": "^-?(?:0|[1-9]\\d*)(?:\\.\\d+)?$", "type": [ "null", "number", "string" ], "format": "double" }, "employees": { "pattern": "^-?(?:0|[1-9]\\d*)(?:\\.\\d+)?$", "type": [ "null", "number", "string" ], "format": "double" }, "period_end": { "type": [ "null", "string" ], "format": "date" }, "sic_codes": { "type": [ "null", "array" ], "items": { "type": "string" } }, "domain": { "type": [ "null", "string" ], "description": "The company's website, or null. Null means not known: most companies have no site, and a\nresolved one is only present once the crawl has reached that company. Only a verified\nmatch is served here." }, "logo_url": { "type": [ "null", "string" ] }, "theme_colour": { "type": [ "null", "string" ] }, "strapline": { "type": [ "null", "string" ] }, "currency": { "type": [ "null", "string" ] }, "net_assets_gbp": { "pattern": "^-?(?:0|[1-9]\\d*)(?:\\.\\d+)?$", "type": [ "null", "number", "string" ], "format": "double" }, "currency_stated": { "type": "boolean", "default": false }, "currency_note": { "type": [ "null", "string" ] }, "website_confidence": { "pattern": "^-?(?:0|[1-9]\\d*)$", "type": [ "null", "integer", "string" ], "format": "int16" }, "website_source": { "type": [ "null", "string" ] }, "website_via": { "type": [ "null", "string" ] }, "website_relation": { "type": [ "null", "string" ] } }, "description": "A company matching an area search." }, "CompanyBrandResponse": { "required": [ "domain", "theme_colour", "strapline", "contact_email", "contact_email_is_role", "contact_phone", "contact_phone_type", "logo_url", "branded_at" ], "type": "object", "properties": { "domain": { "type": [ "null", "string" ] }, "theme_colour": { "type": [ "null", "string" ] }, "strapline": { "type": [ "null", "string" ] }, "contact_email": { "type": [ "null", "string" ], "description": "The published address, role mailbox preferred over a named one." }, "contact_email_is_role": { "type": [ "null", "boolean" ], "description": "True for info@ and the like, false for a named individual. Stated rather than left to the\ncaller to guess from the spelling." }, "contact_phone": { "type": [ "null", "string" ], "description": "The published number in E.164, for example +441202123456." }, "contact_phone_type": { "type": [ "null", "string" ], "description": "FIXED_LINE, MOBILE and so on. A switchboard and a director's mobile are not the same\nthing, and a caller may reasonably want only one of them." }, "logo_url": { "type": [ "null", "string" ], "description": "Where to fetch the logo, or null if none was found. A path on this API rather than a\nstorage URL, so the image stays revocable and the caller needs no credential of its own." }, "branded_at": { "type": [ "null", "string" ], "description": "When the site was last examined. Null means not yet looked at, which is different from\nlooked at and found to publish nothing.", "format": "date-time" } }, "description": "What a company's website said about it." }, "CompanyProfile": { "required": [ "company_registration", "name", "company_status", "status_code", "status_as_of", "company_type", "legal_form", "incorporated_on", "ceased_on", "sic_codes", "registered_address", "location", "accounts", "charges", "website", "latest_financials", "ownership", "officers", "notices", "health", "score", "people" ], "type": "object", "properties": { "company_registration": { "type": "string" }, "name": { "type": [ "null", "string" ] }, "company_status": { "type": [ "null", "string" ] }, "status_code": { "pattern": "^-?(?:0|[1-9]\\d*)$", "type": [ "integer", "string" ], "description": "The normalised status: 0 unknown, 1 active, 2 proposal to strike off, 3 liquidation,\n4 administration, 5 receivership, 6 voluntary arrangement, 7 dissolved, 99 other.", "format": "int16" }, "status_as_of": { "type": [ "null", "string" ], "description": "The date of the snapshot the status was read from.", "format": "date" }, "company_type": { "type": [ "null", "string" ] }, "legal_form": { "type": [ "null", "string" ], "description": "As the company's own accounts describe it." }, "incorporated_on": { "type": [ "null", "string" ], "format": "date" }, "ceased_on": { "type": [ "null", "string" ], "format": "date" }, "sic_codes": { "type": [ "null", "array" ], "items": { "type": "string" } }, "registered_address": { "$ref": "#/components/schemas/ProfileAddress" }, "location": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/ProfileLocation" } ] }, "accounts": { "$ref": "#/components/schemas/ProfileAccounts" }, "charges": { "$ref": "#/components/schemas/ProfileCharges" }, "website": { "oneOf": [ { "type": "null" }, { "description": "Null when no website has been proved to be the company's.", "$ref": "#/components/schemas/ProfileWebsite" } ] }, "latest_financials": { "oneOf": [ { "type": "null" }, { "description": "The most recent accounts held, or null if none are.", "$ref": "#/components/schemas/ProfileFinancials" } ] }, "ownership": { "$ref": "#/components/schemas/ProfileOwnership" }, "officers": { "$ref": "#/components/schemas/ProfileOfficers" }, "notices": { "type": "array", "items": { "$ref": "#/components/schemas/ProfileNotice" } }, "health": { "$ref": "#/components/schemas/HealthAssessment" }, "score": { "description": "The company's score, made from the same reading as Health.", "$ref": "#/components/schemas/ProfileScore" }, "people": { "$ref": "#/components/schemas/ProfilePeople" }, "group": { "oneOf": [ { "type": "null" }, { "description": "Its parents, subsidiaries and siblings; null when it has none.", "$ref": "#/components/schemas/ProfileGroup" } ] } }, "description": "Everything held about a company, in one response: the register, its accounts, its\nwebsite, where it is, who owns it and how healthy it looks." }, "CompanySearchResult": { "required": [ "company_registration", "name", "legal_form", "address_line1", "address_line2", "post_code" ], "type": "object", "properties": { "company_registration": { "type": "string" }, "name": { "type": [ "null", "string" ] }, "legal_form": { "type": [ "null", "string" ] }, "address_line1": { "type": [ "null", "string" ] }, "address_line2": { "type": [ "null", "string" ] }, "post_code": { "type": [ "null", "string" ] } }, "description": "A company as the search endpoints return it." }, "CorpusTotals": { "required": [ "filings", "companies", "facts", "concepts", "failures" ], "type": "object", "properties": { "filings": { "pattern": "^-?(?:0|[1-9]\\d*)$", "type": [ "integer", "string" ], "format": "int64" }, "companies": { "pattern": "^-?(?:0|[1-9]\\d*)$", "type": [ "integer", "string" ], "format": "int64" }, "facts": { "pattern": "^-?(?:0|[1-9]\\d*)$", "type": [ "integer", "string" ], "format": "int64" }, "concepts": { "pattern": "^-?(?:0|[1-9]\\d*)$", "type": [ "integer", "string" ], "format": "int64" }, "failures": { "pattern": "^-?(?:0|[1-9]\\d*)$", "type": [ "integer", "string" ], "format": "int64" } }, "description": "How much has been accumulated overall." }, "CreateWebhookRequest": { "required": [ "url", "events" ], "type": "object", "properties": { "url": { "type": "string", "description": "An https URL on a public host." }, "events": { "type": [ "null", "array" ], "items": { "type": "string" }, "description": "Event types to receive; omitted or empty means all of them." } } }, "CreatedWebhook": { "required": [ "subscription", "secret" ], "type": "object", "properties": { "subscription": { "$ref": "#/components/schemas/WebhookSubscription" }, "secret": { "type": "string", "description": "Signs every delivery. Shown here once and never again: store it now. Each delivery carries\nX-Fortuna-Signature: t=<unix seconds>,v1=<hex>, where v1 is HMAC-SHA256 with this\nsecret over \"<t>.<raw body>\"." } } }, "DomainProgress": { "required": [ "attempted", "resolved", "queued" ], "type": "object", "properties": { "attempted": { "pattern": "^-?(?:0|[1-9]\\d*)$", "type": [ "integer", "string" ], "format": "int64" }, "resolved": { "pattern": "^-?(?:0|[1-9]\\d*)$", "type": [ "integer", "string" ], "format": "int64" }, "queued": { "pattern": "^-?(?:0|[1-9]\\d*)$", "type": [ "integer", "string" ], "format": "int64" }, "hit_rate": { "pattern": "^-?(?:0|[1-9]\\d*)(?:\\.\\d+)?(?:[eE][+-]?\\d+)?$", "type": [ "number", "string" ], "format": "double" } }, "description": "How domain resolution is getting on." }, "FilingPage": { "required": [ "items", "total", "limit", "offset" ], "type": "object", "properties": { "items": { "type": "array", "description": "The filings on this page." }, "total": { "pattern": "^-?(?:0|[1-9]\\d*)$", "type": [ "integer", "string" ], "description": "Filings matching the request across all pages.", "format": "int32" }, "limit": { "pattern": "^-?(?:0|[1-9]\\d*)$", "type": [ "integer", "string" ], "description": "Page size actually applied, after clamping.", "format": "int32" }, "offset": { "pattern": "^-?(?:0|[1-9]\\d*)$", "type": [ "integer", "string" ], "description": "Offset actually applied.", "format": "int32" }, "has_more": { "type": "boolean" } }, "description": "One page of filings, with enough context for a caller to page through." }, "HealthAssessment": { "required": [ "flags", "ratios", "trends", "latest_period_end", "previous_period_end" ], "type": "object", "properties": { "flags": { "type": "array", "items": { "$ref": "#/components/schemas/HealthFlag" } }, "ratios": { "$ref": "#/components/schemas/HealthRatios" }, "trends": { "type": "object", "additionalProperties": { "$ref": "#/components/schemas/HealthTrend" } }, "latest_period_end": { "type": [ "null", "string" ], "format": "date" }, "previous_period_end": { "type": [ "null", "string" ], "format": "date" } } }, "HealthFlag": { "required": [ "code", "severity", "detail" ], "type": "object", "properties": { "code": { "type": "string" }, "severity": { "type": "string" }, "detail": { "type": "string" } } }, "HealthRatios": { "required": [ "current_ratio", "cash_ratio", "gearing" ], "type": "object", "properties": { "current_ratio": { "pattern": "^-?(?:0|[1-9]\\d*)(?:\\.\\d+)?$", "type": [ "null", "number", "string" ], "format": "double" }, "cash_ratio": { "pattern": "^-?(?:0|[1-9]\\d*)(?:\\.\\d+)?$", "type": [ "null", "number", "string" ], "format": "double" }, "gearing": { "pattern": "^-?(?:0|[1-9]\\d*)(?:\\.\\d+)?$", "type": [ "null", "number", "string" ], "format": "double" } } }, "HealthTrend": { "required": [ "latest", "previous", "change_percent" ], "type": "object", "properties": { "latest": { "pattern": "^-?(?:0|[1-9]\\d*)(?:\\.\\d+)?$", "type": [ "null", "number", "string" ], "format": "double" }, "previous": { "pattern": "^-?(?:0|[1-9]\\d*)(?:\\.\\d+)?$", "type": [ "null", "number", "string" ], "format": "double" }, "change_percent": { "pattern": "^-?(?:0|[1-9]\\d*)(?:\\.\\d+)?$", "type": [ "null", "number", "string" ], "format": "double" } } }, "IngestProgress": { "required": [ "at", "active_runs", "recent_runs", "totals", "domains" ], "type": "object", "properties": { "at": { "type": "string", "format": "date-time" }, "active_runs": { "type": "array", "items": { "$ref": "#/components/schemas/RunProgress" } }, "recent_runs": { "type": "array", "items": { "$ref": "#/components/schemas/RunProgress" } }, "totals": { "$ref": "#/components/schemas/CorpusTotals" }, "domains": { "$ref": "#/components/schemas/DomainProgress" } }, "description": "A snapshot of what the pipelines are doing, as pushed to watchers." }, "MatchBatchRequest": { "required": [ "items" ], "type": "object", "properties": { "items": { "type": "array", "items": { "$ref": "#/components/schemas/MatchRequest" } } } }, "MatchCandidate": { "required": [ "company_registration", "name", "company_status", "status_code", "post_code", "confidence", "reasons" ], "type": "object", "properties": { "company_registration": { "type": "string" }, "name": { "type": [ "null", "string" ] }, "company_status": { "type": [ "null", "string" ] }, "status_code": { "pattern": "^-?(?:0|[1-9]\\d*)$", "type": [ "integer", "string" ], "format": "int16" }, "post_code": { "type": [ "null", "string" ] }, "confidence": { "pattern": "^-?(?:0|[1-9]\\d*)(?:\\.\\d+)?(?:[eE][+-]?\\d+)?$", "type": [ "number", "string" ], "description": "0 to 1.", "format": "double" }, "reasons": { "type": "array", "items": { "type": "string" }, "description": "Why it was proposed: number, verified_domain, exact_name, name_key, similar_name,\npostcode, postcode_district." } } }, "MatchRequest": { "type": "object", "properties": { "reference": { "type": [ "null", "string" ], "description": "Echoed back untouched, to line batch results up with their input." }, "number": { "type": [ "null", "string" ], "description": "A registration number." }, "name": { "type": [ "null", "string" ] }, "postcode": { "type": [ "null", "string" ] }, "domain": { "type": [ "null", "string" ], "description": "A website or bare domain, for example https://www.acme.co.uk/about." }, "email": { "type": [ "null", "string" ], "description": "An email address; its domain is looked up." }, "is_empty": { "type": "boolean" } }, "description": "What a caller knows about a company. Any combination; at least one." }, "MatchResult": { "required": [ "reference", "match", "candidates", "notes" ], "type": "object", "properties": { "reference": { "type": [ "null", "string" ] }, "match": { "oneOf": [ { "type": "null" }, { "description": "The candidate to act on, when one is confident (0.85 or more) and at least 0.1 ahead of the\nnext. Null means a person should look at the candidates.", "$ref": "#/components/schemas/MatchCandidate" } ] }, "candidates": { "type": "array", "items": { "$ref": "#/components/schemas/MatchCandidate" } }, "notes": { "type": "array", "items": { "type": "string" }, "description": "Anything about the input worth knowing, such as a free-mail address." } } }, "ProblemDetails": { "type": "object", "properties": { "type": { "type": [ "null", "string" ] }, "title": { "type": [ "null", "string" ] }, "status": { "pattern": "^-?(?:0|[1-9]\\d*)$", "type": [ "null", "integer", "string" ], "format": "int32" }, "detail": { "type": [ "null", "string" ] }, "instance": { "type": [ "null", "string" ] } } }, "ProfileAccounts": { "required": [ "category", "last_made_up_to", "next_due", "overdue" ], "type": "object", "properties": { "category": { "type": [ "null", "string" ] }, "last_made_up_to": { "type": [ "null", "string" ], "format": "date" }, "next_due": { "type": [ "null", "string" ], "format": "date" }, "overdue": { "type": "boolean", "description": "True when the next due date has passed." } } }, "ProfileAddress": { "required": [ "address_line1", "address_line2", "locality", "region", "country", "post_code" ], "type": "object", "properties": { "address_line1": { "type": [ "null", "string" ] }, "address_line2": { "type": [ "null", "string" ] }, "locality": { "type": [ "null", "string" ] }, "region": { "type": [ "null", "string" ] }, "country": { "type": [ "null", "string" ] }, "post_code": { "type": [ "null", "string" ] } } }, "ProfileCharges": { "required": [ "has_charges", "mortgages_outstanding" ], "type": "object", "properties": { "has_charges": { "type": [ "null", "boolean" ] }, "mortgages_outstanding": { "pattern": "^-?(?:0|[1-9]\\d*)$", "type": [ "null", "integer", "string" ], "description": "Charges not yet satisfied, from the monthly snapshot.", "format": "int32" } } }, "ProfileFinancials": { "required": [ "filing_id", "period_start", "period_end", "dormant", "turnover", "profit_loss", "net_assets", "shareholder_funds", "current_assets", "cash_at_bank", "creditors_due_within_one_year", "creditors_due_after_one_year", "average_employees" ], "type": "object", "properties": { "filing_id": { "pattern": "^-?(?:0|[1-9]\\d*)$", "type": [ "integer", "string" ], "format": "int64" }, "period_start": { "type": [ "null", "string" ], "format": "date" }, "period_end": { "type": [ "null", "string" ], "format": "date" }, "dormant": { "type": [ "null", "boolean" ] }, "turnover": { "pattern": "^-?(?:0|[1-9]\\d*)(?:\\.\\d+)?$", "type": [ "null", "number", "string" ], "format": "double" }, "profit_loss": { "pattern": "^-?(?:0|[1-9]\\d*)(?:\\.\\d+)?$", "type": [ "null", "number", "string" ], "format": "double" }, "net_assets": { "pattern": "^-?(?:0|[1-9]\\d*)(?:\\.\\d+)?$", "type": [ "null", "number", "string" ], "format": "double" }, "shareholder_funds": { "pattern": "^-?(?:0|[1-9]\\d*)(?:\\.\\d+)?$", "type": [ "null", "number", "string" ], "format": "double" }, "current_assets": { "pattern": "^-?(?:0|[1-9]\\d*)(?:\\.\\d+)?$", "type": [ "null", "number", "string" ], "format": "double" }, "cash_at_bank": { "pattern": "^-?(?:0|[1-9]\\d*)(?:\\.\\d+)?$", "type": [ "null", "number", "string" ], "format": "double" }, "creditors_due_within_one_year": { "pattern": "^-?(?:0|[1-9]\\d*)(?:\\.\\d+)?$", "type": [ "null", "number", "string" ], "format": "double" }, "creditors_due_after_one_year": { "pattern": "^-?(?:0|[1-9]\\d*)(?:\\.\\d+)?$", "type": [ "null", "number", "string" ], "format": "double" }, "average_employees": { "pattern": "^-?(?:0|[1-9]\\d*)(?:\\.\\d+)?$", "type": [ "null", "number", "string" ], "format": "double" }, "currency": { "type": [ "null", "string" ], "description": "The currency the figures are in: as the filing declares it, or GBP for a UK company's that\ndeclares none. Null for an overseas company's that declares none, whose currency is unknown." }, "currency_stated": { "type": "boolean", "description": "Whether the filing declares the currency, rather than it being taken as pounds.", "default": false }, "currency_note": { "type": [ "null", "string" ], "description": "Why there are no pounds figures, where there are none." }, "in_pounds": { "oneOf": [ { "type": "null" }, { "description": "The money figures in pounds, or null where they cannot be converted.", "$ref": "#/components/schemas/ProfileFinancialsInPounds" } ] } }, "description": "The latest accounts' figures as filed, in string? ProfileFinancials.Currency, and in pounds beside them." }, "ProfileFinancialsInPounds": { "required": [ "turnover", "profit_loss", "net_assets", "shareholder_funds", "current_assets", "cash_at_bank", "creditors_due_within_one_year", "creditors_due_after_one_year", "closing_rate", "year_rate" ], "type": "object", "properties": { "turnover": { "pattern": "^-?(?:0|[1-9]\\d*)(?:\\.\\d+)?$", "type": [ "null", "number", "string" ], "format": "double" }, "profit_loss": { "pattern": "^-?(?:0|[1-9]\\d*)(?:\\.\\d+)?$", "type": [ "null", "number", "string" ], "format": "double" }, "net_assets": { "pattern": "^-?(?:0|[1-9]\\d*)(?:\\.\\d+)?$", "type": [ "null", "number", "string" ], "format": "double" }, "shareholder_funds": { "pattern": "^-?(?:0|[1-9]\\d*)(?:\\.\\d+)?$", "type": [ "null", "number", "string" ], "format": "double" }, "current_assets": { "pattern": "^-?(?:0|[1-9]\\d*)(?:\\.\\d+)?$", "type": [ "null", "number", "string" ], "format": "double" }, "cash_at_bank": { "pattern": "^-?(?:0|[1-9]\\d*)(?:\\.\\d+)?$", "type": [ "null", "number", "string" ], "format": "double" }, "creditors_due_within_one_year": { "pattern": "^-?(?:0|[1-9]\\d*)(?:\\.\\d+)?$", "type": [ "null", "number", "string" ], "format": "double" }, "creditors_due_after_one_year": { "pattern": "^-?(?:0|[1-9]\\d*)(?:\\.\\d+)?$", "type": [ "null", "number", "string" ], "format": "double" }, "closing_rate": { "pattern": "^-?(?:0|[1-9]\\d*)(?:\\.\\d+)?$", "type": [ "number", "string" ], "format": "double" }, "year_rate": { "pattern": "^-?(?:0|[1-9]\\d*)(?:\\.\\d+)?$", "type": [ "number", "string" ], "format": "double" } }, "description": "The latest accounts' money figures in pounds: the balance sheet at the closing rate on or\nbefore the period end, turnover and profit at the trailing year's average -- the rates the\nscore reads them at. For accounts in pounds, the figures as filed and rates of one." }, "ProfileGroup": { "required": [ "parents", "subsidiaries", "subsidiary_count", "siblings", "sibling_count", "health" ], "type": "object", "properties": { "parents": { "type": "array", "items": { "$ref": "#/components/schemas/ProfileGroupMember" }, "description": "Its controlling owner, that owner's, and so on up: the immediate parent first and the\nultimate parent last. The last may be an owner registered abroad, named but not held." }, "subsidiaries": { "type": "array", "items": { "$ref": "#/components/schemas/ProfileGroupMember" }, "description": "The companies it controls, largest by net assets first; at most int CompanyGroupQueries.Shown." }, "subsidiary_count": { "pattern": "^-?(?:0|[1-9]\\d*)$", "type": [ "integer", "string" ], "format": "int32" }, "siblings": { "type": "array", "items": { "$ref": "#/components/schemas/ProfileGroupMember" }, "description": "The other companies its immediate parent controls, the same way." }, "sibling_count": { "pattern": "^-?(?:0|[1-9]\\d*)$", "type": [ "integer", "string" ], "format": "int32" }, "health": { "description": "Every company under the ultimate parent held in the UK, this one included.", "$ref": "#/components/schemas/ProfileGroupHealth" } }, "description": "The group a company belongs to: the owners that control it, up to the top; the companies it\ncontrols; the others its parent controls; and how the whole group is faring." }, "ProfileGroupHealth": { "required": [ "ultimate_parent", "companies", "capped", "active", "in_insolvency", "strike_off", "dissolved", "weak", "worst_band" ], "type": "object", "properties": { "ultimate_parent": { "type": [ "null", "string" ] }, "companies": { "pattern": "^-?(?:0|[1-9]\\d*)$", "type": [ "integer", "string" ], "description": "Companies in the group, counted up to int CompanyGroupQueries.MaxCounted.", "format": "int32" }, "capped": { "type": "boolean", "description": "True when the group is larger than was counted, or deeper than int CompanyGroupQueries.MaxDepth levels." }, "active": { "pattern": "^-?(?:0|[1-9]\\d*)$", "type": [ "integer", "string" ], "format": "int32" }, "in_insolvency": { "pattern": "^-?(?:0|[1-9]\\d*)$", "type": [ "integer", "string" ], "description": "In liquidation, administration, receivership or a voluntary arrangement.", "format": "int32" }, "strike_off": { "pattern": "^-?(?:0|[1-9]\\d*)$", "type": [ "integer", "string" ], "description": "With a proposal to strike off.", "format": "int32" }, "dissolved": { "pattern": "^-?(?:0|[1-9]\\d*)$", "type": [ "integer", "string" ], "format": "int32" }, "weak": { "pattern": "^-?(?:0|[1-9]\\d*)$", "type": [ "integer", "string" ], "description": "Scored D or E.", "format": "int32" }, "worst_band": { "type": [ "null", "string" ], "description": "The lowest band among those scored." } } }, "ProfileGroupMember": { "required": [ "company_registration", "name", "country_registered", "status_code", "company_status", "band", "score", "ownership_min", "ownership_max", "appoints_directors", "net_assets" ], "type": "object", "properties": { "company_registration": { "type": [ "null", "string" ], "description": "Null for an owner registered abroad, or one whose number is not held." }, "name": { "type": [ "null", "string" ], "description": "The register's name for a company held; else as the owner is named on the PSC register." }, "country_registered": { "type": [ "null", "string" ], "description": "As the PSC register gives it, for an owner." }, "status_code": { "pattern": "^-?(?:0|[1-9]\\d*)$", "type": [ "null", "integer", "string" ], "description": "As on the profile; null for an owner not held.", "format": "int16" }, "company_status": { "type": [ "null", "string" ] }, "band": { "type": [ "null", "string" ], "description": "Its own score's band, A to E or not_rated; null if not scored." }, "score": { "pattern": "^-?(?:0|[1-9]\\d*)$", "type": [ "null", "integer", "string" ], "format": "int32" }, "ownership_min": { "pattern": "^-?(?:0|[1-9]\\d*)$", "type": [ "null", "integer", "string" ], "description": "The share of the company below it held, as a range: a parent's of its child, a subsidiary's parent's of it.", "format": "int32" }, "ownership_max": { "pattern": "^-?(?:0|[1-9]\\d*)$", "type": [ "null", "integer", "string" ], "format": "int32" }, "appoints_directors": { "type": "boolean", "description": "Control by the right to appoint the board." }, "net_assets": { "pattern": "^-?(?:0|[1-9]\\d*)(?:\\.\\d+)?$", "type": [ "null", "number", "string" ], "format": "double" } } }, "ProfileLocation": { "required": [ "post_code", "latitude", "longitude", "admin_district", "admin_county" ], "type": "object", "properties": { "post_code": { "type": "string" }, "latitude": { "pattern": "^-?(?:0|[1-9]\\d*)(?:\\.\\d+)?(?:[eE][+-]?\\d+)?$", "type": [ "number", "string" ], "format": "double" }, "longitude": { "pattern": "^-?(?:0|[1-9]\\d*)(?:\\.\\d+)?(?:[eE][+-]?\\d+)?$", "type": [ "number", "string" ], "format": "double" }, "admin_district": { "type": [ "null", "string" ] }, "admin_county": { "type": [ "null", "string" ] } }, "description": "The registered office's postcode centroid, not the building." }, "ProfileNotice": { "required": [ "notice_id", "code", "type", "published_at", "matched_by", "url" ], "type": "object", "properties": { "notice_id": { "pattern": "^-?(?:0|[1-9]\\d*)$", "type": [ "integer", "string" ], "format": "int64" }, "code": { "type": "string" }, "type": { "type": [ "null", "string" ], "description": "The Gazette's own label, for example \"Petitions to Wind Up (Companies)\"." }, "published_at": { "type": "string", "format": "date-time" }, "matched_by": { "type": [ "null", "string" ], "description": "number when the notice gives the company's number; name when it gives only the name and\nexactly one company has it." }, "url": { "type": "string", "description": "The notice on The Gazette." } }, "description": "A corporate insolvency notice from The Gazette." }, "ProfileOfficer": { "required": [ "name", "role", "appointed_on", "nationality", "occupation", "birth_year", "birth_month", "officer_id" ], "type": "object", "properties": { "name": { "type": "string" }, "role": { "type": [ "null", "string" ] }, "appointed_on": { "type": [ "null", "string" ], "format": "date" }, "nationality": { "type": [ "null", "string" ] }, "occupation": { "type": [ "null", "string" ] }, "birth_year": { "pattern": "^-?(?:0|[1-9]\\d*)$", "type": [ "null", "integer", "string" ], "format": "int32" }, "birth_month": { "pattern": "^-?(?:0|[1-9]\\d*)$", "type": [ "null", "integer", "string" ], "format": "int32" }, "officer_id": { "type": [ "null", "string" ], "description": "Companies House's id for the person, the same on every appointment they hold. Null until\nthe appointment has been seen through the REST API." } } }, "ProfileOfficers": { "required": [ "fetched", "current_count", "current" ], "type": "object", "properties": { "fetched": { "type": "boolean", "description": "Whether this company's officers have been read from the register yet. Every live company's\nare being fetched in turn; asking for a profile moves a company not yet fetched to the\nfront, so its officers are usually here within the hour." }, "current_count": { "pattern": "^-?(?:0|[1-9]\\d*)$", "type": [ "integer", "string" ], "format": "int32" }, "current": { "type": "array", "items": { "$ref": "#/components/schemas/ProfileOfficer" }, "description": "The current appointments, longest serving first." } } }, "ProfileOwnership": { "required": [ "current_count", "current" ], "type": "object", "properties": { "current_count": { "pattern": "^-?(?:0|[1-9]\\d*)$", "type": [ "integer", "string" ], "format": "int32" }, "current": { "type": "array", "items": { "$ref": "#/components/schemas/PscResponse" }, "description": "The current persons with significant control, as /api/company/{id}/psc returns them.\nFormer ones are served there with include_ceased." } } }, "ProfilePeople": { "required": [ "employees_as_filed", "employees_period_end", "directors", "corporate_directors", "at_least", "at_most" ], "type": "object", "properties": { "employees_as_filed": { "pattern": "^-?(?:0|[1-9]\\d*)$", "type": [ "null", "integer", "string" ], "description": "The average number of employees in the latest accounts, exactly as filed; null if not\ngiven. A director counts as an employee only under a contract of employment, so a company\nrun by directors paid by dividend often files 0.", "format": "int32" }, "employees_period_end": { "type": [ "null", "string" ], "format": "date" }, "directors": { "pattern": "^-?(?:0|[1-9]\\d*)$", "type": [ "null", "integer", "string" ], "description": "Directors in office who are people: not secretaries, and not companies acting as directors,\nwhich a person's date of birth tells apart. Null while the company's officers have not been\nread. The score counts its directors its own way, corporate ones included.", "format": "int32" }, "corporate_directors": { "pattern": "^-?(?:0|[1-9]\\d*)$", "type": [ "null", "integer", "string" ], "description": "Companies acting as directors: counted here, and in neither estimate, since they are not people.", "format": "int32" }, "at_least": { "pattern": "^-?(?:0|[1-9]\\d*)$", "type": [ "null", "integer", "string" ], "description": "The larger of employees and directors: the headcount if the accounts count the directors\namong their employees, as some do.", "format": "int32" }, "at_most": { "pattern": "^-?(?:0|[1-9]\\d*)$", "type": [ "null", "integer", "string" ], "description": "Employees and directors together: the headcount if they do not. The truth lies between the\ntwo. Neither is used by the score, which reads the employees as filed.", "format": "int32" } }, "description": "How many people the company has, as far as the public record says: the employees its\nlatest accounts report, the directors in office, and a floor on the two together." }, "ProfileScore": { "required": [ "score", "band", "probability", "factors", "measures", "version" ], "type": "object", "properties": { "score": { "pattern": "^-?(?:0|[1-9]\\d*)$", "type": [ "null", "integer", "string" ], "description": "Null when not rated: a company that has already failed, or one the score cannot judge --\nwith no recent machine-readable accounts, or no officers held. The one factor says which.", "format": "int32" }, "band": { "type": "string", "description": "A to E, or not_rated." }, "probability": { "pattern": "^-?(?:0|[1-9]\\d*)(?:\\.\\d+)?$", "type": [ "null", "number", "string" ], "description": "Of formal insolvency within 12 months; null when not rated.", "format": "double" }, "factors": { "type": "array", "items": { "$ref": "#/components/schemas/ProfileScoreFactor" }, "description": "What moved the score, largest effect first." }, "measures": { "type": "string", "description": "What the score measures, in words, to be shown with it." }, "version": { "type": "string", "description": "The weights it was made with." } }, "description": "The company's score: 1 to 100, higher safer, in bands A (80 to 100) to E (1 to 19), with the\nprobability it stands for and the findings behind it." }, "ProfileScoreFactor": { "required": [ "code", "effect", "log_odds", "description" ], "type": "object", "properties": { "code": { "type": "string" }, "effect": { "type": "string", "description": "raises_risk or lowers_risk; for a company not rated, the reason, as none." }, "log_odds": { "pattern": "^-?(?:0|[1-9]\\d*)(?:\\.\\d+)?$", "type": [ "number", "string" ], "description": "What it added to the log-odds of failure.", "format": "double" }, "description": { "type": "string" } } }, "ProfileWebsite": { "required": [ "domain", "verified", "logo_url", "theme_colour", "strapline", "contact_email", "contact_email_is_role", "contact_phone", "contact_phone_type" ], "type": "object", "properties": { "domain": { "type": "string" }, "verified": { "type": "boolean", "description": "True when the site is proved to be this company's own; false for its group's, shown where\nit has none of its own." }, "logo_url": { "type": [ "null", "string" ] }, "theme_colour": { "type": [ "null", "string" ] }, "strapline": { "type": [ "null", "string" ] }, "contact_email": { "type": [ "null", "string" ] }, "contact_email_is_role": { "type": [ "null", "boolean" ] }, "contact_phone": { "type": [ "null", "string" ] }, "contact_phone_type": { "type": [ "null", "string" ] }, "confidence": { "pattern": "^-?(?:0|[1-9]\\d*)$", "type": [ "null", "integer", "string" ], "description": "How the site was proved: 100 for the registered number on it, 80 for the registered\naddress, 60 for the exact registered name on a domain guessed from it. For a group's site,\nhow that company's was proved.", "format": "int16" }, "method": { "type": [ "null", "string" ], "description": "company-number, registered-address or registered-name." }, "source": { "type": "string", "description": "\"own\", or \"group\" for the site of the company in ProfileWebsiteGroup? ProfileWebsite.Group.", "default": "own" }, "group": { "oneOf": [ { "type": "null" }, { "description": "For a group's site, whose it is and how that company is related.", "$ref": "#/components/schemas/ProfileWebsiteGroup" } ] } } }, "ProfileWebsiteGroup": { "required": [ "company_registration", "name", "relation" ], "type": "object", "properties": { "company_registration": { "type": "string" }, "name": { "type": [ "null", "string" ] }, "relation": { "type": "string", "description": "\"parent\" -- it owns this company -- or \"subsidiary\" -- this company owns it." } } }, "PscAddress": { "required": [ "premises", "address_line1", "address_line2", "locality", "region", "postal_code", "country" ], "type": "object", "properties": { "premises": { "type": [ "null", "string" ] }, "address_line1": { "type": [ "null", "string" ] }, "address_line2": { "type": [ "null", "string" ] }, "locality": { "type": [ "null", "string" ] }, "region": { "type": [ "null", "string" ] }, "postal_code": { "type": [ "null", "string" ] }, "country": { "type": [ "null", "string" ] } } }, "PscBand": { "required": [ "min", "max" ], "type": "object", "properties": { "min": { "pattern": "^-?(?:0|[1-9]\\d*)$", "type": [ "integer", "string" ], "format": "int32" }, "max": { "pattern": "^-?(?:0|[1-9]\\d*)$", "type": [ "integer", "string" ], "format": "int32" } }, "description": "A band of ownership or voting, as the register publishes it: never exact." }, "PscBirth": { "required": [ "year", "month" ], "type": "object", "properties": { "year": { "pattern": "^-?(?:0|[1-9]\\d*)$", "type": [ "integer", "string" ], "format": "int32" }, "month": { "pattern": "^-?(?:0|[1-9]\\d*)$", "type": [ "null", "integer", "string" ], "format": "int32" } } }, "PscResponse": { "required": [ "id", "kind", "beneficial_owner", "name", "title", "forename", "middle_name", "surname", "nationality", "country_of_residence", "birth", "notified_on", "ceased_on", "ownership", "voting", "appoints_directors", "significant_influence", "natures_of_control", "registration_number", "legal_form", "country_registered", "address", "is_sanctioned" ], "type": "object", "properties": { "id": { "type": "string" }, "kind": { "type": "string", "description": "individual, corporate, legal-person or super-secure." }, "beneficial_owner": { "type": "boolean", "description": "Registered as the beneficial owner of an overseas entity rather than as a PSC of a UK company." }, "name": { "type": [ "null", "string" ] }, "title": { "type": [ "null", "string" ] }, "forename": { "type": [ "null", "string" ] }, "middle_name": { "type": [ "null", "string" ] }, "surname": { "type": [ "null", "string" ] }, "nationality": { "type": [ "null", "string" ] }, "country_of_residence": { "type": [ "null", "string" ] }, "birth": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/PscBirth" } ] }, "notified_on": { "type": [ "null", "string" ], "format": "date" }, "ceased_on": { "type": [ "null", "string" ], "format": "date" }, "ownership": { "oneOf": [ { "type": "null" }, { "description": "The band of shares held; null if control is not through shares.", "$ref": "#/components/schemas/PscBand" } ] }, "voting": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/PscBand" } ] }, "appoints_directors": { "type": "boolean" }, "significant_influence": { "type": "boolean" }, "natures_of_control": { "type": "array", "items": { "type": "string" }, "description": "Companies House's own terms, for anything the bands leave out." }, "registration_number": { "type": [ "null", "string" ], "description": "For a corporate owner, its own registration number -- a company whose owners can be looked\nup in turn." }, "legal_form": { "type": [ "null", "string" ] }, "country_registered": { "type": [ "null", "string" ] }, "address": { "$ref": "#/components/schemas/PscAddress" }, "is_sanctioned": { "type": "boolean" } }, "description": "A person with significant control of a company." }, "RadiusCompany": { "required": [ "company_registration", "name", "company_status", "status_code", "post_code", "admin_district", "admin_county", "distance_miles", "net_assets", "employees", "turnover", "period_end", "sic_codes", "domain", "logo_url", "theme_colour", "strapline" ], "type": "object", "properties": { "company_registration": { "type": "string" }, "name": { "type": [ "null", "string" ] }, "company_status": { "type": [ "null", "string" ] }, "status_code": { "pattern": "^-?(?:0|[1-9]\\d*)$", "type": [ "null", "integer", "string" ], "format": "int16" }, "post_code": { "type": "string" }, "admin_district": { "type": [ "null", "string" ] }, "admin_county": { "type": [ "null", "string" ] }, "distance_miles": { "pattern": "^-?(?:0|[1-9]\\d*)(?:\\.\\d+)?(?:[eE][+-]?\\d+)?$", "type": [ "number", "string" ], "format": "double" }, "net_assets": { "pattern": "^-?(?:0|[1-9]\\d*)(?:\\.\\d+)?$", "type": [ "null", "number", "string" ], "format": "double" }, "employees": { "pattern": "^-?(?:0|[1-9]\\d*)(?:\\.\\d+)?$", "type": [ "null", "number", "string" ], "format": "double" }, "turnover": { "pattern": "^-?(?:0|[1-9]\\d*)(?:\\.\\d+)?$", "type": [ "null", "number", "string" ], "format": "double" }, "period_end": { "type": [ "null", "string" ], "format": "date" }, "sic_codes": { "type": [ "null", "array" ], "items": { "type": "string" } }, "domain": { "type": [ "null", "string" ] }, "logo_url": { "type": [ "null", "string" ] }, "theme_colour": { "type": [ "null", "string" ] }, "strapline": { "type": [ "null", "string" ] }, "currency": { "type": [ "null", "string" ] }, "turnover_gbp": { "pattern": "^-?(?:0|[1-9]\\d*)(?:\\.\\d+)?$", "type": [ "null", "number", "string" ], "format": "double" }, "net_assets_gbp": { "pattern": "^-?(?:0|[1-9]\\d*)(?:\\.\\d+)?$", "type": [ "null", "number", "string" ], "format": "double" }, "currency_stated": { "type": "boolean", "default": false }, "currency_note": { "type": [ "null", "string" ] }, "website_confidence": { "pattern": "^-?(?:0|[1-9]\\d*)$", "type": [ "null", "integer", "string" ], "format": "int16" }, "website_source": { "type": [ "null", "string" ] }, "website_via": { "type": [ "null", "string" ] }, "website_relation": { "type": [ "null", "string" ] } }, "description": "A company inside the circle, as the listing returns it." }, "RadiusCompanyPage": { "required": [ "items", "total", "limit", "offset" ], "type": "object", "properties": { "items": { "type": "array", "items": { "$ref": "#/components/schemas/RadiusCompany" } }, "total": { "pattern": "^-?(?:0|[1-9]\\d*)$", "type": [ "integer", "string" ], "format": "int32" }, "limit": { "pattern": "^-?(?:0|[1-9]\\d*)$", "type": [ "integer", "string" ], "format": "int32" }, "offset": { "pattern": "^-?(?:0|[1-9]\\d*)$", "type": [ "integer", "string" ], "format": "int32" }, "total_capped": { "type": "boolean", "default": false }, "has_more": { "type": "boolean" } }, "description": "One page of the companies inside a circle, nearest first. Total is counted up to\nint RadiusSearchQueries.CountCap; beyond it TotalCapped is set and Total means\n\"at least this many\"." }, "RadiusPostcode": { "required": [ "post_code", "latitude", "longitude", "companies" ], "type": "object", "properties": { "post_code": { "type": "string" }, "latitude": { "pattern": "^-?(?:0|[1-9]\\d*)(?:\\.\\d+)?(?:[eE][+-]?\\d+)?$", "type": [ "number", "string" ], "format": "double" }, "longitude": { "pattern": "^-?(?:0|[1-9]\\d*)(?:\\.\\d+)?(?:[eE][+-]?\\d+)?$", "type": [ "number", "string" ], "format": "double" }, "companies": { "pattern": "^-?(?:0|[1-9]\\d*)$", "type": [ "integer", "string" ], "format": "int32" } }, "description": "A postcode inside the circle and how many matching companies are at it." }, "RadiusPostcodes": { "required": [ "latitude", "longitude", "radius_miles", "companies", "postcodes" ], "type": "object", "properties": { "latitude": { "pattern": "^-?(?:0|[1-9]\\d*)(?:\\.\\d+)?(?:[eE][+-]?\\d+)?$", "type": [ "number", "string" ], "format": "double" }, "longitude": { "pattern": "^-?(?:0|[1-9]\\d*)(?:\\.\\d+)?(?:[eE][+-]?\\d+)?$", "type": [ "number", "string" ], "format": "double" }, "radius_miles": { "pattern": "^-?(?:0|[1-9]\\d*)(?:\\.\\d+)?(?:[eE][+-]?\\d+)?$", "type": [ "number", "string" ], "format": "double" }, "companies": { "pattern": "^-?(?:0|[1-9]\\d*)$", "type": [ "integer", "string" ], "format": "int32" }, "postcodes": { "type": "array", "items": { "$ref": "#/components/schemas/RadiusPostcode" } } }, "description": "Every postcode in the circle with at least one matching company, for plotting: the pins\nand their counts." }, "RadiusRegistrations": { "required": [ "companies", "truncated", "company_registrations" ], "type": "object", "properties": { "companies": { "pattern": "^-?(?:0|[1-9]\\d*)$", "type": [ "integer", "string" ], "format": "int32" }, "truncated": { "type": "boolean" }, "company_registrations": { "type": "array", "items": { "type": "string" } } }, "description": "The registration numbers of every matching company, for a bulk import. Truncated at a\nceiling so one request cannot become an unbounded export; bool RadiusRegistrations.Truncated says so." }, "RunProgress": { "required": [ "id", "feed", "source_file", "total", "done", "failed", "started_at", "completed_at", "progress_at" ], "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "feed": { "type": "string" }, "source_file": { "type": "string" }, "total": { "pattern": "^-?(?:0|[1-9]\\d*)$", "type": [ "integer", "string" ], "format": "int32" }, "done": { "pattern": "^-?(?:0|[1-9]\\d*)$", "type": [ "integer", "string" ], "format": "int32" }, "failed": { "pattern": "^-?(?:0|[1-9]\\d*)$", "type": [ "integer", "string" ], "format": "int32" }, "started_at": { "type": "string", "format": "date-time" }, "completed_at": { "type": [ "null", "string" ], "format": "date-time" }, "progress_at": { "type": [ "null", "string" ], "format": "date-time" }, "native": { "pattern": "^-?(?:0|[1-9]\\d*)$", "type": [ "null", "integer", "string" ], "format": "int32" }, "fallback": { "pattern": "^-?(?:0|[1-9]\\d*)$", "type": [ "null", "integer", "string" ], "format": "int32" }, "fallback_reasons": { "type": [ "null", "string" ] }, "is_running": { "type": "boolean", "description": "True only while the run is both unfinished and still reporting. Without the heartbeat\na killed import claims to be running forever, because a dead process and a busy one\nleave completed_at null alike." }, "is_stalled": { "type": "boolean", "description": "Unfinished, but no longer reporting." }, "percent_complete": { "pattern": "^-?(?:0|[1-9]\\d*)(?:\\.\\d+)?(?:[eE][+-]?\\d+)?$", "type": [ "number", "string" ], "format": "double" }, "elapsed": { "pattern": "^-?(\\d+\\.)?\\d{2}:\\d{2}:\\d{2}(\\.\\d{1,7})?$", "type": "string" }, "documents_per_second": { "pattern": "^-?(?:0|[1-9]\\d*)(?:\\.\\d+)?(?:[eE][+-]?\\d+)?$", "type": [ "number", "string" ], "format": "double" }, "remaining": { "pattern": "^-?(\\d+\\.)?\\d{2}:\\d{2}:\\d{2}(\\.\\d{1,7})?$", "type": [ "null", "string" ], "description": "Time left at the rate so far, or null when there is nothing to extrapolate from." } }, "description": "One ingest run, finished or in flight." }, "WatchRequest": { "required": [ "companies" ], "type": "object", "properties": { "companies": { "type": "array", "items": { "type": "string" } } } }, "WatchResult": { "required": [ "watched", "unknown" ], "type": "object", "properties": { "watched": { "pattern": "^-?(?:0|[1-9]\\d*)$", "type": [ "integer", "string" ], "description": "Companies now watched from those given, including any already watched.", "format": "int32" }, "unknown": { "type": "array", "items": { "type": "string" }, "description": "Numbers given that are not held, and so are not watched." } } }, "WatchedCompany": { "required": [ "company_registration", "name", "watched_since" ], "type": "object", "properties": { "company_registration": { "type": "string" }, "name": { "type": [ "null", "string" ] }, "watched_since": { "type": "string", "format": "date-time" } } }, "WatchlistPage": { "required": [ "items", "total", "limit", "offset" ], "type": "object", "properties": { "items": { "type": "array", "items": { "$ref": "#/components/schemas/WatchedCompany" } }, "total": { "pattern": "^-?(?:0|[1-9]\\d*)$", "type": [ "integer", "string" ], "format": "int32" }, "limit": { "pattern": "^-?(?:0|[1-9]\\d*)$", "type": [ "integer", "string" ], "format": "int32" }, "offset": { "pattern": "^-?(?:0|[1-9]\\d*)$", "type": [ "integer", "string" ], "format": "int32" } } }, "WebhookDeliveryRecord": { "required": [ "event_id", "event_type", "company_registration", "occurred_at", "attempts", "delivered_at", "abandoned_at", "next_attempt_at", "last_status", "last_error" ], "type": "object", "properties": { "event_id": { "pattern": "^-?(?:0|[1-9]\\d*)$", "type": [ "integer", "string" ], "format": "int64" }, "event_type": { "type": "string" }, "company_registration": { "type": "string" }, "occurred_at": { "type": "string", "format": "date-time" }, "attempts": { "pattern": "^-?(?:0|[1-9]\\d*)$", "type": [ "integer", "string" ], "format": "int16" }, "delivered_at": { "type": [ "null", "string" ], "format": "date-time" }, "abandoned_at": { "type": [ "null", "string" ], "format": "date-time" }, "next_attempt_at": { "type": "string", "format": "date-time" }, "last_status": { "pattern": "^-?(?:0|[1-9]\\d*)$", "type": [ "null", "integer", "string" ], "format": "int16" }, "last_error": { "type": [ "null", "string" ] } } }, "WebhookSubscription": { "required": [ "id", "url", "event_types", "created_at", "disabled_at" ], "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "url": { "type": "string" }, "event_types": { "type": "array", "items": { "type": "string" } }, "created_at": { "type": "string", "format": "date-time" }, "disabled_at": { "type": [ "null", "string" ], "format": "date-time" } } } }, "securitySchemes": { "ApiKey": { "type": "apiKey", "description": "Issued per caller. Carries a daily and a monthly quota; every response reports what has been spent in the X-RateLimit-* headers.", "name": "X-Api-Key", "in": "header" } } }, "tags": [ { "name": "Company brand" }, { "name": "Company" }, { "name": "Company filings" }, { "name": "Company ownership" }, { "name": "Health" }, { "name": "Match" }, { "name": "Progress" }, { "name": "Search" }, { "name": "Monitoring" } ] }