# MyDataHub developer docs > UK B2B contact counts, quotes and lists, by Emailmovers. Developer documentation for the MyDataHub by Emailmovers REST API (https://mydatahub.emailmovers.com/v1) and MCP server (https://mydatahub.emailmovers.com/mcp). Every page has a Markdown twin at the same path with .md. Status: MyDataHub v2 is built and tested locally and is not yet live. Its host, mydatahub.emailmovers.com, opens at launch with these docs, date to confirm. Today https://mcp.mydatahub.uk and https://app.mydatahub.uk serve the current product. Looking is free: counts, breakdowns, masked samples and machine quotes need no account. One credit buys one complete UK record. A spend needs a machine quote_id plus a person's confirmation or an agent key within its limits. A model-set confirmed flag is never consent. ## Start here - [MyDataHub developer docs](https://emailmovers.com/mydatahub/docs/index.md): Count, preview and quote UK B2B contacts for free, then order by REST, MCP or the app. One credit buys one complete UK record. - [Quickstart for people](https://emailmovers.com/mydatahub/docs/quickstart/people.md): Run a count, read a masked sample and place an order in the MyDataHub app. The target is a first count in under 60 seconds and a first order in under 5 minutes. - [Quickstart for developers](https://emailmovers.com/mydatahub/docs/quickstart/developers.md): Count, preview, quote and order UK B2B contacts over REST with curl and TypeScript. Counts, previews and quotes need no account. - [Quickstart for agents](https://emailmovers.com/mydatahub/docs/quickstart/agents.md): Connect Claude, ChatGPT or Cursor to the MyDataHub MCP server at https://mydatahub.emailmovers.com/mcp, and call its 22 tools from code. Looking is free; spending needs a quote and a confirmation. ## Guides - [The audience definition](https://emailmovers.com/mydatahub/docs/audience.md): Every count starts from one JSON document in the namespace mydatahub.audience/1: filters in groups, with fields, operators, title expansion, geography and defaults. - [Counts and breakdowns](https://emailmovers.com/mydatahub/docs/counts.md): Count an audience for free and get Total, New to you and Emailable, the premium figure beside all records, up to three breakdowns, quality signals and a compliance summary. Small numbers are rounded for anonymous callers. - [Samples](https://emailmovers.com/mydatahub/docs/samples.md): Preview up to 25 masked records for free, with why each one matches and where each field came from. The same audience always returns the same rows. - [Quotes and orders](https://emailmovers.com/mydatahub/docs/quotes-and-orders.md): A machine quote prices a count for 24 hours at 0 credits. An order spends credits against that quote and delivers records under a 12 month licence. - [Spending safely](https://emailmovers.com/mydatahub/docs/spending-safely.md): Three layers guard every spend: a machine quote first, a person's confirmation or a pre-authorised agent key, and hard limits. A flag set by a model is never consent. - [Suppressions and objections](https://emailmovers.com/mydatahub/docs/suppressions.md): Upload suppression lists that apply to every count and order, check records before a send, and report an objection so it reaches every licensee holding the record. - [Compliance receipts](https://emailmovers.com/mydatahub/docs/compliance-receipts.md): Every order issues a signed receipt that proves what was delivered and how it was screened. Verify its ES256 signature with the published key, or with one request and no account. - [Versions and reproducibility](https://emailmovers.com/mydatahub/docs/versions.md): A count id re-runs exactly for 12 months on its pinned dataset version. The API evolves by dated version, and the path major changes only for breaking changes. ## Platform - [Authentication](https://emailmovers.com/mydatahub/docs/authentication.md): API keys and agent keys authenticate REST and MCP clients, AI assistants among them. OAuth 2.1 at mydatahub.emailmovers.com/id signs you in to the app; OAuth sign-in for REST and MCP clients is planned for after launch. - [Errors](https://emailmovers.com/mydatahub/docs/errors.md): The 26 problem types the API returns, each with its HTTP status and what to do next. - [Rate limits](https://emailmovers.com/mydatahub/docs/rate-limits.md): Anonymous callers get 60 counts an hour and 600 a day. Every response reports your remaining quota in the IETF RateLimit headers, and a 429 says how long to wait. - [Webhooks](https://emailmovers.com/mydatahub/docs/webhooks.md): Get told when an order is ready, credits run low or an objection reaches your records. Deliveries follow Standard Webhooks, with signed headers and retries. ## Reference - [Reference](https://emailmovers.com/mydatahub/docs/reference.md): The REST API, the MCP tools and the webhook events, generated from the contracts: 65 operations and 34 tools. - [REST reference](https://emailmovers.com/mydatahub/docs/reference/rest.md): 65 operations of the MyDataHub REST API, generated from the OpenAPI 3.1 document. - [MCP tool reference](https://emailmovers.com/mydatahub/docs/reference/mcp.md): The 22 MCP tools of https://mydatahub.emailmovers.com/mcp in their fixed order, and the 12 deprecated tools, generated from the tools/list result. - [Webhook events](https://emailmovers.com/mydatahub/docs/reference/webhooks.md): The 11 webhook event types, with their payloads, generated from the OpenAPI document. ## Migrate and change - [Migration guide](https://emailmovers.com/mydatahub/docs/migrate.md): Move from today's 13 MCP tools and the RunExtract endpoint to v2. A table maps every old call to its replacement, with worked before and after examples. - [Changelog and deprecation policy](https://emailmovers.com/mydatahub/docs/changelog.md): What changes in each release, and how long old things last: 12 months of notice for breaking changes and for today's 13 MCP tools, X-Api-Key and RunExtract. ## Optional - [OpenAPI 3.1 document](https://emailmovers.com/mydatahub/docs/reference/openapi.json): Every REST operation, schema and example. - [Audience JSON Schema](https://emailmovers.com/mydatahub/docs/reference/audience.schema.json): The schema of mydatahub.audience/1. - [MCP tools/list result](https://emailmovers.com/mydatahub/docs/reference/mcp-tools.json): The tools with their input and output schemas. - [Full text of the guides](https://emailmovers.com/mydatahub/docs/llms-full.txt): The guides, the errors and the reference indexes in one file. ### REST operations - [Get plans and prices](https://emailmovers.com/mydatahub/docs/reference/rest/get-plans.md): GET /v1/plans. Plans, credit packs, credit rules, licence terms, the guarantee and the free trial, in GBP excluding VAT. - [List datasets](https://emailmovers.com/mydatahub/docs/reference/rest/list-datasets.md): GET /v1/datasets. Every dataset with owner, source, licence, refresh, residency, regulator, warranty and credits per record. - [Get a dataset version changelog](https://emailmovers.com/mydatahub/docs/reference/rest/get-dataset-version.md): GET /v1/datasets/{dataset}/versions/{version}. What changed in one immutable weekly build: records added, retired and re-verified, companies dissolved, job changes confirmed, suppressions applied, coverage by field and the input snapshots. - [List filter fields](https://emailmovers.com/mydatahub/docs/reference/rest/list-filters.md): GET /v1/catalogue/filters. Every filterable field of mydatahub.audience/1 with its group, type, operators, value count and default, plus the operators and the dataset list. - [Search filter values](https://emailmovers.com/mydatahub/docs/reference/rest/search-filter-values.md): GET /v1/catalogue/filters/{dimension}/values. Values of one field, searched by text, each with its contact and company count, plus did_you_mean for a near miss. - [List field sets](https://emailmovers.com/mydatahub/docs/reference/rest/list-field-sets.md): GET /v1/field-sets. The named bundles of fields an order can deliver, with their exact columns. - [Expand job titles](https://emailmovers.com/mydatahub/docs/reference/rest/expand-job-titles.md): POST /v1/job-titles/expand. Show every title a keyword matches through the expansion sets (plurals, department synonyms, ampersands, abbreviations, word order), each with a count, or what a bundle such as sdm resolves to. - [Resolve a location](https://emailmovers.com/mydatahub/docs/reference/rest/resolve-location.md): POST /v1/locations/resolve. Turn free text into region, county, town, postcode or radius filters. - [Compile a brief](https://emailmovers.com/mydatahub/docs/reference/rest/compile-audience.md): POST /v1/audiences/compile. Turn a plain English brief into an audience definition with a one-sentence readback, the chips it made and any questions to answer first. - [Count an audience](https://emailmovers.com/mydatahub/docs/reference/rest/create-count.md): POST /v1/counts. Count an audience, inline or by aud_ id, at contact or company level with up to three breakdown fields. - [Get a count](https://emailmovers.com/mydatahub/docs/reference/rest/get-count.md): GET /v1/counts/{id}. Replay a count by id for 12 months: the effective definition, the compiled plan (expanded terms, resolved centres, SIC codes, suppression checksums), the pinned dataset and engine rules versions, all three views, breakdowns, the compliance summary, quality, the estimate and the number on the current dataset. - [Preview sample records](https://emailmovers.com/mydatahub/docs/reference/rest/create-preview.md): POST /v1/previews. Up to 25 masked sample rows from a seed fixed per audience, so a repeat returns the same rows. - [Ask for a sample of a count](https://emailmovers.com/mydatahub/docs/reference/rest/create-sample-request.md): POST /v1/sample-requests. Starts a sample of about 10 records of a counted audience: the person then confirms a work email address and downloads it once. - [Send the confirmation link for a sample](https://emailmovers.com/mydatahub/docs/reference/rest/create-sample-request-email.md): POST /v1/sample-requests/{id}/email. The person's work email address, from the calling server's own form, never through a model. - [Get a sample request](https://emailmovers.com/mydatahub/docs/reference/rest/get-sample-request.md): GET /v1/sample-requests/{id}. The request's status only: never the address or the records. - [Confirm a sample and get its download link](https://emailmovers.com/mydatahub/docs/reference/rest/create-sample-download.md): POST /v1/sample-downloads. Sent by the confirmation page when the person presses its button, with the token from the emailed link; the token is the credential, so no key or session is needed. - [List saved audiences](https://emailmovers.com/mydatahub/docs/reference/rest/list-audiences.md): GET /v1/audiences. Saved audiences shared across the organisation, with current counts and last refresh. - [Save an audience](https://emailmovers.com/mydatahub/docs/reference/rest/create-audience.md): POST /v1/audiences. Save a named audience definition, shared across the organisation. - [Get a saved audience](https://emailmovers.com/mydatahub/docs/reference/rest/get-audience.md): GET /v1/audiences/{id}. One saved audience with its definition and current count. - [Update a saved audience](https://emailmovers.com/mydatahub/docs/reference/rest/update-audience.md): PATCH /v1/audiences/{id}. Rename a saved audience or replace its definition. - [Delete a saved audience](https://emailmovers.com/mydatahub/docs/reference/rest/delete-audience.md): DELETE /v1/audiences/{id}. Delete a saved audience. - [Refresh a saved audience](https://emailmovers.com/mydatahub/docs/reference/rest/refresh-audience.md): POST /v1/audiences/{id}/refresh. Recount a saved audience on the current dataset version and return the difference. - [Quote an order](https://emailmovers.com/mydatahub/docs/reference/rest/create-quote.md): POST /v1/quotes. A signed machine quote for a count, field set, quantity and licence: records after overlap and suppression, credits per record, credits, the GBP price, the balance after, the licence and warranty, and blockers. - [Get a quote](https://emailmovers.com/mydatahub/docs/reference/rest/get-quote.md): GET /v1/quotes/{id}. A machine quote (kind machine, 24 hours) or a human sales quote (kind sales, 14 days). - [List orders](https://emailmovers.com/mydatahub/docs/reference/rest/list-orders.md): GET /v1/orders. Recent orders with status, counts and links, newest first. - [Create an order (spends credits)](https://emailmovers.com/mydatahub/docs/reference/rest/create-order.md): POST /v1/orders. Spend credits against a live machine quote: 1 credit per complete UK record. - [Get an order](https://emailmovers.com/mydatahub/docs/reference/rest/get-order.md): GET /v1/orders/{id}. Status (queued, building, verifying, ready, failed, cancelled), counts, charges, the licence, the buyer kit and the links to records, download and receipt. - [Cancel a queued order](https://emailmovers.com/mydatahub/docs/reference/rest/cancel-order.md): POST /v1/orders/{id}/cancel. Cancel an order while it is queued; its credits are refunded in full. - [Get the compliance receipt](https://emailmovers.com/mydatahub/docs/reference/rest/get-compliance-receipt.md): GET /v1/orders/{id}/receipt. The order's compliance receipt as an ES256 JWS with its decoded claims and a PDF twin: records delivered, suppression removals, counts by subscriber class, TPS status and Article 14 status, the licence and the file hash. - [Fetch order records](https://emailmovers.com/mydatahub/docs/reference/rest/list-order-records.md): GET /v1/orders/{id}/records. Delivered records in token-budgeted pages (default 50, up to 500), as JSON with the licence block on every page or as CSV. - [Download order records](https://emailmovers.com/mydatahub/docs/reference/rest/download-order.md): GET /v1/orders/{id}/download. Redirects to a single-use signed URL for the CSV that lives 5 minutes, bound to the account and logged. - [Look up a company](https://emailmovers.com/mydatahub/docs/reference/rest/lookup-company.md): 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). - [Enrich a contact (spends credits)](https://emailmovers.com/mydatahub/docs/reference/rest/enrich-contact.md): POST /v1/contacts/enrich. The full record for one known person, by email or by name and company. - [List suppression lists](https://emailmovers.com/mydatahub/docs/reference/rest/list-suppressions.md): GET /v1/suppressions. The organisation's suppression lists. - [Upload a suppression list](https://emailmovers.com/mydatahub/docs/reference/rest/create-suppression-list.md): POST /v1/suppressions. Upload emails, domains, phones, company numbers or title terms, raw or already hashed. - [Check suppression](https://emailmovers.com/mydatahub/docs/reference/rest/check-suppression.md): POST /v1/suppressions/check. Suppression status per record id, as of now. - [Report an objection](https://emailmovers.com/mydatahub/docs/reference/rest/report-objection.md): POST /v1/objections. Record an objection to direct marketing. - [Get the trust document](https://emailmovers.com/mydatahub/docs/reference/rest/get-trust.md): GET /v1/trust. The trust page as data: ICO registration, lawful basis and LIA, privacy notice, residency statement, sub-processors, retention, complaints and security. - [Get the legitimate interests assessment](https://emailmovers.com/mydatahub/docs/reference/rest/get-lia.md): GET /v1/compliance/lia. The published LIA (EM-LIA-2026-03) with its version history. - [Verify a compliance receipt](https://emailmovers.com/mydatahub/docs/reference/rest/verify-compliance-receipt.md): POST /v1/compliance/receipts/verify. Check a receipt's JWS against the published key without an account, and learn whether the order exists, until when its licence is in force and whether it was revoked. - [Get the account](https://emailmovers.com/mydatahub/docs/reference/rest/get-account.md): GET /v1/account. Balance by source, plan, per-action prices, the rate limit and, for an agent key, its budget and per-order cap. - [Confirm the business details](https://emailmovers.com/mydatahub/docs/reference/rest/update-account.md): PATCH /v1/account. Set the organisation's business name and confirm that it is a UK business. - [Accept the data processing agreement](https://emailmovers.com/mydatahub/docs/reference/rest/accept-account-agreements.md): POST /v1/account/agreements. Accept the Article 28 data processing agreement at the version in force (the account's agreements.dpa). - [Get account usage](https://emailmovers.com/mydatahub/docs/reference/rest/get-account-usage.md): GET /v1/account/usage. Credits charged, refunded and added in a period, by action and by key. - [Cancel the plan](https://emailmovers.com/mydatahub/docs/reference/rest/cancel-account.md): POST /v1/account/cancel. End a rolling plan at the end of its period, in one call, with no reason required; any notice terms in your agreement still apply. - [List credit purchases](https://emailmovers.com/mydatahub/docs/reference/rest/list-credit-purchases.md): GET /v1/account/purchases. Credits bought by card, newest first, each with its price excluding VAT, the VAT, the total and, once paid, its payment receipt. - [Buy credits by card](https://emailmovers.com/mydatahub/docs/reference/rest/create-credit-purchase.md): POST /v1/account/purchases. Start a card payment in Stripe Checkout for credits at the per-contact scale (the size of the line picks its band), the 40,000 credit pack, or a quote's purchase option line by line. - [Get a credit purchase](https://emailmovers.com/mydatahub/docs/reference/rest/get-credit-purchase.md): GET /v1/account/purchases/{id}. One purchase of credits by card. - [List API keys](https://emailmovers.com/mydatahub/docs/reference/rest/list-api-keys.md): GET /v1/api-keys. API keys and agent keys, with each agent key's live spend meter. - [Create an API key](https://emailmovers.com/mydatahub/docs/reference/rest/create-api-key.md): POST /v1/api-keys. Create a standard key or an agent key. - [Update an API key](https://emailmovers.com/mydatahub/docs/reference/rest/update-api-key.md): PATCH /v1/api-keys/{id}. Change a key's label, scopes, allowlist, expiry or, for an agent key, its tools, connections, budget and cap. - [Revoke an API key](https://emailmovers.com/mydatahub/docs/reference/rest/revoke-api-key.md): DELETE /v1/api-keys/{id}. Revoke a key at once. - [List CRM connections](https://emailmovers.com/mydatahub/docs/reference/rest/list-connections.md): GET /v1/connections. CRM and destination connections with their status. - [Create a CRM connection](https://emailmovers.com/mydatahub/docs/reference/rest/create-connection.md): POST /v1/connections. Start a connection to HubSpot, Salesforce, Google Sheets, Deliverite, a webhook or CSV. - [Check CRM overlap](https://emailmovers.com/mydatahub/docs/reference/rest/check-connection-overlap.md): POST /v1/connections/{id}/overlap. The New to you check before an order: read-only, email-only, salted SHA-256 matching in memory, nothing retained and nothing added to our database. - [Push an order to a CRM](https://emailmovers.com/mydatahub/docs/reference/rest/create-push.md): POST /v1/orders/{id}/pushes. Push an order's records to a connection, keyed on mydatahub_record_id with the MyDataHub property group. - [Get a push](https://emailmovers.com/mydatahub/docs/reference/rest/get-push.md): GET /v1/pushes/{id}. A push's status and summary: to create, to update, already present, skipped and failed. - [Retry a push](https://emailmovers.com/mydatahub/docs/reference/rest/retry-push.md): POST /v1/pushes/{id}/retry. Retry the failed records of a partial or failed push. - [List webhook endpoints](https://emailmovers.com/mydatahub/docs/reference/rest/list-webhook-endpoints.md): GET /v1/webhooks. Webhook endpoints, their events and pinned MyDataHub-Version. - [Create a webhook endpoint](https://emailmovers.com/mydatahub/docs/reference/rest/create-webhook-endpoint.md): POST /v1/webhooks. Register an https endpoint for events. - [Delete a webhook endpoint](https://emailmovers.com/mydatahub/docs/reference/rest/delete-webhook-endpoint.md): DELETE /v1/webhooks/{id}. Stop deliveries to an endpoint. - [Send a test event](https://emailmovers.com/mydatahub/docs/reference/rest/test-webhook-endpoint.md): POST /v1/webhooks/{id}/test. Send a signed test event to an endpoint and report the response. - [List events](https://emailmovers.com/mydatahub/docs/reference/rest/list-events.md): GET /v1/events. Replay events from the last 30 days, oldest first, in the same envelope webhooks deliver. - [Get this OpenAPI document](https://emailmovers.com/mydatahub/docs/reference/rest/get-open-api-document.md): GET /v1/openapi.json. This document: OpenAPI 3.1 with x-cost-credits and x-free on every operation, generated from the same schemas as the MCP tools. - [Check health](https://emailmovers.com/mydatahub/docs/reference/rest/get-health.md): GET /v1/health. Whether the API is up, with the release, the latest MyDataHub-Version, the current dataset version and how old its TPS and CTPS screen is. ### MCP tools - [Plans and prices](https://emailmovers.com/mydatahub/docs/reference/mcp/get_plans.md): get_plans: Returns the plans of MyDataHub by Emailmovers, the UK B2B count engine: credit packs, credit rules, licence terms, the bounce warranty and the free trial, in GBP excluding VAT. - [Account and balance](https://emailmovers.com/mydatahub/docs/reference/mcp/get_account.md): get_account: Returns the organisation's credit balance by source, plan, per-action prices and rate limit, and for an agent key its monthly budget and per-order cap. - [Filter catalogue](https://emailmovers.com/mydatahub/docs/reference/mcp/list_filters.md): list_filters: Lists every filterable field of the audience definition (mydatahub.audience/1) with its group, type, operators, value count and default, plus the datasets. - [Search filter values](https://emailmovers.com/mydatahub/docs/reference/mcp/search_filter_values.md): search_filter_values: Searches the values of one field by text, such as towns matching leeds, and returns each code with its contact and company counts plus did_you_mean for near misses. - [Expand job titles](https://emailmovers.com/mydatahub/docs/reference/mcp/expand_job_titles.md): expand_job_titles: Expands title keywords into every matching title (plurals, department synonyms, ampersands, abbreviations such as CEO), each with a count, or shows what a bundle such as sdm resolves to. - [Resolve a location](https://emailmovers.com/mydatahub/docs/reference/mcp/resolve_location.md): resolve_location: Turns free text such as 20 miles of Leeds, Yorkshire or LS1 into region, county, town, postcode or radius filters, each with a count and a ready filter. - [Compile a brief](https://emailmovers.com/mydatahub/docs/reference/mcp/compile_audience.md): compile_audience: Compiles a plain English brief, such as 300 finance directors at law firms in Manchester, into an audience definition with a one-sentence readback, editable chips and any questions to answer first. - [Count an audience](https://emailmovers.com/mydatahub/docs/reference/mcp/count_audience.md): count_audience: Counts UK contacts and companies matching an audience, inline or a saved aud_ id, and returns Total, New to you and Emailable, up to three breakdowns, quality, the compliance summary, a price estimate and a count id. - [Preview sample records](https://emailmovers.com/mydatahub/docs/reference/mcp/preview_records.md): preview_records: Returns up to 25 masked sample rows (10 by default) for an audience or a count id, each with verification badges, why it matches and a provenance card. - [Save an audience](https://emailmovers.com/mydatahub/docs/reference/mcp/save_audience.md): save_audience: Saves an audience definition under a name, shared across the organisation, or updates a saved one when audience_id is given. - [List saved audiences](https://emailmovers.com/mydatahub/docs/reference/mcp/list_audiences.md): list_audiences: Lists the organisation's saved audiences with their current counts and last refresh, newest first, optionally filtered by name. - [List field sets](https://emailmovers.com/mydatahub/docs/reference/mcp/list_field_sets.md): list_field_sets: Lists the field sets an order can deliver, such as standard or standard_telephone, with their exact columns. - [Quote an order](https://emailmovers.com/mydatahub/docs/reference/mcp/quote_order.md): quote_order: Creates a machine quote for a count: the records you would receive after removing ones already held and suppressed, the credits and GBP price, the licence, the warranty and any blockers. - [Create an order (spends credits)](https://emailmovers.com/mydatahub/docs/reference/mcp/create_order.md): create_order: Spends 1 credit per complete UK record against a live machine quote from quote_order, and queues the order. - [Get order status](https://emailmovers.com/mydatahub/docs/reference/mcp/get_order.md): get_order: Returns one order's status (queued, building, verifying, ready, failed or cancelled), counts, charges, licence and links to its records, download and receipt, or the recent orders when order_id is left out. - [Fetch order records](https://emailmovers.com/mydatahub/docs/reference/mcp/fetch_order_records.md): fetch_order_records: Returns a page of an order's delivered records (50 by default, up to 100) with the licence block on every page, as JSON or, on request, as CSV. - [Push an order to a CRM](https://emailmovers.com/mydatahub/docs/reference/mcp/push_to_crm.md): push_to_crm: Pushes an order's records to a connected CRM such as HubSpot or Salesforce, keyed on mydatahub_record_id, as record operations only: nothing is ever sent to the contacts. - [Look up a company](https://emailmovers.com/mydatahub/docs/reference/mcp/lookup_company.md): 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. - [Enrich a contact (spends credits)](https://emailmovers.com/mydatahub/docs/reference/mcp/enrich_contact.md): enrich_contact: Returns the full record for one known person, matched by email or by name with a company name, number or domain. - [Check suppression](https://emailmovers.com/mydatahub/docs/reference/mcp/check_suppression.md): check_suppression: Checks the suppression status of up to 1,000 delivered records by record id, as of now, and names the lists that suppress each. - [Report an objection](https://emailmovers.com/mydatahub/docs/reference/mcp/report_objection.md): report_objection: Records an objection to direct marketing for one record, by record id or email hash. - [Get a compliance receipt](https://emailmovers.com/mydatahub/docs/reference/mcp/get_compliance_receipt.md): get_compliance_receipt: Returns an order's signed compliance receipt: an ES256 JWS with its decoded claims and a PDF link, covering records delivered, suppression removals, subscriber classes, TPS screening, Article 14 status, the licence and the file hash. - [Deprecated: filter categories](https://emailmovers.com/mydatahub/docs/reference/mcp/available_selection_categories.md): available_selection_categories: deprecated; use list_filters instead. - [Deprecated: filter values](https://emailmovers.com/mydatahub/docs/reference/mcp/available_selection_values.md): available_selection_values: deprecated; use search_filter_values instead. - [Deprecated: search filter values](https://emailmovers.com/mydatahub/docs/reference/mcp/search_discrete_values.md): search_discrete_values: deprecated; use search_filter_values instead. - [Deprecated: build a count](https://emailmovers.com/mydatahub/docs/reference/mcp/create_search.md): create_search: deprecated; use compile_audience, then count_audience instead. - [Deprecated: clear the count](https://emailmovers.com/mydatahub/docs/reference/mcp/clear_search.md): clear_search: deprecated; use count_audience instead. - [Deprecated: get the count](https://emailmovers.com/mydatahub/docs/reference/mcp/get_count.md): get_count: deprecated; use count_audience instead. - [Deprecated: save an audience](https://emailmovers.com/mydatahub/docs/reference/mcp/save_selections.md): save_selections: deprecated; use save_audience instead. - [Deprecated: list saved audiences](https://emailmovers.com/mydatahub/docs/reference/mcp/get_saved_selections.md): get_saved_selections: deprecated; use list_audiences instead. - [Deprecated: create an order](https://emailmovers.com/mydatahub/docs/reference/mcp/create_data_extract.md): create_data_extract: deprecated; use quote_order, then create_order instead. - [Deprecated: credit balance](https://emailmovers.com/mydatahub/docs/reference/mcp/get_credits.md): get_credits: deprecated; use get_account instead. - [Deprecated: list field sets](https://emailmovers.com/mydatahub/docs/reference/mcp/get_packs.md): get_packs: deprecated; use list_field_sets instead. - [Deprecated: field set columns](https://emailmovers.com/mydatahub/docs/reference/mcp/get_pack_details.md): get_pack_details: deprecated; use list_field_sets instead. ### Problem types - [The request could not be read](https://emailmovers.com/mydatahub/docs/errors/invalid-request.md): invalid-request: HTTP 400. Send a JSON body with Content-Type: application/json and check the query string. - [An Idempotency-Key header is required](https://emailmovers.com/mydatahub/docs/errors/idempotency-key-required.md): idempotency-key-required: HTTP 400. Send an Idempotency-Key header (a V4 UUID is a good choice) and reuse it on every retry. - [Unsupported MyDataHub-Version](https://emailmovers.com/mydatahub/docs/errors/unsupported-version.md): unsupported-version: HTTP 400. Send a MyDataHub-Version date the API lists, such as 2027-01-15, or leave it out. - [Sign in or send an API key](https://emailmovers.com/mydatahub/docs/errors/authentication-required.md): authentication-required: HTTP 401. Send Authorization: Bearer with an mdh_ API key. Sign-in through https://mydatahub.emailmovers.com/id is planned. - [This needs a free account](https://emailmovers.com/mydatahub/docs/errors/account-required.md): account-required: HTTP 401. Create a free account (100 credits, no card) for single company counts, more than 6 filters in one audience, free text title search or a radius under 5 miles. Free and trial accounts still see rounded small counts; exact figures come with a paid plan. - [Not enough credits](https://emailmovers.com/mydatahub/docs/errors/insufficient-credits.md): insufficient-credits: HTTP 402. Top up at the top_up_url, then retry with the same machine quote_id (or the same enrichment request). - [The token lacks a scope](https://emailmovers.com/mydatahub/docs/errors/insufficient-scope.md): insufficient-scope: HTTP 403. Ask the user to approve the scope named in required_scope, then retry. - [A person must confirm this spend](https://emailmovers.com/mydatahub/docs/errors/confirmation-required.md): confirmation-required: HTTP 403. Nothing was charged. Keep the machine quote_id and give the user the approval_url; retry with the confirmation_token it returns, or use an agent key whose limits cover the spend. - [Business details are needed before the first order](https://emailmovers.com/mydatahub/docs/errors/business-details-required.md): business-details-required: HTTP 403. Nothing was charged. A person who owns the account confirms the business name and that it is a UK business, in the app's Settings or with PATCH /v1/account, then the same machine quote_id is ordered again. - [The data licence agreement must be accepted](https://emailmovers.com/mydatahub/docs/errors/licence-acceptance-required.md): licence-acceptance-required: HTTP 403. Nothing was charged. A person accepts the version in force (the account's agreements.dlsa): by ticking the box on the quote or at approval_url, where they can also approve this spend, or, for an agent key that orders or enriches on its own, on the key. Then the same request is sent again. - [The data processing agreement must be accepted](https://emailmovers.com/mydatahub/docs/errors/dpa-acceptance-required.md): dpa-acceptance-required: HTTP 403. Nothing was uploaded. A person who owns the account accepts the Article 28 data processing agreement at the version in force (the account's agreements.dpa): in the app's Settings, with the box on the app's first upload, or with POST /v1/account/agreements. Then the same list is uploaded again. - [The agent key budget does not cover this spend](https://emailmovers.com/mydatahub/docs/errors/agent-budget-exceeded.md): agent-budget-exceeded: HTTP 403. Keep the machine quote_id and ask the key owner to approve it at approval_url, or top up at top_up_url. - [Not found](https://emailmovers.com/mydatahub/docs/errors/not-found.md): not-found: HTTP 404. Check the id; ids are prefixed, such as ord_ for orders and aud_ for audiences. - [Method not allowed](https://emailmovers.com/mydatahub/docs/errors/method-not-allowed.md): method-not-allowed: HTTP 405. Use a method named in the Allow header; every path starts /v1 and /v1/openapi.json lists them. - [Idempotency-Key reused with different parameters](https://emailmovers.com/mydatahub/docs/errors/idempotency-key-reused.md): idempotency-key-reused: HTTP 409. Use a new Idempotency-Key for a different request; reuse a key only to retry. - [The machine quote has expired](https://emailmovers.com/mydatahub/docs/errors/quote-expired.md): quote-expired: HTTP 409. Call quote_order (POST /v1/quotes) again; a machine quote is valid for 24 hours. - [The order is not ready](https://emailmovers.com/mydatahub/docs/errors/order-not-ready.md): order-not-ready: HTTP 409. Wait for the order.ready webhook, or poll GET /v1/orders/{id} until status is ready. - [Only a queued order can be cancelled](https://emailmovers.com/mydatahub/docs/errors/order-not-cancellable.md): order-not-cancellable: HTTP 409. Records already delivered stay under licence; report bounces for a warranty claim. - [The request is not valid](https://emailmovers.com/mydatahub/docs/errors/validation-failed.md): validation-failed: HTTP 422. Fix each entry in errors, using did_you_mean where given, and send it again. - [A machine quote is required](https://emailmovers.com/mydatahub/docs/errors/quote-required.md): quote-required: HTTP 422. Call quote_order first; a machine quote is valid for 24 hours. - [The dataset is not served yet](https://emailmovers.com/mydatahub/docs/errors/dataset-unavailable.md): dataset-unavailable: HTTP 422. Use uk_contacts; GET /v1/datasets shows when other datasets open. - [Too many requests](https://emailmovers.com/mydatahub/docs/errors/rate-limited.md): rate-limited: HTTP 429. Wait for the seconds in Retry-After, then retry. - [Something went wrong on our side](https://emailmovers.com/mydatahub/docs/errors/internal-error.md): internal-error: HTTP 500. Nothing was charged. Retry with the same Idempotency-Key; if it persists, quote the instance to support. - [Not implemented yet](https://emailmovers.com/mydatahub/docs/errors/not-implemented.md): not-implemented: HTTP 501. Use the operations that answer today; /v1/openapi.json lists every operation and how it is declared. - [The service is briefly unavailable](https://emailmovers.com/mydatahub/docs/errors/service-unavailable.md): service-unavailable: HTTP 503. Wait for the seconds in Retry-After, then retry with the same Idempotency-Key. The status page shows incidents. - [The TPS and CTPS screen is more than 28 days old](https://emailmovers.com/mydatahub/docs/errors/tps-screen-expired.md): tps-screen-expired: HTTP 503. Nothing was charged. Email-only audiences carry on, with a field set without telephone and no phone. filter or breakdown. Telephone audiences return once a new dataset version is published; GET /v1/health shows the screen's age.