# CompanyLens — Full Documentation

CompanyLens is a company registry intelligence platform providing structured, normalised access to company and director data across 18 jurisdictions via a unified REST API and an MCP (Model Context Protocol) server for AI tools.

Website: https://companylens.io
API: https://api.companylens.io
MCP: https://mcp.companylens.io/mcp
Docs: https://companylens.io/docs

---

## Platform Overview

CompanyLens aggregates and normalises data from official government company registries (not scraped, not resold). Every jurisdiction returns the same JSON schema, so you write integration code once and it works for all 18 countries.

Key facts:
- 29M+ company records across 18 jurisdictions
- 45M+ officers and directors with appointment history
- 11M+ beneficial owners (PSC / UBO data)
- Daily updates from source registries
- Sub-100ms REST API response times
- 99.9% uptime SLA
- OpenAPI 3.1 specification available at /docs/swagger

---

## Products

### 1. REST API

For developers building integrations, compliance tools, KYB workflows, and corporate intelligence applications.

- Unified JSON schema across all jurisdictions
- Bearer token authentication
- Monthly query quota, no per-country billing
- Full OpenAPI 3.1 spec with interactive Swagger playground
- Pagination: page and pageSize parameters (default 20, max 100)

### 2. MCP Server (Model Context Protocol)

For AI tools: Claude Desktop, Cursor, Windsurf, and any MCP-compatible client.

- No code required — add the MCP URL to your AI tool config
- Query in natural language; the AI calls CompanyLens as a tool
- OAuth 2.0 authentication (one-click login)
- Daily query quota (resets at midnight UTC, independent from REST API)
- Available tools: search_entities, get_entity_detail, search_officers, execute_query

Configuration:
```json
{
  "mcpServers": {
    "companylens": {
      "url": "https://mcp.companylens.io/mcp"
    }
  }
}
```

Add this to:
- Claude Desktop: ~/Library/Application Support/Claude/claude_desktop_config.json
- Cursor: Settings > MCP > Add server
- Windsurf: Settings > MCP Servers

### 3. Agent & Automation

REST API plans with full data depth from day one — including beneficial ownership, charges, and disqualifications — designed for unattended pipelines and AI agents that cannot be interrupted to upgrade mid-project.

---

## REST API Reference

Base URL: https://api.companylens.io
Authentication: Authorization: Bearer cl_live_your_api_key

### Company Search

GET /api/v1/companies/search
Query parameters:
- q (string, required): Company name to search
- jurisdiction (string): ISO 3166-1 alpha-2 code (e.g. "GB", "IE", "NO")
- status (string): Filter by status ("active", "dissolved", etc.)
- page (int, default 1)
- pageSize (int, default 20, max 100)

Returns: Array of company summaries with entity_id, entity_name, jurisdiction, source_id, status, incorporation_date, registered_address.

### Company Autocomplete

GET /api/v1/companies/autocomplete
Fast prefix-match typeahead with trigram fallback for short queries.
Query parameters: q, jurisdiction, page, pageSize

### Company Profile

GET /api/v1/companies/{id}
{id} format: {isoCode}/{registryNumber} — e.g. GB/12345678

Returns full profile:
- entity_id, entity_name, entity_type (normalised)
- jurisdiction, source_id, status
- incorporation_date, dissolution_date
- registered_address, industry_codes (SIC/NACE), industry_descriptions
- officers[] (name, role, is_active, appointed_date, resigned_date)
- beneficial_owners[] (UK PSC / Latvia UBO)
- charges[] (registration_date, classification, status)

### Officers (by company)

GET /api/v1/companies/{id}/officers
Returns paginated list of officers:
- officer_id, officer_name, role, is_active
- appointed_date, resigned_date

### Beneficial Owners (by company)

GET /api/v1/companies/{id}/beneficial-owners
Returns paginated PSC / UBO list:
- owner_name, owner_type (individual, corporate, legal)
- share_min, share_max (percentage held)
- natures_of_control
- notified_date, ceased_date

### Company Network

GET /api/v1/companies/{id}/network
Returns companies connected via shared officers or beneficial owners.
Useful for mapping corporate groups and subsidiary structures.

### Charges (by company)

GET /api/v1/companies/{id}/charges
Registered charges and mortgages (UK only currently):
- charge_id, charge_code, classification, status
- registration_date, satisfied_date
- chargees (array of names)

### Filings (by company)

GET /api/v1/companies/{id}/filings
Paginated filing history (UK only currently). Each entry is one event filed at Companies House:
- source_id (Companies House transaction id, stable across requests)
- filing_type (slug, e.g. "annual-accounts", "confirmation-statement", "change-of-name", "change-of-registered-office", "dissolution")
- filing_date (date the filing was received)
- description (human-readable, with relevant dates interpolated)
- document_url (link to the public Companies House filing page)
Query parameters: cursor (pagination), limit (max 100)

### Companies by Address

GET /api/v1/companies/by-address
Find companies registered at a given address (fuzzy matched).
Query parameters: address (string, required), jurisdiction (string, optional), page, pageSize
Returns: Array of matching companies with the same schema as company search.

### People Search — Unified

GET /api/v1/people/search
Search across officers, beneficial owners, and disqualified directors simultaneously.
Query parameters: q (name), jurisdiction, page, pageSize

### People Search — Type-specific

GET /api/v1/people/officers/search
GET /api/v1/people/beneficial-owners/search
GET /api/v1/people/disqualified-directors/search
Query parameters: q (name), jurisdiction (optional), page, pageSize

### Person Profile (officer or beneficial owner)

GET /api/v1/people/{jurisdiction}/{id}
Full officer or beneficial owner profile. {id} can be the stable internal UUID (preferred)
or a registry source ID (emits Deprecation header).
- person (name, sourceId, id, nationality, countryOfResidence)
- types[] ("officer" and/or "beneficial_owner")
- officerRoles[] if officer
- companyLinks[] if beneficial owner

### Disqualified Director

GET /api/v1/people/disqualified-directors/{jurisdiction}/{personId}
Disqualification record including type, start/end dates, company involved.

---

## MCP Tools Reference

### search_entities
Search for companies across jurisdictions.
Parameters: query (string), jurisdiction (string, optional), status (string, optional)
Returns: List of matching companies with profiles.

### get_entity_detail
Fetch full company profile including officers and beneficial owners.
Parameters: entity_id (string, format: {isoCode}/{registryNumber})
Returns: Full company data object.

### search_officers
Find directors and officers by name, optionally filtered by jurisdiction.
Parameters: name (string), jurisdiction (string, optional)
Returns: List of matching officers with appointment summaries.

### execute_query
Run a read-only natural language query against the unified schema.
Parameters: query (string)
Use for: relationship mapping, multi-company analysis, custom filters.

---

## Jurisdictions

All jurisdictions return the same unified JSON schema. Entity counts are approximate and updated regularly.

| Jurisdiction | ISO | Registry | Entities | Officer data | Beneficial ownership |
|---|---|---|---|---|---|
| United Kingdom | GB | Companies House | 7.3M+ | Yes | Yes (PSC) |
| Ireland | IE | CRO | 815K+ | Yes | No |
| Norway | NO | Brønnøysund | 2M+ | Yes | No |
| Estonia | EE | E-Business Register | 373K+ | Yes | Yes |
| Latvia | LV | Enterprise Register | 484K+ | Yes | Yes (UBO) |
| Czech Republic | CZ | ARES | 1.2M+ | Yes | No |
| Belgium | BE | KBO/BCE | 1.9M+ | Yes | No |
| Slovenia | SI | AJPES | 293K+ | No | No |
| Switzerland | CH | Zefix | 784K+ | No | No |
| Cyprus | CY | DRCOR | 487K+ | No | No |
| Moldova | MD | ASP | 281K+ | No | No |
| Ukraine | UA | Unified State Register | 1.9M+ | Yes | Yes |
| Chile | CL | RES | 1.5M+ | No | No |
| Argentina | AR | IGJ | 1M+ | No | No |
| Canada (Federal) | CA | Corporations Canada | 1.5M+ | No | No |
| Canada (Québec) | QC | Registraire | 2.6M+ | No | No |
| New Zealand | NZ | Companies Office | 1.8M+ | Yes | No |
| Slovakia | SK | RPO2 | 2.1M+ | Yes | No |

---

## Pricing

### REST API Plans

Free: £0/month
- 500 queries/month
- 50 queries/day hard limit
- Entity profiles (name, number, status, address, incorporation date)
- Search and autocomplete

Starter: £39/month (£31/month annual)
- 5,000 queries/month
- No daily cap
- Entity profiles + search
- Officers and directors (current and historical)

Pro: £99/month (£79/month annual)
- 25,000 queries/month
- No daily cap
- All Starter features
- Beneficial ownership (UK PSC, Latvia UBO)
- UK charges and mortgages
- Director disqualifications (UK)

Business: £299/month (£239/month annual)
- 100,000 queries/month
- No daily cap
- All Pro features
- Priority support

### MCP Plans

Free (Trial): £0
- 50 MCP queries/month
- All jurisdictions
- Entity profiles, officers, directors, network analysis, search

Pro: £20/month (£16/month annual)
- 200 MCP queries/day
- All jurisdictions
- Full data depth: officers, beneficial owners
- Commercial use permitted

Team: £18/seat/month (£15/seat/month annual, minimum 3 seats)
- 200 MCP queries/day per seat
- Team dashboard
- Commercial use permitted

### Agent & Automation Plans

Agent Starter: £49/month (£39/month annual)
- 1 service token for unattended pipelines
- 5,000 service-token calls/month
- 5,000 OAuth MCP calls/month (independent quota)
- All jurisdictions and data endpoints
- Commercial and production use

Agent Pro: £149/month (£119/month annual)
- 5 service tokens
- 25,000 service-token calls/month
- 25,000 OAuth MCP calls/month (independent quota)
- All jurisdictions and data endpoints
- Commercial and production use

Service tokens allow automated agents and CI/CD pipelines to connect to MCP
without an OAuth browser flow. Service-token and OAuth call quotas are
tracked independently and both reset at the start of each billing period.

### Billing notes
- Annual billing saves ~20% across all paid plans
- MCP, REST API, and Agent plans are independent — subscribe to any combination
- No credit card required for free tiers
- Upgrades take effect immediately (prorated charge)
- Downgrades apply at next billing cycle
- No per-country billing, no seat restrictions on API plans

---

## Common use cases

### Due diligence and KYB (Know Your Business)
- Verify a company exists and is active before onboarding
- Check director identity and appointment history
- Screen for disqualified directors
- Map beneficial ownership chains (PSC / UBO)
- Retrieve charges and other registered interests

### Corporate intelligence
- Discover connected companies via shared directors
- Map director networks across jurisdictions
- Identify subsidiary and group structures
- Track changes to officer appointments

### AI agent workflows (MCP)
- Ask Claude: "Who are the directors of Acme Ltd and are any disqualified?"
- Ask Claude: "Find all companies connected to this director across Europe"
- Use in Cursor or Windsurf for automated KYB pipelines
- Pre-fill due diligence reports from natural language queries

### Autocomplete / company name search
- Power company name lookup in onboarding flows
- Real-time search-as-you-type for forms
- Validate user-entered company names

---

## Authentication

### REST API
Include your API key as a Bearer token:
Authorization: Bearer cl_live_your_api_key

Get your API key at: https://companylens.io/dashboard

### MCP Server
OAuth 2.0 — when you first connect your AI tool to the MCP server, you will be redirected to a one-click login at companylens.io. No manual token handling required.

---

## Rate limits and quotas

- REST API quota: resets monthly on your billing date
- MCP quota: resets daily at midnight UTC
- Both quotas are tracked independently
- One REST API call = one REST query (regardless of data depth)
- One MCP tool call = one MCP query
- Autocomplete calls count against the REST API quota
- Free tier REST: 500/month and 50/day hard limit
- Free tier MCP: 50/day

---

## Data quality and sourcing

- All data sourced directly from official government registries
- No scraping, no third-party resellers
- Open data licences (Companies House, INPI, Brønnøysund, etc.)
- Typically updated within 24 hours of registry updates at source
- Entity names and addresses normalised to UTF-8
- Entity types normalised (e.g. UK "Private limited company" = IE "Private company limited by shares" = NO "AS")
- Cross-jurisdiction linking: directors appear in results from all jurisdictions where they are appointed

---

## FAQ

Q: What counts as one query?
A: Each REST API call (including autocomplete) is one REST query. Each MCP tool call is one MCP query. The two quotas are independent.

Q: Do all plans include every jurisdiction?
A: Entity profiles and search are available across all jurisdictions on every plan. Officer data is available where source registries provide it (UK, Ireland, Norway, Latvia, Czech Republic, Estonia, New Zealand, Ukraine). Beneficial ownership is deepest for UK (PSC) and Latvia (UBO).

Q: What is the MCP server?
A: The MCP (Model Context Protocol) server lets AI tools like Claude and Cursor query company data as a tool call — you ask a question in natural language, the AI calls CompanyLens, and returns structured results. No code required. The REST API is for developers integrating into applications.

Q: Can I subscribe to more than one plan track?
A: Yes. MCP, REST API, and Agent plans are independent. A common combination is REST API Starter plus MCP Pro for research using Claude or Cursor.

Q: Why do Agent plans cost more than REST API plans for the same query count?
A: Agent plans include all data endpoints (beneficial ownership, charges, disqualifications) from day one. On REST API plans these unlock at Pro tier (£149/mo). Agent plans are designed for automated pipelines that need full data depth without interruption.

Q: Is there a free trial?
A: Yes — both the REST API Free tier (500 queries/month) and MCP Free tier (50 queries/day) are permanently free with no credit card required.

Q: Can I upgrade or downgrade at any time?
A: Yes. Upgrades take effect immediately with a prorated charge. Downgrades apply at the next billing cycle.

---

## Browseable page URLs

Company profile: https://companylens.io/companies/{jurisdiction}/{companyNumber}/{name-slug}
Example: https://companylens.io/companies/gb/12345678/acme-ltd

Person profile: https://companylens.io/people/{name-slug}
Shows all officer appointments, beneficial ownership positions, and any disqualifications.
Example: https://companylens.io/people/john-smith

Address page: https://companylens.io/addresses/{jurisdiction}/{address-slug}
Shows all companies registered at a given address.

Company search: https://companylens.io/search?q={query}
People search: https://companylens.io/search/people?q={query}

---

## Contact and support

Website: https://companylens.io
Email: hello@companylens.io
Documentation: https://companylens.io/docs
API status: https://companylens.io/status
Interactive API explorer: https://api.companylens.io/docs/swagger