Company data API for the UK
One API for UK company and contact data: count, quote, order and enrich. Counts, quotes and plans need no key, and every response states what it cost in credits.
MyDataHub by Emailmovers has a REST API at https://mydatahub.emailmovers.com/v1. It counts UK business contacts, prices an audience,
places an order and returns the records. Counts, breakdowns, masked previews, machine quotes and plans work without an account, and
credits move only when you order.
One API key works on REST and on the MCP server. A dated MyDataHub-Version header lets the API evolve without breaking
you, and the OpenAPI 3.1 document at https://mydatahub.emailmovers.com/v1/openapi.json marks the credit cost of every operation.
What can the API do?
The endpoints fall into 14 groups. Groups marked public need no account, so an agent or a developer can count and price an audience before signing up.
| Group | Endpoints |
|---|---|
| Catalogue (public) | GET /v1/plans, GET /v1/datasets, GET /v1/catalogue/filters, GET /v1/catalogue/filters/{dimension}/values?q=&cursor=, GET /v1/field-sets, POST /v1/job-titles/expand, POST /v1/locations/resolve, POST /v1/audiences/compile |
| Counts (public) | POST /v1/counts, GET /v1/counts/{id} (replay for 12 months, ETag equals the id), POST /v1/previews |
| Audiences | GET, POST /v1/audiences; GET, PATCH, DELETE /v1/audiences/{id}; POST /v1/audiences/{id}/refresh |
| Quotes (public) | POST /v1/quotes, GET /v1/quotes/{id} |
| Orders | POST /v1/orders (quote_id, Idempotency-Key), GET /v1/orders, GET /v1/orders/{id}, POST /v1/orders/{id}/cancel (while queued), GET /v1/orders/{id}/receipt |
| Records | GET /v1/orders/{id}/records?cursor=&limit=&format=json or csv&fields=, GET /v1/orders/{id}/download (302 to a 5 minute single-use signed URL) |
| Lookups | POST /v1/companies/lookup, POST /v1/contacts/enrich |
| Suppressions | GET, POST /v1/suppressions (hashed emails, domains, phones and company numbers), POST /v1/suppressions/check, POST /v1/objections |
| Compliance (public) | GET /v1/trust, GET /v1/compliance/lia, POST /v1/compliance/receipts/verify (JWS in, verdict out) |
| Account | GET /v1/account, GET /v1/account/usage?from=&to=, POST /v1/account/cancel (ends a rolling plan at period end) |
| Keys | GET, POST /v1/api-keys; PATCH, DELETE /v1/api-keys/{id} |
| CRM push | GET, POST /v1/connections; POST /v1/connections/{id}/overlap; POST /v1/orders/{id}/pushes (dry_run default true); GET /v1/pushes/{id}; POST /v1/pushes/{id}/retry |
| Webhooks | GET, POST /v1/webhooks; DELETE /v1/webhooks/{id}; POST /v1/webhooks/{id}/test; GET /v1/events?since= (30 day replay) |
| Meta | GET /v1/openapi.json, GET /v1/health |
How do you run a count?
A count is one POST to https://mydatahub.emailmovers.com/v1/counts with an audience definition, and it needs no key. The developer reference has a worked request and response.
What does a count response tell you?
Every count carries enough to reason before you spend. The id is content addressed. It is cnt_ plus 20 characters of a hash of the effective definition, the dataset version and the engine rules version, so the same audience always gets the same id.
- dataset, dataset_version and credits_per_record: which data was counted and what a record costs.
- contacts, companies, emailable and new_to_you (signed in only): the three headline views.
- quality: email coverage, share verified in the last 90 days with the measurement date, and a deliverability split.
- compliance_summary: lawful basis, subscriber classes, TPS and CTPS exclusions and Article 14 notice counts.
- estimate and expires_at: the credits a quote would charge, what they cost in GBP ex VAT at the per-contact scale (per_contact_scale) and bought the cheapest way, at the scale or with a credit pack (cheapest), and when the id stops replaying. A machine quote gives the price you would pay.
GET /v1/counts/{id} replays a count for 12 months on its pinned dataset version, with the ETag equal to the id.
How do you quote and order?
A machine quote prices a count's records after removing duplicates and suppressed records, and it is valid for 24 hours. An order spends credits against that quote.
The quote returns the records, credits_required, gbp_ex_vat, licence, warranty and any blockers. POST /v1/orders is idempotent on the quote_id plus your Idempotency-Key, so a retry never charges twice, and records follow from GET /v1/orders/{id}/records.
How does authentication work?
Catalogue, counts, previews, quotes and pricing need no token. The first 401 arrives only when a call needs your account.
- API keys with the prefixes mdh_live_ and mdh_test_ are bearer tokens in the Authorization header, never a query string. Test keys return synthetic data and never charge.
- OAuth 2.1 with PKCE, issued by mydatahub.emailmovers.com/id, signs you in to the app. At launch, REST and MCP clients, AI assistants among them, use an API key; OAuth sign-in for them is planned for after launch.
- Scopes are fine-grained, such as counts:read, audiences:write, orders:write and records:read, and the first order asks for orders:write so the consent screen names the spend.
How is the API versioned?
The base path is /v1. Send a MyDataHub-Version header with a date, for example 2027-01-15, and your key pins to the behaviour of that date. The path major changes only for breaking changes, with a 12 month deprecation window.
How are errors and limits reported?
Errors are RFC 9457 problem details with type URIs under https://emailmovers.com/mydatahub/docs/errors/ and two extra members, next_step and did_you_mean. Rate limits use the IETF RateLimit and RateLimit-Policy headers, with Retry-After on a 429.
| Caller | Count limit | Other controls |
|---|---|---|
| Anonymous | 60 an hour and 600 a day per IP and fingerprint | At most 6 predicates; no free-text title search or radius under 5 miles |
| Free account | Published when confirmed | Rounded counts |
| Paid plan | Published per plan | Exact counts |
What does a call cost?
Every operation in the OpenAPI document carries x-cost-credits, and counts are marked x-free: true. Every charging response returns credits_charged, credits_remaining, cost_gbp and licence_expires_at, so your code can reconcile without asking.
How do webhooks work?
Webhooks follow the Standard Webhooks specification: webhook-id, webhook-timestamp and webhook-signature headers, an HMAC-SHA256 signature with rotating secrets, and retries over 24 hours with backoff. The webhook-id is your idempotency key.
| Event | Fires when |
|---|---|
order.ready, order.failed | Records are available, or processing failed |
audience.refreshed | A saved audience was recounted, with the diff |
credits.low, credits.topped_up | Balance crossed the configured threshold, or a top-up settled |
warranty.replacement_issued | A bounced or job-changed record was replaced |
suppression.created | An objection reached the organisation's records |
push.completed, push.partial, push.failed, connection.expired | CRM push outcomes and token failures |
How do pagination and idempotency work?
Lists use cursors and return data, has_more and next_cursor. The limit defaults to 25 and tops out at 100, or 500 on records. Every POST that creates or charges takes an Idempotency-Key, which we keep for the life of your account.
What happens to today's download endpoint?
The current endpoint, POST /api/RunExtract with an X-Api-Key header, stays available for 12 months from the version 2 launch, with three emailed notices, then returns 410. Legacy responses carry Deprecation and Sunset headers, and a migration map at https://emailmovers.com/mydatahub/docs/migrate lists the replacement for each old call. Today's MCP server stays at mcp.mydatahub.uk, on today's MyDataHub, until the new server supports OAuth sign-in for clients.
Where are the docs and the status page?
The developer reference lives at https://emailmovers.com/mydatahub/docs, and every page there has a Markdown twin. Measured latency will be published on a status page, which is planned, not on this page.
Frequently asked questions
Do I need an API key to run a count?
No. Counts, breakdowns, masked previews, machine quotes and plans need no key and no account. You need an API key to save audiences, order records and read your account.
What does a count cost?
Nothing. A count, breakdown, preview or machine quote costs 0 credits, and the OpenAPI document marks those operations x-free. A full UK record costs 1 credit when you order it.
Does the API return contact details?
Not before an order. Previews are masked, with the first character of the local part plus the top-level domain. Order records carry the full record and a licence block on every page.
Can the same key be used for the MCP server?
Yes. API keys with the prefixes mdh_live_ and mdh_test_ are bearer tokens on REST and on MCP alike. The agent guide covers the MCP server.
How do I test without spending credits?
Use an mdh_test_ key. Test keys return synthetic data and never charge.