Data model
The CompanyLens unified schema normalises data from every supported registry into a consistent data model. This is the core product — the reason a single API call returns UK and French companies in the same format.
Core tables
entities
Companies and legal persons from all jurisdictions.
| Column | Type | Description |
|---|---|---|
| entity_id | bigint | Primary key |
| source_registry | varchar(50) | e.g. 'companies_house', 'inpi', 'usr' |
| source_id | varchar(100) | Registry-specific ID (company number, CIK) |
| entity_name | varchar(500) | Company name |
| entity_name_normalised | varchar(500) | Lowercase, trimmed — for search |
| entity_type | varchar(100) | Normalised: 'private_limited', 'public_limited', etc. |
| jurisdiction | varchar(10) | ISO 3166: 'GB', 'IE', 'US', 'DK', 'EE', etc. |
| status | varchar(50) | Normalised: 'active', 'dissolved', 'liquidation' |
| incorporation_date | date | Date of incorporation |
| dissolution_date | date | Date of dissolution (if applicable) |
| registered_address | varchar(1000) | Registered office address |
| industry_codes | varchar(500) | SIC/NACE codes |
| ticker | varchar(20) | Stock ticker (SEC companies) |
officers
Directors, secretaries, and board members.
| Column | Type | Description |
|---|---|---|
| officer_id | bigint | Primary key |
| entity_id | bigint | FK to entities |
| officer_name | varchar(500) | Full name |
| officer_name_normalised | varchar(500) | Normalised for cross-jurisdiction matching |
| role | varchar(100) | Normalised: 'director', 'secretary', 'board_member' |
| appointed_date | date | Date appointed |
| resigned_date | date | Date resigned (if applicable) |
| is_active | bit | Currently serving |
| nationality | varchar(100) | Nationality |
| country_of_residence | varchar(10) | ISO country code |
financial_statements
Parsed financial data extracted from iXBRL accounts submitted to Companies House. UK coverage from 2021.
| Column | Type | Description |
|---|---|---|
| statement_id | bigint | Primary key |
| entity_id | bigint | FK to entities |
| period_start | date | Reporting period start (null for instant-context facts) |
| period_end | date | Reporting period end |
| metric_name | varchar(200) | Raw XBRL concept name |
| metric_name_normalised | varchar(200) | Normalised: revenue, gross_profit, net_profit, fixed_assets, etc. |
| value | decimal(28,4) | Metric value |
| currency | varchar(3) | Currency code (e.g. GBP) |
beneficial_owners
Persons with Significant Control (PSC) and beneficial ownership data.
| Column | Type | Description |
|---|---|---|
| owner_id | bigint | Primary key |
| entity_id | bigint | FK to entities |
| owner_name | varchar(500) | Owner name |
| owner_type | varchar(50) | 'individual', 'corporate', 'government', 'trust' |
| shares_percentage_min | decimal(5,2) | Minimum shareholding % |
| shares_percentage_max | decimal(5,2) | Maximum shareholding % |
| is_active | bit | Currently active |