Reference

Preview sample records

POST /v1/previews. Up to 25 masked sample rows from a seed fixed per audience, so a repeat returns the same rows.

Generated from the contractsView as Markdown

POST /v1/previews

Up to 25 masked sample rows from a seed fixed per audience, so a repeat returns the same rows. Each row has verification badges, why it matches and a provenance card with the compliance object. No rows when the count is under 25. Free.

Property	Value
Endpoint	`POST https://mydatahub.emailmovers.com/v1/previews`
Operation id	`createPreview`
Cost	Free (0 credits)
Access	No account needed. An API key or OAuth token with the scope `previews:read` is optional and adds your organisation's own figures.
MCP tool	`preview_records`
Tag	Counts

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.

Body

Member	Type	Required	Description
`audience`	string or `Audience`	no	An audience definition (mydatahub.audience/1) inline, or the aud_ id of a saved audience.
`count_id`	string	no	A count id instead of an audience.
`limit`	integer (1 to 25)	no	Rows to return, 1 to 25. Default 10. Default `10`.
`shuffle`	boolean	no	Draw a new seed. Counts against your rate budget and is logged. Default false, so a repeat returns the same rows. Default `false`.

Example request

curl -X POST "https://mydatahub.emailmovers.com/v1/previews" \
  -H "Content-Type: application/json" \
  --data '{
  "count_id": "cnt_7K2PQ4MAXN3R6TBY5WDZ",
  "limit": 10
}'

Responses

200: The sample.

Headers: RateLimit, RateLimit-Policy.

Member	Type	Always present	Description
`id`	string	yes	Format: a preview id: prv_ followed by a 26 character ULID in upper case Crockford base32, such as prv_01JB4H3M7Q2V7XN3M9R6T1Y5W8.
`count_id`	string	yes	Format: a count id: cnt_ followed by 20 base32 characters (A to Z and 2 to 7), such as cnt_7K2PQ4MAXN3R6TBY5WDZ.
`dataset_version`	string	yes	The immutable weekly build a count is bound to, such as 2026-W39. The last 52 stay queryable.
`seed`	string	yes	The seed the rows came from; the same audience gives the same seed.
`count`	integer (0 or more)	yes	The count the rows were drawn from, rounded as disclosure says.
`disclosure`	`Disclosure`	yes	Whether these numbers are exact or protected: "under 10" cells, rounding to 5 and secondary suppression for anonymous and trial callers.
`disclosure.level`	enum: `exact`, `rounded`	yes	exact for authenticated paid callers; rounded for anonymous and trial callers, whose counts under 100 and every cell are rounded to the nearest 5.
`disclosure.rounded_to`	integer or null	yes	5 when numbers are rounded; null when they are exact.
`disclosure.secondary_suppression`	boolean	yes	True when cross-tab or breakdown cells of 10 or more were hidden as "suppressed" so totals cannot be differenced.
`disclosure.notes`	array of string	yes
`rows`	array of `PreviewRow`	yes
`rows[].id`	string	yes	A session-scoped id standing in for the record. It never reveals contact_ ids.
`rows[].title`	string	yes
`rows[].job_level`	string or null	yes	The level, such as Director; null when the level is not known.
`rows[].job_function`	string or null	yes
`rows[].company`	object	yes
`rows[].site`	object	yes
`rows[].email_masked`	string or null	yes	First character of the local part plus the top level domain, such as j••••@••••.co.uk.
`rows[].email_type`	enum: `named`, `generic_local_part`, `generic_domain` or null	yes
`rows[].phone_masked`	string or null	yes	To the area code, such as 0113 ••• •••1.
`rows[].tps_ctps_status`	enum: `clear`, `tps_registered`, `ctps_registered`, `tps_or_ctps_registered`, `not_screened` or null	yes
`rows[].badges`	array of `VerifiedBadge` or `OtherBadge`	yes
`rows[].why_it_matches`	array of `WhyItMatches`	yes
`rows[].provenance`	`ProvenanceCard`	yes	The ICO due diligence answers for one record, as shown on the sample row.
`rows[].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.
`withheld`	object or null	yes	Rows held back: all of them when the count is under 25, or rows whose title fewer than 10 people hold.
`withheld.rows`	integer (0 or more)	yes
`withheld.reason`	string	yes
`masked`	`true`	yes
`watermark`	string or null	yes	The account id watermarked into sample CSVs; null when signed out.
`created_at`	string (date-time)	yes

Example response

{
  "id": "prv_01JB4H3M7Q2V7XN3M9R6T1Y5W8",
  "count_id": "cnt_7K2PQ4MAXN3R6TBY5WDZ",
  "dataset_version": "2026-W39",
  "seed": "7k2pq4ma",
  "count": 12840,
  "rows": [
    {
      "id": "prv_01JB4H3N2V7XN3M9R6T1Y5W8ZA",
      "title": "Marketing Director",
      "job_level": "Director",
      "job_function": "Marketing",
      "company": {
        "name": "Example Manufacturing Ltd",
        "companies_house_number": "12345678",
        "status": "active",
        "employee_band": "100-199",
        "sic_2007": ["C"]
      },
      "site": {
        "town": "Leeds",
        "postcode_district": "LS11",
        "region": "yorkshire_and_the_humber"
      },
      "email_masked": "j••••@••••.co.uk",
      "email_type": "named",
      "phone_masked": "0113 ••• •••1",
      "tps_ctps_status": "clear",
      "badges": [
        {
          "badge": "verified",
          "date": "2026-09-10",
          "label": "Verified 10 September 2026"
        }
      ],
      "why_it_matches": [
        {
          "pointer": "/where/all/0",
          "field": "contact.title",
          "value": "Marketing Director",
          "explanation": "Marketing Director matched marketing manager through expansion."
        },
        {
          "pointer": "/where/all/3",
          "field": "company.employee_band",
          "value": "100-199",
          "explanation": "Employees 120, inside 50 or more."
        }
      ],
      "provenance": {
        "sources": {
          "title": "emailmovers_research",
          "company": "companies_house",
          "email": "emailmovers_research"
        },
        "first_seen_at": "2026-05-02",
        "last_verified_at": "2026-08-30",
        "method": "telephone",
        "companies_house_number": "12345678",
        "company_status": "active",
        "article14_status": "notified",
        "tps_ctps_screened_at": "2026-09-12",
        "lawful_basis": "legitimate_interests_art6_1_f"
      },
      "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"
      }
    }
  ],
  "withheld": null,
  "masked": true,
  "watermark": null,
  "created_at": "2026-09-26T10:15:00Z",
  "disclosure": {
    "level": "rounded",
    "rounded_to": 5,
    "secondary_suppression": false,
    "notes": [
      "Counts under 100 and every breakdown cell are rounded to the nearest 5 for anonymous and trial callers."
    ]
  }
}

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