Company Analysis API

Overview

The Company Analysis API searches multiple official company registries and databases:

UK Companies House: UK company registrations, officers, and filings
GLEIF LEI: Global Legal Entity Identifier database
SEC EDGAR: US Securities and Exchange Commission filings

This endpoint uses Server-Sent Events (SSE) streaming to provide real-time results as each data source responds.

UK Companies House API requires COMPANIES_HOUSE_API_KEY environment variable.

Endpoint

POST /api/company/analyze

Request

Headers

Content-Type: application/json

Body Parameters

query

string

Company name or search query. Either query, companyNumber, or ticker is required.Example: "Apple Inc"

companyNumber

string

Specific company registration number (UK Companies House or CIK for SEC).Example: "00000789"

ticker

string

Stock ticker symbol (US companies only).Example: "AAPL"

country

string

Target country for registry search. Determines which data sources to query.Valid values: "US", "UK"Default: "US"

"UK": Searches Companies House and GLEIF
"US": Searches SEC EDGAR and GLEIF

Request Example

curl -X POST http://localhost:3000/api/company/analyze \
  -H "Content-Type: application/json" \
  -d '{
    "query": "Apple Inc",
    "ticker": "AAPL",
    "country": "US"
  }'

Response

The endpoint returns a Server-Sent Events (SSE) stream with Content-Type: text/event-stream.

Event Types

progress

object

Progress update during search

Show properties

type

string

Always "progress"

data.step

string

Current step (e.g., “Searching UK Companies House”)

data.source

string

Data source: "companiesHouse", "gleif", or "secEdgar"

data.total

number

Total steps

data.completed

number

Completed steps

result

object

Partial result from a data source

Show properties

type

string

Always "result"

data.source

string

Source of this result

data.result

object

Partial results from one data source

data.completed

number

Steps completed

data.total

number

Total steps

complete

object

Final complete result with all data sources

Show properties

type

string

Always "complete"

data.result

CompanyAnalysisResult

See complete result structure below

error

object

Error event

Show properties

type

string

Always "error"

data.message

string

Error message

Complete Result Structure

CompanyAnalysisResult

object

Show properties

query

string

The search query used

analyzedAt

string

ISO 8601 timestamp

UK Companies House

companiesHouse

object

UK company registry data (only for country: “UK”)

Show properties

searchResults

array

Search results matching the queryEach result:

{
  company_number: string,
  title: string,
  company_status: string,
  company_type: string,
  date_of_creation?: string,
  address_snippet?: string
}

company

CompaniesHouseCompany

Full company details (first match)

Show CompaniesHouseCompany properties

company_number

string

UK company number

company_name

string

Official company name

company_status

string

Status (“active”, “dissolved”, etc.)

company_type

string

Type (“ltd”, “plc”, etc.)

date_of_creation

string

Incorporation date

registered_office_address

object

Registered address

sic_codes

string[]

Standard Industrial Classification codes

accounts

object

Accounting information and deadlines

has_charges

boolean

Whether company has charges registered

has_insolvency_history

boolean

Insolvency history flag

officers

CompaniesHouseOfficer[]

Company officers (directors, secretaries)Each officer:

{
  name: string,
  officer_role: string,
  appointed_on?: string,
  resigned_on?: string,
  nationality?: string,
  country_of_residence?: string,
  occupation?: string,
  date_of_birth?: { month: number, year: number }
}

filings

CompaniesHouseFiling[]

Recent company filingsEach filing:

{
  category: string,
  date: string,
  description: string,
  type: string
}

GLEIF LEI Database

gleif

object

Global Legal Entity Identifier data (always included)

Show properties

records

GleifLeiRecord[]

LEI records matching the queryEach record:

{
  lei: string,  // Legal Entity Identifier
  entity: {
    legalName: { name: string, language?: string },
    legalAddress: {
      addressLines: string[],
      city: string,
      country: string,
      postalCode?: string
    },
    jurisdiction?: string,
    category?: string,
    status: string
  },
  registration: {
    initialRegistrationDate: string,
    lastUpdateDate: string,
    status: string,
    managingLou: string
  }
}

totalCount

number

Total matching records

SEC EDGAR

secEdgar

object

US SEC filings data (only for country: “US”)

Show properties

searchResults

array

Search resultsEach result:

{
  cik: string,       // Central Index Key
  name: string,
  tickers?: string[]
}

company

SecEdgarCompany

Full company details

Show SecEdgarCompany properties

cik

string

Central Index Key

name

string

Company name

tickers

string[]

Stock ticker symbols

exchanges

string[]

Stock exchanges

sic

string

Standard Industrial Classification

sicDescription

string

Industry description

fiscalYearEnd

string

Fiscal year end (MMDD format)

stateOfIncorporation

string

State code

businessAddress

object

Business address

phone

string

Phone number

website

string

Company website

recentFilings

SecEdgarFiling[]

Recent SEC filingsEach filing:

{
  accessionNumber: string,
  filingDate: string,
  reportDate?: string,
  form: string,  // e.g., "10-K", "8-K", "10-Q"
  primaryDocument?: string,
  items?: string,
  size?: number
}

Errors

errors

object

Errors from individual data sources (omitted if no errors)

{
  companiesHouse?: string,
  gleif?: string,
  secEdgar?: string
}

Response Example

{
  "type": "progress",
  "data": {
    "step": "Searching SEC EDGAR",
    "source": "secEdgar",
    "total": 2,
    "completed": 1
  }
}

Error Responses

400

Required parameter missing

{
  "success": false,
  "error": "Company name, number, or ticker is required"
}

500

Request failed

{
  "success": false,
  "error": "Request failed"
}

Configuration

For UK Companies House access:

# Optional: UK Companies House API key
COMPANIES_HOUSE_API_KEY=your_companies_house_key

Get a Companies House API key at https://developer.company-information.service.gov.uk/

Source Code Reference

API Route: source/app/api/company/analyze/route.ts:15
Companies House: source/lib/company/companies-house.ts
SEC EDGAR: source/lib/company/sec-edgar.ts
GLEIF: source/lib/company/gleif.ts
Type Definitions: source/lib/company/types.ts

Data Source Coverage

UK (Companies House)
US (SEC EDGAR)
Global (GLEIF)

Coverage: All UK registered companiesData includes:

Company registration details
Directors and officers
Filings and accounts
Charges and insolvency
SIC codes

Requires: API key

Best Practices

Recommendations

Specify country: Set correct country parameter for better results
Use ticker for speed: US ticker lookups are faster than name searches
Handle partial results: Some data sources may fail or timeout
Cache results: Company data changes infrequently
Check errors field: Individual sources may fail without blocking others

Example Implementation

interface CompanySummary {
  name: string;
  country: string;
  status: string;
  officers?: string[];
  lei?: string;
  filings?: number;
}

async function searchCompany(query: string, country: 'US' | 'UK'): Promise<CompanySummary> {
  const response = await fetch('/api/company/analyze', {
    method: 'POST',
    headers: { 'Content-Type': 'application/json' },
    body: JSON.stringify({ query, country })
  });

  const reader = response.body!.getReader();
  const decoder = new TextDecoder();
  let result: any;

  while (true) {
    const { done, value } = await reader.read();
    if (done) break;

    const text = decoder.decode(value);
    const lines = text.split('\n');

    for (const line of lines) {
      if (line.startsWith('data: ')) {
        const event = JSON.parse(line.slice(6));
        if (event.type === 'complete') {
          result = event.data.result;
        }
      }
    }
  }

  // Build summary
  const summary: CompanySummary = {
    name: query,
    country,
    status: 'unknown',
    officers: [],
    filings: 0
  };

  if (country === 'UK' && result.companiesHouse?.company) {
    const ch = result.companiesHouse;
    summary.name = ch.company.company_name;
    summary.status = ch.company.company_status;
    summary.officers = ch.officers?.map((o: any) => o.name) ?? [];
    summary.filings = ch.filings?.length ?? 0;
  } else if (country === 'US' && result.secEdgar?.company) {
    const sec = result.secEdgar;
    summary.name = sec.company.name;
    summary.status = 'active';  // SEC only lists active companies
    summary.filings = sec.recentFilings?.length ?? 0;
  }

  if (result.gleif?.records?.[0]) {
    summary.lei = result.gleif.records[0].lei;
  }

  return summary;
}

Endpoints

Company Analysis API

Overview

Endpoint

Request

Headers

Body Parameters

Request Example

Response

Event Types

Complete Result Structure

UK Companies House

GLEIF LEI Database

SEC EDGAR

Errors

Response Example

Error Responses

Configuration

Source Code Reference

Data Source Coverage

Best Practices

Recommendations

Example Implementation

Build docs developers (and LLMs) love

Endpoints

​Overview

​Endpoint

​Request

​Headers

​Body Parameters

​Request Example

​Response

​Event Types

​Complete Result Structure

​UK Companies House

​GLEIF LEI Database

​SEC EDGAR

​Errors

​Response Example

​Error Responses

​Configuration

​Source Code Reference

​Data Source Coverage

​Best Practices

​Recommendations

​Example Implementation

Build docs developers (and LLMs) love

Overview

Endpoint

Request

Headers

Body Parameters

Request Example

Response

Event Types

Complete Result Structure

UK Companies House

GLEIF LEI Database

SEC EDGAR

Errors

Response Example

Error Responses

Configuration

Source Code Reference

Data Source Coverage

Best Practices

Recommendations

Example Implementation