# REST reference

> 65 operations of the MyDataHub REST API, generated from the OpenAPI 3.1 document.

Source: https://emailmovers.com/mydatahub/docs/reference/rest

65 operations in 15 groups, all under `https://mydatahub.emailmovers.com/v1`. Each page is generated from the OpenAPI 3.1 document, so a member, scope or cost on a page is the one the API is tested against.

> **Not yet live.** MyDataHub v2 is built and tested locally and is not yet live. The v2 hosts open at launch, date to confirm.

Send `MyDataHub-Version` with a date to pin behaviour, and `Idempotency-Key` on any request that creates or charges. See [Versions and reproducibility](https://emailmovers.com/mydatahub/docs/versions.md) and [Quotes and orders](https://emailmovers.com/mydatahub/docs/quotes-and-orders.md). Lists return `{data, has_more, next_cursor}`.

## Catalogue

Free and public: plans, datasets, filter fields and values, field sets, title expansion, location resolution and compiling a brief.

| Operation | Endpoint | Cost |
| --- | --- | --- |
| [Get plans and prices](https://emailmovers.com/mydatahub/docs/reference/rest/get-plans.md) | `GET /v1/plans` | Free (0 credits) |
| [List datasets](https://emailmovers.com/mydatahub/docs/reference/rest/list-datasets.md) | `GET /v1/datasets` | Free (0 credits) |
| [Get a dataset version changelog](https://emailmovers.com/mydatahub/docs/reference/rest/get-dataset-version.md) | `GET /v1/datasets/{dataset}/versions/{version}` | Free (0 credits) |
| [List filter fields](https://emailmovers.com/mydatahub/docs/reference/rest/list-filters.md) | `GET /v1/catalogue/filters` | Free (0 credits) |
| [Search filter values](https://emailmovers.com/mydatahub/docs/reference/rest/search-filter-values.md) | `GET /v1/catalogue/filters/{dimension}/values` | Free (0 credits) |
| [List field sets](https://emailmovers.com/mydatahub/docs/reference/rest/list-field-sets.md) | `GET /v1/field-sets` | Free (0 credits) |
| [Expand job titles](https://emailmovers.com/mydatahub/docs/reference/rest/expand-job-titles.md) | `POST /v1/job-titles/expand` | Free (0 credits) |
| [Resolve a location](https://emailmovers.com/mydatahub/docs/reference/rest/resolve-location.md) | `POST /v1/locations/resolve` | Free (0 credits) |
| [Compile a brief](https://emailmovers.com/mydatahub/docs/reference/rest/compile-audience.md) | `POST /v1/audiences/compile` | Free (0 credits) |

## Counts

Free and public: counts with breakdowns, and masked samples (previews).

| Operation | Endpoint | Cost |
| --- | --- | --- |
| [Count an audience](https://emailmovers.com/mydatahub/docs/reference/rest/create-count.md) | `POST /v1/counts` | Free (0 credits) |
| [Get a count](https://emailmovers.com/mydatahub/docs/reference/rest/get-count.md) | `GET /v1/counts/{id}` | Free (0 credits) |
| [Preview sample records](https://emailmovers.com/mydatahub/docs/reference/rest/create-preview.md) | `POST /v1/previews` | Free (0 credits) |

## Samples

A sample of a counted audience, sent only after a person confirms a work email address, and downloaded once.

| Operation | Endpoint | Cost |
| --- | --- | --- |
| [Ask for a sample of a count](https://emailmovers.com/mydatahub/docs/reference/rest/create-sample-request.md) | `POST /v1/sample-requests` | Free (0 credits) |
| [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` | Free (0 credits) |
| [Get a sample request](https://emailmovers.com/mydatahub/docs/reference/rest/get-sample-request.md) | `GET /v1/sample-requests/{id}` | Free (0 credits) |
| [Confirm a sample and get its download link](https://emailmovers.com/mydatahub/docs/reference/rest/create-sample-download.md) | `POST /v1/sample-downloads` | Free (0 credits) |

## Audiences

Saved audiences shared across the organisation.

| Operation | Endpoint | Cost |
| --- | --- | --- |
| [List saved audiences](https://emailmovers.com/mydatahub/docs/reference/rest/list-audiences.md) | `GET /v1/audiences` | Free (0 credits) |
| [Save an audience](https://emailmovers.com/mydatahub/docs/reference/rest/create-audience.md) | `POST /v1/audiences` | Free (0 credits) |
| [Get a saved audience](https://emailmovers.com/mydatahub/docs/reference/rest/get-audience.md) | `GET /v1/audiences/{id}` | Free (0 credits) |
| [Update a saved audience](https://emailmovers.com/mydatahub/docs/reference/rest/update-audience.md) | `PATCH /v1/audiences/{id}` | Free (0 credits) |
| [Delete a saved audience](https://emailmovers.com/mydatahub/docs/reference/rest/delete-audience.md) | `DELETE /v1/audiences/{id}` | Free (0 credits) |
| [Refresh a saved audience](https://emailmovers.com/mydatahub/docs/reference/rest/refresh-audience.md) | `POST /v1/audiences/{id}/refresh` | Free (0 credits) |

## Quotes

Machine quotes (24 hours, free and public) and human sales quotes (14 days).

| Operation | Endpoint | Cost |
| --- | --- | --- |
| [Quote an order](https://emailmovers.com/mydatahub/docs/reference/rest/create-quote.md) | `POST /v1/quotes` | Free (0 credits) |
| [Get a quote](https://emailmovers.com/mydatahub/docs/reference/rest/get-quote.md) | `GET /v1/quotes/{id}` | Free (0 credits) |

## Orders

Spend credits against a machine quote; status, cancellation and the signed compliance receipt.

| Operation | Endpoint | Cost |
| --- | --- | --- |
| [List orders](https://emailmovers.com/mydatahub/docs/reference/rest/list-orders.md) | `GET /v1/orders` | Free (0 credits) |
| [Create an order (spends credits)](https://emailmovers.com/mydatahub/docs/reference/rest/create-order.md) | `POST /v1/orders` | 1 credit per complete UK record (uk_contacts). Suppressed, duplicate and already held records cost 0. |
| [Get an order](https://emailmovers.com/mydatahub/docs/reference/rest/get-order.md) | `GET /v1/orders/{id}` | Free (0 credits) |
| [Cancel a queued order](https://emailmovers.com/mydatahub/docs/reference/rest/cancel-order.md) | `POST /v1/orders/{id}/cancel` | Free (0 credits) |
| [Get the compliance receipt](https://emailmovers.com/mydatahub/docs/reference/rest/get-compliance-receipt.md) | `GET /v1/orders/{id}/receipt` | Free (0 credits) |

## Records

Delivered records under licence, as pages or a signed download. Free.

| Operation | Endpoint | Cost |
| --- | --- | --- |
| [Fetch order records](https://emailmovers.com/mydatahub/docs/reference/rest/list-order-records.md) | `GET /v1/orders/{id}/records` | Free (0 credits) |
| [Download order records](https://emailmovers.com/mydatahub/docs/reference/rest/download-order.md) | `GET /v1/orders/{id}/download` | Free (0 credits) |

## Lookups

Company lookup (free) and contact enrichment (1 credit on a confident match).

| Operation | Endpoint | Cost |
| --- | --- | --- |
| [Look up a company](https://emailmovers.com/mydatahub/docs/reference/rest/lookup-company.md) | `POST /v1/companies/lookup` | Free (0 credits) |
| [Enrich a contact (spends credits)](https://emailmovers.com/mydatahub/docs/reference/rest/enrich-contact.md) | `POST /v1/contacts/enrich` | 1 credit on a confident match; 0 on no match or when already licensed. |

## Suppressions

Suppression lists, checks before a send, and objections.

| Operation | Endpoint | Cost |
| --- | --- | --- |
| [List suppression lists](https://emailmovers.com/mydatahub/docs/reference/rest/list-suppressions.md) | `GET /v1/suppressions` | Free (0 credits) |
| [Upload a suppression list](https://emailmovers.com/mydatahub/docs/reference/rest/create-suppression-list.md) | `POST /v1/suppressions` | Free (0 credits) |
| [Check suppression](https://emailmovers.com/mydatahub/docs/reference/rest/check-suppression.md) | `POST /v1/suppressions/check` | Free (0 credits) |
| [Report an objection](https://emailmovers.com/mydatahub/docs/reference/rest/report-objection.md) | `POST /v1/objections` | Free (0 credits) |

## Compliance

Public: the trust document, the LIA and compliance receipt verification.

| Operation | Endpoint | Cost |
| --- | --- | --- |
| [Get the trust document](https://emailmovers.com/mydatahub/docs/reference/rest/get-trust.md) | `GET /v1/trust` | Free (0 credits) |
| [Get the legitimate interests assessment](https://emailmovers.com/mydatahub/docs/reference/rest/get-lia.md) | `GET /v1/compliance/lia` | Free (0 credits) |
| [Verify a compliance receipt](https://emailmovers.com/mydatahub/docs/reference/rest/verify-compliance-receipt.md) | `POST /v1/compliance/receipts/verify` | Free (0 credits) |

## Account

Balance, plan, usage, credits bought by card, and ending a rolling plan.

| Operation | Endpoint | Cost |
| --- | --- | --- |
| [Get the account](https://emailmovers.com/mydatahub/docs/reference/rest/get-account.md) | `GET /v1/account` | Free (0 credits) |
| [Confirm the business details](https://emailmovers.com/mydatahub/docs/reference/rest/update-account.md) | `PATCH /v1/account` | Free (0 credits) |
| [Accept the data processing agreement](https://emailmovers.com/mydatahub/docs/reference/rest/accept-account-agreements.md) | `POST /v1/account/agreements` | Free (0 credits) |
| [Get account usage](https://emailmovers.com/mydatahub/docs/reference/rest/get-account-usage.md) | `GET /v1/account/usage` | Free (0 credits) |
| [Cancel the plan](https://emailmovers.com/mydatahub/docs/reference/rest/cancel-account.md) | `POST /v1/account/cancel` | Free (0 credits) |
| [List credit purchases](https://emailmovers.com/mydatahub/docs/reference/rest/list-credit-purchases.md) | `GET /v1/account/purchases` | Free (0 credits) |
| [Buy credits by card](https://emailmovers.com/mydatahub/docs/reference/rest/create-credit-purchase.md) | `POST /v1/account/purchases` | Free (0 credits) |
| [Get a credit purchase](https://emailmovers.com/mydatahub/docs/reference/rest/get-credit-purchase.md) | `GET /v1/account/purchases/{id}` | Free (0 credits) |

## Keys

API keys and agent keys with budgets.

| Operation | Endpoint | Cost |
| --- | --- | --- |
| [List API keys](https://emailmovers.com/mydatahub/docs/reference/rest/list-api-keys.md) | `GET /v1/api-keys` | Free (0 credits) |
| [Create an API key](https://emailmovers.com/mydatahub/docs/reference/rest/create-api-key.md) | `POST /v1/api-keys` | Free (0 credits) |
| [Update an API key](https://emailmovers.com/mydatahub/docs/reference/rest/update-api-key.md) | `PATCH /v1/api-keys/{id}` | Free (0 credits) |
| [Revoke an API key](https://emailmovers.com/mydatahub/docs/reference/rest/revoke-api-key.md) | `DELETE /v1/api-keys/{id}` | Free (0 credits) |

## CRM push

CRM connections, the New to you overlap check and record pushes.

| Operation | Endpoint | Cost |
| --- | --- | --- |
| [List CRM connections](https://emailmovers.com/mydatahub/docs/reference/rest/list-connections.md) | `GET /v1/connections` | Free (0 credits) |
| [Create a CRM connection](https://emailmovers.com/mydatahub/docs/reference/rest/create-connection.md) | `POST /v1/connections` | Free (0 credits) |
| [Check CRM overlap](https://emailmovers.com/mydatahub/docs/reference/rest/check-connection-overlap.md) | `POST /v1/connections/{id}/overlap` | Free (0 credits) |
| [Push an order to a CRM](https://emailmovers.com/mydatahub/docs/reference/rest/create-push.md) | `POST /v1/orders/{id}/pushes` | Free (0 credits) |
| [Get a push](https://emailmovers.com/mydatahub/docs/reference/rest/get-push.md) | `GET /v1/pushes/{id}` | Free (0 credits) |
| [Retry a push](https://emailmovers.com/mydatahub/docs/reference/rest/retry-push.md) | `POST /v1/pushes/{id}/retry` | Free (0 credits) |

## Webhooks

Webhook endpoints and the 30 day event log.

| Operation | Endpoint | Cost |
| --- | --- | --- |
| [List webhook endpoints](https://emailmovers.com/mydatahub/docs/reference/rest/list-webhook-endpoints.md) | `GET /v1/webhooks` | Free (0 credits) |
| [Create a webhook endpoint](https://emailmovers.com/mydatahub/docs/reference/rest/create-webhook-endpoint.md) | `POST /v1/webhooks` | Free (0 credits) |
| [Delete a webhook endpoint](https://emailmovers.com/mydatahub/docs/reference/rest/delete-webhook-endpoint.md) | `DELETE /v1/webhooks/{id}` | Free (0 credits) |
| [Send a test event](https://emailmovers.com/mydatahub/docs/reference/rest/test-webhook-endpoint.md) | `POST /v1/webhooks/{id}/test` | Free (0 credits) |
| [List events](https://emailmovers.com/mydatahub/docs/reference/rest/list-events.md) | `GET /v1/events` | Free (0 credits) |

## Meta

This document and the health check.

| Operation | Endpoint | Cost |
| --- | --- | --- |
| [Get this OpenAPI document](https://emailmovers.com/mydatahub/docs/reference/rest/get-open-api-document.md) | `GET /v1/openapi.json` | Free (0 credits) |
| [Check health](https://emailmovers.com/mydatahub/docs/reference/rest/get-health.md) | `GET /v1/health` | Free (0 credits) |