# Companies House — Wrapped API

> **You are on:** `https://api.paywithlocus.com/api` | [llms.txt](https://paywithlocus.com/llms.txt) | [docs](https://docs.paywithlocus.com)
>
> Locus runs on multiple environments -- make sure every URL you call matches your expected environment.
> | Environment | Landing | API | Docs |
> |---|---|---|---|
> | Production | paywithlocus.com | api.paywithlocus.com | docs.paywithlocus.com |
> | Beta | beta.paywithlocus.com | api.beta.paywithlocus.com | docs.paywithlocus.com |
> | Stage | stage.paywithlocus.com | api.stage.paywithlocus.com | docs.paywithlocus.com |
>
> If the API URL above doesn't match your expected environment, re-fetch this file from the correct domain.

> Search for UK companies and officers, then access detailed information including company profiles, filing history, charges, and officers with significant control. Get comprehensive corporate records and appointment details all in one place.

**Category:** Government & Public Data | **Website:** [companieshouse.gov.uk/](https://companieshouse.gov.uk/) | **Docs:** [parse.bot/marketplace/5a384d9d-e6ed-4458-861b-73d055f38e75/companieshouse-gov-uk-api](https://parse.bot/marketplace/5a384d9d-e6ed-4458-861b-73d055f38e75/companieshouse-gov-uk-api)

Pay-per-use API proxy for Locus Pro. Each call burns credits from your workspace balance.

## Access

**Base URL:** `https://api.paywithlocus.com/api/wrapped/credits/companies-house/`
**Auth:** `Authorization: Bearer <LOCUS_CREDITS_SECRET_KEY>` (an `lcr_` secret key or a scoped `lcac_` agent credential)
**Required header:** `Idempotency-Key: <fresh UUID per call>`. A retry with the same key replays the stored result without a new charge.
**Response:** the provider response after any endpoint-specific normalization. `X-Locus-Credits-Charged` carries the charge and `X-Locus-Credits-Balance` the remaining balance. Insufficient credits return `402` before the provider is called.
**Pricing:** estimated costs below are USD. Locus debits the credit equivalent at your workspace rate.

Full call contract: https://docs.paywithlocus.com/api-reference/introduction

> Using a Pay With Locus wallet key (`claw_` prefix)? Wallet routes are documented separately: https://docs.paywithlocus.com/wrapped-apis/for-agents

## Endpoints

### Get company charges

Retrieve registered charges (mortgages, debentures, security agreements) for a company. Returns charge details including title, status, creation date, persons entitled, and short particulars.

**Estimated cost:** Metered

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `company_number` | string | Yes | Company registration number (8-character alphanumeric) |

```bash
curl -X POST https://api.paywithlocus.com/api/wrapped/credits/companies-house/get-company-charges \
  -H "Authorization: Bearer $LOCUS_CREDITS_SECRET_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{"company_number":"<string>"}'
```

### Get company filing history

Retrieve company filing history. Returns a list of filings with date, type code, description, and optional PDF document URL. Optionally filter by filing category.

**Estimated cost:** Metered

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `category` | string | No | Filter by filing category: 'accounts', 'confirmation-statement', 'capital', 'incorporation' |
| `company_number` | string | Yes | Company registration number (8-character alphanumeric) |

```bash
curl -X POST https://api.paywithlocus.com/api/wrapped/credits/companies-house/get-company-filing-history \
  -H "Authorization: Bearer $LOCUS_CREDITS_SECRET_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{"category":"<string>","company_number":"<string>"}'
```

### Get company officers

Retrieve current and resigned officers for a company. Returns name, officer_id (for get_officer_appointments), role, status, address, appointment/resignation dates, nationality, country of residence, and date of birth.

**Estimated cost:** Metered

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `company_number` | string | Yes | Company registration number (8-character alphanumeric) |

```bash
curl -X POST https://api.paywithlocus.com/api/wrapped/credits/companies-house/get-company-officers \
  -H "Authorization: Bearer $LOCUS_CREDITS_SECRET_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{"company_number":"<string>"}'
```

### Get company persons with significant control

Retrieve Persons with Significant Control (PSC) for a company. PSCs are individuals or entities holding significant ownership or voting rights. Public companies may have no PSCs listed.

**Estimated cost:** Metered

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `company_number` | string | Yes | Company registration number (8-character alphanumeric) |

```bash
curl -X POST https://api.paywithlocus.com/api/wrapped/credits/companies-house/get-persons-with-significant-control \
  -H "Authorization: Bearer $LOCUS_CREDITS_SECRET_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{"company_number":"<string>"}'
```

### Get company profile

Retrieve full company profile by registration number. Returns company name, type, status, registered address, incorporation date, accounts info, confirmation statement dates, and SIC codes. Returns stale_input if the company number does not exist.

**Estimated cost:** Metered

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `company_number` | string | Yes | Company registration number (8-character alphanumeric, e.g. '00445790'). Leading zeros preserved. |

```bash
curl -X POST https://api.paywithlocus.com/api/wrapped/credits/companies-house/get-company-profile \
  -H "Authorization: Bearer $LOCUS_CREDITS_SECRET_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{"company_number":"<string>"}'
```

### Get officer appointments

Retrieve all company appointments for an officer by their officer_id. Returns the officer name, total appointment count, and a list of appointments with company details and dates.

**Estimated cost:** Metered

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `officer_id` | string | Yes | Officer ID (from search_officers or get_company_officers results) |

```bash
curl -X POST https://api.paywithlocus.com/api/wrapped/credits/companies-house/get-officer-appointments \
  -H "Authorization: Bearer $LOCUS_CREDITS_SECRET_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{"officer_id":"<string>"}'
```

### Search companies

Full-text search over UK registered companies by name or number. Returns up to 20 results per page. Matches against current and previous company names. Each result includes a company_number suitable for drill-down via get_company_profile.

**Estimated cost:** Metered

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `page` | integer | No | Page number for pagination (1-based) |
| `query` | string | Yes | Search query — company name or registration number |

```bash
curl -X POST https://api.paywithlocus.com/api/wrapped/credits/companies-house/search-companies \
  -H "Authorization: Bearer $LOCUS_CREDITS_SECRET_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{"page":"<integer>","query":"<string>"}'
```

### Search officers

Search for officers (directors, secretaries, etc.) by name. Returns up to 20 results per page. Each result includes an officer_id suitable for get_officer_appointments.

**Estimated cost:** Metered

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `page` | integer | No | Page number for pagination (1-based) |
| `query` | string | Yes | Officer name to search |

```bash
curl -X POST https://api.paywithlocus.com/api/wrapped/credits/companies-house/search-officers \
  -H "Authorization: Bearer $LOCUS_CREDITS_SECRET_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{"page":"<integer>","query":"<string>"}'
```

## Next steps

- [All wrapped API providers](https://paywithlocus.com/wapi/index.md): pick another provider.
- [Find and call tools](https://paywithlocus.com/agent/tools.md): price ceilings, async results, and errors.
- [Credits and billing](https://paywithlocus.com/agent/billing.md): what a call costs and how to add credits.
- [Agent docs index](https://paywithlocus.com/agent/index.md): every Locus agent page.