openapi: 3.0.3 info: title: DataLedger API description: | Enriched UK company financial data API built on top of Companies House filings. 🔐 All requests must include your API key in the `x-api-key` header. Example: x-api-key: YOUR_API_KEY_HERE version: 1.0.0 servers: - url: https://api.dataledger.uk/v1 security: - ApiKeyAuth: [] paths: /companies/autocomplete: get: tags: - Beta summary: Return a short list of companies based on partial name match description: | This endpoint returns a list of companies whose names partially match the provided query string. parameters: - in: query name: name required: true schema: type: string description: Partial company name (min 3 characters) - in: query name: limit schema: type: integer default: 10 maximum: 50 description: Number of results to return responses: '200': description: List of matching companies content: application/json: schema: type: array items: type: object properties: companyNumber: type: string description: Unique company number issued by Companies House companyName: type: string description: Registered name of the company '400': $ref: '#/components/responses/BadRequest' '403': $ref: '#/components/responses/Forbidden' '404': $ref: '#/components/responses/NotFound' '500': $ref: '#/components/responses/InternalServerError' '502': $ref: '#/components/responses/BadGateway' /companies/search: get: tags: - Beta summary: Search for companies using filters (non-financial + financial filters). A maximum of 5 filters can be applied at once. description: | This endpoint allows you to search for companies based on various filters. You can combine multiple filters to narrow down your search results. The maximum number of filters that can be applied at once is 5. If the meta parameter is set to true, the response will include the total count of records matching the query instead of the actual records. The filters include company status, incorporation date, name, SIC code, postcode, local authority, and financial metrics such as equity, total assets, total liabilities, and employee count. The results can be paginated using the limit and offset parameters. parameters: - in: query name: meta schema: type: boolean default: false description: | If true, the API will **not return full company result objects**. Instead, it will return only the total count of companies matching the current filters. This is useful for: - estimating result size before making a full query - implementing pagination efficiently - generating analytics dashboards - in: query name: limit schema: type: integer default: 20 maximum: 50 description: Number of results to return (maximum 50) - in: query name: offset schema: type: integer default: 0 description: Number of records to skip for pagination - in: query name: name schema: type: string description: Partial match on company name - in: query name: sic schema: type: number description: SIC code (5 digits) - in: query name: postcode schema: type: string description: Filter by postcode prefix - in: query name: localAuthority schema: type: string description: Filter by local authority name - in: query name: isActive schema: type: boolean description: Active or Active - Proposal to Strike off = True. Any other status such as In Administration, Liquidation = False - in: query name: incorporationDateFrom schema: type: string format: date description: Filter for companies incorporated on or after this date - in: query name: incorporationDateTo schema: type: string format: date description: Filter for companies incorporated on or before this date - in: query name: minEquity schema: type: number description: Minimum equity threshold - in: query name: maxEquity schema: type: number description: Maximum equity threshold - in: query name: minTotalAssets schema: type: number description: Minimum total assets threshold - in: query name: maxTotalAssets schema: type: number description: Maximum total assets threshold - in: query name: minTotalLiabilities schema: type: number description: Minimum total liabilities threshold - in: query name: maxTotalLiabilities schema: type: number description: Maximum total liabilities threshold - in: query name: minEmployees schema: type: number description: Minimum employee count - in: query name: maxEmployees schema: type: number description: Maximum employee count responses: '200': description: List of companies or metadata summary depending on `meta` flag content: application/json: schema: oneOf: - type: object properties: totalCount: type: integer limit: type: integer offset: type: integer results: type: array items: type: object properties: companyNumber: type: string companyName: type: string isActive: type: boolean incorporationDate: type: string format: date balanceSheetDate: type: string format: date sicCodes: type: array items: type: string registeredAddress: type: object properties: address: type: string postcode: type: string localAuthority: type: string - type: object properties: meta: type: object properties: filter: type: object additionalProperties: true totalCount: type: string examples: default: summary: Default search response value: totalCount: 2 limit: 20 offset: 0 results: - companyNumber: "12345678" companyName: "Example Ltd" isActive: true incorporationDate: "2015-01-01" balanceSheetDate: "2023-12-31" sicCodes: ["62020"] registeredAddress: address: "123 Example St" postcode: "AB1 2CD" localAuthority: "Example Borough" meta: summary: Meta response when meta=true value: meta: filter: localAuthority: "example" totalCount: "4573" '204': description: No companies match the query content: application/json: schema: type: array items: type: object properties: {} '400': $ref: '#/components/responses/BadRequest' '403': $ref: '#/components/responses/Forbidden' '404': $ref: '#/components/responses/NotFound' '500': $ref: '#/components/responses/InternalServerError' '502': $ref: '#/components/responses/BadGateway' /companies/{companyNumber}: get: tags: - Beta summary: Retrieve a company profile with headline financials and key ratios parameters: - in: path name: companyNumber required: true description: Unique company number issued by Companies House schema: type: string responses: '200': description: Enriched company profile content: application/json: schema: type: object properties: companyProfile: $ref: '#/components/schemas/CompanyProfile' '204': description: No companies match the query content: application/json: schema: type: object items: {} '400': $ref: '#/components/responses/BadRequest' '403': $ref: '#/components/responses/Forbidden' '404': $ref: '#/components/responses/NotFound' '500': $ref: '#/components/responses/InternalServerError' '502': $ref: '#/components/responses/BadGateway' components: securitySchemes: ApiKeyAuth: type: apiKey in: header name: x-api-key description: > Your unique API key. Required in the `x-api-key` header for every request. You can request a key at https://dataledger.uk/api-key responses: BadRequest: description: Bad request – usually a missing or invalid parameter content: application/json: schema: type: object properties: error: type: object properties: status: type: string description: Error type example: Bad request message: type: string description: Error message example: instance.sic does not meet maximum length of 5 Forbidden: description: Missing or invalid API key content: text/html: schema: type: string example: | 403 Forbidden

403 Forbidden

nginx/1.18.0 (Ubuntu) NotFound: description: The requested resource was not found content: text/html: schema: type: string example: | 404 Not Found

404 Not Found

nginx/1.18.0 (Ubuntu) InternalServerError: description: Server error – an unexpected problem occurred content: text/html: schema: type: string example: | 500 Internal Server Error

500 Internal Server Error

nginx/1.18.0 (Ubuntu) BadGateway: description: Bad Gateway – usually due to an upstream server error content: text/html: schema: type: string example: | 502 Bad Gateway

502 Bad Gateway

nginx/1.18.0 (Ubuntu) schemas: CompanyProfile: type: object properties: companyNumber: type: string description: Unique identifier assigned to a company by Companies House companyName: type: string description: Official registered name of the company isActive: type: boolean description: Indicates if the company is currently active on the register countryOfOrigin: type: string description: Country where the company was originally incorporated companyCategory: type: string description: Classification of the company (e.g., Private Limited, Public Limited) incorporationDate: type: string format: date description: Date the company was incorporated balanceSheetDate: type: string format: date description: End date of the latest balance sheet reported nameEntityOfficer: type: string description: Name of the person or officer representing the entity entityDormant: type: boolean description: Indicates if the company is dormant (not currently trading) nameProductionSoftware: type: string description: Name of the accounting or reporting software used by the company descriptionPrincipalActivities: type: string description: Description of the main business activities of the company startDateForPeriodCoveredByReport: type: string format: date description: Start date for the financial reporting period endDateForPeriodCoveredByReport: type: string format: date description: End date for the financial reporting period averageNumberEmployeesDuringPeriod: type: integer description: Average number of employees during the reporting period currentLegalOrRegisteredName: type: string description: Current legal or registered name of the company (if changed) accountsAccountCategory: type: string description: Category of accounts filed (e.g. total exemption full, micro entity) accountsLastMadeUpDate: type: string format: date description: Date to which the last set of accounts was made up accountsNextDueDate: type: string format: date description: Deadline for the next accounts to be filed confStmtLastMadeUpDate: type: string format: date description: Date the last confirmation statement was made up to confStmtNextDueDate: type: string format: date description: Deadline for the next confirmation statement employees: type: integer description: Total number of employees reported (if provided separately) uri: type: string description: URI for retrieving the full company profile or resource link registeredAddress: type: object description: The company’s official registered address properties: address: type: string description: Street-level address or building name/number postcode: type: string description: UK postcode of the registered office localAuthority: type: string description: Local authority responsible for the address jurisdiction industry: type: object description: Standard Industrial Classification (SIC) codes identifying the business activities of the company properties: sic1: type: integer description: Primary SIC code representing the main business activity sic2: type: integer description: Secondary SIC code, if applicable sic3: type: integer description: Tertiary SIC code, if applicable sic4: type: integer description: Quaternary SIC code, if applicable sic1Description: type: string description: Description of the primary SIC code sic2Description: type: string description: Description of the secondary SIC code sic3Description: type: string description: Description of the tertiary SIC code sic4Description: type: string description: Description of the quaternary SIC code financials: type: object description: Key financial figures from the most recent and previous year balance sheets and P&L statements properties: cEquity: type: number description: Current year total equity reported (net assets - liabilities) cTotalAssets: type: number description: Current year total assets cTotalCurrentAssets: type: number description: Current year current assets (e.g. cash, receivables) cTotalFixedAssets: type: number description: Current year fixed assets (e.g. property, plant) cTotalLiabilities: type: number description: Current year total liabilities pEquity: type: number description: Previous year total equity (net assets - liabilities) pTotalAssets: type: number description: Previous year total assets pTotalCurrentAssets: type: number description: Previous year current assets pTotalFixedAssets: type: number description: Previous year fixed assets pTotalLiabilities: type: number description: Previous year total liabilities cVerified: type: boolean description: Indicates whether the balance sheet figures were verified using our proprietary, accountant verified process pVerified: type: boolean description: Indicates whether the balance sheet figures were verified using our proprietary, accountant verified process cProfitLoss: type: number description: Current year profit and loss. Only companies that submitted a full set of accounts will have this field pProfitLoss: type: number description: Previous year profit and loss. Only companies that submitted a full set of accounts will have this field cTurnoverRevenue: type: number description: Current year turnover. Only companies that submitted a full set of accounts will have this field pTurnoverRevenue: type: number description: Previous year turnover. Only companies that submitted a full set of accounts will have this field cDebtToEquityRatio: type: number description: Current year ratio of total liabilities to shareholder equity pDebtToEquityRatio: type: number description: Previous year ratio of total liabilities to shareholder equity cDebtToAssetRatio: type: number description: Current year ratio of total liabilities to total assets pDebtToAssetRatio: type: number description: Previous year ratio of total liabilities to total assets assetsGrowthRate: type: number description: Year-on-year percentage change in total assets netAssetsGrowthRate: type: number description: Year-on-year percentage change in net assets (total assets minus total liabilities)