Reference

Fetch order records

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.

Generated from the contractsView as Markdown

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. Fetching again under licence costs 0 credits.

Property	Value
Endpoint	`GET https://mydatahub.emailmovers.com/v1/orders/{id}/records`
Operation id	`listOrderRecords`
Cost	Free (0 credits)
Access	An API key or an OAuth 2.1 token with the scope `records:read`.
MCP tool	`fetch_order_records`
Tag	Records

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.
`cursor`	query	string	no	An opaque cursor from next_cursor. Pass it back unchanged.
`limit`	query	integer (1 to 500)	no	Records per page, 1 to 500. Default 50.
`format`	query	enum: `json`, `csv`	no	json (default) or csv.
`fields`	query	comma separated list	no	Columns to return, comma separated; default the order's field set.
`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

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

Responses

200: A page of records.

Headers: RateLimit, RateLimit-Policy.

Member	Type	Always present	Description
`order_id`	string	yes	Format: an order id: ord_ followed by a 26 character ULID in upper case Crockford base32, such as ord_01JB4N9S3W2X6Y7Z8A1B2C3D4E.
`format`	`json`	yes
`fields`	array of string	yes	The field set's columns in this page.
`data`	array of `ContactRecord`	yes
`data[].id`	string	yes	The record id, pushed to CRMs as mydatahub_record_id.
`data[].dataset_version`	string	yes	The immutable weekly build a count is bound to, such as 2026-W39. The last 52 stay queryable.
`data[].contact`	object	yes
`data[].email`	object or null	yes
`data[].phone`	object or null	yes	Present when the field set includes telephone and a number is held.
`data[].company`	object	yes
`data[].site`	object	yes
`data[].compliance`	`ComplianceObject`	yes	Carried by every preview row, order record, lookup and enrichment, and repeated as CSV columns and as the MyDataHub property group on CRM push.
`data[].licence_expires_at`	string (date) or null	yes
`has_more`	boolean	yes
`next_cursor`	string or null	yes
`remaining`	integer (0 or more)	yes	Records after this page.
`approx_tokens`	integer (0 or more)	no	A rough token size of this page; pages stay under about 8,000 tokens.
`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.

Example response

{
  "order_id": "ord_01JB4N9S3W2X6Y7Z8A1B2C3D4E",
  "format": "json",
  "fields": ["first_name", "last_name", "title", "email", "phone", "company_name", "postcode"],
  "data": [
    {
      "id": "contact_01JA9X2V7XN3M9R6T1Y5W8ZAK8",
      "dataset_version": "2026-W39",
      "contact": {
        "first_name": "Jo",
        "last_name": "Example",
        "title": "Marketing Director",
        "title_family": "Marketing Director",
        "job_function": "Marketing",
        "job_level_rank": 6,
        "job_level": "Director"
      },
      "email": {
        "address": "[email protected]",
        "type": "named",
        "deliverability_score": 88,
        "verified_at": "2026-09-10",
        "result": "ok"
      },
      "phone": {
        "e164": "+441130000001",
        "line_type": "landline",
        "tps_ctps_status": "clear",
        "screened_at": "2026-09-12"
      },
      "company": {
        "name": "Example Manufacturing Ltd",
        "companies_house_number": "12345678",
        "status": "active",
        "type": "ltd",
        "subscriber_class": "ltd",
        "sic_2007": [
          {
            "code": "25620",
            "label": "Machining"
          }
        ],
        "employee_band": "100-199",
        "turnover_band": "11M-20M",
        "website_domain": "example.co.uk"
      },
      "site": {
        "address_lines": ["1 Example Street"],
        "town": "Leeds",
        "county": "West Yorkshire",
        "postcode": "LS11 5AA",
        "region": "yorkshire_and_the_humber"
      },
      "compliance": {
        "lawful_basis": "legitimate_interests_art6_1_f",
        "lia_ref": "EM-LIA-2026-03",
        "subscriber_class": "ltd",
        "corporate_subscriber": true,
        "email_marketing_basis": "pecr_corporate_subscriber",
        "subscriber_evidence": {
          "companies_house_number": "12345678",
          "company_type": "ltd"
        },
        "article14_status": "notified",
        "article14_notified_at": "2026-06-14",
        "notice_version": "2026-02",
        "provenance": {
          "company": {
            "source": "companies_house",
            "as_of": "2026-09-21"
          },
          "contact": {
            "source": "emailmovers_research",
            "compiled_at": "2026-05-02",
            "last_verified_at": "2026-08-30",
            "method": "telephone"
          },
          "email": {
            "verified_at": "2026-09-10",
            "result": "ok",
            "provider_location": "EU"
          }
        },
        "tps_ctps_status": "clear",
        "tps_ctps_screened_at": "2026-09-12",
        "tps_ctps_valid_until": "2026-10-10",
        "suppression_status": "none",
        "record_age_days": 147,
        "attribution": "Contains public sector information licensed under the Open Government Licence v3.0"
      },
      "licence_expires_at": "2027-09-26"
    }
  ],
  "has_more": true,
  "next_cursor": "b3JkXzAxSkI0TjlTM1cyWDZZN1o4QTFCMkMzRDRFOjUw",
  "remaining": 4950,
  "approx_tokens": 7400,
  "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).
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.
404	`not-found`	No such object for this organisation.
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.