Companies House Pet

Access official UK company information from Companies House, including company profiles, officers, filing history, charges, and persons with significant control (PSC).

Features

• Company Search - Search for companies by name or keywords
• Company Profiles - Get detailed company information and registered addresses
• Officers - List directors, secretaries, and LLP members
• Filing History - Access company filings and submissions
• Charges - View mortgages and debentures
• PSC Data - List persons with significant control
• Officer Search - Search for individual officers across all companies

Quick Start

1. Get Your API Key

Register for a free Companies House API key:

1. Visit the Companies House Developer Hub
2. Create an account or sign in
3. Register an application to get your API key
4. Copy your API key

2. Configure Environment

# Copy the example env file
cp .env.example .env

# Edit .env and add your API key
COMPANIES_HOUSE_API_KEY=your_api_key_here

3. Test the Connection

bun install
opencode run "test companies-house connection"

You should see:

{
  "success": true,
  "status": "connected",
  "message": "Connected to Companies House API successfully"
}

Usage Examples

Search for Companies

opencode run "search companies house for Microsoft UK"
opencode run "find companies named Google in companies house"

Get Company Details

# Get full company profile
opencode run "get companies house profile for company number 00000006"

# Get registered address
opencode run "get registered office address for company 00000006"

List Company Officers

opencode run "list officers for company 00000006"
opencode run "show directors for company number 00445790"

Filing History

opencode run "get filing history for company 00000006"
opencode run "show recent accounts filings for company 00445790"

Charges and Mortgages

opencode run "list charges for company 00000006"

Persons with Significant Control

opencode run "list PSCs for company 00000006"

Search for Officers

opencode run "search for officers named John Smith in companies house"
opencode run "find appointments for officer abc123xyz"

Available Tools

| Tool | Description | |------|-------------| | companies-house-test-connection | Test API connection and verify credentials | | companies-house-search-companies | Search for companies by name or keyword | | companies-house-get-company-profile | Get detailed company profile by company number | | companies-house-get-registered-office-address | Get the registered office address | | companies-house-list-officers | List all officers (directors, secretaries) | | companies-house-get-filing-history | Get filing history for a company | | companies-house-list-charges | List charges (mortgages and debentures) | | companies-house-get-charge-details | Get details of a specific charge | | companies-house-search-officers | Search for officer appointments across all companies | | companies-house-get-officer-appointments | Get all company appointments for an officer | | companies-house-list-pscs | List persons with significant control |

API Limits

The Companies House API has rate limits:

• Free tier: 600 requests per 5 minutes
• Authenticated: Higher limits available

Respect these limits to avoid temporary blocks.

Company Numbers

Each UK company has a unique company number (e.g., 00000006). You can:

1. Search for companies by name to find their number
2. Use the number to query specific company details

Example company numbers:

• 00000006 - MARINE AND GENERAL MUTUAL LIFE ASSURANCE SOCIETY
• 00445790 - EASYJET PLC

Data Coverage

The API provides access to:

• Company Information: Name, status, type, incorporation date
• Registered Addresses: Current and previous addresses
• Officers: Directors, secretaries, LLP members
• Filing History: Accounts, annual returns, confirmation statements
• Charges: Mortgages, debentures, secured loans
• PSC: Individuals and entities with significant control (>25% shares/voting rights)
• Insolvency: Insolvency information where applicable

Authentication

The Companies House API uses Basic Authentication:

• Username: Your API key
• Password: Empty string

The pet handles this automatically using your COMPANIES_HOUSE_API_KEY.

Data Accuracy

This is official UK government data maintained by Companies House. The data is:

• Public: All information is publicly available
• Official: Legal register of UK companies
• Up-to-date: Updated as companies file documents

Common Workflows

Research a Company

# 1. Search for the company
opencode run "search companies house for Deliveroo"

# 2. Get the company number from results

# 3. Get full profile
opencode run "get company profile for company number 08167130"

# 4. Check officers
opencode run "list officers for company 08167130"

# 5. View filing history
opencode run "get filing history for company 08167130"

# 6. Check PSCs
opencode run "list PSCs for company 08167130"

Officer Research

# 1. Search for the officer
opencode run "search companies house for officer named Elon Musk"

# 2. Get officer ID from results

# 3. View all their appointments
opencode run "get officer appointments for officer id XYZ123"

Troubleshooting

"not_configured" Error

Problem: API key not set

Solution:

# Check .env file exists
cat .env

# Verify COMPANIES_HOUSE_API_KEY is set
grep COMPANIES_HOUSE_API_KEY .env

# If missing, add it
echo "COMPANIES_HOUSE_API_KEY=your_key_here" >> .env

"API error 401: Unauthorized"

Problem: Invalid API key

Solutions:

1. Check your API key is correct
2. Ensure there are no extra spaces in .env
3. Get a new API key from the developer hub
4. Verify the key has not expired

"API error 404: Not found"

Problem: Company number doesn't exist

Solutions:

1. Verify the company number is correct (8 digits, possibly with leading zeros)
2. Try searching for the company name first
3. Check the company hasn't been dissolved

Rate Limit Errors (429)

Problem: Too many requests

Solutions:

1. Wait 5 minutes before retrying
2. Reduce request frequency
3. Consider batching queries

Development

Testing Changes

# Test locally
opencode run "test companies-house connection"

# Build the pet
pets build companies-house

# Validate configuration
pets validate

Publishing

# Preview what will be published
pets publish --preview

# Publish to npm
pets publish companies-house

Links

• Companies House Developer Hub
• API Documentation
• Companies House Main Site
• Get an API Key

FAQ

How do I get a Companies House API key?

Register for a free API key at https://developer.company-information.service.gov.uk/. You'll need to create an account and register an application.

What data can I access?

You can access public company information including: company profiles and addresses, officers and directors, filing history, charges and mortgages, insolvency information, persons with significant control (PSC), and more. All data is read-only.

How do I find a company number?

Use the search tools to find companies by name. Each company has a unique number (e.g., 00000006). You'll need this number to query specific company details.

Are there rate limits?

Yes, the Companies House API has rate limits. Free tier typically allows 600 requests per 5 minutes. Respect these limits to avoid temporary blocks.

Is this data official?

Yes, this is official UK government data from Companies House, which maintains the register of companies in the United Kingdom.

Can I access historical data?

Yes, filing history includes historical filings and submissions. Some endpoint also show previous addresses and former officers.

What about Scottish/Northern Irish companies?

All UK companies (England, Wales, Scotland, Northern Ireland) are registered with Companies House and available through this API.

Support

For issues with:

• The pet: Open an issue on the OpenPets GitHub
• The API: Contact Companies House developer support
• Your API key: Check the Companies House developer hub

License

MIT