# Look up a company

> lookup_company: Looks up one company by Companies House number, domain or name and returns its Companies House fields and compliance facts, and for a signed-in caller the contacts held there by job level.

Source: https://emailmovers.com/mydatahub/docs/reference/mcp/lookup_company

Looks up one company by Companies House number, domain or name and returns its Companies House fields and compliance facts, and for a signed-in caller the contacts held there by job level. It returns no contact details: use enrich_contact for one known person, or count_audience for everyone at the company. Free and needs no account, though the contacts held are a single company count that needs an account (null when signed out). Lawful basis is UK GDPR Article 6(1)(f) legitimate interests; email audiences include corporate subscribers only by default (PECR), so sole traders and ordinary partnerships are left out unless the toggle is changed.

| Property | Value |
| --- | --- |
| Tool name | `lookup_company` |
| Position in tools/list | 18 of 22 |
| Cost | Free |
| Scope | None. Works without an account. |
| Annotations | readOnlyHint true, destructiveHint false, idempotentHint true, openWorldHint false |
| Kind | Read only; idempotent, not destructive, closed world |
| REST equivalent | [`POST /v1/companies/lookup`](https://emailmovers.com/mydatahub/docs/reference/rest/lookup-company.md) |

> **Not yet live.** MyDataHub v2 is built and tested locally and is not yet live. The v2 hosts open at launch, date to confirm. This is what `tools/list` returns from https://mydatahub.emailmovers.com/mcp once v2 launches.

## Input

The schema sets `additionalProperties` to false, so a member that is not listed is refused.

| Member | Type | Required | Description |
| --- | --- | --- | --- |
| `company_number` | string | no | Eight characters in upper case, such as 05046417 or SC123456. |
| `domain` | string | no |  |
| `name` | string | no |  |
| `town` | string | no | Narrows a name search. |

## Example call

The `params` of a `tools/call` request:

```json
{
  "name": "lookup_company",
  "arguments": {
    "company_number": "12345678"
  }
}
```

## Output

The result carries `structuredContent` that matches this schema, and one line of text that leads with the number.

| Member | Type | Always present | Description |
| --- | --- | --- | --- |
| `match_confidence` | number (0 to 1) | yes |  |
| `dataset_version` | string | yes | The immutable weekly build a count is bound to, such as 2026-W39. The last 52 stay queryable. |
| `company` | object | yes |  |
| `company.companies_house_number` | string or null | yes |  |
| `company.name` | string | yes |  |
| `company.status` | string | yes |  |
| `company.type` | string | yes |  |
| `company.subscriber_class` | enum: `ltd`, `plc`, `llp`, `scottish_partnership`, `public_body`, `charity_incorporated`, `sole_trader`, `ordinary_partnership`, and 1 more | yes |  |
| `company.incorporation_date` | string (date) or null | yes |  |
| `company.sic_2007` | array of `SicCode` | yes |  |
| `company.employee_band` | string or null | yes |  |
| `company.turnover_band` | string or null | yes |  |
| `company.website_domain` | string or null | yes |  |
| `company.registered_office` | object | yes |  |
| `contacts_held` | integer (0 or more) or `under 10` or `suppressed` or null | yes | Contacts we hold at the company: a single-company count, so signed-in callers only (null otherwise) and logged. Trial callers see it rounded. |
| `contacts_by_level` | array of `LevelCount` or null | yes | The same count by job level, most senior first, with Level not known last; null when signed out. |
| `contacts_by_level[].level` | string | yes |  |
| `contacts_by_level[].contacts` | integer (0 or more) or `under 10` or `suppressed` | yes | A whole number; "under 10" when disclosure control withholds a small cell; or "suppressed" when secondary suppression hides a cell of 10 or more in a cross-tab or breakdown, so totals cannot be differenced. Anonymous and trial callers see cells rounded to the nearest 5. |
| `disclosure` | `Disclosure` | yes | Whether these numbers are exact or protected: "under 10" cells, rounding to 5 and secondary suppression for anonymous and trial callers. |
| `disclosure.level` | enum: `exact`, `rounded` | yes | exact for authenticated paid callers; rounded for anonymous and trial callers, whose counts under 100 and every cell are rounded to the nearest 5. |
| `disclosure.rounded_to` | integer or null | yes | 5 when numbers are rounded; null when they are exact. |
| `disclosure.secondary_suppression` | boolean | yes | True when cross-tab or breakdown cells of 10 or more were hidden as "suppressed" so totals cannot be differenced. |
| `disclosure.notes` | array of string | yes |  |
| `compliance` | `CompanyCompliance` | yes | The company facts of the compliance object, for results with no contact. |
| `compliance.lawful_basis` | enum: `legitimate_interests_art6_1_f` | yes |  |
| `compliance.subscriber_class` | enum: `ltd`, `plc`, `llp`, `scottish_partnership`, `public_body`, `charity_incorporated`, `sole_trader`, `ordinary_partnership`, and 1 more | yes |  |
| `compliance.corporate_subscriber` | boolean | yes |  |
| `compliance.email_marketing_basis` | enum: `pecr_corporate_subscriber`, `consent_required` | yes |  |
| `compliance.subscriber_evidence` | object | yes |  |
| `compliance.provenance` | object | yes |  |
| `compliance.attribution` | string or null | yes |  |
| `credits_charged` | `0` | yes |  |

## Errors

A failed call returns `isError` true. The text content leads with the sentence a person acts on, then the whole problem as JSON, with `code`, `detail`, `next_step` and `did_you_mean`. A 401 and a step-up 403 are answered at HTTP level so the client can start authorisation. See [Errors](https://emailmovers.com/mydatahub/docs/errors.md).