# Get an order

> 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.

Source: https://emailmovers.com/mydatahub/docs/reference/rest/get-order

`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.

| Property | Value |
| --- | --- |
| Endpoint | `GET https://mydatahub.emailmovers.com/v1/orders/{id}` |
| Operation id | `getOrder` |
| Cost | Free (0 credits) |
| Access | An API key or an OAuth 2.1 token with the scope `orders:read`. |
| MCP tool | [`get_order`](https://emailmovers.com/mydatahub/docs/reference/mcp/get_order.md) |
| Tag | Orders |

> **Not yet live.** MyDataHub v2 is built and tested locally and is not yet live. The v2 hosts open at launch, date to confirm. This page describes the contract the API is tested against.

## Request

### Parameters

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `id` | path | string | yes | Format: an order id: ord_ followed by a 26 character ULID in upper case Crockford base32, such as ord_01JB4N9S3W2X6Y7Z8A1B2C3D4E. |
| `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. |

## Example request

```bash
curl "https://mydatahub.emailmovers.com/v1/orders/ord_01JB4N9S3W2X6Y7Z8A1B2C3D4E" \
  -H "Authorization: Bearer $MYDATAHUB_API_KEY"
```

## Responses

### 200: The order.

Headers: `RateLimit`, `RateLimit-Policy`.

| 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

```json
{
  "id": "ord_01JB4N9S3W2X6Y7Z8A1B2C3D4E",
  "status": "ready",
  "credits_charged": 5000,
  "records": 5000,
  "confirmed_by": {
    "method": "agent_key",
    "key_id": "key_01JB3Z4Q2V7XN3M9R6T1Y5W8ZA",
    "client_id": "https://claude.ai/oauth/claude-code-client-metadata",
    "user_agent": "claude-code/2.1",
    "mtls_certificate_fingerprint": null,
    "web_bot_auth_signature_agent": null,
    "confirmed_at": "2026-09-26T10:16:00Z"
  },
  "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"
  },
  "name": "Leeds marketing Q4",
  "dataset_version": "2026-W39",
  "field_set": "standard",
  "delivery": ["api", "csv"],
  "verification": {
    "checked": 5000,
    "passed": 4962,
    "replaced": 38
  },
  "download_url": "/v1/orders/ord_01JB4N9S3W2X6Y7Z8A1B2C3D4E/download",
  "receipt_url": "/v1/orders/ord_01JB4N9S3W2X6Y7Z8A1B2C3D4E/receipt",
  "validation_report": {
    "pdf_url": "https://mydatahub.emailmovers.com/orders/ord_01JB4N9S3W2X6Y7Z8A1B2C3D4E/validation-report.pdf",
    "json_url": "https://mydatahub.emailmovers.com/orders/ord_01JB4N9S3W2X6Y7Z8A1B2C3D4E/validation-report.json"
  },
  "buyer_kit": {
    "draft_lia_url": "https://mydatahub.emailmovers.com/orders/ord_01JB4N9S3W2X6Y7Z8A1B2C3D4E/kit/lia",
    "first_email_wording_url": "https://mydatahub.emailmovers.com/orders/ord_01JB4N9S3W2X6Y7Z8A1B2C3D4E/kit/first-email",
    "article30_stub_url": "https://mydatahub.emailmovers.com/orders/ord_01JB4N9S3W2X6Y7Z8A1B2C3D4E/kit/article30",
    "due_diligence_file_url": "https://mydatahub.emailmovers.com/orders/ord_01JB4N9S3W2X6Y7Z8A1B2C3D4E/kit/due-diligence"
  },
  "created_at": "2026-09-26T10:16:00Z",
  "ready_at": "2026-09-26T10:16:04Z",
  "failure": null
}
```

## 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](https://emailmovers.com/mydatahub/docs/rate-limits.md).

| Status | Problem codes | When |
| --- | --- | --- |
| 400 | [`invalid-request`](https://emailmovers.com/mydatahub/docs/errors/invalid-request.md), [`idempotency-key-required`](https://emailmovers.com/mydatahub/docs/errors/idempotency-key-required.md), [`unsupported-version`](https://emailmovers.com/mydatahub/docs/errors/unsupported-version.md) | The request could not be read, or an Idempotency-Key is missing. |
| 401 | [`authentication-required`](https://emailmovers.com/mydatahub/docs/errors/authentication-required.md), [`account-required`](https://emailmovers.com/mydatahub/docs/errors/account-required.md) | 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). |
| 403 | [`insufficient-scope`](https://emailmovers.com/mydatahub/docs/errors/insufficient-scope.md), [`confirmation-required`](https://emailmovers.com/mydatahub/docs/errors/confirmation-required.md), [`business-details-required`](https://emailmovers.com/mydatahub/docs/errors/business-details-required.md), [`licence-acceptance-required`](https://emailmovers.com/mydatahub/docs/errors/licence-acceptance-required.md), [`dpa-acceptance-required`](https://emailmovers.com/mydatahub/docs/errors/dpa-acceptance-required.md), [`agent-budget-exceeded`](https://emailmovers.com/mydatahub/docs/errors/agent-budget-exceeded.md) | 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. |
| 404 | [`not-found`](https://emailmovers.com/mydatahub/docs/errors/not-found.md) | No such object for this organisation. |
| 429 | [`rate-limited`](https://emailmovers.com/mydatahub/docs/errors/rate-limited.md) | Too many requests. Wait for Retry-After. |
| Any other failure | [`internal-error`](https://emailmovers.com/mydatahub/docs/errors/internal-error.md), [`service-unavailable`](https://emailmovers.com/mydatahub/docs/errors/service-unavailable.md), [`tps-screen-expired`](https://emailmovers.com/mydatahub/docs/errors/tps-screen-expired.md) | 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. |