# UK Overseas Entity Registry Profiles (`afkdigital/uk-overseas-entity-registry-profiles`) Actor

Look up UK Overseas Entity IDs using official Companies House JSON. Get validated entity profiles, registered-office details, source-labelled dates and JSON/CSV exports. No API key required. $7.50 per 1,000 successful unique profiles. ID-based lookup; no property-title ownership data.

- **URL**: https://apify.com/afkdigital/uk-overseas-entity-registry-profiles.md
- **Developed by:** [AFK Digital](https://apify.com/afkdigital) (community)
- **Categories:** Business
- **Security:** Limited permissions
- **Stats:** 2 total users, 1 monthly users, 100.0% runs succeeded, 0 bookmarks
- **User rating**: No ratings yet

## Pricing

$7.50 / 1,000 successful unique overseas-entity profiles

This Actor is paid per event. You are not charged for the Apify platform usage, but only a fixed price for specific events.

Learn more: https://docs.apify.com/actors/running/actors-in-store.md#pay-per-event

## What's an Apify Actor?

An Actor is a serverless cloud program that runs on the Apify platform. It has two run modes.
In Batch mode, an Actor accepts a well-defined JSON input, performs an action which can take anything from a few seconds to a few hours,
and optionally produces a well-defined JSON output, datasets with results, or files in key-value store.
In Standby mode, an Actor provides a web server which can be used as a website, API, or an MCP server.

Apify vocabulary and the platform model are defined once, in the agent quickstart at https://apify.com/agents.md.

## How to integrate an Actor?

If asked about integration, you help developers integrate Actors into their projects.
You adapt to their stack and deliver integrations that are safe, well-documented, and production-ready.

Do not guess an integration path. Every one of them is in the agent quickstart at https://apify.com/agents.md: the Apify MCP server, Agent Skills with the Apify CLI, the JavaScript and Python clients, the REST API, and the account-free path for an agent with no human to sign in. It also carries the rule on stating cost before the first paid run.

For examples already wired to this Actor's own input schema, see the [API](#api) section below.

Each client library has reference documentation the quickstart does not restate: [JavaScript/TypeScript](https://docs.apify.com/api/client/js/docs.md) (`npm install apify-client`) and [Python](https://docs.apify.com/api/client/python/docs.md) (`pip install apify-client`).

# README

## UK Overseas Entity Registry Profiles

Look up known Overseas Entity IDs in the **Companies House official company URI JSON service**, normalize the basic registry fields, filter the requested profiles, and export JSON or CSV.

**No API key, source account, licensed file upload or special data-permission application is required for this endpoint.** Source: Companies House public register. Public-register reuse is governed by its published statutory-access guidance; this is not a blanket claim that all government information is licence-free.

This product was redesigned from NEWAPI59's earlier private OCOD prototype. The released version retrieves Companies House registry profiles only.

### What this Actor does

- Accepts 1–100 explicit OE IDs such as OE000002.
- Retrieves the official JSON document for each unique ID.
- Validates the returned identifier and overseas-entity category.
- Normalizes dates and preserves absent values as null.
- Applies transparent local filters to the requested list.
- Emits one record per unique successful match with links and retrieval time.

The scope is **United Kingdom overseas-entity registration**. It does not determine where the entity owns property.

### Quick start

```json
{
  "entityIds": ["OE000002", "OE000003"],
  "maxResults": 2,
  "maxChargeUsd": 0.015
}
```

The defaults retrieve real public profiles for HANLEY PARKS LTD and HANLEY CARAVANS LIMITED if those IDs remain available. Names, status and other fields always come from the response at run time.

### Inputs

| Field | Meaning |
| --- | --- |
| entityIds | Required conceptually; default examples supplied. 1–100 OE IDs, each OE plus 6 digits. Case/whitespace normalized and duplicates removed before requesting or charging. |
| companyName | Case-insensitive substring filter on company name. |
| companyStatus | Exact source status ignoring case; it does not certify operational or legal standing. |
| registeredOfficeCountry | Exact registered-office country ignoring case. This is not the foreign incorporation jurisdiction. |
| cityOrRegion | Case-insensitive substring across the registered office PostTown and County fields. |
| postcode | Exact registered-office postcode or outward district, ignoring spaces/case. |
| registeredFrom / registeredTo | Inclusive YYYY-MM-DD filters on the UK overseas-entity RegistrationDate. |
| maxResults | 1–100 successful unique profiles; default 100. |
| maxChargeUsd | Additional event-cost cap, 0–75 USD; default 1 USD. Apify's run charge cap also applies. |

All filters operate on the supplied ID list. **This is an ID-based lookup, not a nationwide company-name search, property search or discovery database.** Missing fields do not match an active filter. OCOD-specific inputs, including proprietorAddedFrom/To and incorporatedCountry, are rejected with an error; they are not silently ignored.

### Output fields

overseas_entity_id, company_name, company_category, company_status_as_reported, registered_date, country_of_origin_as_reported, registered_office_address, registered_office_city, registered_office_region, registered_office_country, registered_office_postcode, returns_next_due_date_as_reported, returns_last_made_up_date_as_reported, source_url, official_register_url, fetched_at, source_updated_at and data_caveats.

The Dataset and OUTPUT JSON contain the full profile. OUTPUT-CSV preserves objects and arrays as JSON cells, with formula-like scalar strings escaped for spreadsheets. STATUS records per-ID failures and limits; unsuccessful/filtered profiles do not create Dataset rows.

### Read the fields correctly

- The registered office address is not an owned property address.
- An OE registration is not proof that the entity currently owns any particular title.
- RegistrationDate is UK overseas-entity registration, not foreign incorporation.
- CountryOfOrigin is returned exactly as reported by the URI service. For example, it may report United Kingdom while the office is in Jersey. It is not relabelled as incorporation country.
- Returns fields retain their source labels. They are not silently renamed as ROE annual-update deadlines, nor treated as a legal compliance determination.
- The URI service may provide incomplete or delayed fields. Use official_register_url to inspect current filings where necessary. fetched_at records when this Actor retrieved the response, not when Companies House updated the record. source_updated_at stays null because the response supplies no verified record-update timestamp.

There is no HMLR/OCOD data, title_number, tenure, property address, title-to-entity join, beneficial-owner or managing-officer data in this release.

### Price

**USD 0.0075 per successfully emitted unique overseas-entity profile — USD 7.50 per 1,000 profiles.** The event is unique-entity. No startup fee. Duplicate input IDs, not-found entities, source failures and filtered-out records are not charged. Results across separate runs are separate lookups.

The event price includes run infrastructure; Apify post-run storage/API access follows platform terms. Owner test runs may record charge events without a purchase invoice.

### Access limits and reliability

Only https://data.companieshouse.gov.uk/doc/company/{OE_ID}.json is requested. No arbitrary URLs, proxies, user credentials or source-permission uploads are accepted.

Requests are sequential with at least 1 second between source attempts. At most one retry is allowed for selected transient failures. Each response is capped at 1 MiB, request timeout is 20 seconds, and total Actor execution is capped at 180 seconds. A long rate-limit response stops that lookup rather than attempting to bypass the restriction. These are this Actor's own limits; no numeric URI-service quota is assumed from the separate authenticated Companies House API.

### Source and reuse

- Data service: https://www.gov.uk/guidance/companies-house-data-products
- Public-register reuse: https://www.gov.uk/government/publications/companies-house-accreditation-to-information-fair-traders-scheme/public-task-copyright-and-crown-copyright
- Register context: https://www.gov.uk/guidance/register-an-overseas-entity

Source attribution is included in every row. Companies House states that it imposes no rules or requirements on how information on the public register is used. Applicable law and third-party rights still apply. No Crown insignia, filing-document imagery, unpublished material or HMLR restricted dataset is redistributed.

### Development

Python 3.13. Run python -m unittest discover -v. All implementation and deployment files remain in /opt/NEWAPI/NEWAPI59 on the authorised Netcup host. Actor identity is preserved across the redesign.

# Actor input Schema

## `entityIds` (type: `array`):

1–100 known OE IDs. Explicit ID lookup only, no name or property discovery. Duplicates are removed before requesting/charging.

## `companyName` (type: `string`):

Local case-insensitive substring filter across the requested ID profiles.

## `companyStatus` (type: `string`):

Exact source status ignoring case; not a legal standing assessment.

## `registeredOfficeCountry` (type: `string`):

Exact source office country ignoring case; not foreign incorporation jurisdiction.

## `cityOrRegion` (type: `string`):

Local substring across office PostTown/County. Not a property-location filter.

## `postcode` (type: `string`):

Exact full postcode or outward district, spaces/case ignored.

## `registeredFrom` (type: `string`):

Inclusive YYYY-MM-DD on UK overseas-entity RegistrationDate.

## `registeredTo` (type: `string`):

Inclusive YYYY-MM-DD; not a property ownership acquisition date.

## `maxResults` (type: `integer`):

Successful unique matches only. At most 100 input IDs per run.

## `maxChargeUsd` (type: `number`):

USD 0.0075 per successful unique profile. Apify's platform charge cap also applies.

## Actor input object example

```json
{
  "entityIds": [
    "OE000002",
    "OE000003"
  ],
  "maxResults": 2,
  "maxChargeUsd": 1
}
```

# Actor output Schema

## `profiles` (type: `string`):

No description

## `csv` (type: `string`):

No description

## `status` (type: `string`):

No description

## `provenance` (type: `string`):

No description

# API

You can run this Actor programmatically using our API. Below are code examples in JavaScript, Python, and CLI, as well as the OpenAPI specification and MCP server setup.

## JavaScript example

```javascript
import { ApifyClient } from 'apify-client';

// Initialize the ApifyClient with your Apify API token
// Replace the '<YOUR_API_TOKEN>' with your token
const client = new ApifyClient({
    token: '<YOUR_API_TOKEN>',
});

// Prepare Actor input
const input = {
    "entityIds": [
        "OE000002",
        "OE000003"
    ],
    "maxResults": 2
};

// Run the Actor and wait for it to finish
const run = await client.actor("afkdigital/uk-overseas-entity-registry-profiles").call(input);

// Fetch and print Actor results from the run's dataset (if any)
console.log('Results from dataset');
console.log(`💾 Check your data here: https://console.apify.com/storage/datasets/${run.defaultDatasetId}`);
const { items } = await client.dataset(run.defaultDatasetId).listItems();
items.forEach((item) => {
    console.dir(item);
});

// 📚 Want to learn more 📖? Go to → https://docs.apify.com/api/client/js/docs

```

## Python example

```python
from apify_client import ApifyClient

# Initialize the ApifyClient with your Apify API token
# Replace '<YOUR_API_TOKEN>' with your token.
client = ApifyClient("<YOUR_API_TOKEN>")

# Prepare the Actor input
run_input = {
    "entityIds": [
        "OE000002",
        "OE000003",
    ],
    "maxResults": 2,
}

# Run the Actor and wait for it to finish
run = client.actor("afkdigital/uk-overseas-entity-registry-profiles").call(run_input=run_input)

# Fetch and print Actor results from the run's dataset (if there are any)
print(f"💾 Check your data here: https://console.apify.com/storage/datasets/{run.default_dataset_id}")
for item in client.dataset(run.default_dataset_id).iterate_items():
    print(item)

# 📚 Want to learn more 📖? Go to → https://docs.apify.com/api/client/python/docs/quick-start

```

## CLI example

```bash
echo '{
  "entityIds": [
    "OE000002",
    "OE000003"
  ],
  "maxResults": 2
}' |
apify call afkdigital/uk-overseas-entity-registry-profiles --silent --output-dataset

```

## MCP server setup

```json
{
    "mcpServers": {
        "apify": {
            "type": "http",
            "url": "https://mcp.apify.com/?tools=fetch-actor-details,afkdigital/uk-overseas-entity-registry-profiles"
        }
    }
}
```

The hosted server signs you in with OAuth on first connect, so no API token belongs in this config. Clients without OAuth support can send an `Authorization: Bearer <APIFY_API_TOKEN>` header instead, using a token from API & Integrations in Apify Console (https://console.apify.com/settings/integrations).

## OpenAPI specification

Download the OpenAPI definition: https://api.apify.com/v2/actors/5SBbkI7BCBJgVy4VU/builds/bzmrZBgQbpmKf3FkS/openapi.json