Reference

Look up a company

POST /v1/companies/lookup. Companies House fields for one company, by number, domain or name, and for signed-in callers the contacts we hold there by job level (a single company count needs an account and is logged; signed out, the counts are null).

Generated from the contractsView as Markdown

POST /v1/companies/lookup

Companies House fields for one company, by number, domain or name, and for signed-in callers the contacts we hold there by job level (a single company count needs an account and is logged; signed out, the counts are null). No contact details, and no charge (to confirm).

Property	Value
Endpoint	`POST https://mydatahub.emailmovers.com/v1/companies/lookup`
Operation id	`lookupCompany`
Cost	Free (0 credits)
Access	No account needed. An API key or OAuth token with the scope `counts:read` is optional and adds your organisation's own figures.
MCP tool	`lookup_company`
Tag	Lookups

Request

Parameters

Name	In	Type	Required	Description
`MyDataHub-Version`	header	string	no	The dated API version, pinned per key when left out. Non-breaking changes ship as new dates; the path major changes only for breaking changes, with a 12 month deprecation window.

Body

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 request

curl -X POST "https://mydatahub.emailmovers.com/v1/companies/lookup" \
  -H "Content-Type: application/json" \
  --data '{
  "company_number": "12345678"
}'

Responses

200: The company.

Headers: RateLimit, RateLimit-Policy.

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

Example response

{
  "match_confidence": 1,
  "dataset_version": "2026-W39",
  "company": {
    "companies_house_number": "12345678",
    "name": "Example Manufacturing Ltd",
    "status": "active",
    "type": "ltd",
    "subscriber_class": "ltd",
    "incorporation_date": "2004-02-19",
    "sic_2007": [
      {
        "code": "25620",
        "label": "Machining"
      }
    ],
    "employee_band": "100-199",
    "turnover_band": "11M-20M",
    "website_domain": "example.co.uk",
    "registered_office": {
      "town": "Leeds",
      "postcode": "LS11 5AA"
    }
  },
  "contacts_held": 14,
  "contacts_by_level": [
    {
      "level": "Director",
      "contacts": 3
    },
    {
      "level": "Manager",
      "contacts": 6
    }
  ],
  "compliance": {
    "lawful_basis": "legitimate_interests_art6_1_f",
    "subscriber_class": "ltd",
    "corporate_subscriber": true,
    "email_marketing_basis": "pecr_corporate_subscriber",
    "subscriber_evidence": {
      "companies_house_number": "12345678",
      "company_type": "ltd"
    },
    "provenance": {
      "company": {
        "source": "companies_house",
        "as_of": "2026-09-21"
      }
    },
    "attribution": "Contains public sector information licensed under the Open Government Licence v3.0"
  },
  "disclosure": {
    "level": "exact",
    "rounded_to": null,
    "secondary_suppression": false,
    "notes": []
  },
  "credits_charged": 0
}

Errors

Every error is a problem object with a code and a next_step. Every response carries the RateLimit and RateLimit-Policy headers; see Rate limits.

Status	Problem codes	When
400	`invalid-request`, `idempotency-key-required`, `unsupported-version`	The request could not be read, or an Idempotency-Key is missing.
401	`authentication-required`, `account-required`	Sign in (OAuth) or send an API key (authentication-required), or create a free account for what the anonymous tier does not cover (account-required).
422	`validation-failed`, `quote-required`, `dataset-unavailable`	The request is not valid. errors lists every problem with a JSON pointer and did_you_mean.
429	`rate-limited`	Too many requests. Wait for Retry-After.
Any other failure	`internal-error`, `service-unavailable`, `tps-screen-expired`	Something failed on our side (500 internal-error) or the service is briefly unavailable (503 service-unavailable, with Retry-After). Nothing was charged; retry with the same Idempotency-Key. A count, sample, quote or order with telephone in play is also refused with 503 tps-screen-expired, with no Retry-After, while the dataset version's TPS and CTPS screen is more than 28 days old.