Reference

Create an order (spends credits)

POST /v1/orders. Spend credits against a live machine quote: 1 credit per complete UK record.

Generated from the contractsView as Markdown

POST /v1/orders

Spend credits against a live machine quote: 1 credit per complete UK record. Needs the quote_id plus a human confirmation (MCP elicitation, the confirmation_token from the approval page, or a person ordering in the app itself) or a pre-authorised agent key within its per-order cap and monthly budget; a model-set confirmed flag is never consent. A standard API key or an OAuth token with no confirmation gets 403 confirmation-required carrying the approval_url, and nothing is charged. Idempotent on quote_id plus the Idempotency-Key header, so a retry never double charges. Returns 402 with the machine quote and a top_up_url when the balance is short, 403 agent-budget-exceeded when a key's limits do not cover it, 403 business-details-required when an account made by self-serve sign-up has not yet confirmed its business name and that it is a UK business (PATCH /v1/account), and 403 licence-acceptance-required, with the approval_url, when the Data Licence and Sharing Agreement in force was not accepted (licence_accepted_version from a person in the app, the approval page's token, or the agent key's own acceptance). Lawful basis for named work emails is UK GDPR Article 6(1)(f) legitimate interests; sole traders and ordinary partnerships are individual subscribers and are left out of email audiences by default.

Property	Value
Endpoint	`POST https://mydatahub.emailmovers.com/v1/orders`
Operation id	`createOrder`
Cost	1 credit per complete UK record (uk_contacts). Suppressed, duplicate and already held records cost 0.
Access	An API key or an OAuth 2.1 token with the scope `orders:write`.
Idempotency-Key	Required. A retry never charges twice.
MCP tool	`create_order`
Tag	Orders

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.
`Idempotency-Key`	header	string	yes	Required. A retry with the same key never charges twice; a different request with the same key returns 409. Keys are kept for the life of the organisation.

Body

Member	Type	Required	Description
`quote_id`	string	yes	A live machine quote from quote_order. Without one nothing is charged.
`name`	string	no
`delivery`	array of enum: `api`, `csv`, `google_sheets`	no	api (fetch records), csv (signed download) and google_sheets. Default api.
`confirmation_token`	string	no	The token the approval page on mydatahub.emailmovers.com returns once the signed-in person approves. It is bound to that person (their sub), this spend (the machine quote_id, or the enrichment or push) and an expiry no later than the quote's, and it is redeemable once.
`licence_accepted_version`	string	no	The version of the Data Licence and Sharing Agreement the person accepted for this order: the version in force, the account's agreements.dlsa.version. Required when a person orders in the app; an agent key carries the acceptance made with it, and a confirmation_token the one made on the approval page.

Example request

curl -X POST "https://mydatahub.emailmovers.com/v1/orders" \
  -H "Authorization: Bearer $MYDATAHUB_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  --data '{
  "quote_id": "qte_01JB4M2R6T1Y5W8ZAK8Q2V7XN3",
  "name": "Leeds marketing Q4",
  "delivery": ["api", "csv"]
}'

Responses

202: The order, queued.

Headers: RateLimit, RateLimit-Policy, Location.

Member	Type	Always present	Description
`id`	string	yes	Format: an order id: ord_ followed by a 26 character ULID in upper case Crockford base32, such as ord_01JB4N9S3W2X6Y7Z8A1B2C3D4E.
`status`	enum: `queued`, `building`, `verifying`, `ready`, `failed`, `cancelled`	yes	queued, building, verifying, ready; failed if processing failed; cancelled (only while queued).
`name`	string	no
`quote_id`	string	yes	The machine quote the order settled.
`count_id`	string	yes	The count the machine quote was priced from.
`dataset_version`	string	no	The immutable weekly build a count is bound to, such as 2026-W39. The last 52 stay queryable.
`field_set`	string	no
`delivery`	array of enum: `api`, `csv`, `google_sheets`	no
`records`	integer (0 or more)	yes
`credits_charged`	number (0 or more)	yes	Credits, to one decimal place: whole at 1 credit a record, fractional only where a rule is (0.1 company-only, 1.8 outright, both proposed).
`credits_remaining`	number (0 or more)	yes	The balance right after this order was charged.
`cost_gbp`	number (0 or more)	yes	The charge in GBP excluding VAT at your plan's rate.
`licence_expires_at`	string (date) or null	yes	When the licence ends; null for outright ownership.
`licence`	`Licence`	yes	Licence terms as data, on every quote, order, records page and receipt. Records stay usable, pushable and re-downloadable free until reuse_until.
`licence.type`	enum: `multi_use_12m`, `outright`	yes	multi_use_12m (12 month multi-use, every plan) or outright (1.8 credits a record, proposed).
`licence.reuse_until`	string (date) or null	yes	Order date plus 12 months; null for outright.
`licence.resale_prohibited`	boolean	yes
`licence.permitted_channels`	array of enum: `email`, `telephone`, `post`	yes	email, telephone and post on standard terms.
`licence.warranty_url`	string (uri)	yes
`licence.terms_version`	string	yes	The version of the Data Licence and Sharing Agreement the licence is under, such as 1.0.
`licence.terms_url`	string (uri)	no	Where that version of the Data Licence and Sharing Agreement is published.
`confirmed_by`	`ConfirmedBy`	yes	Who approved the spend and from which client, recorded in the audit trail and on invoices.
`confirmed_by.method`	enum: `elicitation_form`, `approval_url`, `agent_key`, `app`	yes	elicitation_form (the MCP form), approval_url (the approval page's confirmation_token), agent_key (a pre-authorised agent key within its limits) or app (a person ordering in the app itself, a first-party session; third-party OAuth clients never count).
`confirmed_by.key_id`	string	no	The agent key, for agent_key.
`confirmed_by.user_id`	string	no	The person who confirmed.
`confirmed_by.client_id`	string	no	The OAuth client, such as a Client ID Metadata Document URL.
`confirmed_by.user_agent`	string or null	no	The calling client's User-Agent.
`confirmed_by.mtls_certificate_fingerprint`	string or null	no	SHA-256 of the client certificate when one was presented (ChatGPT's mTLS).
`confirmed_by.web_bot_auth_signature_agent`	string or null	no	The Signature-Agent of a verified Web Bot Auth signature, when present.
`confirmed_by.confirmed_at`	string (date-time)	no
`verification`	object	no	The real-time check at delivery, such as 4,102 checked, 4,071 passed.
`verification.checked`	integer (0 or more)	yes
`verification.passed`	integer (0 or more)	yes
`verification.replaced`	integer (0 or more)	yes
`records_url`	string (uri-reference)	yes	A path on https://mydatahub.emailmovers.com starting /v1/. Resolve it against the origin (RFC 3986), not by appending it to the server URL.
`download_url`	string (uri-reference)	no	302 to a single-use signed URL that lives 5 minutes.
`receipt_url`	string (uri-reference)	no	A path on https://mydatahub.emailmovers.com starting /v1/. Resolve it against the origin (RFC 3986), not by appending it to the server URL.
`validation_report`	`ValidationReportLinks`	no	Present once the order is ready.
`validation_report.pdf_url`	string (uri)	yes
`validation_report.json_url`	string (uri)	yes
`buyer_kit`	`BuyerKit`	no	Four signed documents that help the buyer use the list lawfully.
`buyer_kit.draft_lia_url`	string (uri)	yes
`buyer_kit.first_email_wording_url`	string (uri)	yes
`buyer_kit.article30_stub_url`	string (uri)	yes
`buyer_kit.due_diligence_file_url`	string (uri)	yes
`created_at`	string (date-time)	no
`ready_at`	string (date-time) or null	no
`failure`	string or null	no

Example response

{
  "id": "ord_01JB4N9S3W2X6Y7Z8A1B2C3D4E",
  "status": "queued",
  "credits_charged": 5000,
  "records": 5000,
  "confirmed_by": {
    "method": "agent_key",
    "key_id": "key_01JB3Z4Q2V7XN3M9R6T1Y5W8ZA",
    "client_id": "https://claude.ai/oauth/claude-code-client-metadata"
  },
  "records_url": "/v1/orders/ord_01JB4N9S3W2X6Y7Z8A1B2C3D4E/records",
  "quote_id": "qte_01JB4M2R6T1Y5W8ZAK8Q2V7XN3",
  "count_id": "cnt_7K2PQ4MAXN3R6TBY5WDZ",
  "credits_remaining": 1200,
  "cost_gbp": 1495,
  "licence_expires_at": "2027-09-26",
  "licence": {
    "type": "multi_use_12m",
    "reuse_until": "2027-09-26",
    "resale_prohibited": true,
    "permitted_channels": ["email", "telephone", "post"],
    "warranty_url": "https://emailmovers.com/trust/warranty",
    "terms_version": "2026-09"
  }
}

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).
402	`insufficient-credits`	The balance does not cover the machine quote, which is carried here. Nothing was charged; top up on mydatahub.emailmovers.com and retry with the same quote_id.
403	`insufficient-scope`, `confirmation-required`, `business-details-required`, `licence-acceptance-required`, `dpa-acceptance-required`, `agent-budget-exceeded`	The token lacks a scope (insufficient-scope, with required_scope and a WWW-Authenticate step-up challenge); no person confirmed the spend and no agent key covers it (confirmation-required, with an approval_url); an agent key's per-order cap or monthly budget does not cover it (agent-budget-exceeded); an account made by self-serve sign-up has not yet confirmed its business name and that it is a UK business, which its first order needs (business-details-required); the order needs the Data Licence and Sharing Agreement accepted at the version in force (licence-acceptance-required); or a suppression upload comes before the organisation has accepted the Article 28 data processing agreement in force (dpa-acceptance-required). Nothing is charged.
409	`idempotency-key-reused`, `quote-expired`, `order-not-ready`, `order-not-cancellable`	An Idempotency-Key reused with different parameters, an expired machine quote, or an object in the wrong state.
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.