The audience definition

An audience is one JSON document, and the app's chips, a brief compiled by an agent and a saved audience (aud_) all produce the same one. It has 6 members, 32 fields in 6 groups and 11 operators, and the same document gives the same count over REST, MCP and in the app. The JSON Schema is at /reference/audience.schema.json.

A worked example

This audience is "marketing managers and above at manufacturing companies with 50 or more staff within 20 miles of Leeds, excluding my suppression list".

{
  "schema": "mydatahub.audience/1",
  "dataset": "uk_contacts",
  "dataset_version": "2026-W39",
  "where": {
    "all": [
      { "field": "contact.title", "op": "matches", "terms": ["marketing manager"], "mode": "contains",
        "expand": ["plural_singular", "department_synonyms", "ampersand_and", "abbreviations"] },
      { "field": "contact.job_level_rank", "op": "in", "values": [1, 2, 3, 4, 5, 6, 8, 9] },
      { "field": "company.sic_2007", "op": "in", "values": ["C"] },
      { "field": "company.employee_band", "op": "gte", "value": "50-99" },
      { "field": "site.location", "op": "within_radius", "centre": { "place": "Leeds" }, "radius_miles": 20 },
      { "not": { "field": "email.address_sha256", "op": "in_list", "list_id": "sup_01JB4H7Q2V7XN3M9R6T1Y5W8ZA" } }
    ]
  },
  "email_policy": { "min_deliverability_score": 70, "allow_catch_all": false },
  "dedupe": "none"
}

Read it top to bottom. The all group is an AND of six nodes.

1. A job title with its expansions.
2. The seniority ranks for Manager and above.
3. The SIC section for manufacturing.
4. 50 or more employees.
5. A 20 mile radius around Leeds.
6. A not that removes your suppression list.

Send it to POST /v1/counts as audience, or save it with POST /v1/audiences.

Two rules apply when you send this example as written. Leeds is ambiguous, so the engine refuses it with 422 validation-failed and the candidate ONS codes in did_you_mean. Pin one with code, such as { "place": "Leeds", "code": "E08000035" } for the metropolitan district.

Free text job titles, contact.title with matches, also need a free account. An anonymous request that uses one gets 401 account-required.

Members

An audience has these top-level members. Only schema is required, and parsing never fills a default.

level and breakdown_by belong to the count request, not the audience. dedupe takes none, one_per_company or one_per_site.

Groups and filters

A node in where is a group or a filter. A group is all (AND), any (OR) or not (negation), and groups nest.

A tree may nest at most 32 groups deep and hold at most 1,000 nodes, so a malformed body gets a 422 problem, never a crash. A filter has a field, an op and the operands that op takes.

Each operator takes its own operands.

A boolean field such as email.exists uses in with [true] or [false], because there is no equality operator.

Fields

Fields are grouped by entity: company., site., contact., email., phone. and signal.. The catalogue is public. GET /v1/catalogue/filters lists every field with its type, operators and value count, and GET /v1/catalogue/filters/{dimension}/values?q= searches the values of one field with a contact and company count for each. The list_filters and search_filter_values tools do the same.

A field marked for breakdown can also appear in breakdown_by. See Counts and breakdowns.

Job titles

contact.title with matches is a keyword match. Title expansion is data, not code: a dictionary of normalised titles and a synonyms table keyed by expansion set. The server returns the expanded list with a count per term, from POST /v1/job-titles/expand and with every count, so nothing is hidden behind a toggle.

The mode is contains by default, starts_with narrows it, and exact takes a verbatim list with no expansion. The expand member names the sets to apply.

Left out, the first four apply. An empty list applies none, and permutations is opt in because it broadens most.

Remove a term by adding it to exclude_terms. The exclusion is written into the definition, so the edited count stays reproducible when the title dictionary changes. See Versions and reproducibility.

Seniority and bundles

contact.job_level_rank runs from 1 (Owner) to 13 (Volunteer). Rank 1 is the most senior, so "and above" is lte. A contact with no known level has rank 0, Level not known: only in with 0 matches it, so no range and no "and above" includes it, and its records and samples show no level.

A bundle is a named shortcut written as { "bundle": "sdm" }. The server swaps it for its fragment before the count id is hashed, so the effective definition holds the fragment and not the name.

Geography

Every site carries ONS codes for region, county, local authority, ward, LSOA and ITL levels, plus latitude, longitude and an H3 cell, from the quarterly ONS Postcode Directory under the Open Government Licence v3.0.

• Region, county and town. Use in with codes from the catalogue. The Crown Dependencies are one region value.
• Postcode. Use in with a hierarchical code: area LS, district LS1, sector LS1 4 or unit LS1 4AP. A sector needs its space, because LS14 is the district LS14. There is no starts_with operator on postcodes.
• Radius. within_radius takes a centre and radius_miles from 1 to 100. The centre is exactly one of { "place": "Leeds" }, { "postcode": "M1 1AE" } or { "lat": 53.8, "lon": -1.55 }. A radius under 5 miles needs a free account.

An ambiguous place name such as Leeds comes back from POST /v1/locations/resolve as candidates, never as a silent choice. Pin one with { "place": "Leeds", "code": "..." } using the ONS code from the candidate. London (33 boroughs including the City of London) and Yorkshire (North, South and West Yorkshire and the East Riding) remain as named geography sets.

Premium records

contact.premium keeps premium records: a contact at an active company with a LinkedIn profile, at launch in the premium export of a stated date (the dataset version's as-of date), and later validated within the last 12 months from the validations feed. Use in with [true] for premium records only or [false] for the rest.

{ "field": "contact.premium", "op": "in", "values": [true] }

Two more fields come from the same data. contact.last_validated_at with since keeps records validated in the last N days. contact.company_contact_rank with lte keeps at most that many contacts per company, most senior first and Level not known last; the rank is set across the whole dataset version, so other filters can leave a company with fewer. The server never applies either one for you.

Premium is the default view in the app and in a compiled brief, never in a count: an audience you send is counted exactly as written. Every count shows the premium figure beside all records, so turning premium on or off never hides the other number. See Counts and breakdowns.

A dataset version without premium data cannot answer these fields. A filter on one gets 422 validation-failed with the reason, and GET /v1/catalogue/filters leaves it out, so a count is never 0 for want of data.

Suppressions inside an audience

in_list removes the records on one of your lists. Each list has a kind that must match the field: hashed email on email.address_sha256, domain on email.domain_sha256, phone on phone.e164_sha256, company number on company.companies_house_number and title term on contact.title.

Every count reports how many records each list removed in compliance_summary.suppressed_removed. See Suppressions and objections.

Defaults the server fills

You do not have to ask for these. The server applies each one, writes it into the effective definition it returns, and shows it as a toggle with the number it removed.

The server also fills the current dataset_version and the email policy: a deliverability score of at least 70, with catch-all addresses excluded. Older schema versions are upgraded by a pure function, so an audience saved in 2026 still compiles in 2028.

More examples

New incorporations in London, at senior decision makers with an email, using a bundle and a signal.

{
  "schema": "mydatahub.audience/1",
  "dataset": "uk_contacts",
  "where": {
    "all": [
      { "field": "signal.type", "op": "since", "values": ["company.incorporated"], "days": 90 },
      { "field": "site.region", "op": "in", "values": ["london"] },
      { "bundle": "sdm" },
      { "field": "email.exists", "op": "in", "values": [true] }
    ]
  }
}

Marketing at director level and above, or sales directors other than interim ones, excluding sole traders, partnerships and dissolved companies, with any, all and not nested.

{
  "schema": "mydatahub.audience/1",
  "dataset": "uk_contacts",
  "where": {
    "all": [
      {
        "any": [
          {
            "all": [
              { "field": "contact.title", "op": "matches", "terms": ["marketing"] },
              { "field": "contact.job_level_rank", "op": "lte", "value": 6 }
            ]
          },
          {
            "all": [
              { "field": "contact.title", "op": "matches", "terms": ["sales director"] },
              { "not": { "field": "contact.title", "op": "matches", "terms": ["Sales Director (Interim)"], "mode": "exact" } }
            ]
          }
        ]
      },
      {
        "not": {
          "any": [
            { "field": "company.subscriber_class", "op": "in", "values": ["sole_trader", "ordinary_partnership"] },
            { "field": "company.status", "op": "in", "values": ["dissolved", "liquidation"] }
          ]
        }
      }
    ]
  }
}

Managers and above at engineering companies in the Midlands, one contact per company.

{
  "schema": "mydatahub.audience/1",
  "dataset": "uk_contacts",
  "dataset_version": "2026-W39",
  "where": {
    "all": [
      { "bundle": "manager_and_above" },
      { "field": "company.sic_2007", "op": "in", "values": ["25", "28", "29"] },
      { "field": "site.region", "op": "in", "values": ["east_midlands", "west_midlands"] },
      { "field": "company.turnover_band", "op": "gte", "value": "2.1M-5M" }
    ]
  },
  "dedupe": "one_per_company"
}

Build one from a brief

Send plain English to POST /v1/audiences/compile or call compile_audience. You get the audience, a one-line readback, a chip for each phrase with the words it came from, and any questions that need an answer, such as which Manchester. Nothing ambiguous is resolved silently.

{ "brief": "300 finance directors at law firms in Manchester" }

The chips are the truth and the count is the receipt. Run the compiled audience through POST /v1/counts to see its size.

Validate a definition

Validation errors are RFC 9457 problems. Each entry in errors has a JSON pointer such as /audience/where/all/0/field, a message and, where there is one, did_you_mean.

A field, operator, mode or code that is not recognised comes back with its closest valid values. See Errors.

For a local check, validate against the published JSON Schema, whose $id is https://mydatahub.emailmovers.com/schemas/audience/1.json. The schema holds which operator each field takes and the per-field value rules. One rule it cannot express is that a between range must be in order, which the server checks.

Next steps

• Run an audience through Counts and breakdowns.
• Reproduce a count later with Versions and reproducibility.
• See the field values at REST reference: List filter fields.