Server definition
- Hash
- sha256:b9724f9ef3ac53b3dec2e11a8a6c90f14b7ea37d0f7bc438fcc33900d4b17f27
- What it is
- What a remote MCP server returned when asked what it offers: 22 tools
The blob, as servednamed by its sha256
{
"instructions": "Count first, preview second, quote third, then create_order. Counting, previewing and quoting are free; one credit buys one complete UK record. create_order needs a quote_id from quote_order.",
"tools": [
{
"description": "Checks the suppression status of up to 1,000 delivered records by record id, as of now, and names the lists that suppress each. Use it before every send, because objections reach records after delivery. Free; it needs suppressions:read. Leave suppressed records out of the send, and call report_objection when someone objects. Lawful basis is UK GDPR Article 6(1)(f) legitimate interests; email audiences include corporate subscribers only by default (PECR), so sole traders and ordinary partnerships are left out unless the toggle is changed.",
"inputSchema": {
"additionalProperties": false,
"description": "Records to check before a send.",
"properties": {
"record_ids": {
"items": {
"description": "Format: a contact id: contact_ followed by a 26 character ULID in upper case Crockford base32, such as contact_01JA9X2V7XN3M9R6T1Y5W8ZAK8.",
"examples": [
"contact_01JA9X2V7XN3M9R6T1Y5W8ZAK8"
],
"pattern": "^contact_[0-7][0-9A-HJKMNP-TV-Z]{25}$",
"type": "string"
},
"maxItems": 1000,
"minItems": 1,
"type": "array"
}
},
"required": [
"record_ids"
],
"type": "object"
},
"name": "check_suppression",
"outputSchema": {
"description": "Suppression status per record, as of now.",
"properties": {
"checked_at": {
"format": "date-time",
"type": "string"
},
"results": {
"items": {
"properties": {
"list_ids": {
"items": {
"description": "Format: a suppression list id: sup_ followed by a 26 character ULID in upper case Crockford base32, such as sup_01JB4H7Q2V7XN3M9R6T1Y5W8ZA.",
"examples": [
"sup_01JB4H7Q2V7XN3M9R6T1Y5W8ZA"
],
"pattern": "^sup_[0-7][0-9A-HJKMNP-TV-Z]{25}$",
"type": "string"
},
"type": "array"
},
"record_id": {
"description": "Format: a contact id: contact_ followed by a 26 character ULID in upper case Crockford base32, such as contact_01JA9X2V7XN3M9R6T1Y5W8ZAK8.",
"examples": [
"contact_01JA9X2V7XN3M9R6T1Y5W8ZAK8"
],
"pattern": "^contact_[0-7][0-9A-HJKMNP-TV-Z]{25}$",
"type": "string"
},
"suppressed": {
"type": "boolean"
},
"suppression_status": {
"enum": [
"none",
"objected_to_emailmovers",
"objected_to_licensee",
"deceased",
"left_company"
],
"type": "string"
}
},
"required": [
"record_id",
"suppressed",
"suppression_status",
"list_ids"
],
"type": "object"
},
"type": "array"
}
},
"required": [
"checked_at",
"results"
],
"type": "object"
}
},
{
"description": "Compiles a plain English brief, such as 300 finance directors at law firms in Manchester, into an audience definition with a one-sentence readback, editable chips and any questions to answer first. Use it first for a request in words, read the readback to the user and settle the questions before counting. Words that match no filter come back in unrecognised, never guessed. Free and needs no account; pass the audience to count_audience next. Lawful basis is UK GDPR Article 6(1)(f) legitimate interests; email audiences include corporate subscribers only by default (PECR), so sole traders and ordinary partnerships are left out unless the toggle is changed.",
"inputSchema": {
"additionalProperties": false,
"description": "A brief to compile into an audience definition.",
"properties": {
"brief": {
"description": "A plain English brief, such as \"300 finance directors at law firms in Manchester\".",
"maxLength": 2000,
"minLength": 3,
"type": "string"
},
"dataset": {
"description": "The dataset an audience draws from. uk_contacts is live; ie_contacts and global_contacts are listed but not yet served.",
"enum": [
"uk_contacts",
"ie_contacts",
"global_contacts"
],
"type": "string"
}
},
"required": [
"brief"
],
"type": "object"
},
"name": "compile_audience",
"outputSchema": {
"$defs": {
"AllGroup": {
"additionalProperties": false,
"description": "AND: every node inside must match.",
"properties": {
"all": {
"items": {
"$ref": "#/$defs/WhereNode"
},
"minItems": 1,
"type": "array"
}
},
"required": [
"all"
],
"type": "object"
},
"AnyGroup": {
"additionalProperties": false,
"description": "OR: at least one node inside must match.",
"properties": {
"any": {
"items": {
"$ref": "#/$defs/WhereNode"
},
"minItems": 1,
"type": "array"
}
},
"required": [
"any"
],
"type": "object"
},
"Audience": {
"additionalProperties": false,
"description": "Who you want, as filters grouped by entity (company., site., contact., email., phone., signal.). The server fills its defaults (active companies, named emails, corporate subscribers, the current dataset_version) and returns the effective definition with every count.",
"properties": {
"dataset": {
"description": "The dataset an audience draws from. uk_contacts is live; ie_contacts and global_contacts are listed but not yet served.",
"enum": [
"uk_contacts",
"ie_contacts",
"global_contacts"
],
"type": "string"
},
"dataset_version": {
"description": "The weekly build to count against, such as 2026-W39. Left out, the current version is filled in and returned.",
"examples": [
"2026-W39"
],
"pattern": "^[0-9]{4}-W(0[1-9]|[1-4][0-9]|5[0-3])$",
"type": "string"
},
"dedupe": {
"description": "none keeps every matching contact, one_per_company keeps one contact per company, one_per_site keeps one per site. Default none.",
"enum": [
"none",
"one_per_company",
"one_per_site"
],
"type": "string"
},
"email_policy": {
"$ref": "#/$defs/EmailPolicy"
},
"schema": {
"const": "mydatahub.audience/1",
"description": "The definition's namespace and version. Older versions are upgraded by a pure function.",
"type": "string"
},
"where": {
"$ref": "#/$defs/WhereNode",
"description": "The filters. Left out, the audience is the whole dataset after the defaults."
}
},
"required": [
"schema"
],
"title": "MyDataHub audience definition (mydatahub.audience/1)",
"type": "object"
},
"BetweenFilter": {
"additionalProperties": false,
"description": "The field lies from one value to another inclusive, over the field's order.",
"examples": [
{
"field": "company.employee_band",
"from": "10-19",
"op": "between",
"to": "200-349"
}
],
"properties": {
"field": {
"enum": [
"company.employee_band",
"company.turnover_band",
"company.fleet_band",
"contact.job_level_rank",
"email.deliverability_score"
],
"type": "string"
},
"from": {
"anyOf": [
{
"maxLength": 200,
"minLength": 1,
"type": "string"
},
{
"type": "number"
}
],
"description": "A band code or a number from the field's order."
},
"op": {
"const": "between",
"type": "string"
},
"to": {
"anyOf": [
{
"maxLength": 200,
"minLength": 1,
"type": "string"
},
{
"type": "number"
}
],
"description": "A band code or a number from the field's order."
}
},
"required": [
"field",
"op",
"from",
"to"
],
"type": "object"
},
"BriefQuestion": {
"description": "An ambiguity to answer before counting.",
"properties": {
"id": {
"type": "string"
},
"options": {
"items": {
"properties": {
"filter": {
"$ref": "#/$defs/Filter"
},
"label": {
"type": "string"
}
},
"required": [
"label",
"filter"
],
"type": "object"
},
"type": "array"
},
"text": {
"type": "string"
}
},
"required": [
"id",
"text",
"options"
],
"type": "object"
},
"BundleNode": {
"additionalProperties": false,
"description": "A title bundle, resolved to its filters in the effective definition: sdm (senior decision makers), manager_and_above (managers and above), owner_managed (owner managed).",
"properties": {
"bundle": {
"enum": [
"sdm",
"manager_and_above",
"owner_managed"
],
"type": "string"
}
},
"required": [
"bundle"
],
"type": "object"
},
"Chip": {
"description": "One visible, editable filter compiled from the brief.",
"properties": {
"from_brief": {
"description": "The words of the brief it came from.",
"type": "string"
},
"label": {
"description": "What the chip reads, such as Within 20 miles of Leeds.",
"type": "string"
},
"pointer": {
"description": "JSON pointer to the filter inside audience.",
"type": "string"
}
},
"required": [
"label",
"pointer",
"from_brief"
],
"type": "object"
},
"EmailPolicy": {
"additionalProperties": false,
"description": "Email quality floor. Defaults: min_deliverability_score 70, allow_catch_all false.",
"properties": {
"allow_catch_all": {
"description": "Whether catch-all addresses count. Default false.",
"type": "boolean"
},
"min_deliverability_score": {
"description": "Lowest deliverability score counted, 0 to 100. Default 70.",
"maximum": 100,
"minimum": 0,
"type": "integer"
}
},
"type": "object"
},
"Filter": {
"description": "One criterion: a field from GET /v1/catalogue/filters, an operator and its operands. Exclusions nest under not.",
"oneOf": [
{
"$ref": "#/$defs/InFilter"
},
{
"$ref": "#/$defs/BetweenFilter"
},
{
"$ref": "#/$defs/GteFilter"
},
{
"$ref": "#/$defs/LteFilter"
},
{
"$ref": "#/$defs/MatchesFilter"
},
{
"$ref": "#/$defs/WithinRadiusFilter"
},
{
"$ref": "#/$defs/InListFilter"
},
{
"$ref": "#/$defs/SinceFilter"
}
]
},
"GteFilter": {
"additionalProperties": false,
"description": "The field is at or after the value in its order: for bands, the band and every larger one.",
"examples": [
{
"field": "company.employee_band",
"op": "gte",
"value": "50-99"
}
],
"properties": {
"field": {
"enum": [
"company.employee_band",
"company.turnover_band",
"company.fleet_band",
"contact.job_level_rank",
"email.deliverability_score"
],
"type": "string"
},
"op": {
"const": "gte",
"type": "string"
},
"value": {
"anyOf": [
{
"maxLength": 200,
"minLength": 1,
"type": "string"
},
{
"type": "number"
}
],
"description": "A band code or a number from the field's order."
}
},
"required": [
"field",
"op",
"value"
],
"type": "object"
},
"InFilter": {
"additionalProperties": false,
"description": "The field holds one of the listed codes.",
"examples": [
{
"field": "company.sic_2007",
"op": "in",
"values": [
"C"
]
}
],
"properties": {
"field": {
"enum": [
"company.sic_2007",
"company.business_class",
"company.employee_band",
"company.turnover_band",
"company.fleet_band",
"company.type",
"company.status",
"company.subscriber_class",
"company.companies_house_number",
"site.region",
"site.county",
"site.town",
"site.postcode",
"contact.title_family",
"contact.job_function",
"contact.job_level_rank",
"contact.premium",
"email.exists",
"email.type",
"phone.exists",
"phone.tps_ctps_status"
],
"type": "string"
},
"op": {
"const": "in",
"type": "string"
},
"values": {
"items": {
"anyOf": [
{
"maxLength": 200,
"minLength": 1,
"type": "string"
},
{
"type": "number"
},
{
"type": "boolean"
}
],
"description": "A code, a rank or a boolean, as the field's catalogue lists it."
},
"maxItems": 10000,
"minItems": 1,
"type": "array"
}
},
"required": [
"field",
"op",
"values"
],
"type": "object"
},
"InListFilter": {
"additionalProperties": false,
"description": "The record's hashed email, domain, phone, company number or title term is on a suppression list. Usually nested under not; each list reports the records it removed.",
"examples": [
{
"field": "email.address_sha256",
"list_id": "sup_01JB4H7Q2V7XN3M9R6T1Y5W8ZA",
"op": "in_list"
}
],
"properties": {
"field": {
"enum": [
"company.companies_house_number",
"contact.title",
"email.address_sha256",
"email.domain_sha256",
"phone.e164_sha256"
],
"type": "string"
},
"list_id": {
"description": "Format: a suppression list id: sup_ followed by a 26 character ULID in upper case Crockford base32, such as sup_01JB4H7Q2V7XN3M9R6T1Y5W8ZA.",
"examples": [
"sup_01JB4H7Q2V7XN3M9R6T1Y5W8ZA"
],
"pattern": "^sup_[0-7][0-9A-HJKMNP-TV-Z]{25}$",
"type": "string"
},
"op": {
"const": "in_list",
"type": "string"
}
},
"required": [
"field",
"op",
"list_id"
],
"type": "object"
},
"LteFilter": {
"additionalProperties": false,
"description": "The field is at or before the value in its order. Rank 1 is the most senior, so Director and above is contact.job_level_rank lte 6.",
"examples": [
{
"field": "contact.job_level_rank",
"op": "lte",
"value": 6
}
],
"properties": {
"field": {
"enum": [
"company.employee_band",
"company.turnover_band",
"company.fleet_band",
"contact.job_level_rank",
"contact.company_contact_rank",
"email.deliverability_score"
],
"type": "string"
},
"op": {
"const": "lte",
"type": "string"
},
"value": {
"anyOf": [
{
"maxLength": 200,
"minLength": 1,
"type": "string"
},
{
"type": "number"
}
],
"description": "A band code or a number from the field's order."
}
},
"required": [
"field",
"op",
"value"
],
"type": "object"
},
"MatchesFilter": {
"additionalProperties": false,
"allOf": [
{
"if": {
"properties": {
"mode": {
"const": "exact"
}
},
"required": [
"mode"
],
"type": "object"
},
"then": {
"properties": {
"exclude_terms": {
"maxItems": 0,
"type": "array"
},
"expand": {
"maxItems": 0,
"type": "array"
}
},
"type": "object"
}
}
],
"description": "Job title keyword match. mode contains (the default) or starts_with expands each term with the expansion sets; mode exact matches verbatim titles. Every expanded term is returned with the count.",
"examples": [
{
"expand": [
"plural_singular",
"department_synonyms",
"ampersand_and",
"abbreviations"
],
"field": "contact.title",
"mode": "contains",
"op": "matches",
"terms": [
"marketing manager"
]
}
],
"properties": {
"exclude_terms": {
"description": "Expanded terms removed by hand. Kept in the definition so the count stays reproducible when the title dictionary changes.",
"items": {
"maxLength": 200,
"minLength": 1,
"type": "string"
},
"maxItems": 500,
"type": "array"
},
"expand": {
"description": "Expansion sets to apply, each once: plural_singular, department_synonyms, ampersand_and, abbreviations, permutations. Left out, the first four apply; an empty list applies none. Not used with mode exact.",
"items": {
"enum": [
"plural_singular",
"department_synonyms",
"ampersand_and",
"abbreviations",
"permutations"
],
"type": "string"
},
"maxItems": 5,
"type": "array",
"uniqueItems": true
},
"field": {
"enum": [
"contact.title"
],
"type": "string"
},
"mode": {
"description": "contains (the default) matches titles containing a term, starts_with matches titles beginning with it, exact takes verbatim titles with no expansion.",
"enum": [
"contains",
"starts_with",
"exact"
],
"type": "string"
},
"op": {
"const": "matches",
"type": "string"
},
"terms": {
"items": {
"maxLength": 200,
"minLength": 1,
"type": "string"
},
"maxItems": 500,
"minItems": 1,
"type": "array"
}
},
"required": [
"field",
"op",
"terms"
],
"type": "object"
},
"NotGroup": {
"additionalProperties": false,
"description": "Negation: the single node inside must not match.",
"properties": {
"not": {
"$ref": "#/$defs/WhereNode"
}
},
"required": [
"not"
],
"type": "object"
},
"PlaceCentre": {
"additionalProperties": false,
"description": "A named place. Ambiguous names come back from resolve_location as candidates, never a silent choice.",
"properties": {
"code": {
"description": "The ONS geography code of the chosen candidate when resolve_location found more than one, such as E08000035 for the Leeds district.",
"maxLength": 20,
"minLength": 1,
"type": "string"
},
"place": {
"description": "A place name, resolved with resolve_location, such as Leeds.",
"maxLength": 100,
"minLength": 1,
"type": "string"
}
},
"required": [
"place"
],
"type": "object"
},
"PointCentre": {
"additionalProperties": false,
"description": "A latitude and longitude in WGS84 degrees.",
"properties": {
"lat": {
"maximum": 61,
"minimum": 49,
"type": "number"
},
"lon": {
"maximum": 2,
"minimum": -9,
"type": "number"
}
},
"required": [
"lat",
"lon"
],
"type": "object"
},
"PostcodeCentre": {
"additionalProperties": false,
"description": "A postcode centroid from ONSPD.",
"properties": {
"postcode": {
"description": "The centroid of a postcode unit, sector, district or area, such as LS1 4AP.",
"pattern": "^[A-Za-z]{1,2}([0-9][0-9A-Za-z]?( [0-9]([A-Za-z]{2})?| ?[0-9][A-Za-z]{2})?)?$",
"type": "string"
}
},
"required": [
"postcode"
],
"type": "object"
},
"RadiusCentre": {
"anyOf": [
{
"$ref": "#/$defs/PlaceCentre"
},
{
"$ref": "#/$defs/PostcodeCentre"
},
{
"$ref": "#/$defs/PointCentre"
}
],
"description": "The centre of a radius: a place, a postcode or a latitude and longitude."
},
"SinceFilter": {
"additionalProperties": false,
"description": "Within the last N days: a date field, or a Companies House signal of the listed types on signal.type.",
"examples": [
{
"days": 90,
"field": "signal.type",
"op": "since",
"values": [
"company.incorporated"
]
}
],
"properties": {
"days": {
"maximum": 3650,
"minimum": 1,
"type": "integer"
},
"field": {
"enum": [
"contact.last_validated_at",
"email.last_verified_at",
"signal.type",
"signal.observed_at"
],
"type": "string"
},
"op": {
"const": "since",
"type": "string"
},
"values": {
"description": "For signal.type only: the signal types to look for, such as company.incorporated.",
"items": {
"maxLength": 200,
"minLength": 1,
"type": "string"
},
"maxItems": 10000,
"minItems": 1,
"type": "array"
}
},
"required": [
"field",
"op",
"days"
],
"type": "object"
},
"WhereNode": {
"anyOf": [
{
"$ref": "#/$defs/AllGroup"
},
{
"$ref": "#/$defs/AnyGroup"
},
{
"$ref": "#/$defs/NotGroup"
},
{
"$ref": "#/$defs/BundleNode"
},
{
"$ref": "#/$defs/Filter"
}
],
"description": "A group (all, any, not), a title bundle or a filter. Groups nest up to 32 deep, and a where tree holds up to 1,000 filters, groups and bundles."
},
"WithinRadiusFilter": {
"additionalProperties": false,
"description": "Sites within radius_miles of the centre. The count reports the centroid used and the postcodes matched.",
"examples": [
{
"centre": {
"place": "Leeds"
},
"field": "site.location",
"op": "within_radius",
"radius_miles": 20
}
],
"properties": {
"centre": {
"$ref": "#/$defs/RadiusCentre"
},
"field": {
"enum": [
"site.location"
],
"type": "string"
},
"op": {
"const": "within_radius",
"type": "string"
},
"radius_miles": {
"description": "Radius in miles, 1 to 100. Under 5 miles needs an account.",
"maximum": 100,
"minimum": 1,
"type": "number"
}
},
"required": [
"field",
"op",
"centre",
"radius_miles"
],
"type": "object"
}
},
"description": "An audience definition from a brief, with its chips and any questions.",
"properties": {
"audience": {
"$ref": "#/$defs/Audience"
},
"chips": {
"items": {
"$ref": "#/$defs/Chip"
},
"type": "array"
},
"quantity": {
"anyOf": [
{
"minimum": 0,
"type": "integer"
},
{
"type": "null"
}
],
"description": "A quantity named in the brief, such as 300, for quote_order limit."
},
"questions": {
"items": {
"$ref": "#/$defs/BriefQuestion"
},
"type": "array"
},
"readback": {
"description": "The audience in one sentence, to confirm with the person.",
"type": "string"
},
"unrecognised": {
"description": "Words of the brief that matched no filter, shown rather than guessed.",
"items": {
"type": "string"
},
"type": "array"
}
},
"required": [
"audience",
"readback",
"chips",
"questions",
"unrecognised",
"quantity"
],
"type": "object"
}
},
{
"description": "Counts UK contacts and companies matching an audience, inline or a saved aud_ id, and returns Total, New to you and Emailable, up to three breakdowns, quality, the compliance summary, a price estimate and a count id. Use it whenever a filter changes, and before preview_records or quote_order, which both take the count id. Free and needs no account; anonymous and trial callers see counts under 100 and breakdown cells rounded to the nearest 5 (disclosure says which), and exact small counts need a paid plan. It returns no contact details, and over MCP a cross-tab holds at most 200 cells (truncated true; GET /v1/counts/{id} has the rest). Lawful basis is UK GDPR Article 6(1)(f) legitimate interests; email audiences include corporate subscribers only by default (PECR), so sole traders and ordinary partnerships are left out unless the toggle is changed.",
"inputSchema": {
"$defs": {
"AllGroup": {
"additionalProperties": false,
"description": "AND: every node inside must match.",
"properties": {
"all": {
"items": {
"$ref": "#/$defs/WhereNode"
},
"minItems": 1,
"type": "array"
}
},
"required": [
"all"
],
"type": "object"
},
"AnyGroup": {
"additionalProperties": false,
"description": "OR: at least one node inside must match.",
"properties": {
"any": {
"items": {
"$ref": "#/$defs/WhereNode"
},
"minItems": 1,
"type": "array"
}
},
"required": [
"any"
],
"type": "object"
},
"Audience": {
"additionalProperties": false,
"description": "Who you want, as filters grouped by entity (company., site., contact., email., phone., signal.). The server fills its defaults (active companies, named emails, corporate subscribers, the current dataset_version) and returns the effective definition with every count.",
"properties": {
"dataset": {
"description": "The dataset an audience draws from. uk_contacts is live; ie_contacts and global_contacts are listed but not yet served.",
"enum": [
"uk_contacts",
"ie_contacts",
"global_contacts"
],
"type": "string"
},
"dataset_version": {
"description": "The weekly build to count against, such as 2026-W39. Left out, the current version is filled in and returned.",
"examples": [
"2026-W39"
],
"pattern": "^[0-9]{4}-W(0[1-9]|[1-4][0-9]|5[0-3])$",
"type": "string"
},
"dedupe": {
"description": "none keeps every matching contact, one_per_company keeps one contact per company, one_per_site keeps one per site. Default none.",
"enum": [
"none",
"one_per_company",
"one_per_site"
],
"type": "string"
},
"email_policy": {
"$ref": "#/$defs/EmailPolicy"
},
"schema": {
"const": "mydatahub.audience/1",
"description": "The definition's namespace and version. Older versions are upgraded by a pure function.",
"type": "string"
},
"where": {
"$ref": "#/$defs/WhereNode",
"description": "The filters. Left out, the audience is the whole dataset after the defaults."
}
},
"required": [
"schema"
],
"title": "MyDataHub audience definition (mydatahub.audience/1)",
"type": "object"
},
"AudienceRef": {
"anyOf": [
{
"description": "Format: an audience id: aud_ followed by a 26 character ULID in upper case Crockford base32, such as aud_01JB4H2K9V6XN3M9R6T1Y5W8ZA.",
"examples": [
"aud_01JB4H2K9V6XN3M9R6T1Y5W8ZA"
],
"pattern": "^aud_[0-7][0-9A-HJKMNP-TV-Z]{25}$",
"type": "string"
},
{
"$ref": "#/$defs/Audience"
}
],
"description": "An audience definition (mydatahub.audience/1) inline, or the aud_ id of a saved audience."
},
"BetweenFilter": {
"additionalProperties": false,
"description": "The field lies from one value to another inclusive, over the field's order.",
"examples": [
{
"field": "company.employee_band",
"from": "10-19",
"op": "between",
"to": "200-349"
}
],
"properties": {
"field": {
"enum": [
"company.employee_band",
"company.turnover_band",
"company.fleet_band",
"contact.job_level_rank",
"email.deliverability_score"
],
"type": "string"
},
"from": {
"anyOf": [
{
"maxLength": 200,
"minLength": 1,
"type": "string"
},
{
"type": "number"
}
],
"description": "A band code or a number from the field's order."
},
"op": {
"const": "between",
"type": "string"
},
"to": {
"anyOf": [
{
"maxLength": 200,
"minLength": 1,
"type": "string"
},
{
"type": "number"
}
],
"description": "A band code or a number from the field's order."
}
},
"required": [
"field",
"op",
"from",
"to"
],
"type": "object"
},
"BundleNode": {
"additionalProperties": false,
"description": "A title bundle, resolved to its filters in the effective definition: sdm (senior decision makers), manager_and_above (managers and above), owner_managed (owner managed).",
"properties": {
"bundle": {
"enum": [
"sdm",
"manager_and_above",
"owner_managed"
],
"type": "string"
}
},
"required": [
"bundle"
],
"type": "object"
},
"EmailPolicy": {
"additionalProperties": false,
"description": "Email quality floor. Defaults: min_deliverability_score 70, allow_catch_all false.",
"properties": {
"allow_catch_all": {
"description": "Whether catch-all addresses count. Default false.",
"type": "boolean"
},
"min_deliverability_score": {
"description": "Lowest deliverability score counted, 0 to 100. Default 70.",
"maximum": 100,
"minimum": 0,
"type": "integer"
}
},
"type": "object"
},
"Filter": {
"description": "One criterion: a field from GET /v1/catalogue/filters, an operator and its operands. Exclusions nest under not.",
"oneOf": [
{
"$ref": "#/$defs/InFilter"
},
{
"$ref": "#/$defs/BetweenFilter"
},
{
"$ref": "#/$defs/GteFilter"
},
{
"$ref": "#/$defs/LteFilter"
},
{
"$ref": "#/$defs/MatchesFilter"
},
{
"$ref": "#/$defs/WithinRadiusFilter"
},
{
"$ref": "#/$defs/InListFilter"
},
{
"$ref": "#/$defs/SinceFilter"
}
]
},
"GteFilter": {
"additionalProperties": false,
"description": "The field is at or after the value in its order: for bands, the band and every larger one.",
"examples": [
{
"field": "company.employee_band",
"op": "gte",
"value": "50-99"
}
],
"properties": {
"field": {
"enum": [
"company.employee_band",
"company.turnover_band",
"company.fleet_band",
"contact.job_level_rank",
"email.deliverability_score"
],
"type": "string"
},
"op": {
"const": "gte",
"type": "string"
},
"value": {
"anyOf": [
{
"maxLength": 200,
"minLength": 1,
"type": "string"
},
{
"type": "number"
}
],
"description": "A band code or a number from the field's order."
}
},
"required": [
"field",
"op",
"value"
],
"type": "object"
},
"InFilter": {
"additionalProperties": false,
"description": "The field holds one of the listed codes.",
"examples": [
{
"field": "company.sic_2007",
"op": "in",
"values": [
"C"
]
}
],
"properties": {
"field": {
"enum": [
"company.sic_2007",
"company.business_class",
"company.employee_band",
"company.turnover_band",
"company.fleet_band",
"company.type",
"company.status",
"company.subscriber_class",
"company.companies_house_number",
"site.region",
"site.county",
"site.town",
"site.postcode",
"contact.title_family",
"contact.job_function",
"contact.job_level_rank",
"contact.premium",
"email.exists",
"email.type",
"phone.exists",
"phone.tps_ctps_status"
],
"type": "string"
},
"op": {
"const": "in",
"type": "string"
},
"values": {
"items": {
"anyOf": [
{
"maxLength": 200,
"minLength": 1,
"type": "string"
},
{
"type": "number"
},
{
"type": "boolean"
}
],
"description": "A code, a rank or a boolean, as the field's catalogue lists it."
},
"maxItems": 10000,
"minItems": 1,
"type": "array"
}
},
"required": [
"field",
"op",
"values"
],
"type": "object"
},
"InListFilter": {
"additionalProperties": false,
"description": "The record's hashed email, domain, phone, company number or title term is on a suppression list. Usually nested under not; each list reports the records it removed.",
"examples": [
{
"field": "email.address_sha256",
"list_id": "sup_01JB4H7Q2V7XN3M9R6T1Y5W8ZA",
"op": "in_list"
}
],
"properties": {
"field": {
"enum": [
"company.companies_house_number",
"contact.title",
"email.address_sha256",
"email.domain_sha256",
"phone.e164_sha256"
],
"type": "string"
},
"list_id": {
"description": "Format: a suppression list id: sup_ followed by a 26 character ULID in upper case Crockford base32, such as sup_01JB4H7Q2V7XN3M9R6T1Y5W8ZA.",
"examples": [
"sup_01JB4H7Q2V7XN3M9R6T1Y5W8ZA"
],
"pattern": "^sup_[0-7][0-9A-HJKMNP-TV-Z]{25}$",
"type": "string"
},
"op": {
"const": "in_list",
"type": "string"
}
},
"required": [
"field",
"op",
"list_id"
],
"type": "object"
},
"LteFilter": {
"additionalProperties": false,
"description": "The field is at or before the value in its order. Rank 1 is the most senior, so Director and above is contact.job_level_rank lte 6.",
"examples": [
{
"field": "contact.job_level_rank",
"op": "lte",
"value": 6
}
],
"properties": {
"field": {
"enum": [
"company.employee_band",
"company.turnover_band",
"company.fleet_band",
"contact.job_level_rank",
"contact.company_contact_rank",
"email.deliverability_score"
],
"type": "string"
},
"op": {
"const": "lte",
"type": "string"
},
"value": {
"anyOf": [
{
"maxLength": 200,
"minLength": 1,
"type": "string"
},
{
"type": "number"
}
],
"description": "A band code or a number from the field's order."
}
},
"required": [
"field",
"op",
"value"
],
"type": "object"
},
"MatchesFilter": {
"additionalProperties": false,
"allOf": [
{
"if": {
"properties": {
"mode": {
"const": "exact"
}
},
"required": [
"mode"
],
"type": "object"
},
"then": {
"properties": {
"exclude_terms": {
"maxItems": 0,
"type": "array"
},
"expand": {
"maxItems": 0,
"type": "array"
}
},
"type": "object"
}
}
],
"description": "Job title keyword match. mode contains (the default) or starts_with expands each term with the expansion sets; mode exact matches verbatim titles. Every expanded term is returned with the count.",
"examples": [
{
"expand": [
"plural_singular",
"department_synonyms",
"ampersand_and",
"abbreviations"
],
"field": "contact.title",
"mode": "contains",
"op": "matches",
"terms": [
"marketing manager"
]
}
],
"properties": {
"exclude_terms": {
"description": "Expanded terms removed by hand. Kept in the definition so the count stays reproducible when the title dictionary changes.",
"items": {
"maxLength": 200,
"minLength": 1,
"type": "string"
},
"maxItems": 500,
"type": "array"
},
"expand": {
"description": "Expansion sets to apply, each once: plural_singular, department_synonyms, ampersand_and, abbreviations, permutations. Left out, the first four apply; an empty list applies none. Not used with mode exact.",
"items": {
"enum": [
"plural_singular",
"department_synonyms",
"ampersand_and",
"abbreviations",
"permutations"
],
"type": "string"
},
"maxItems": 5,
"type": "array",
"uniqueItems": true
},
"field": {
"enum": [
"contact.title"
],
"type": "string"
},
"mode": {
"description": "contains (the default) matches titles containing a term, starts_with matches titles beginning with it, exact takes verbatim titles with no expansion.",
"enum": [
"contains",
"starts_with",
"exact"
],
"type": "string"
},
"op": {
"const": "matches",
"type": "string"
},
"terms": {
"items": {
"maxLength": 200,
"minLength": 1,
"type": "string"
},
"maxItems": 500,
"minItems": 1,
"type": "array"
}
},
"required": [
"field",
"op",
"terms"
],
"type": "object"
},
"NotGroup": {
"additionalProperties": false,
"description": "Negation: the single node inside must not match.",
"properties": {
"not": {
"$ref": "#/$defs/WhereNode"
}
},
"required": [
"not"
],
"type": "object"
},
"PlaceCentre": {
"additionalProperties": false,
"description": "A named place. Ambiguous names come back from resolve_location as candidates, never a silent choice.",
"properties": {
"code": {
"description": "The ONS geography code of the chosen candidate when resolve_location found more than one, such as E08000035 for the Leeds district.",
"maxLength": 20,
"minLength": 1,
"type": "string"
},
"place": {
"description": "A place name, resolved with resolve_location, such as Leeds.",
"maxLength": 100,
"minLength": 1,
"type": "string"
}
},
"required": [
"place"
],
"type": "object"
},
"PointCentre": {
"additionalProperties": false,
"description": "A latitude and longitude in WGS84 degrees.",
"properties": {
"lat": {
"maximum": 61,
"minimum": 49,
"type": "number"
},
"lon": {
"maximum": 2,
"minimum": -9,
"type": "number"
}
},
"required": [
"lat",
"lon"
],
"type": "object"
},
"PostcodeCentre": {
"additionalProperties": false,
"description": "A postcode centroid from ONSPD.",
"properties": {
"postcode": {
"description": "The centroid of a postcode unit, sector, district or area, such as LS1 4AP.",
"pattern": "^[A-Za-z]{1,2}([0-9][0-9A-Za-z]?( [0-9]([A-Za-z]{2})?| ?[0-9][A-Za-z]{2})?)?$",
"type": "string"
}
},
"required": [
"postcode"
],
"type": "object"
},
"RadiusCentre": {
"anyOf": [
{
"$ref": "#/$defs/PlaceCentre"
},
{
"$ref": "#/$defs/PostcodeCentre"
},
{
"$ref": "#/$defs/PointCentre"
}
],
"description": "The centre of a radius: a place, a postcode or a latitude and longitude."
},
"SinceFilter": {
"additionalProperties": false,
"description": "Within the last N days: a date field, or a Companies House signal of the listed types on signal.type.",
"examples": [
{
"days": 90,
"field": "signal.type",
"op": "since",
"values": [
"company.incorporated"
]
}
],
"properties": {
"days": {
"maximum": 3650,
"minimum": 1,
"type": "integer"
},
"field": {
"enum": [
"contact.last_validated_at",
"email.last_verified_at",
"signal.type",
"signal.observed_at"
],
"type": "string"
},
"op": {
"const": "since",
"type": "string"
},
"values": {
"description": "For signal.type only: the signal types to look for, such as company.incorporated.",
"items": {
"maxLength": 200,
"minLength": 1,
"type": "string"
},
"maxItems": 10000,
"minItems": 1,
"type": "array"
}
},
"required": [
"field",
"op",
"days"
],
"type": "object"
},
"WhereNode": {
"anyOf": [
{
"$ref": "#/$defs/AllGroup"
},
{
"$ref": "#/$defs/AnyGroup"
},
{
"$ref": "#/$defs/NotGroup"
},
{
"$ref": "#/$defs/BundleNode"
},
{
"$ref": "#/$defs/Filter"
}
],
"description": "A group (all, any, not), a title bundle or a filter. Groups nest up to 32 deep, and a where tree holds up to 1,000 filters, groups and bundles."
},
"WithinRadiusFilter": {
"additionalProperties": false,
"description": "Sites within radius_miles of the centre. The count reports the centroid used and the postcodes matched.",
"examples": [
{
"centre": {
"place": "Leeds"
},
"field": "site.location",
"op": "within_radius",
"radius_miles": 20
}
],
"properties": {
"centre": {
"$ref": "#/$defs/RadiusCentre"
},
"field": {
"enum": [
"site.location"
],
"type": "string"
},
"op": {
"const": "within_radius",
"type": "string"
},
"radius_miles": {
"description": "Radius in miles, 1 to 100. Under 5 miles needs an account.",
"maximum": 100,
"minimum": 1,
"type": "number"
}
},
"required": [
"field",
"op",
"centre",
"radius_miles"
],
"type": "object"
}
},
"additionalProperties": false,
"description": "An audience, a level and up to three breakdown fields. Free, and needs no account.",
"properties": {
"audience": {
"$ref": "#/$defs/AudienceRef",
"type": [
"string",
"object"
]
},
"breakdown_by": {
"description": "Up to three fields to break the count down by, each once, such as industry by seniority by region. Returns the top 50 cells per field plus other.",
"items": {
"description": "A field a count can be broken down by.",
"enum": [
"company.sic_2007",
"company.business_class",
"company.employee_band",
"company.turnover_band",
"company.fleet_band",
"company.type",
"company.status",
"company.subscriber_class",
"site.region",
"site.county",
"site.town",
"site.postcode",
"contact.title_family",
"contact.job_function",
"contact.job_level_rank",
"email.exists",
"email.type",
"phone.exists",
"phone.tps_ctps_status"
],
"type": "string"
},
"maxItems": 3,
"type": "array",
"uniqueItems": true
},
"level": {
"default": "contact",
"description": "contact (the default) or company. Contacts and companies come back together either way.",
"enum": [
"contact",
"company"
],
"type": "string"
}
},
"required": [
"audience"
],
"type": "object"
},
"name": "count_audience",
"outputSchema": {
"$defs": {
"AllGroup": {
"additionalProperties": false,
"description": "AND: every node inside must match.",
"properties": {
"all": {
"items": {
"$ref": "#/$defs/WhereNode"
},
"minItems": 1,
"type": "array"
}
},
"required": [
"all"
],
"type": "object"
},
"AnyGroup": {
"additionalProperties": false,
"description": "OR: at least one node inside must match.",
"properties": {
"any": {
"items": {
"$ref": "#/$defs/WhereNode"
},
"minItems": 1,
"type": "array"
}
},
"required": [
"any"
],
"type": "object"
},
"Audience": {
"additionalProperties": false,
"description": "Who you want, as filters grouped by entity (company., site., contact., email., phone., signal.). The server fills its defaults (active companies, named emails, corporate subscribers, the current dataset_version) and returns the effective definition with every count.",
"properties": {
"dataset": {
"description": "The dataset an audience draws from. uk_contacts is live; ie_contacts and global_contacts are listed but not yet served.",
"enum": [
"uk_contacts",
"ie_contacts",
"global_contacts"
],
"type": "string"
},
"dataset_version": {
"description": "The weekly build to count against, such as 2026-W39. Left out, the current version is filled in and returned.",
"examples": [
"2026-W39"
],
"pattern": "^[0-9]{4}-W(0[1-9]|[1-4][0-9]|5[0-3])$",
"type": "string"
},
"dedupe": {
"description": "none keeps every matching contact, one_per_company keeps one contact per company, one_per_site keeps one per site. Default none.",
"enum": [
"none",
"one_per_company",
"one_per_site"
],
"type": "string"
},
"email_policy": {
"$ref": "#/$defs/EmailPolicy"
},
"schema": {
"const": "mydatahub.audience/1",
"description": "The definition's namespace and version. Older versions are upgraded by a pure function.",
"type": "string"
},
"where": {
"$ref": "#/$defs/WhereNode",
"description": "The filters. Left out, the audience is the whole dataset after the defaults."
}
},
"required": [
"schema"
],
"title": "MyDataHub audience definition (mydatahub.audience/1)",
"type": "object"
},
"BetweenFilter": {
"additionalProperties": false,
"description": "The field lies from one value to another inclusive, over the field's order.",
"examples": [
{
"field": "company.employee_band",
"from": "10-19",
"op": "between",
"to": "200-349"
}
],
"properties": {
"field": {
"enum": [
"company.employee_band",
"company.turnover_band",
"company.fleet_band",
"contact.job_level_rank",
"email.deliverability_score"
],
"type": "string"
},
"from": {
"anyOf": [
{
"maxLength": 200,
"minLength": 1,
"type": "string"
},
{
"type": "number"
}
],
"description": "A band code or a number from the field's order."
},
"op": {
"const": "between",
"type": "string"
},
"to": {
"anyOf": [
{
"maxLength": 200,
"minLength": 1,
"type": "string"
},
{
"type": "number"
}
],
"description": "A band code or a number from the field's order."
}
},
"required": [
"field",
"op",
"from",
"to"
],
"type": "object"
},
"Breakdown": {
"description": "A count split by one field: the top 50 cells plus other. Cells under 10 read \"under 10\".",
"properties": {
"by": {
"description": "A field a count can be broken down by.",
"enum": [
"company.sic_2007",
"company.business_class",
"company.employee_band",
"company.turnover_band",
"company.fleet_band",
"company.type",
"company.status",
"company.subscriber_class",
"site.region",
"site.county",
"site.town",
"site.postcode",
"contact.title_family",
"contact.job_function",
"contact.job_level_rank",
"email.exists",
"email.type",
"phone.exists",
"phone.tps_ctps_status"
],
"type": "string"
},
"cells": {
"items": {
"$ref": "#/$defs/BreakdownCell"
},
"maxItems": 50,
"type": "array"
},
"other": {
"anyOf": [
{
"$ref": "#/$defs/OtherBucket"
},
{
"type": "null"
}
]
}
},
"required": [
"by",
"cells"
],
"type": "object"
},
"BreakdownCell": {
"description": "One cell of a breakdown.",
"properties": {
"companies": {
"$ref": "#/$defs/CellCount"
},
"contacts": {
"$ref": "#/$defs/CellCount"
},
"filter_value": {
"anyOf": [
{
"type": "string"
},
{
"type": "number"
},
{
"type": "boolean"
}
],
"description": "The value a filter takes when it differs from value, such as 6 for director on contact.job_level_rank (filters take ranks)."
},
"label": {
"type": "string"
},
"value": {
"anyOf": [
{
"type": "string"
},
{
"type": "number"
},
{
"type": "boolean"
}
],
"description": "The cell's code as shown, such as director or C. To add the cell to the audience as a filter, use filter_value when present, otherwise value."
}
},
"required": [
"value",
"contacts"
],
"type": "object"
},
"BundleNode": {
"additionalProperties": false,
"description": "A title bundle, resolved to its filters in the effective definition: sdm (senior decision makers), manager_and_above (managers and above), owner_managed (owner managed).",
"properties": {
"bundle": {
"enum": [
"sdm",
"manager_and_above",
"owner_managed"
],
"type": "string"
}
},
"required": [
"bundle"
],
"type": "object"
},
"CellCount": {
"anyOf": [
{
"minimum": 0,
"type": "integer"
},
{
"const": "under 10",
"type": "string"
},
{
"const": "suppressed",
"type": "string"
}
],
"description": "A whole number; \"under 10\" when disclosure control withholds a small cell; or \"suppressed\" when secondary suppression hides a cell of 10 or more in a cross-tab or breakdown, so totals cannot be differenced. Anonymous and trial callers see cells rounded to the nearest 5.",
"examples": [
4120,
"under 10",
"suppressed"
]
},
"CompiledPlan": {
"description": "How the definition was run: expanded terms, resolved centres, SIC codes behind a business class and suppression checksums.",
"properties": {
"centres": {
"items": {
"$ref": "#/$defs/ResolvedCentre"
},
"type": "array"
},
"defaults_applied": {
"description": "Defaults the server filled, such as active_companies and named_emails.",
"items": {
"pattern": "^[a-z0-9]+(_[a-z0-9]+)*$",
"type": "string"
},
"type": "array"
},
"engine_rules_version": {
"type": "string"
},
"expanded_terms": {
"items": {
"$ref": "#/$defs/ExpandedTerm"
},
"type": "array"
},
"geography_sets": {
"items": {
"type": "string"
},
"type": "array"
},
"sic_codes": {
"description": "SIC codes behind any business class filter.",
"items": {
"type": "string"
},
"type": "array"
},
"suppressions": {
"items": {
"$ref": "#/$defs/SuppressionChecksum"
},
"type": "array"
}
},
"required": [
"engine_rules_version",
"defaults_applied",
"expanded_terms",
"centres",
"sic_codes",
"geography_sets",
"suppressions"
],
"type": "object"
},
"ComplianceSummary": {
"description": "Beside every count, so a person or an agent can reason before spending. Individual subscribers and TPS and CTPS registered numbers are excluded by default, as visible toggles; numbers not screened are kept.",
"properties": {
"article14_notified": {
"minimum": 0,
"type": "integer"
},
"article14_pending_within_window": {
"description": "Records inside the one month Article 14 window, not yet notified.",
"minimum": 0,
"type": "integer"
},
"corporate_subscriber": {
"description": "Records at corporate subscribers.",
"minimum": 0,
"type": "integer"
},
"individual_subscriber_excluded": {
"description": "Sole traders and ordinary partnerships left out of an email audience.",
"minimum": 0,
"type": "integer"
},
"jurisdiction_excluded": {
"description": "Partner datasets only: records the jurisdiction policy table left out (Germany, Canada and California by policy), reported like suppression removals.",
"items": {
"$ref": "#/$defs/JurisdictionExclusion"
},
"type": "array"
},
"lawful_basis": {
"enum": [
"legitimate_interests_art6_1_f"
],
"type": "string"
},
"suppressed_removed": {
"items": {
"$ref": "#/$defs/SuppressionRemoval"
},
"type": "array"
},
"tps_ctps_excluded": {
"description": "TPS or CTPS registered numbers left out when phone is requested.",
"minimum": 0,
"type": "integer"
}
},
"required": [
"lawful_basis",
"corporate_subscriber",
"individual_subscriber_excluded",
"tps_ctps_excluded",
"article14_notified",
"article14_pending_within_window",
"suppressed_removed"
],
"type": "object"
},
"CountDefault": {
"description": "A default the count applied, and the records it removed, for its toggle.",
"properties": {
"applied": {
"description": "False when the audience filters the same field itself, or turned it off.",
"type": "boolean"
},
"id": {
"description": "active_companies, named_emails, corporate_subscribers or no_registered_phones.",
"enum": [
"active_companies",
"named_emails",
"corporate_subscribers",
"no_registered_phones"
],
"type": "string"
},
"removed": {
"$ref": "#/$defs/CellCount",
"description": "What the toggle shows: the dissolved and insolvent count, the generic (info@, sales@) count, the individual subscriber count or the TPS and CTPS registered count."
},
"screened_at": {
"anyOf": [
{
"format": "date",
"type": "string"
},
{
"type": "null"
}
],
"description": "no_registered_phones only: the version's TPS and CTPS screen date."
},
"views": {
"description": "The headline views the default shapes; named emails and corporate subscribers shape Emailable only.",
"items": {
"enum": [
"total",
"new_to_you",
"emailable"
],
"type": "string"
},
"type": "array"
}
},
"required": [
"id",
"applied",
"views",
"removed"
],
"type": "object"
},
"CountView": {
"description": "Contacts and companies in one headline view.",
"properties": {
"companies": {
"minimum": 0,
"type": "integer"
},
"contacts": {
"minimum": 0,
"type": "integer"
}
},
"required": [
"contacts",
"companies"
],
"type": "object"
},
"CountViews": {
"description": "Contacts and companies for the three headline views, and the premium figure beside all records.",
"properties": {
"all_records": {
"$ref": "#/$defs/CountView",
"description": "The full figure: the audience with its top-level premium filters taken out (one inside any or not stays). The same as total when it has none."
},
"emailable": {
"$ref": "#/$defs/CountView",
"description": "A named email scoring 70 or more at a corporate subscriber."
},
"new_to_you": {
"anyOf": [
{
"$ref": "#/$defs/CountView"
},
{
"type": "null"
}
],
"description": "Removes records from earlier orders and a connected CRM; null when signed out."
},
"premium": {
"anyOf": [
{
"$ref": "#/$defs/CountView"
},
{
"type": "null"
}
],
"description": "The premium records of all_records (contact.premium true); null when the dataset version carries no premium data, or withheld when they are at a single company and the caller has no account."
},
"total": {
"$ref": "#/$defs/CountView"
}
},
"required": [
"total",
"new_to_you",
"emailable",
"premium",
"all_records"
],
"type": "object"
},
"Crosstab": {
"description": "Two or three fields as one grouped table (industry by seniority by region), top 50 values per field, capped at 5,000 cells. For anonymous and trial callers, secondary suppression hides enough further cells, each reading \"suppressed\", that no total can be differenced to reveal a cell under 10.",
"properties": {
"by": {
"items": {
"description": "A field a count can be broken down by.",
"enum": [
"company.sic_2007",
"company.business_class",
"company.employee_band",
"company.turnover_band",
"company.fleet_band",
"company.type",
"company.status",
"company.subscriber_class",
"site.region",
"site.county",
"site.town",
"site.postcode",
"contact.title_family",
"contact.job_function",
"contact.job_level_rank",
"email.exists",
"email.type",
"phone.exists",
"phone.tps_ctps_status"
],
"type": "string"
},
"maxItems": 3,
"minItems": 2,
"type": "array"
},
"cells": {
"items": {
"$ref": "#/$defs/CrosstabCell"
},
"maxItems": 5000,
"type": "array"
},
"other": {
"anyOf": [
{
"$ref": "#/$defs/OtherBucket"
},
{
"type": "null"
}
]
},
"truncated": {
"description": "True when a cap cut the table: 5,000 cells, or fewer over MCP to keep a result under about 8,000 tokens.",
"type": "boolean"
}
},
"required": [
"by",
"cells",
"other",
"truncated"
],
"type": "object"
},
"CrosstabCell": {
"description": "One cell of a cross-tab, one value per field.",
"properties": {
"contacts": {
"$ref": "#/$defs/CellCount"
},
"filter_values": {
"description": "The values filters take, when any differs from values (ranks for seniority).",
"items": {
"anyOf": [
{
"type": "string"
},
{
"type": "number"
},
{
"type": "boolean"
}
]
},
"maxItems": 3,
"minItems": 2,
"type": "array"
},
"values": {
"items": {
"anyOf": [
{
"type": "string"
},
{
"type": "number"
},
{
"type": "boolean"
}
]
},
"maxItems": 3,
"minItems": 2,
"type": "array"
}
},
"required": [
"values",
"contacts"
],
"type": "object"
},
"CurrentCount": {
"description": "The same audience on the current dataset version.",
"properties": {
"companies": {
"minimum": 0,
"type": "integer"
},
"contacts": {
"minimum": 0,
"type": "integer"
},
"dataset_version": {
"description": "The immutable weekly build a count is bound to, such as 2026-W39. The last 52 stay queryable.",
"examples": [
"2026-W39"
],
"pattern": "^[0-9]{4}-W(0[1-9]|[1-4][0-9]|5[0-3])$",
"type": "string"
}
},
"required": [
"dataset_version",
"contacts",
"companies"
],
"type": "object"
},
"Disclosure": {
"description": "Whether these numbers are exact or protected: \"under 10\" cells, rounding to 5 and secondary suppression for anonymous and trial callers.",
"properties": {
"level": {
"description": "exact for authenticated paid callers; rounded for anonymous and trial callers, whose counts under 100 and every cell are rounded to the nearest 5.",
"enum": [
"exact",
"rounded"
],
"type": "string"
},
"notes": {
"items": {
"type": "string"
},
"type": "array"
},
"rounded_to": {
"anyOf": [
{
"exclusiveMinimum": 0,
"type": "integer"
},
{
"type": "null"
}
],
"description": "5 when numbers are rounded; null when they are exact."
},
"secondary_suppression": {
"description": "True when cross-tab or breakdown cells of 10 or more were hidden as \"suppressed\" so totals cannot be differenced.",
"type": "boolean"
}
},
"required": [
"level",
"rounded_to",
"secondary_suppression",
"notes"
],
"type": "object"
},
"EmailPolicy": {
"additionalProperties": false,
"description": "Email quality floor. Defaults: min_deliverability_score 70, allow_catch_all false.",
"properties": {
"allow_catch_all": {
"description": "Whether catch-all addresses count. Default false.",
"type": "boolean"
},
"min_deliverability_score": {
"description": "Lowest deliverability score counted, 0 to 100. Default 70.",
"maximum": 100,
"minimum": 0,
"type": "integer"
}
},
"type": "object"
},
"ExpandedTerm": {
"description": "One title a matches filter covers, with its count.",
"properties": {
"contacts": {
"$ref": "#/$defs/CellCount"
},
"excluded": {
"description": "True when exclude_terms removed it from the audience.",
"type": "boolean"
},
"expansion_set": {
"anyOf": [
{
"enum": [
"plural_singular",
"department_synonyms",
"ampersand_and",
"abbreviations",
"permutations"
],
"type": "string"
},
{
"const": "input",
"type": "string"
}
],
"description": "The expansion set that produced it, or input for the term itself."
},
"from_term": {
"description": "The input term it came from.",
"type": "string"
},
"term": {
"description": "A matched title.",
"type": "string"
}
},
"required": [
"term",
"from_term",
"expansion_set",
"contacts"
],
"type": "object"
},
"Filter": {
"description": "One criterion: a field from GET /v1/catalogue/filters, an operator and its operands. Exclusions nest under not.",
"oneOf": [
{
"$ref": "#/$defs/InFilter"
},
{
"$ref": "#/$defs/BetweenFilter"
},
{
"$ref": "#/$defs/GteFilter"
},
{
"$ref": "#/$defs/LteFilter"
},
{
"$ref": "#/$defs/MatchesFilter"
},
{
"$ref": "#/$defs/WithinRadiusFilter"
},
{
"$ref": "#/$defs/InListFilter"
},
{
"$ref": "#/$defs/SinceFilter"
}
]
},
"GteFilter": {
"additionalProperties": false,
"description": "The field is at or after the value in its order: for bands, the band and every larger one.",
"examples": [
{
"field": "company.employee_band",
"op": "gte",
"value": "50-99"
}
],
"properties": {
"field": {
"enum": [
"company.employee_band",
"company.turnover_band",
"company.fleet_band",
"contact.job_level_rank",
"email.deliverability_score"
],
"type": "string"
},
"op": {
"const": "gte",
"type": "string"
},
"value": {
"anyOf": [
{
"maxLength": 200,
"minLength": 1,
"type": "string"
},
{
"type": "number"
}
],
"description": "A band code or a number from the field's order."
}
},
"required": [
"field",
"op",
"value"
],
"type": "object"
},
"InFilter": {
"additionalProperties": false,
"description": "The field holds one of the listed codes.",
"examples": [
{
"field": "company.sic_2007",
"op": "in",
"values": [
"C"
]
}
],
"properties": {
"field": {
"enum": [
"company.sic_2007",
"company.business_class",
"company.employee_band",
"company.turnover_band",
"company.fleet_band",
"company.type",
"company.status",
"company.subscriber_class",
"company.companies_house_number",
"site.region",
"site.county",
"site.town",
"site.postcode",
"contact.title_family",
"contact.job_function",
"contact.job_level_rank",
"contact.premium",
"email.exists",
"email.type",
"phone.exists",
"phone.tps_ctps_status"
],
"type": "string"
},
"op": {
"const": "in",
"type": "string"
},
"values": {
"items": {
"anyOf": [
{
"maxLength": 200,
"minLength": 1,
"type": "string"
},
{
"type": "number"
},
{
"type": "boolean"
}
],
"description": "A code, a rank or a boolean, as the field's catalogue lists it."
},
"maxItems": 10000,
"minItems": 1,
"type": "array"
}
},
"required": [
"field",
"op",
"values"
],
"type": "object"
},
"InListFilter": {
"additionalProperties": false,
"description": "The record's hashed email, domain, phone, company number or title term is on a suppression list. Usually nested under not; each list reports the records it removed.",
"examples": [
{
"field": "email.address_sha256",
"list_id": "sup_01JB4H7Q2V7XN3M9R6T1Y5W8ZA",
"op": "in_list"
}
],
"properties": {
"field": {
"enum": [
"company.companies_house_number",
"contact.title",
"email.address_sha256",
"email.domain_sha256",
"phone.e164_sha256"
],
"type": "string"
},
"list_id": {
"description": "Format: a suppression list id: sup_ followed by a 26 character ULID in upper case Crockford base32, such as sup_01JB4H7Q2V7XN3M9R6T1Y5W8ZA.",
"examples": [
"sup_01JB4H7Q2V7XN3M9R6T1Y5W8ZA"
],
"pattern": "^sup_[0-7][0-9A-HJKMNP-TV-Z]{25}$",
"type": "string"
},
"op": {
"const": "in_list",
"type": "string"
}
},
"required": [
"field",
"op",
"list_id"
],
"type": "object"
},
"JurisdictionExclusion": {
"description": "Records one policy removed.",
"properties": {
"jurisdiction": {
"description": "An ISO 3166 code, such as DE, CA or US-CA.",
"type": "string"
},
"removed": {
"minimum": 0,
"type": "integer"
}
},
"required": [
"jurisdiction",
"removed"
],
"type": "object"
},
"LteFilter": {
"additionalProperties": false,
"description": "The field is at or before the value in its order. Rank 1 is the most senior, so Director and above is contact.job_level_rank lte 6.",
"examples": [
{
"field": "contact.job_level_rank",
"op": "lte",
"value": 6
}
],
"properties": {
"field": {
"enum": [
"company.employee_band",
"company.turnover_band",
"company.fleet_band",
"contact.job_level_rank",
"contact.company_contact_rank",
"email.deliverability_score"
],
"type": "string"
},
"op": {
"const": "lte",
"type": "string"
},
"value": {
"anyOf": [
{
"maxLength": 200,
"minLength": 1,
"type": "string"
},
{
"type": "number"
}
],
"description": "A band code or a number from the field's order."
}
},
"required": [
"field",
"op",
"value"
],
"type": "object"
},
"MatchesFilter": {
"additionalProperties": false,
"allOf": [
{
"if": {
"properties": {
"mode": {
"const": "exact"
}
},
"required": [
"mode"
],
"type": "object"
},
"then": {
"properties": {
"exclude_terms": {
"maxItems": 0,
"type": "array"
},
"expand": {
"maxItems": 0,
"type": "array"
}
},
"type": "object"
}
}
],
"description": "Job title keyword match. mode contains (the default) or starts_with expands each term with the expansion sets; mode exact matches verbatim titles. Every expanded term is returned with the count.",
"examples": [
{
"expand": [
"plural_singular",
"department_synonyms",
"ampersand_and",
"abbreviations"
],
"field": "contact.title",
"mode": "contains",
"op": "matches",
"terms": [
"marketing manager"
]
}
],
"properties": {
"exclude_terms": {
"description": "Expanded terms removed by hand. Kept in the definition so the count stays reproducible when the title dictionary changes.",
"items": {
"maxLength": 200,
"minLength": 1,
"type": "string"
},
"maxItems": 500,
"type": "array"
},
"expand": {
"description": "Expansion sets to apply, each once: plural_singular, department_synonyms, ampersand_and, abbreviations, permutations. Left out, the first four apply; an empty list applies none. Not used with mode exact.",
"items": {
"enum": [
"plural_singular",
"department_synonyms",
"ampersand_and",
"abbreviations",
"permutations"
],
"type": "string"
},
"maxItems": 5,
"type": "array",
"uniqueItems": true
},
"field": {
"enum": [
"contact.title"
],
"type": "string"
},
"mode": {
"description": "contains (the default) matches titles containing a term, starts_with matches titles beginning with it, exact takes verbatim titles with no expansion.",
"enum": [
"contains",
"starts_with",
"exact"
],
"type": "string"
},
"op": {
"const": "matches",
"type": "string"
},
"terms": {
"items": {
"maxLength": 200,
"minLength": 1,
"type": "string"
},
"maxItems": 500,
"minItems": 1,
"type": "array"
}
},
"required": [
"field",
"op",
"terms"
],
"type": "object"
},
"NotGroup": {
"additionalProperties": false,
"description": "Negation: the single node inside must not match.",
"properties": {
"not": {
"$ref": "#/$defs/WhereNode"
}
},
"required": [
"not"
],
"type": "object"
},
"OtherBucket": {
"description": "Every cell beyond the top 50, summed.",
"properties": {
"cells": {
"description": "How many cells were folded into other.",
"minimum": 0,
"type": "integer"
},
"companies": {
"$ref": "#/$defs/CellCount"
},
"contacts": {
"$ref": "#/$defs/CellCount"
}
},
"required": [
"cells",
"contacts"
],
"type": "object"
},
"PlaceCentre": {
"additionalProperties": false,
"description": "A named place. Ambiguous names come back from resolve_location as candidates, never a silent choice.",
"properties": {
"code": {
"description": "The ONS geography code of the chosen candidate when resolve_location found more than one, such as E08000035 for the Leeds district.",
"maxLength": 20,
"minLength": 1,
"type": "string"
},
"place": {
"description": "A place name, resolved with resolve_location, such as Leeds.",
"maxLength": 100,
"minLength": 1,
"type": "string"
}
},
"required": [
"place"
],
"type": "object"
},
"PointCentre": {
"additionalProperties": false,
"description": "A latitude and longitude in WGS84 degrees.",
"properties": {
"lat": {
"maximum": 61,
"minimum": 49,
"type": "number"
},
"lon": {
"maximum": 2,
"minimum": -9,
"type": "number"
}
},
"required": [
"lat",
"lon"
],
"type": "object"
},
"PostcodeCentre": {
"additionalProperties": false,
"description": "A postcode centroid from ONSPD.",
"properties": {
"postcode": {
"description": "The centroid of a postcode unit, sector, district or area, such as LS1 4AP.",
"pattern": "^[A-Za-z]{1,2}([0-9][0-9A-Za-z]?( [0-9]([A-Za-z]{2})?| ?[0-9][A-Za-z]{2})?)?$",
"type": "string"
}
},
"required": [
"postcode"
],
"type": "object"
},
"PriceEstimate": {
"description": "What ordering the whole count would cost. An estimate; quote_order gives the machine quote.",
"properties": {
"credits": {
"description": "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).",
"minimum": 0,
"type": "number"
},
"gbp_ex_vat": {
"additionalProperties": {
"description": "Pounds sterling excluding VAT, to two decimal places.",
"minimum": 0,
"type": "number"
},
"description": "The price in GBP excluding VAT: per_contact_scale (every credit at the scale) and cheapest (the cheapest real purchase, at the scale or with credit packs).",
"propertyNames": {
"pattern": "^[a-z0-9]+(_[a-z0-9]+)*$",
"type": "string"
},
"type": "object"
}
},
"required": [
"credits",
"gbp_ex_vat"
],
"type": "object"
},
"Quality": {
"description": "Quality signals shown with every count.",
"properties": {
"avg_days_since_verification": {
"anyOf": [
{
"minimum": 0,
"type": "number"
},
{
"type": "null"
}
],
"description": "Mean days since each email was last verified. Null when the dataset version's verification dates are assigned, not measured."
},
"deliverability": {
"anyOf": [
{
"properties": {
"good": {
"maximum": 100,
"minimum": 0,
"type": "number"
},
"poor": {
"maximum": 100,
"minimum": 0,
"type": "number"
},
"risky": {
"maximum": 100,
"minimum": 0,
"type": "number"
}
},
"required": [
"good",
"risky",
"poor"
],
"type": "object"
},
{
"type": "null"
}
],
"description": "Score distribution: good 70 to 100, risky 40 to 69, poor under 40. Null when the dataset version's verification dates are assigned, not measured."
},
"email_coverage_pct": {
"description": "Records with a named email as a share of the count.",
"maximum": 100,
"minimum": 0,
"type": "number"
},
"phone_coverage_pct": {
"description": "Share with a validated number, when phone is requested.",
"maximum": 100,
"minimum": 0,
"type": "number"
},
"tps_ctps_screened_at": {
"description": "The version's TPS and CTPS screen date, when phone is requested and a number in it is screened; each number carries its own status and screen date.",
"format": "date",
"type": "string"
},
"verified_90d_pct": {
"anyOf": [
{
"maximum": 100,
"minimum": 0,
"type": "number"
},
{
"type": "null"
}
],
"description": "Share of emails with a provider result of ok in the last 90 days. Null when the dataset version's verification dates are assigned, not measured."
},
"verified_measured_at": {
"format": "date",
"type": "string"
}
},
"required": [
"email_coverage_pct",
"verified_90d_pct"
],
"type": "object"
},
"RadiusCentre": {
"anyOf": [
{
"$ref": "#/$defs/PlaceCentre"
},
{
"$ref": "#/$defs/PostcodeCentre"
},
{
"$ref": "#/$defs/PointCentre"
}
],
"description": "The centre of a radius: a place, a postcode or a latitude and longitude."
},
"ResolvedCentre": {
"description": "A radius centre as the engine resolved it.",
"properties": {
"code": {
"type": [
"string",
"null"
]
},
"label": {
"type": "string"
},
"lat": {
"type": "number"
},
"lon": {
"type": "number"
},
"postcode_districts_matched": {
"minimum": 0,
"type": "integer"
},
"radius_miles": {
"type": "number"
}
},
"required": [
"label",
"code",
"lat",
"lon",
"radius_miles",
"postcode_districts_matched"
],
"type": "object"
},
"SinceFilter": {
"additionalProperties": false,
"description": "Within the last N days: a date field, or a Companies House signal of the listed types on signal.type.",
"examples": [
{
"days": 90,
"field": "signal.type",
"op": "since",
"values": [
"company.incorporated"
]
}
],
"properties": {
"days": {
"maximum": 3650,
"minimum": 1,
"type": "integer"
},
"field": {
"enum": [
"contact.last_validated_at",
"email.last_verified_at",
"signal.type",
"signal.observed_at"
],
"type": "string"
},
"op": {
"const": "since",
"type": "string"
},
"values": {
"description": "For signal.type only: the signal types to look for, such as company.incorporated.",
"items": {
"maxLength": 200,
"minLength": 1,
"type": "string"
},
"maxItems": 10000,
"minItems": 1,
"type": "array"
}
},
"required": [
"field",
"op",
"days"
],
"type": "object"
},
"SuppressionChecksum": {
"description": "A suppression list as the count read it.",
"properties": {
"checksum": {
"type": "string"
},
"list_id": {
"description": "Format: a suppression list id: sup_ followed by a 26 character ULID in upper case Crockford base32, such as sup_01JB4H7Q2V7XN3M9R6T1Y5W8ZA.",
"examples": [
"sup_01JB4H7Q2V7XN3M9R6T1Y5W8ZA"
],
"pattern": "^sup_[0-7][0-9A-HJKMNP-TV-Z]{25}$",
"type": "string"
},
"row_count": {
"minimum": 0,
"type": "integer"
}
},
"required": [
"list_id",
"checksum",
"row_count"
],
"type": "object"
},
"SuppressionRemoval": {
"description": "Records one suppression list removed.",
"properties": {
"list_id": {
"description": "Format: a suppression list id: sup_ followed by a 26 character ULID in upper case Crockford base32, such as sup_01JB4H7Q2V7XN3M9R6T1Y5W8ZA.",
"examples": [
"sup_01JB4H7Q2V7XN3M9R6T1Y5W8ZA"
],
"pattern": "^sup_[0-7][0-9A-HJKMNP-TV-Z]{25}$",
"type": "string"
},
"removed": {
"minimum": 0,
"type": "integer"
}
},
"required": [
"list_id",
"removed"
],
"type": "object"
},
"WhereNode": {
"anyOf": [
{
"$ref": "#/$defs/AllGroup"
},
{
"$ref": "#/$defs/AnyGroup"
},
{
"$ref": "#/$defs/NotGroup"
},
{
"$ref": "#/$defs/BundleNode"
},
{
"$ref": "#/$defs/Filter"
}
],
"description": "A group (all, any, not), a title bundle or a filter. Groups nest up to 32 deep, and a where tree holds up to 1,000 filters, groups and bundles."
},
"WithinRadiusFilter": {
"additionalProperties": false,
"description": "Sites within radius_miles of the centre. The count reports the centroid used and the postcodes matched.",
"examples": [
{
"centre": {
"place": "Leeds"
},
"field": "site.location",
"op": "within_radius",
"radius_miles": 20
}
],
"properties": {
"centre": {
"$ref": "#/$defs/RadiusCentre"
},
"field": {
"enum": [
"site.location"
],
"type": "string"
},
"op": {
"const": "within_radius",
"type": "string"
},
"radius_miles": {
"description": "Radius in miles, 1 to 100. Under 5 miles needs an account.",
"maximum": 100,
"minimum": 1,
"type": "number"
}
},
"required": [
"field",
"op",
"centre",
"radius_miles"
],
"type": "object"
}
},
"description": "Total, New to you and Emailable, the premium figure beside all records, with companies, breakdowns, quality, the compliance summary, the defaults behind the toggles, disclosure and a price estimate. The id is content addressed, so the same definition from chips, REST or MCP gives the same id.",
"properties": {
"all_records": {
"description": "All records: every matching contact with the audience's top-level premium filters taken out (a premium filter inside any or not stays), so the premium figure always has the full figure beside it. The same as contacts when the audience has no premium filter.",
"minimum": 0,
"type": "integer"
},
"as_of": {
"description": "The date the dataset version was built, for as-of statements.",
"format": "date",
"type": "string"
},
"breakdowns": {
"items": {
"$ref": "#/$defs/Breakdown"
},
"type": "array"
},
"companies": {
"minimum": 0,
"type": "integer"
},
"compliance_summary": {
"$ref": "#/$defs/ComplianceSummary"
},
"contacts": {
"description": "Total: every matching contact.",
"minimum": 0,
"type": "integer"
},
"created_at": {
"format": "date-time",
"type": "string"
},
"credits_per_record": {
"description": "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).",
"minimum": 0,
"type": "number"
},
"crosstab": {
"anyOf": [
{
"$ref": "#/$defs/Crosstab"
},
{
"type": "null"
}
]
},
"current": {
"anyOf": [
{
"$ref": "#/$defs/CurrentCount"
},
{
"type": "null"
}
],
"description": "On a replay: the same audience on the current dataset version."
},
"dataset": {
"description": "The dataset an audience draws from. uk_contacts is live; ie_contacts and global_contacts are listed but not yet served.",
"enum": [
"uk_contacts",
"ie_contacts",
"global_contacts"
],
"type": "string"
},
"dataset_version": {
"description": "The immutable weekly build a count is bound to, such as 2026-W39. The last 52 stay queryable.",
"examples": [
"2026-W39"
],
"pattern": "^[0-9]{4}-W(0[1-9]|[1-4][0-9]|5[0-3])$",
"type": "string"
},
"defaults": {
"description": "Every default with the number behind its toggle: dissolved and insolvent, generic emails, individual subscribers, TPS and CTPS registered.",
"items": {
"$ref": "#/$defs/CountDefault"
},
"type": "array"
},
"disclosure": {
"$ref": "#/$defs/Disclosure"
},
"effective_audience": {
"$ref": "#/$defs/Audience",
"description": "The definition after defaults and bundles, as hashed into the id."
},
"emailable": {
"description": "A named email scoring 70 or more at a corporate subscriber.",
"minimum": 0,
"type": "integer"
},
"engine_rules_version": {
"description": "The engine rules (title expansion, defaults, geography sets) the count ran under; part of what the count id hashes, such as 2026.09.1.",
"minLength": 1,
"type": "string"
},
"estimate": {
"$ref": "#/$defs/PriceEstimate"
},
"expanded_terms": {
"description": "Every title a matches filter covered, with a count per term.",
"items": {
"$ref": "#/$defs/ExpandedTerm"
},
"type": "array"
},
"expires_at": {
"description": "The id replays until then (12 months).",
"format": "date-time",
"type": "string"
},
"id": {
"description": "Format: a count id: cnt_ followed by 20 base32 characters (A to Z and 2 to 7), such as cnt_7K2PQ4MAXN3R6TBY5WDZ.",
"examples": [
"cnt_7K2PQ4MAXN3R6TBY5WDZ"
],
"pattern": "^cnt_[A-Z2-7]{20}$",
"type": "string"
},
"level": {
"description": "contact (the default) or company. Contacts and companies come back together either way.",
"enum": [
"contact",
"company"
],
"type": "string"
},
"new_to_you": {
"anyOf": [
{
"minimum": 0,
"type": "integer"
},
{
"type": "null"
}
],
"description": "Excludes your earlier orders and CRM overlap; null when signed out."
},
"plan": {
"$ref": "#/$defs/CompiledPlan"
},
"premium": {
"anyOf": [
{
"minimum": 0,
"type": "integer"
},
{
"type": "null"
}
],
"description": "Premium: the contacts of all_records that are premium records (contact.premium true). At launch, a premium record is in the premium export of a stated date. Null when the dataset version carries no premium data, or withheld when the premium records are at a single company and the caller has no account; premium_note says which."
},
"premium_note": {
"description": "What premium means on this dataset version, or why premium is null: no premium data on the version, or withheld because the premium records are at a single company.",
"minLength": 1,
"type": "string"
},
"quality": {
"$ref": "#/$defs/Quality"
},
"removed_since": {
"description": "On a replay: records since removed by objections and erasure.",
"minimum": 0,
"type": "integer"
},
"views": {
"$ref": "#/$defs/CountViews"
},
"warnings": {
"items": {
"type": "string"
},
"type": "array"
}
},
"required": [
"id",
"dataset",
"dataset_version",
"engine_rules_version",
"credits_per_record",
"contacts",
"companies",
"emailable",
"new_to_you",
"premium",
"all_records",
"premium_note",
"quality",
"breakdowns",
"compliance_summary",
"defaults",
"estimate",
"disclosure",
"expires_at"
],
"type": "object"
}
},
{
"description": "Spends 1 credit per complete UK record against a live machine quote from quote_order, and queues the order. It needs the quote_id and an idempotency_key to reuse on any retry, so a retry never charges twice; a flag set by a model is never consent. Where the host supports elicitation the user confirms the spend in a form or on mydatahub.emailmovers.com; otherwise an agent key must cover it within its per-order cap and monthly budget. If neither applies nothing is charged: the result is a confirmation-required error with an approval_url to give the user, so keep the quote_id; a short balance returns a top_up_url. Call get_order until the status is ready, then fetch_order_records. Lawful basis is UK GDPR Article 6(1)(f) legitimate interests; email audiences include corporate subscribers only by default (PECR), so sole traders and ordinary partnerships are left out unless the toggle is changed.",
"inputSchema": {
"additionalProperties": false,
"properties": {
"confirmation_token": {
"description": "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.",
"maxLength": 2000,
"minLength": 16,
"type": "string"
},
"delivery": {
"description": "api (fetch records), csv (signed download) and google_sheets. Default api.",
"items": {
"enum": [
"api",
"csv",
"google_sheets"
],
"type": "string"
},
"minItems": 1,
"type": "array"
},
"idempotency_key": {
"description": "Any unique string, such as a V4 UUID. Reuse it when retrying the same order so it is never charged twice; a different order needs a new key.",
"maxLength": 255,
"minLength": 1,
"type": "string"
},
"name": {
"maxLength": 200,
"minLength": 1,
"type": "string"
},
"quote_id": {
"description": "A live machine quote from quote_order. Without one nothing is charged.",
"examples": [
"qte_01JB4M2R6T1Y5W8ZAK8Q2V7XN3"
],
"pattern": "^qte_[0-7][0-9A-HJKMNP-TV-Z]{25}$",
"type": "string"
}
},
"required": [
"quote_id",
"idempotency_key"
],
"type": "object"
},
"name": "create_order",
"outputSchema": {
"$defs": {
"BuyerKit": {
"description": "Four signed documents that help the buyer use the list lawfully.",
"properties": {
"article30_stub_url": {
"format": "uri",
"type": "string"
},
"draft_lia_url": {
"format": "uri",
"type": "string"
},
"due_diligence_file_url": {
"format": "uri",
"type": "string"
},
"first_email_wording_url": {
"format": "uri",
"type": "string"
}
},
"required": [
"draft_lia_url",
"first_email_wording_url",
"article30_stub_url",
"due_diligence_file_url"
],
"type": "object"
},
"ConfirmedBy": {
"description": "Who approved the spend and from which client, recorded in the audit trail and on invoices.",
"properties": {
"client_id": {
"description": "The OAuth client, such as a Client ID Metadata Document URL.",
"type": "string"
},
"confirmed_at": {
"format": "date-time",
"type": "string"
},
"key_id": {
"description": "The agent key, for agent_key.",
"examples": [
"key_01JB3Z4Q2V7XN3M9R6T1Y5W8ZA"
],
"pattern": "^key_[0-7][0-9A-HJKMNP-TV-Z]{25}$",
"type": "string"
},
"method": {
"description": "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).",
"enum": [
"elicitation_form",
"approval_url",
"agent_key",
"app"
],
"type": "string"
},
"mtls_certificate_fingerprint": {
"description": "SHA-256 of the client certificate when one was presented (ChatGPT's mTLS).",
"type": [
"string",
"null"
]
},
"user_agent": {
"description": "The calling client's User-Agent.",
"type": [
"string",
"null"
]
},
"user_id": {
"description": "The person who confirmed.",
"examples": [
"usr_01JA0Q3V7XN3M9R6T1Y5W8ZAK8"
],
"pattern": "^usr_[0-7][0-9A-HJKMNP-TV-Z]{25}$",
"type": "string"
},
"web_bot_auth_signature_agent": {
"description": "The Signature-Agent of a verified Web Bot Auth signature, when present.",
"type": [
"string",
"null"
]
}
},
"required": [
"method"
],
"type": "object"
},
"Licence": {
"description": "Licence terms as data, on every quote, order, records page and receipt. Records stay usable, pushable and re-downloadable free until reuse_until.",
"properties": {
"permitted_channels": {
"description": "email, telephone and post on standard terms.",
"items": {
"enum": [
"email",
"telephone",
"post"
],
"type": "string"
},
"type": "array"
},
"resale_prohibited": {
"type": "boolean"
},
"reuse_until": {
"anyOf": [
{
"format": "date",
"type": "string"
},
{
"type": "null"
}
],
"description": "Order date plus 12 months; null for outright."
},
"terms_url": {
"description": "Where that version of the Data Licence and Sharing Agreement is published.",
"format": "uri",
"type": "string"
},
"terms_version": {
"description": "The version of the Data Licence and Sharing Agreement the licence is under, such as 1.0.",
"type": "string"
},
"type": {
"description": "multi_use_12m (12 month multi-use, every plan) or outright (1.8 credits a record, proposed).",
"enum": [
"multi_use_12m",
"outright"
],
"type": "string"
},
"warranty_url": {
"format": "uri",
"type": "string"
}
},
"required": [
"type",
"reuse_until",
"resale_prohibited",
"permitted_channels",
"warranty_url",
"terms_version"
],
"type": "object"
},
"ValidationReportLinks": {
"description": "The per-order validation report: dataset version, status distribution, verification age, expected bounce band, TPS screen date, provider locations and the guarantee window.",
"properties": {
"json_url": {
"format": "uri",
"type": "string"
},
"pdf_url": {
"format": "uri",
"type": "string"
}
},
"required": [
"pdf_url",
"json_url"
],
"type": "object"
}
},
"description": "The purchase and its delivery: status, records, charges, the licence, links to records, download, the validation report and the signed compliance receipt.",
"properties": {
"buyer_kit": {
"$ref": "#/$defs/BuyerKit"
},
"confirmed_by": {
"$ref": "#/$defs/ConfirmedBy"
},
"cost_gbp": {
"description": "The charge in GBP excluding VAT at your plan's rate.",
"minimum": 0,
"type": "number"
},
"count_id": {
"description": "The count the machine quote was priced from.",
"examples": [
"cnt_7K2PQ4MAXN3R6TBY5WDZ"
],
"pattern": "^cnt_[A-Z2-7]{20}$",
"type": "string"
},
"created_at": {
"format": "date-time",
"type": "string"
},
"credits_charged": {
"description": "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).",
"minimum": 0,
"type": "number"
},
"credits_remaining": {
"description": "The balance right after this order was charged.",
"minimum": 0,
"type": "number"
},
"dataset_version": {
"description": "The immutable weekly build a count is bound to, such as 2026-W39. The last 52 stay queryable.",
"examples": [
"2026-W39"
],
"pattern": "^[0-9]{4}-W(0[1-9]|[1-4][0-9]|5[0-3])$",
"type": "string"
},
"delivery": {
"items": {
"enum": [
"api",
"csv",
"google_sheets"
],
"type": "string"
},
"type": "array"
},
"download_url": {
"description": "302 to a single-use signed URL that lives 5 minutes.",
"format": "uri-reference",
"pattern": "^\\/v1\\/[A-Za-z0-9_\\-./]+$",
"type": "string"
},
"failure": {
"type": [
"string",
"null"
]
},
"field_set": {
"pattern": "^[a-z0-9]+(_[a-z0-9]+)*$",
"type": "string"
},
"id": {
"description": "Format: an order id: ord_ followed by a 26 character ULID in upper case Crockford base32, such as ord_01JB4N9S3W2X6Y7Z8A1B2C3D4E.",
"examples": [
"ord_01JB4N9S3W2X6Y7Z8A1B2C3D4E"
],
"pattern": "^ord_[0-7][0-9A-HJKMNP-TV-Z]{25}$",
"type": "string"
},
"licence": {
"$ref": "#/$defs/Licence"
},
"licence_expires_at": {
"anyOf": [
{
"format": "date",
"type": "string"
},
{
"type": "null"
}
],
"description": "When the licence ends; null for outright ownership."
},
"name": {
"type": "string"
},
"quote_id": {
"description": "The machine quote the order settled.",
"examples": [
"qte_01JB4M2R6T1Y5W8ZAK8Q2V7XN3"
],
"pattern": "^qte_[0-7][0-9A-HJKMNP-TV-Z]{25}$",
"type": "string"
},
"ready_at": {
"anyOf": [
{
"format": "date-time",
"type": "string"
},
{
"type": "null"
}
]
},
"receipt_url": {
"description": "A path on https://mydatahub.emailmovers.com starting /v1/. Resolve it against the origin (RFC 3986), not by appending it to the server URL.",
"format": "uri-reference",
"pattern": "^\\/v1\\/[A-Za-z0-9_\\-./]+$",
"type": "string"
},
"records": {
"minimum": 0,
"type": "integer"
},
"records_url": {
"description": "A path on https://mydatahub.emailmovers.com starting /v1/. Resolve it against the origin (RFC 3986), not by appending it to the server URL.",
"format": "uri-reference",
"pattern": "^\\/v1\\/[A-Za-z0-9_\\-./]+$",
"type": "string"
},
"status": {
"description": "queued, building, verifying, ready; failed if processing failed; cancelled (only while queued).",
"enum": [
"queued",
"building",
"verifying",
"ready",
"failed",
"cancelled"
],
"type": "string"
},
"test": {
"const": true,
"description": "A test mode order (a test key, or anyone in a demo organisation): no credits were charged, the records are invented and no licence is granted. Absent on a live order.",
"type": "boolean"
},
"validation_report": {
"$ref": "#/$defs/ValidationReportLinks",
"description": "Present once the order is ready."
},
"verification": {
"description": "The real-time check at delivery, such as 4,102 checked, 4,071 passed.",
"properties": {
"checked": {
"minimum": 0,
"type": "integer"
},
"passed": {
"minimum": 0,
"type": "integer"
},
"replaced": {
"minimum": 0,
"type": "integer"
}
},
"required": [
"checked",
"passed",
"replaced"
],
"type": "object"
}
},
"required": [
"id",
"status",
"quote_id",
"count_id",
"records",
"credits_charged",
"credits_remaining",
"cost_gbp",
"licence_expires_at",
"licence",
"confirmed_by",
"records_url"
],
"type": "object"
}
},
{
"description": "Returns the full record for one known person, matched by email or by name with a company name, number or domain. It spends 1 credit only on a confident match, and 0 on no match or when you already hold the record under licence, so a repeat never charges twice. Like create_order it needs the user's confirmation (a form, or the confirmation_token from an approval_url) or an agent key whose allowed_tools include enrich_contact within its per-order cap and monthly budget; otherwise nothing is charged and it returns confirmation-required or agent-budget-exceeded. It needs enrich:write; use it for a single named person, and the result gives credits_charged and the balance left. Lawful basis is UK GDPR Article 6(1)(f) legitimate interests; email audiences include corporate subscribers only by default (PECR), so sole traders and ordinary partnerships are left out unless the toggle is changed.",
"inputSchema": {
"additionalProperties": false,
"anyOf": [
{
"properties": {
"email": true
},
"required": [
"email"
],
"type": "object"
},
{
"anyOf": [
{
"properties": {
"company_name": true
},
"required": [
"company_name"
],
"type": "object"
},
{
"properties": {
"company_number": true
},
"required": [
"company_number"
],
"type": "object"
},
{
"properties": {
"domain": true
},
"required": [
"domain"
],
"type": "object"
}
],
"properties": {
"first_name": true,
"last_name": true
},
"required": [
"first_name",
"last_name"
],
"type": "object"
}
],
"description": "One known person to match. Send email, or first_name and last_name with company_name, company_number or domain.",
"properties": {
"company_name": {
"maxLength": 200,
"minLength": 1,
"type": "string"
},
"company_number": {
"description": "Eight characters in upper case, such as 05046417 or SC123456.",
"pattern": "^[A-Z0-9]{8}$",
"type": "string"
},
"confirmation_token": {
"description": "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.",
"maxLength": 2000,
"minLength": 16,
"type": "string"
},
"domain": {
"maxLength": 253,
"minLength": 3,
"type": "string"
},
"email": {
"format": "email",
"type": "string"
},
"first_name": {
"maxLength": 100,
"minLength": 1,
"type": "string"
},
"last_name": {
"maxLength": 100,
"minLength": 1,
"type": "string"
}
},
"type": "object"
},
"name": "enrich_contact",
"outputSchema": {
"$defs": {
"ComplianceObject": {
"description": "Carried by every preview row, order record, lookup and enrichment, and repeated as CSV columns and as the MyDataHub property group on CRM push.",
"examples": [
{
"article14_notified_at": "2026-06-14",
"article14_status": "notified",
"attribution": "Contains public sector information licensed under the Open Government Licence v3.0",
"corporate_subscriber": true,
"email_marketing_basis": "pecr_corporate_subscriber",
"lawful_basis": "legitimate_interests_art6_1_f",
"lia_ref": "EM-LIA-2026-03",
"notice_version": "2026-02",
"provenance": {
"company": {
"as_of": "2026-09-21",
"source": "companies_house"
},
"contact": {
"compiled_at": "2026-05-02",
"last_verified_at": "2026-08-30",
"method": "telephone",
"source": "emailmovers_research"
},
"email": {
"provider_location": "EU",
"result": "ok",
"verified_at": "2026-09-10"
}
},
"record_age_days": 147,
"subscriber_class": "ltd",
"subscriber_evidence": {
"companies_house_number": "05046417",
"company_type": "ltd"
},
"suppression_status": "none",
"tps_ctps_screened_at": "2026-09-12",
"tps_ctps_status": "clear",
"tps_ctps_valid_until": "2026-10-10"
}
],
"properties": {
"article14_notified_at": {
"anyOf": [
{
"format": "date",
"type": "string"
},
{
"type": "null"
}
]
},
"article14_status": {
"description": "Article 14 notice status: notified, publicly_notified_disproportionate_effort, pending_within_window.",
"enum": [
"notified",
"publicly_notified_disproportionate_effort",
"pending_within_window"
],
"type": "string"
},
"attribution": {
"description": "The OGL v3.0 attribution for Companies House company data. Officer names are personal data outside the OGL, so they carry article14_status instead.",
"type": [
"string",
"null"
]
},
"corporate_subscriber": {
"description": "True for companies, LLPs, Scottish partnerships and public bodies, where the PECR regulation 22 consent rule does not apply.",
"type": "boolean"
},
"email_marketing_basis": {
"enum": [
"pecr_corporate_subscriber",
"consent_required"
],
"type": "string"
},
"lawful_basis": {
"description": "UK GDPR Article 6(1)(f) legitimate interests, with the LIA in lia_ref.",
"enum": [
"legitimate_interests_art6_1_f"
],
"type": "string"
},
"lia_ref": {
"description": "The published legitimate interests assessment.",
"type": "string"
},
"notice_version": {
"description": "The privacy notice version sent.",
"type": "string"
},
"provenance": {
"$ref": "#/$defs/Provenance"
},
"record_age_days": {
"description": "Days since the record was compiled.",
"minimum": 0,
"type": "integer"
},
"subscriber_class": {
"description": "PECR subscriber class: ltd, plc, llp, scottish_partnership, public_body, charity_incorporated, sole_trader, ordinary_partnership, unknown.",
"enum": [
"ltd",
"plc",
"llp",
"scottish_partnership",
"public_body",
"charity_incorporated",
"sole_trader",
"ordinary_partnership",
"unknown"
],
"type": "string"
},
"subscriber_evidence": {
"description": "The register entry behind subscriber_class.",
"properties": {
"companies_house_number": {
"type": [
"string",
"null"
]
},
"company_type": {
"type": "string"
}
},
"required": [
"companies_house_number",
"company_type"
],
"type": "object"
},
"suppression_status": {
"enum": [
"none",
"objected_to_emailmovers",
"objected_to_licensee",
"deceased",
"left_company"
],
"type": "string"
},
"tps_ctps_screened_at": {
"anyOf": [
{
"format": "date",
"type": "string"
},
{
"type": "null"
}
],
"description": "The date of the screen the status is as of; null when not screened."
},
"tps_ctps_status": {
"description": "Telephone screen: clear, tps_registered, ctps_registered, tps_or_ctps_registered, not_screened. The result of the screen on tps_ctps_screened_at, valid until tps_ctps_valid_until. In a sample, an order's records (each time they are fetched, downloaded or pushed) and an enrichment, a clear number reads not_screened, with no dates, once that screen is more than 28 days before the day the record is served; a registered number stays registered.",
"enum": [
"clear",
"tps_registered",
"ctps_registered",
"tps_or_ctps_registered",
"not_screened"
],
"type": "string"
},
"tps_ctps_valid_until": {
"anyOf": [
{
"format": "date",
"type": "string"
},
{
"type": "null"
}
],
"description": "28 days after tps_ctps_screened_at, when this screen stops being valid. Null when not screened. Screen the numbers you are supplied yourself before calling, and again every 28 days."
}
},
"required": [
"lawful_basis",
"lia_ref",
"subscriber_class",
"corporate_subscriber",
"email_marketing_basis",
"subscriber_evidence",
"article14_status",
"article14_notified_at",
"notice_version",
"provenance",
"tps_ctps_status",
"tps_ctps_screened_at",
"tps_ctps_valid_until",
"suppression_status",
"record_age_days",
"attribution"
],
"type": "object"
},
"ContactRecord": {
"description": "One complete UK record: named email, telephone where held, postal address and company fields with Companies House number and SIC, plus the compliance object.",
"properties": {
"company": {
"properties": {
"companies_house_number": {
"type": [
"string",
"null"
]
},
"employee_band": {
"type": [
"string",
"null"
]
},
"name": {
"type": "string"
},
"sic_2007": {
"items": {
"$ref": "#/$defs/SicCode"
},
"type": "array"
},
"status": {
"type": "string"
},
"subscriber_class": {
"enum": [
"ltd",
"plc",
"llp",
"scottish_partnership",
"public_body",
"charity_incorporated",
"sole_trader",
"ordinary_partnership",
"unknown"
],
"type": "string"
},
"turnover_band": {
"type": [
"string",
"null"
]
},
"type": {
"type": "string"
},
"website_domain": {
"type": [
"string",
"null"
]
}
},
"required": [
"name",
"companies_house_number",
"status",
"type",
"subscriber_class",
"sic_2007",
"employee_band",
"turnover_band",
"website_domain"
],
"type": "object"
},
"compliance": {
"$ref": "#/$defs/ComplianceObject"
},
"contact": {
"properties": {
"first_name": {
"type": "string"
},
"job_function": {
"type": [
"string",
"null"
]
},
"job_level": {
"description": "The level, such as Director; null when the level is not known.",
"type": [
"string",
"null"
]
},
"job_level_rank": {
"anyOf": [
{
"maximum": 13,
"minimum": 1,
"type": "integer"
},
{
"type": "null"
}
],
"description": "Rank on the 13-rank ladder, 1 (Owner) the most senior to 13 (Volunteer); null when the level is not known."
},
"last_name": {
"type": "string"
},
"title": {
"type": "string"
},
"title_family": {
"type": [
"string",
"null"
]
}
},
"required": [
"first_name",
"last_name",
"title",
"title_family",
"job_function",
"job_level_rank",
"job_level"
],
"type": "object"
},
"dataset_version": {
"description": "The immutable weekly build a count is bound to, such as 2026-W39. The last 52 stay queryable.",
"examples": [
"2026-W39"
],
"pattern": "^[0-9]{4}-W(0[1-9]|[1-4][0-9]|5[0-3])$",
"type": "string"
},
"email": {
"anyOf": [
{
"properties": {
"address": {
"format": "email",
"type": "string"
},
"deliverability_score": {
"maximum": 100,
"minimum": 0,
"type": "integer"
},
"result": {
"enum": [
"ok",
"catch_all",
"unknown",
"invalid",
"disposable"
],
"type": "string"
},
"type": {
"enum": [
"named",
"generic_local_part",
"generic_domain"
],
"type": "string"
},
"verified_at": {
"anyOf": [
{
"format": "date",
"type": "string"
},
{
"type": "null"
}
]
}
},
"required": [
"address",
"type",
"deliverability_score",
"verified_at",
"result"
],
"type": "object"
},
{
"type": "null"
}
]
},
"id": {
"description": "The record id, pushed to CRMs as mydatahub_record_id.",
"examples": [
"contact_01JA9X2V7XN3M9R6T1Y5W8ZAK8"
],
"pattern": "^contact_[0-7][0-9A-HJKMNP-TV-Z]{25}$",
"type": "string"
},
"licence_expires_at": {
"anyOf": [
{
"format": "date",
"type": "string"
},
{
"type": "null"
}
]
},
"phone": {
"anyOf": [
{
"properties": {
"e164": {
"pattern": "^\\+[1-9][0-9]{7,14}$",
"type": "string"
},
"line_type": {
"enum": [
"landline",
"mobile",
"voip",
"unknown"
],
"type": "string"
},
"screened_at": {
"anyOf": [
{
"format": "date",
"type": "string"
},
{
"type": "null"
}
]
},
"tps_ctps_status": {
"enum": [
"clear",
"tps_registered",
"ctps_registered",
"tps_or_ctps_registered",
"not_screened"
],
"type": "string"
}
},
"required": [
"e164",
"line_type",
"tps_ctps_status",
"screened_at"
],
"type": "object"
},
{
"type": "null"
}
],
"description": "Present when the field set includes telephone and a number is held."
},
"site": {
"properties": {
"address_lines": {
"items": {
"type": "string"
},
"type": "array"
},
"county": {
"type": [
"string",
"null"
]
},
"postcode": {
"type": "string"
},
"region": {
"type": "string"
},
"town": {
"type": [
"string",
"null"
]
}
},
"required": [
"address_lines",
"town",
"county",
"postcode",
"region"
],
"type": "object"
}
},
"required": [
"id",
"dataset_version",
"contact",
"email",
"phone",
"company",
"site",
"compliance",
"licence_expires_at"
],
"type": "object"
},
"Provenance": {
"description": "Source per entity, answering the ICO questions who compiled it and where from.",
"properties": {
"company": {
"description": "Where the company facts came from and the snapshot date.",
"properties": {
"as_of": {
"format": "date",
"type": "string"
},
"source": {
"enum": [
"emailmovers_research",
"companies_house",
"onspd",
"ukbizdirectory",
"partner_rampedup"
],
"type": "string"
}
},
"required": [
"source",
"as_of"
],
"type": "object"
},
"contact": {
"anyOf": [
{
"properties": {
"compiled_at": {
"format": "date",
"type": "string"
},
"last_verified_at": {
"anyOf": [
{
"format": "date",
"type": "string"
},
{
"type": "null"
}
]
},
"method": {
"enum": [
"telephone",
"web",
"register"
],
"type": "string"
},
"source": {
"enum": [
"emailmovers_research",
"companies_house",
"onspd",
"ukbizdirectory",
"partner_rampedup"
],
"type": "string"
}
},
"required": [
"source",
"compiled_at",
"last_verified_at",
"method"
],
"type": "object"
},
{
"type": "null"
}
],
"description": "Who compiled the contact, when, and how it was last confirmed."
},
"email": {
"anyOf": [
{
"properties": {
"provider_location": {
"enum": [
"UK",
"EU",
"US"
],
"type": "string"
},
"result": {
"enum": [
"ok",
"catch_all",
"unknown",
"invalid",
"disposable"
],
"type": "string"
},
"verified_at": {
"format": "date",
"type": "string"
}
},
"required": [
"verified_at",
"result",
"provider_location"
],
"type": "object"
},
{
"type": "null"
}
],
"description": "The latest email verification: date, provider result and location."
}
},
"required": [
"company",
"contact"
],
"type": "object"
},
"SicCode": {
"description": "A SIC 2007 code and its label, such as 25620 Machining.",
"properties": {
"code": {
"type": "string"
},
"label": {
"type": "string"
}
},
"required": [
"code",
"label"
],
"type": "object"
}
},
"description": "The full record for a confident match, or no match at no charge.",
"properties": {
"already_licensed": {
"description": "True when you already hold the record, so it costs 0.",
"type": "boolean"
},
"cost_gbp": {
"description": "Pounds sterling excluding VAT, to two decimal places.",
"minimum": 0,
"type": "number"
},
"credits_charged": {
"description": "1 on a confident match, otherwise 0.",
"minimum": 0,
"type": "number"
},
"credits_remaining": {
"description": "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).",
"minimum": 0,
"type": "number"
},
"licence_expires_at": {
"anyOf": [
{
"format": "date",
"type": "string"
},
{
"type": "null"
}
]
},
"match_confidence": {
"anyOf": [
{
"maximum": 1,
"minimum": 0,
"type": "number"
},
{
"type": "null"
}
]
},
"matched": {
"type": "boolean"
},
"record": {
"anyOf": [
{
"$ref": "#/$defs/ContactRecord"
},
{
"type": "null"
}
]
}
},
"required": [
"matched",
"match_confidence",
"already_licensed",
"record",
"credits_charged",
"credits_remaining",
"cost_gbp",
"licence_expires_at"
],
"type": "object"
}
},
{
"description": "Expands title keywords into every matching title (plurals, department synonyms, ampersands, abbreviations such as CEO), each with a count, or shows what a bundle such as sdm resolves to. Use it before counting so the user can see and edit which titles a keyword covers; nothing is expanded silently. Free and needs no account. Put the returned filter into the audience, then call count_audience. Lawful basis is UK GDPR Article 6(1)(f) legitimate interests; email audiences include corporate subscribers only by default (PECR), so sole traders and ordinary partnerships are left out unless the toggle is changed.",
"inputSchema": {
"additionalProperties": false,
"description": "Keywords or a bundle to expand into an editable title list: exactly one of terms or bundle.",
"oneOf": [
{
"properties": {
"terms": true
},
"required": [
"terms"
],
"type": "object"
},
{
"properties": {
"bundle": true
},
"required": [
"bundle"
],
"type": "object"
}
],
"properties": {
"bundle": {
"description": "A title bundle to show: sdm, manager_and_above or owner_managed.",
"enum": [
"sdm",
"manager_and_above",
"owner_managed"
],
"type": "string"
},
"dataset": {
"description": "The dataset an audience draws from. uk_contacts is live; ie_contacts and global_contacts are listed but not yet served.",
"enum": [
"uk_contacts",
"ie_contacts",
"global_contacts"
],
"type": "string"
},
"expand": {
"description": "Expansion sets to apply, each once. Left out, the four default sets apply.",
"items": {
"enum": [
"plural_singular",
"department_synonyms",
"ampersand_and",
"abbreviations",
"permutations"
],
"type": "string"
},
"type": "array",
"uniqueItems": true
},
"mode": {
"description": "contains (the default) matches titles containing a term, starts_with matches titles beginning with it, exact takes verbatim titles with no expansion.",
"enum": [
"contains",
"starts_with",
"exact"
],
"type": "string"
},
"terms": {
"description": "Title keywords to expand, such as marketing manager.",
"items": {
"maxLength": 200,
"minLength": 1,
"type": "string"
},
"maxItems": 50,
"minItems": 1,
"type": "array"
}
},
"type": "object"
},
"name": "expand_job_titles",
"outputSchema": {
"$defs": {
"AllGroup": {
"additionalProperties": false,
"description": "AND: every node inside must match.",
"properties": {
"all": {
"items": {
"$ref": "#/$defs/WhereNode"
},
"minItems": 1,
"type": "array"
}
},
"required": [
"all"
],
"type": "object"
},
"AnyGroup": {
"additionalProperties": false,
"description": "OR: at least one node inside must match.",
"properties": {
"any": {
"items": {
"$ref": "#/$defs/WhereNode"
},
"minItems": 1,
"type": "array"
}
},
"required": [
"any"
],
"type": "object"
},
"BetweenFilter": {
"additionalProperties": false,
"description": "The field lies from one value to another inclusive, over the field's order.",
"examples": [
{
"field": "company.employee_band",
"from": "10-19",
"op": "between",
"to": "200-349"
}
],
"properties": {
"field": {
"enum": [
"company.employee_band",
"company.turnover_band",
"company.fleet_band",
"contact.job_level_rank",
"email.deliverability_score"
],
"type": "string"
},
"from": {
"anyOf": [
{
"maxLength": 200,
"minLength": 1,
"type": "string"
},
{
"type": "number"
}
],
"description": "A band code or a number from the field's order."
},
"op": {
"const": "between",
"type": "string"
},
"to": {
"anyOf": [
{
"maxLength": 200,
"minLength": 1,
"type": "string"
},
{
"type": "number"
}
],
"description": "A band code or a number from the field's order."
}
},
"required": [
"field",
"op",
"from",
"to"
],
"type": "object"
},
"BundleNode": {
"additionalProperties": false,
"description": "A title bundle, resolved to its filters in the effective definition: sdm (senior decision makers), manager_and_above (managers and above), owner_managed (owner managed).",
"properties": {
"bundle": {
"enum": [
"sdm",
"manager_and_above",
"owner_managed"
],
"type": "string"
}
},
"required": [
"bundle"
],
"type": "object"
},
"CellCount": {
"anyOf": [
{
"minimum": 0,
"type": "integer"
},
{
"const": "under 10",
"type": "string"
},
{
"const": "suppressed",
"type": "string"
}
],
"description": "A whole number; \"under 10\" when disclosure control withholds a small cell; or \"suppressed\" when secondary suppression hides a cell of 10 or more in a cross-tab or breakdown, so totals cannot be differenced. Anonymous and trial callers see cells rounded to the nearest 5.",
"examples": [
4120,
"under 10",
"suppressed"
]
},
"Disclosure": {
"description": "Whether these numbers are exact or protected: \"under 10\" cells, rounding to 5 and secondary suppression for anonymous and trial callers.",
"properties": {
"level": {
"description": "exact for authenticated paid callers; rounded for anonymous and trial callers, whose counts under 100 and every cell are rounded to the nearest 5.",
"enum": [
"exact",
"rounded"
],
"type": "string"
},
"notes": {
"items": {
"type": "string"
},
"type": "array"
},
"rounded_to": {
"anyOf": [
{
"exclusiveMinimum": 0,
"type": "integer"
},
{
"type": "null"
}
],
"description": "5 when numbers are rounded; null when they are exact."
},
"secondary_suppression": {
"description": "True when cross-tab or breakdown cells of 10 or more were hidden as \"suppressed\" so totals cannot be differenced.",
"type": "boolean"
}
},
"required": [
"level",
"rounded_to",
"secondary_suppression",
"notes"
],
"type": "object"
},
"ExpandedTerm": {
"description": "One title a matches filter covers, with its count.",
"properties": {
"contacts": {
"$ref": "#/$defs/CellCount"
},
"excluded": {
"description": "True when exclude_terms removed it from the audience.",
"type": "boolean"
},
"expansion_set": {
"anyOf": [
{
"enum": [
"plural_singular",
"department_synonyms",
"ampersand_and",
"abbreviations",
"permutations"
],
"type": "string"
},
{
"const": "input",
"type": "string"
}
],
"description": "The expansion set that produced it, or input for the term itself."
},
"from_term": {
"description": "The input term it came from.",
"type": "string"
},
"term": {
"description": "A matched title.",
"type": "string"
}
},
"required": [
"term",
"from_term",
"expansion_set",
"contacts"
],
"type": "object"
},
"Filter": {
"description": "One criterion: a field from GET /v1/catalogue/filters, an operator and its operands. Exclusions nest under not.",
"oneOf": [
{
"$ref": "#/$defs/InFilter"
},
{
"$ref": "#/$defs/BetweenFilter"
},
{
"$ref": "#/$defs/GteFilter"
},
{
"$ref": "#/$defs/LteFilter"
},
{
"$ref": "#/$defs/MatchesFilter"
},
{
"$ref": "#/$defs/WithinRadiusFilter"
},
{
"$ref": "#/$defs/InListFilter"
},
{
"$ref": "#/$defs/SinceFilter"
}
]
},
"GteFilter": {
"additionalProperties": false,
"description": "The field is at or after the value in its order: for bands, the band and every larger one.",
"examples": [
{
"field": "company.employee_band",
"op": "gte",
"value": "50-99"
}
],
"properties": {
"field": {
"enum": [
"company.employee_band",
"company.turnover_band",
"company.fleet_band",
"contact.job_level_rank",
"email.deliverability_score"
],
"type": "string"
},
"op": {
"const": "gte",
"type": "string"
},
"value": {
"anyOf": [
{
"maxLength": 200,
"minLength": 1,
"type": "string"
},
{
"type": "number"
}
],
"description": "A band code or a number from the field's order."
}
},
"required": [
"field",
"op",
"value"
],
"type": "object"
},
"InFilter": {
"additionalProperties": false,
"description": "The field holds one of the listed codes.",
"examples": [
{
"field": "company.sic_2007",
"op": "in",
"values": [
"C"
]
}
],
"properties": {
"field": {
"enum": [
"company.sic_2007",
"company.business_class",
"company.employee_band",
"company.turnover_band",
"company.fleet_band",
"company.type",
"company.status",
"company.subscriber_class",
"company.companies_house_number",
"site.region",
"site.county",
"site.town",
"site.postcode",
"contact.title_family",
"contact.job_function",
"contact.job_level_rank",
"contact.premium",
"email.exists",
"email.type",
"phone.exists",
"phone.tps_ctps_status"
],
"type": "string"
},
"op": {
"const": "in",
"type": "string"
},
"values": {
"items": {
"anyOf": [
{
"maxLength": 200,
"minLength": 1,
"type": "string"
},
{
"type": "number"
},
{
"type": "boolean"
}
],
"description": "A code, a rank or a boolean, as the field's catalogue lists it."
},
"maxItems": 10000,
"minItems": 1,
"type": "array"
}
},
"required": [
"field",
"op",
"values"
],
"type": "object"
},
"InListFilter": {
"additionalProperties": false,
"description": "The record's hashed email, domain, phone, company number or title term is on a suppression list. Usually nested under not; each list reports the records it removed.",
"examples": [
{
"field": "email.address_sha256",
"list_id": "sup_01JB4H7Q2V7XN3M9R6T1Y5W8ZA",
"op": "in_list"
}
],
"properties": {
"field": {
"enum": [
"company.companies_house_number",
"contact.title",
"email.address_sha256",
"email.domain_sha256",
"phone.e164_sha256"
],
"type": "string"
},
"list_id": {
"description": "Format: a suppression list id: sup_ followed by a 26 character ULID in upper case Crockford base32, such as sup_01JB4H7Q2V7XN3M9R6T1Y5W8ZA.",
"examples": [
"sup_01JB4H7Q2V7XN3M9R6T1Y5W8ZA"
],
"pattern": "^sup_[0-7][0-9A-HJKMNP-TV-Z]{25}$",
"type": "string"
},
"op": {
"const": "in_list",
"type": "string"
}
},
"required": [
"field",
"op",
"list_id"
],
"type": "object"
},
"LteFilter": {
"additionalProperties": false,
"description": "The field is at or before the value in its order. Rank 1 is the most senior, so Director and above is contact.job_level_rank lte 6.",
"examples": [
{
"field": "contact.job_level_rank",
"op": "lte",
"value": 6
}
],
"properties": {
"field": {
"enum": [
"company.employee_band",
"company.turnover_band",
"company.fleet_band",
"contact.job_level_rank",
"contact.company_contact_rank",
"email.deliverability_score"
],
"type": "string"
},
"op": {
"const": "lte",
"type": "string"
},
"value": {
"anyOf": [
{
"maxLength": 200,
"minLength": 1,
"type": "string"
},
{
"type": "number"
}
],
"description": "A band code or a number from the field's order."
}
},
"required": [
"field",
"op",
"value"
],
"type": "object"
},
"MatchesFilter": {
"additionalProperties": false,
"allOf": [
{
"if": {
"properties": {
"mode": {
"const": "exact"
}
},
"required": [
"mode"
],
"type": "object"
},
"then": {
"properties": {
"exclude_terms": {
"maxItems": 0,
"type": "array"
},
"expand": {
"maxItems": 0,
"type": "array"
}
},
"type": "object"
}
}
],
"description": "Job title keyword match. mode contains (the default) or starts_with expands each term with the expansion sets; mode exact matches verbatim titles. Every expanded term is returned with the count.",
"examples": [
{
"expand": [
"plural_singular",
"department_synonyms",
"ampersand_and",
"abbreviations"
],
"field": "contact.title",
"mode": "contains",
"op": "matches",
"terms": [
"marketing manager"
]
}
],
"properties": {
"exclude_terms": {
"description": "Expanded terms removed by hand. Kept in the definition so the count stays reproducible when the title dictionary changes.",
"items": {
"maxLength": 200,
"minLength": 1,
"type": "string"
},
"maxItems": 500,
"type": "array"
},
"expand": {
"description": "Expansion sets to apply, each once: plural_singular, department_synonyms, ampersand_and, abbreviations, permutations. Left out, the first four apply; an empty list applies none. Not used with mode exact.",
"items": {
"enum": [
"plural_singular",
"department_synonyms",
"ampersand_and",
"abbreviations",
"permutations"
],
"type": "string"
},
"maxItems": 5,
"type": "array",
"uniqueItems": true
},
"field": {
"enum": [
"contact.title"
],
"type": "string"
},
"mode": {
"description": "contains (the default) matches titles containing a term, starts_with matches titles beginning with it, exact takes verbatim titles with no expansion.",
"enum": [
"contains",
"starts_with",
"exact"
],
"type": "string"
},
"op": {
"const": "matches",
"type": "string"
},
"terms": {
"items": {
"maxLength": 200,
"minLength": 1,
"type": "string"
},
"maxItems": 500,
"minItems": 1,
"type": "array"
}
},
"required": [
"field",
"op",
"terms"
],
"type": "object"
},
"NotGroup": {
"additionalProperties": false,
"description": "Negation: the single node inside must not match.",
"properties": {
"not": {
"$ref": "#/$defs/WhereNode"
}
},
"required": [
"not"
],
"type": "object"
},
"PlaceCentre": {
"additionalProperties": false,
"description": "A named place. Ambiguous names come back from resolve_location as candidates, never a silent choice.",
"properties": {
"code": {
"description": "The ONS geography code of the chosen candidate when resolve_location found more than one, such as E08000035 for the Leeds district.",
"maxLength": 20,
"minLength": 1,
"type": "string"
},
"place": {
"description": "A place name, resolved with resolve_location, such as Leeds.",
"maxLength": 100,
"minLength": 1,
"type": "string"
}
},
"required": [
"place"
],
"type": "object"
},
"PointCentre": {
"additionalProperties": false,
"description": "A latitude and longitude in WGS84 degrees.",
"properties": {
"lat": {
"maximum": 61,
"minimum": 49,
"type": "number"
},
"lon": {
"maximum": 2,
"minimum": -9,
"type": "number"
}
},
"required": [
"lat",
"lon"
],
"type": "object"
},
"PostcodeCentre": {
"additionalProperties": false,
"description": "A postcode centroid from ONSPD.",
"properties": {
"postcode": {
"description": "The centroid of a postcode unit, sector, district or area, such as LS1 4AP.",
"pattern": "^[A-Za-z]{1,2}([0-9][0-9A-Za-z]?( [0-9]([A-Za-z]{2})?| ?[0-9][A-Za-z]{2})?)?$",
"type": "string"
}
},
"required": [
"postcode"
],
"type": "object"
},
"RadiusCentre": {
"anyOf": [
{
"$ref": "#/$defs/PlaceCentre"
},
{
"$ref": "#/$defs/PostcodeCentre"
},
{
"$ref": "#/$defs/PointCentre"
}
],
"description": "The centre of a radius: a place, a postcode or a latitude and longitude."
},
"SinceFilter": {
"additionalProperties": false,
"description": "Within the last N days: a date field, or a Companies House signal of the listed types on signal.type.",
"examples": [
{
"days": 90,
"field": "signal.type",
"op": "since",
"values": [
"company.incorporated"
]
}
],
"properties": {
"days": {
"maximum": 3650,
"minimum": 1,
"type": "integer"
},
"field": {
"enum": [
"contact.last_validated_at",
"email.last_verified_at",
"signal.type",
"signal.observed_at"
],
"type": "string"
},
"op": {
"const": "since",
"type": "string"
},
"values": {
"description": "For signal.type only: the signal types to look for, such as company.incorporated.",
"items": {
"maxLength": 200,
"minLength": 1,
"type": "string"
},
"maxItems": 10000,
"minItems": 1,
"type": "array"
}
},
"required": [
"field",
"op",
"days"
],
"type": "object"
},
"WhereNode": {
"anyOf": [
{
"$ref": "#/$defs/AllGroup"
},
{
"$ref": "#/$defs/AnyGroup"
},
{
"$ref": "#/$defs/NotGroup"
},
{
"$ref": "#/$defs/BundleNode"
},
{
"$ref": "#/$defs/Filter"
}
],
"description": "A group (all, any, not), a title bundle or a filter. Groups nest up to 32 deep, and a where tree holds up to 1,000 filters, groups and bundles."
},
"WithinRadiusFilter": {
"additionalProperties": false,
"description": "Sites within radius_miles of the centre. The count reports the centroid used and the postcodes matched.",
"examples": [
{
"centre": {
"place": "Leeds"
},
"field": "site.location",
"op": "within_radius",
"radius_miles": 20
}
],
"properties": {
"centre": {
"$ref": "#/$defs/RadiusCentre"
},
"field": {
"enum": [
"site.location"
],
"type": "string"
},
"op": {
"const": "within_radius",
"type": "string"
},
"radius_miles": {
"description": "Radius in miles, 1 to 100. Under 5 miles needs an account.",
"maximum": 100,
"minimum": 1,
"type": "number"
}
},
"required": [
"field",
"op",
"centre",
"radius_miles"
],
"type": "object"
}
},
"description": "Every expanded title with a count, or what a bundle resolves to. Nothing is resolved silently.",
"properties": {
"bundle": {
"anyOf": [
{
"properties": {
"id": {
"enum": [
"sdm",
"manager_and_above",
"owner_managed"
],
"type": "string"
},
"label": {
"type": "string"
},
"resolves_to": {
"$ref": "#/$defs/WhereNode"
},
"status": {
"enum": [
"confirmed",
"proposed",
"to_confirm"
],
"type": "string"
}
},
"required": [
"id",
"label",
"status",
"resolves_to"
],
"type": "object"
},
{
"type": "null"
}
]
},
"dataset_version": {
"description": "The immutable weekly build a count is bound to, such as 2026-W39. The last 52 stay queryable.",
"examples": [
"2026-W39"
],
"pattern": "^[0-9]{4}-W(0[1-9]|[1-4][0-9]|5[0-3])$",
"type": "string"
},
"disclosure": {
"$ref": "#/$defs/Disclosure"
},
"expand": {
"items": {
"enum": [
"plural_singular",
"department_synonyms",
"ampersand_and",
"abbreviations",
"permutations"
],
"type": "string"
},
"type": "array"
},
"filter": {
"anyOf": [
{
"$ref": "#/$defs/Filter"
},
{
"type": "null"
}
],
"description": "A ready matches filter for the terms, or null for a bundle."
},
"mode": {
"description": "contains (the default) matches titles containing a term, starts_with matches titles beginning with it, exact takes verbatim titles with no expansion.",
"enum": [
"contains",
"starts_with",
"exact"
],
"type": "string"
},
"terms": {
"items": {
"$ref": "#/$defs/ExpandedTerm"
},
"type": "array"
},
"total_contacts": {
"$ref": "#/$defs/CellCount"
}
},
"required": [
"dataset_version",
"mode",
"expand",
"terms",
"total_contacts",
"bundle",
"filter",
"disclosure"
],
"type": "object"
}
},
{
"description": "Returns a page of an order's delivered records (50 by default, up to 100) with the licence block on every page, as JSON or, on request, as CSV. Pages stay under about 8,000 tokens, with approx_tokens on each; pass next_cursor to continue. Fetching again under licence costs 0 credits; it needs records:read. Call check_suppression before any send, and get_compliance_receipt for proof of screening. Lawful basis is UK GDPR Article 6(1)(f) legitimate interests; email audiences include corporate subscribers only by default (PECR), so sole traders and ordinary partnerships are left out unless the toggle is changed.",
"inputSchema": {
"additionalProperties": false,
"properties": {
"cursor": {
"description": "An opaque cursor from next_cursor. Pass it back unchanged.",
"maxLength": 512,
"minLength": 1,
"type": "string"
},
"fields": {
"description": "Columns to return; default the order's field set.",
"items": {
"pattern": "^[a-z0-9_]+$",
"type": "string"
},
"type": "array"
},
"format": {
"default": "json",
"description": "json (default) or csv.",
"enum": [
"json",
"csv"
],
"type": "string"
},
"limit": {
"default": 50,
"description": "Records per page, 1 to 100 over MCP so a result stays under about 8,000 tokens. Default 50.",
"maximum": 100,
"minimum": 1,
"type": "integer"
},
"order_id": {
"description": "The order whose records to fetch. It must be ready.",
"examples": [
"ord_01JB4N9S3W2X6Y7Z8A1B2C3D4E"
],
"pattern": "^ord_[0-7][0-9A-HJKMNP-TV-Z]{25}$",
"type": "string"
}
},
"required": [
"order_id"
],
"type": "object"
},
"name": "fetch_order_records",
"outputSchema": {
"$defs": {
"ComplianceObject": {
"description": "Carried by every preview row, order record, lookup and enrichment, and repeated as CSV columns and as the MyDataHub property group on CRM push.",
"examples": [
{
"article14_notified_at": "2026-06-14",
"article14_status": "notified",
"attribution": "Contains public sector information licensed under the Open Government Licence v3.0",
"corporate_subscriber": true,
"email_marketing_basis": "pecr_corporate_subscriber",
"lawful_basis": "legitimate_interests_art6_1_f",
"lia_ref": "EM-LIA-2026-03",
"notice_version": "2026-02",
"provenance": {
"company": {
"as_of": "2026-09-21",
"source": "companies_house"
},
"contact": {
"compiled_at": "2026-05-02",
"last_verified_at": "2026-08-30",
"method": "telephone",
"source": "emailmovers_research"
},
"email": {
"provider_location": "EU",
"result": "ok",
"verified_at": "2026-09-10"
}
},
"record_age_days": 147,
"subscriber_class": "ltd",
"subscriber_evidence": {
"companies_house_number": "05046417",
"company_type": "ltd"
},
"suppression_status": "none",
"tps_ctps_screened_at": "2026-09-12",
"tps_ctps_status": "clear",
"tps_ctps_valid_until": "2026-10-10"
}
],
"properties": {
"article14_notified_at": {
"anyOf": [
{
"format": "date",
"type": "string"
},
{
"type": "null"
}
]
},
"article14_status": {
"description": "Article 14 notice status: notified, publicly_notified_disproportionate_effort, pending_within_window.",
"enum": [
"notified",
"publicly_notified_disproportionate_effort",
"pending_within_window"
],
"type": "string"
},
"attribution": {
"description": "The OGL v3.0 attribution for Companies House company data. Officer names are personal data outside the OGL, so they carry article14_status instead.",
"type": [
"string",
"null"
]
},
"corporate_subscriber": {
"description": "True for companies, LLPs, Scottish partnerships and public bodies, where the PECR regulation 22 consent rule does not apply.",
"type": "boolean"
},
"email_marketing_basis": {
"enum": [
"pecr_corporate_subscriber",
"consent_required"
],
"type": "string"
},
"lawful_basis": {
"description": "UK GDPR Article 6(1)(f) legitimate interests, with the LIA in lia_ref.",
"enum": [
"legitimate_interests_art6_1_f"
],
"type": "string"
},
"lia_ref": {
"description": "The published legitimate interests assessment.",
"type": "string"
},
"notice_version": {
"description": "The privacy notice version sent.",
"type": "string"
},
"provenance": {
"$ref": "#/$defs/Provenance"
},
"record_age_days": {
"description": "Days since the record was compiled.",
"minimum": 0,
"type": "integer"
},
"subscriber_class": {
"description": "PECR subscriber class: ltd, plc, llp, scottish_partnership, public_body, charity_incorporated, sole_trader, ordinary_partnership, unknown.",
"enum": [
"ltd",
"plc",
"llp",
"scottish_partnership",
"public_body",
"charity_incorporated",
"sole_trader",
"ordinary_partnership",
"unknown"
],
"type": "string"
},
"subscriber_evidence": {
"description": "The register entry behind subscriber_class.",
"properties": {
"companies_house_number": {
"type": [
"string",
"null"
]
},
"company_type": {
"type": "string"
}
},
"required": [
"companies_house_number",
"company_type"
],
"type": "object"
},
"suppression_status": {
"enum": [
"none",
"objected_to_emailmovers",
"objected_to_licensee",
"deceased",
"left_company"
],
"type": "string"
},
"tps_ctps_screened_at": {
"anyOf": [
{
"format": "date",
"type": "string"
},
{
"type": "null"
}
],
"description": "The date of the screen the status is as of; null when not screened."
},
"tps_ctps_status": {
"description": "Telephone screen: clear, tps_registered, ctps_registered, tps_or_ctps_registered, not_screened. The result of the screen on tps_ctps_screened_at, valid until tps_ctps_valid_until. In a sample, an order's records (each time they are fetched, downloaded or pushed) and an enrichment, a clear number reads not_screened, with no dates, once that screen is more than 28 days before the day the record is served; a registered number stays registered.",
"enum": [
"clear",
"tps_registered",
"ctps_registered",
"tps_or_ctps_registered",
"not_screened"
],
"type": "string"
},
"tps_ctps_valid_until": {
"anyOf": [
{
"format": "date",
"type": "string"
},
{
"type": "null"
}
],
"description": "28 days after tps_ctps_screened_at, when this screen stops being valid. Null when not screened. Screen the numbers you are supplied yourself before calling, and again every 28 days."
}
},
"required": [
"lawful_basis",
"lia_ref",
"subscriber_class",
"corporate_subscriber",
"email_marketing_basis",
"subscriber_evidence",
"article14_status",
"article14_notified_at",
"notice_version",
"provenance",
"tps_ctps_status",
"tps_ctps_screened_at",
"tps_ctps_valid_until",
"suppression_status",
"record_age_days",
"attribution"
],
"type": "object"
},
"ContactRecord": {
"description": "One complete UK record: named email, telephone where held, postal address and company fields with Companies House number and SIC, plus the compliance object.",
"properties": {
"company": {
"properties": {
"companies_house_number": {
"type": [
"string",
"null"
]
},
"employee_band": {
"type": [
"string",
"null"
]
},
"name": {
"type": "string"
},
"sic_2007": {
"items": {
"$ref": "#/$defs/SicCode"
},
"type": "array"
},
"status": {
"type": "string"
},
"subscriber_class": {
"enum": [
"ltd",
"plc",
"llp",
"scottish_partnership",
"public_body",
"charity_incorporated",
"sole_trader",
"ordinary_partnership",
"unknown"
],
"type": "string"
},
"turnover_band": {
"type": [
"string",
"null"
]
},
"type": {
"type": "string"
},
"website_domain": {
"type": [
"string",
"null"
]
}
},
"required": [
"name",
"companies_house_number",
"status",
"type",
"subscriber_class",
"sic_2007",
"employee_band",
"turnover_band",
"website_domain"
],
"type": "object"
},
"compliance": {
"$ref": "#/$defs/ComplianceObject"
},
"contact": {
"properties": {
"first_name": {
"type": "string"
},
"job_function": {
"type": [
"string",
"null"
]
},
"job_level": {
"description": "The level, such as Director; null when the level is not known.",
"type": [
"string",
"null"
]
},
"job_level_rank": {
"anyOf": [
{
"maximum": 13,
"minimum": 1,
"type": "integer"
},
{
"type": "null"
}
],
"description": "Rank on the 13-rank ladder, 1 (Owner) the most senior to 13 (Volunteer); null when the level is not known."
},
"last_name": {
"type": "string"
},
"title": {
"type": "string"
},
"title_family": {
"type": [
"string",
"null"
]
}
},
"required": [
"first_name",
"last_name",
"title",
"title_family",
"job_function",
"job_level_rank",
"job_level"
],
"type": "object"
},
"dataset_version": {
"description": "The immutable weekly build a count is bound to, such as 2026-W39. The last 52 stay queryable.",
"examples": [
"2026-W39"
],
"pattern": "^[0-9]{4}-W(0[1-9]|[1-4][0-9]|5[0-3])$",
"type": "string"
},
"email": {
"anyOf": [
{
"properties": {
"address": {
"format": "email",
"type": "string"
},
"deliverability_score": {
"maximum": 100,
"minimum": 0,
"type": "integer"
},
"result": {
"enum": [
"ok",
"catch_all",
"unknown",
"invalid",
"disposable"
],
"type": "string"
},
"type": {
"enum": [
"named",
"generic_local_part",
"generic_domain"
],
"type": "string"
},
"verified_at": {
"anyOf": [
{
"format": "date",
"type": "string"
},
{
"type": "null"
}
]
}
},
"required": [
"address",
"type",
"deliverability_score",
"verified_at",
"result"
],
"type": "object"
},
{
"type": "null"
}
]
},
"id": {
"description": "The record id, pushed to CRMs as mydatahub_record_id.",
"examples": [
"contact_01JA9X2V7XN3M9R6T1Y5W8ZAK8"
],
"pattern": "^contact_[0-7][0-9A-HJKMNP-TV-Z]{25}$",
"type": "string"
},
"licence_expires_at": {
"anyOf": [
{
"format": "date",
"type": "string"
},
{
"type": "null"
}
]
},
"phone": {
"anyOf": [
{
"properties": {
"e164": {
"pattern": "^\\+[1-9][0-9]{7,14}$",
"type": "string"
},
"line_type": {
"enum": [
"landline",
"mobile",
"voip",
"unknown"
],
"type": "string"
},
"screened_at": {
"anyOf": [
{
"format": "date",
"type": "string"
},
{
"type": "null"
}
]
},
"tps_ctps_status": {
"enum": [
"clear",
"tps_registered",
"ctps_registered",
"tps_or_ctps_registered",
"not_screened"
],
"type": "string"
}
},
"required": [
"e164",
"line_type",
"tps_ctps_status",
"screened_at"
],
"type": "object"
},
{
"type": "null"
}
],
"description": "Present when the field set includes telephone and a number is held."
},
"site": {
"properties": {
"address_lines": {
"items": {
"type": "string"
},
"type": "array"
},
"county": {
"type": [
"string",
"null"
]
},
"postcode": {
"type": "string"
},
"region": {
"type": "string"
},
"town": {
"type": [
"string",
"null"
]
}
},
"required": [
"address_lines",
"town",
"county",
"postcode",
"region"
],
"type": "object"
}
},
"required": [
"id",
"dataset_version",
"contact",
"email",
"phone",
"company",
"site",
"compliance",
"licence_expires_at"
],
"type": "object"
},
"Licence": {
"description": "Licence terms as data, on every quote, order, records page and receipt. Records stay usable, pushable and re-downloadable free until reuse_until.",
"properties": {
"permitted_channels": {
"description": "email, telephone and post on standard terms.",
"items": {
"enum": [
"email",
"telephone",
"post"
],
"type": "string"
},
"type": "array"
},
"resale_prohibited": {
"type": "boolean"
},
"reuse_until": {
"anyOf": [
{
"format": "date",
"type": "string"
},
{
"type": "null"
}
],
"description": "Order date plus 12 months; null for outright."
},
"terms_url": {
"description": "Where that version of the Data Licence and Sharing Agreement is published.",
"format": "uri",
"type": "string"
},
"terms_version": {
"description": "The version of the Data Licence and Sharing Agreement the licence is under, such as 1.0.",
"type": "string"
},
"type": {
"description": "multi_use_12m (12 month multi-use, every plan) or outright (1.8 credits a record, proposed).",
"enum": [
"multi_use_12m",
"outright"
],
"type": "string"
},
"warranty_url": {
"format": "uri",
"type": "string"
}
},
"required": [
"type",
"reuse_until",
"resale_prohibited",
"permitted_channels",
"warranty_url",
"terms_version"
],
"type": "object"
},
"Provenance": {
"description": "Source per entity, answering the ICO questions who compiled it and where from.",
"properties": {
"company": {
"description": "Where the company facts came from and the snapshot date.",
"properties": {
"as_of": {
"format": "date",
"type": "string"
},
"source": {
"enum": [
"emailmovers_research",
"companies_house",
"onspd",
"ukbizdirectory",
"partner_rampedup"
],
"type": "string"
}
},
"required": [
"source",
"as_of"
],
"type": "object"
},
"contact": {
"anyOf": [
{
"properties": {
"compiled_at": {
"format": "date",
"type": "string"
},
"last_verified_at": {
"anyOf": [
{
"format": "date",
"type": "string"
},
{
"type": "null"
}
]
},
"method": {
"enum": [
"telephone",
"web",
"register"
],
"type": "string"
},
"source": {
"enum": [
"emailmovers_research",
"companies_house",
"onspd",
"ukbizdirectory",
"partner_rampedup"
],
"type": "string"
}
},
"required": [
"source",
"compiled_at",
"last_verified_at",
"method"
],
"type": "object"
},
{
"type": "null"
}
],
"description": "Who compiled the contact, when, and how it was last confirmed."
},
"email": {
"anyOf": [
{
"properties": {
"provider_location": {
"enum": [
"UK",
"EU",
"US"
],
"type": "string"
},
"result": {
"enum": [
"ok",
"catch_all",
"unknown",
"invalid",
"disposable"
],
"type": "string"
},
"verified_at": {
"format": "date",
"type": "string"
}
},
"required": [
"verified_at",
"result",
"provider_location"
],
"type": "object"
},
{
"type": "null"
}
],
"description": "The latest email verification: date, provider result and location."
}
},
"required": [
"company",
"contact"
],
"type": "object"
},
"RecordsCsvPage": {
"description": "A page of delivered records as CSV text with the licence block, for fetch_order_records with format csv.",
"properties": {
"approx_tokens": {
"minimum": 0,
"type": "integer"
},
"csv": {
"description": "The page as CSV with a header row and compliance fields as columns: the text GET /v1/orders/{id}/records returns with format=csv.",
"type": "string"
},
"fields": {
"description": "The columns, in the order of the header.",
"items": {
"pattern": "^[a-z0-9]+(_[a-z0-9]+)*$",
"type": "string"
},
"type": "array"
},
"format": {
"const": "csv",
"type": "string"
},
"has_more": {
"type": "boolean"
},
"licence": {
"$ref": "#/$defs/Licence"
},
"next_cursor": {
"anyOf": [
{
"description": "An opaque cursor from next_cursor. Pass it back unchanged.",
"maxLength": 512,
"minLength": 1,
"type": "string"
},
{
"type": "null"
}
]
},
"order_id": {
"description": "Format: an order id: ord_ followed by a 26 character ULID in upper case Crockford base32, such as ord_01JB4N9S3W2X6Y7Z8A1B2C3D4E.",
"examples": [
"ord_01JB4N9S3W2X6Y7Z8A1B2C3D4E"
],
"pattern": "^ord_[0-7][0-9A-HJKMNP-TV-Z]{25}$",
"type": "string"
},
"remaining": {
"description": "Records after this page.",
"minimum": 0,
"type": "integer"
},
"rows": {
"description": "Records in this page, not counting the header.",
"minimum": 0,
"type": "integer"
}
},
"required": [
"order_id",
"format",
"fields",
"rows",
"csv",
"has_more",
"next_cursor",
"remaining",
"licence"
],
"type": "object"
},
"RecordsPage": {
"description": "A page of delivered records with the licence block. Re-fetching records under licence costs 0 credits.",
"properties": {
"approx_tokens": {
"description": "A rough token size of this page; pages stay under about 8,000 tokens.",
"minimum": 0,
"type": "integer"
},
"data": {
"items": {
"$ref": "#/$defs/ContactRecord"
},
"type": "array"
},
"fields": {
"description": "The field set's columns in this page.",
"items": {
"pattern": "^[a-z0-9]+(_[a-z0-9]+)*$",
"type": "string"
},
"type": "array"
},
"format": {
"const": "json",
"type": "string"
},
"has_more": {
"type": "boolean"
},
"licence": {
"$ref": "#/$defs/Licence"
},
"next_cursor": {
"anyOf": [
{
"description": "An opaque cursor from next_cursor. Pass it back unchanged.",
"maxLength": 512,
"minLength": 1,
"type": "string"
},
{
"type": "null"
}
]
},
"order_id": {
"description": "Format: an order id: ord_ followed by a 26 character ULID in upper case Crockford base32, such as ord_01JB4N9S3W2X6Y7Z8A1B2C3D4E.",
"examples": [
"ord_01JB4N9S3W2X6Y7Z8A1B2C3D4E"
],
"pattern": "^ord_[0-7][0-9A-HJKMNP-TV-Z]{25}$",
"type": "string"
},
"remaining": {
"description": "Records after this page.",
"minimum": 0,
"type": "integer"
}
},
"required": [
"order_id",
"format",
"fields",
"data",
"has_more",
"next_cursor",
"remaining",
"licence"
],
"type": "object"
},
"SicCode": {
"description": "A SIC 2007 code and its label, such as 25620 Machining.",
"properties": {
"code": {
"type": "string"
},
"label": {
"type": "string"
}
},
"required": [
"code",
"label"
],
"type": "object"
}
},
"oneOf": [
{
"$ref": "#/$defs/RecordsPage"
},
{
"$ref": "#/$defs/RecordsCsvPage"
}
],
"type": "object"
}
},
{
"description": "Returns the organisation's credit balance by source, plan, per-action prices and rate limit, and for an agent key its monthly budget and per-order cap. Use it before quoting a large order, or when a spend is refused, to see what remains. Free; it needs a token with account:read. Top-ups happen on mydatahub.emailmovers.com, never inside a tool. Lawful basis is UK GDPR Article 6(1)(f) legitimate interests; email audiences include corporate subscribers only by default (PECR), so sole traders and ordinary partnerships are left out unless the toggle is changed.",
"inputSchema": {
"additionalProperties": false,
"properties": {},
"type": "object"
},
"name": "get_account",
"outputSchema": {
"$defs": {
"Agreement": {
"properties": {
"accepted": {
"anyOf": [
{
"properties": {
"accepted_at": {
"format": "date-time",
"type": "string"
},
"accepted_by": {
"description": "Format: a user id: usr_ followed by a 26 character ULID in upper case Crockford base32, such as usr_01JA0Q3V7XN3M9R6T1Y5W8ZAK8.",
"examples": [
"usr_01JA0Q3V7XN3M9R6T1Y5W8ZAK8"
],
"pattern": "^usr_[0-7][0-9A-HJKMNP-TV-Z]{25}$",
"type": "string"
},
"version": {
"type": "string"
}
},
"required": [
"version",
"accepted_at",
"accepted_by"
],
"type": "object"
},
{
"type": "null"
}
],
"description": "The organisation's acceptance of the latest version it accepted: which version, when and by whom, first time for that version. null until one is accepted. When version (the one in force) differs, the agreement is accepted again."
},
"accepted_version": {
"description": "The latest version accepted, accepted.version; null when none was.",
"type": [
"string",
"null"
]
},
"in_force": {
"description": "Whether the version accepted is the version in force. false when none was accepted, or an older one.",
"type": "boolean"
},
"name": {
"type": "string"
},
"url": {
"format": "uri",
"type": "string"
},
"version": {
"description": "The version in force: draft until the text is approved.",
"type": "string"
}
},
"required": [
"name",
"version",
"url",
"accepted",
"accepted_version",
"in_force"
],
"type": "object"
},
"Budget": {
"description": "An agent key's monthly budget in credits.",
"properties": {
"monthly_credits": {
"minimum": 0,
"type": "integer"
},
"remaining": {
"description": "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).",
"minimum": 0,
"type": "number"
},
"resets_at": {
"format": "date-time",
"type": "string"
},
"spent": {
"description": "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).",
"minimum": 0,
"type": "number"
}
},
"required": [
"monthly_credits",
"spent",
"remaining",
"resets_at"
],
"type": "object"
},
"BusinessDetails": {
"description": "Whether the business name and a UK business confirmation are on record, which a self-serve account needs before its first order and before it buys credits.",
"properties": {
"confirmed_at": {
"anyOf": [
{
"format": "date-time",
"type": "string"
},
{
"type": "null"
}
],
"description": "When a person confirmed the business name and that it is a UK business; null until then."
},
"name_editable": {
"description": "true for an organisation made by self-serve sign-up, whose business name PATCH /v1/account sets. false for one Emailmovers set up, which keeps the name staff gave it and needs no business details before an order.",
"type": "boolean"
},
"required_before_order": {
"description": "true: an order, an enrichment or a card purchase of credits is refused with business-details-required until a person who owns the account confirms them with PATCH /v1/account. Only an organisation made by self-serve sign-up before sign-up asked for them can need them, and whether it does is set when it is made.",
"type": "boolean"
}
},
"required": [
"confirmed_at",
"required_before_order",
"name_editable"
],
"type": "object"
},
"CreditRule": {
"description": "What one action costs in credits.",
"properties": {
"action": {
"pattern": "^[a-z0-9]+(_[a-z0-9]+)*$",
"type": "string"
},
"credits": {
"description": "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).",
"minimum": 0,
"type": "number"
},
"label": {
"type": "string"
},
"note": {
"type": "string"
},
"status": {
"description": "confirmed is in force; proposed awaits a decision; to_confirm is a figure still being checked.",
"enum": [
"confirmed",
"proposed",
"to_confirm"
],
"type": "string"
},
"unit": {
"enum": [
"call",
"record",
"match"
],
"type": "string"
}
},
"required": [
"action",
"label",
"credits",
"unit",
"status"
],
"type": "object"
},
"RateLimit": {
"description": "The caller's count limits and what remains in the window.",
"properties": {
"counts_per_day": {
"anyOf": [
{
"minimum": 0,
"type": "integer"
},
{
"type": "null"
}
]
},
"counts_per_hour": {
"anyOf": [
{
"minimum": 0,
"type": "integer"
},
{
"type": "null"
}
]
},
"counts_per_minute": {
"anyOf": [
{
"minimum": 0,
"type": "integer"
},
{
"type": "null"
}
]
},
"remaining": {
"minimum": 0,
"type": "integer"
},
"resets_at": {
"format": "date-time",
"type": "string"
},
"status": {
"enum": [
"confirmed",
"to_confirm"
],
"type": "string"
},
"tier": {
"enum": [
"anonymous",
"free",
"paid"
],
"type": "string"
}
},
"required": [
"tier",
"counts_per_minute",
"counts_per_hour",
"counts_per_day",
"remaining",
"resets_at",
"status"
],
"type": "object"
}
},
"description": "Balance, plan, per-action prices, rate limit and the calling key's budget.",
"properties": {
"account_manager": {
"anyOf": [
{
"properties": {
"calendar_url": {
"format": "uri",
"type": "string"
},
"name": {
"type": "string"
}
},
"required": [
"name",
"calendar_url"
],
"type": "object"
},
{
"type": "null"
}
],
"description": "The named person behind Talk to us."
},
"agreements": {
"description": "The Terms of Sale (accepted at sign-up; accepted: null for an organisation Emailmovers set up), the Data Licence and Sharing Agreement (the licence: accepted with every order, or with an agent key that orders on its own) and the Article 28 DPA (accepted with the first suppression list).",
"properties": {
"dlsa": {
"$ref": "#/$defs/Agreement"
},
"dpa": {
"$ref": "#/$defs/Agreement"
},
"terms": {
"$ref": "#/$defs/Agreement"
}
},
"required": [
"terms",
"dlsa",
"dpa"
],
"type": "object"
},
"balance": {
"description": "Credits by source.",
"properties": {
"credits": {
"description": "Credits available to spend now.",
"type": "number"
},
"low_threshold": {
"anyOf": [
{
"minimum": 0,
"type": "integer"
},
{
"type": "null"
}
],
"description": "The credits.low webhook fires when the balance crosses this."
},
"pack_credits": {
"description": "From credit packs: never expire.",
"type": "number"
},
"rollover_cap": {
"anyOf": [
{
"minimum": 0,
"type": "integer"
},
{
"type": "null"
}
]
},
"subscription_credits": {
"description": "From the plan: roll over while subscribed, up to the cap.",
"type": "number"
}
},
"required": [
"credits",
"pack_credits",
"subscription_credits",
"rollover_cap",
"low_threshold"
],
"type": "object"
},
"demo": {
"anyOf": [
{
"properties": {
"expires_at": {
"format": "date-time",
"type": "string"
}
},
"required": [
"expires_at"
],
"type": "object"
},
{
"type": "null"
}
],
"description": "A demo organisation: everything runs in test mode, nothing is charged, order records are invented, and it stops working at expires_at. null for a real account."
},
"gbp_per_credit": {
"description": "Your plan's price per credit, excluding VAT.",
"minimum": 0,
"type": "number"
},
"key": {
"anyOf": [
{
"properties": {
"budget": {
"anyOf": [
{
"$ref": "#/$defs/Budget"
},
{
"type": "null"
}
]
},
"expires_at": {
"anyOf": [
{
"format": "date-time",
"type": "string"
},
{
"type": "null"
}
]
},
"id": {
"description": "Format: an API key id: key_ followed by a 26 character ULID in upper case Crockford base32, such as key_01JB3Z4Q2V7XN3M9R6T1Y5W8ZA.",
"examples": [
"key_01JB3Z4Q2V7XN3M9R6T1Y5W8ZA"
],
"pattern": "^key_[0-7][0-9A-HJKMNP-TV-Z]{25}$",
"type": "string"
},
"kind": {
"enum": [
"standard",
"agent"
],
"type": "string"
},
"per_order_max_credits": {
"anyOf": [
{
"minimum": 0,
"type": "integer"
},
{
"type": "null"
}
]
}
},
"required": [
"id",
"kind",
"budget",
"per_order_max_credits",
"expires_at"
],
"type": "object"
},
{
"type": "null"
}
],
"description": "The calling key and, for an agent key, its budget; null for a person."
},
"mode": {
"description": "live keys (mdh_live_) spend real credits; test keys (mdh_test_) return synthetic data and never charge.",
"enum": [
"live",
"test"
],
"type": "string"
},
"organisation": {
"properties": {
"business_details": {
"$ref": "#/$defs/BusinessDetails"
},
"id": {
"description": "Format: an organisation id: org_ followed by a 26 character ULID in upper case Crockford base32, such as org_01JA0Q2V7XN3M9R6T1Y5W8ZAK8.",
"examples": [
"org_01JA0Q2V7XN3M9R6T1Y5W8ZAK8"
],
"pattern": "^org_[0-7][0-9A-HJKMNP-TV-Z]{25}$",
"type": "string"
},
"name": {
"type": "string"
}
},
"required": [
"id",
"name",
"business_details"
],
"type": "object"
},
"plan": {
"properties": {
"cancel_at_period_end": {
"type": "boolean"
},
"id": {
"pattern": "^[a-z0-9]+(_[a-z0-9]+)*$",
"type": "string"
},
"kind": {
"enum": [
"free",
"subscription",
"pack"
],
"type": "string"
},
"name": {
"type": "string"
},
"renews_at": {
"anyOf": [
{
"format": "date",
"type": "string"
},
{
"type": "null"
}
]
}
},
"required": [
"id",
"name",
"kind",
"renews_at",
"cancel_at_period_end"
],
"type": "object"
},
"prices": {
"description": "What each action costs in credits.",
"items": {
"$ref": "#/$defs/CreditRule"
},
"type": "array"
},
"rate_limit": {
"$ref": "#/$defs/RateLimit"
},
"user": {
"anyOf": [
{
"properties": {
"id": {
"description": "Format: a user id: usr_ followed by a 26 character ULID in upper case Crockford base32, such as usr_01JA0Q3V7XN3M9R6T1Y5W8ZAK8.",
"examples": [
"usr_01JA0Q3V7XN3M9R6T1Y5W8ZAK8"
],
"pattern": "^usr_[0-7][0-9A-HJKMNP-TV-Z]{25}$",
"type": "string"
},
"name": {
"type": "string"
}
},
"required": [
"id",
"name"
],
"type": "object"
},
{
"type": "null"
}
],
"description": "The signed-in person; null when the caller is an API key."
}
},
"required": [
"organisation",
"user",
"mode",
"demo",
"plan",
"balance",
"prices",
"gbp_per_credit",
"rate_limit",
"key",
"account_manager",
"agreements"
],
"type": "object"
}
},
{
"description": "Returns an order's signed compliance receipt: an ES256 JWS with its decoded claims and a PDF link, covering records delivered, suppression removals, subscriber classes, TPS screening, Article 14 status, the licence and the file hash. Use it to prove to the user, a colleague or another agent that a list is licensed and screened; anyone can verify it with POST /v1/compliance/receipts/verify. Free; it needs orders:read. Lawful basis is UK GDPR Article 6(1)(f) legitimate interests; email audiences include corporate subscribers only by default (PECR), so sole traders and ordinary partnerships are left out unless the toggle is changed.",
"inputSchema": {
"additionalProperties": false,
"properties": {
"order_id": {
"description": "The order the receipt covers.",
"examples": [
"ord_01JB4N9S3W2X6Y7Z8A1B2C3D4E"
],
"pattern": "^ord_[0-7][0-9A-HJKMNP-TV-Z]{25}$",
"type": "string"
}
},
"required": [
"order_id"
],
"type": "object"
},
"name": "get_compliance_receipt",
"outputSchema": {
"$defs": {
"Licence": {
"description": "Licence terms as data, on every quote, order, records page and receipt. Records stay usable, pushable and re-downloadable free until reuse_until.",
"properties": {
"permitted_channels": {
"description": "email, telephone and post on standard terms.",
"items": {
"enum": [
"email",
"telephone",
"post"
],
"type": "string"
},
"type": "array"
},
"resale_prohibited": {
"type": "boolean"
},
"reuse_until": {
"anyOf": [
{
"format": "date",
"type": "string"
},
{
"type": "null"
}
],
"description": "Order date plus 12 months; null for outright."
},
"terms_url": {
"description": "Where that version of the Data Licence and Sharing Agreement is published.",
"format": "uri",
"type": "string"
},
"terms_version": {
"description": "The version of the Data Licence and Sharing Agreement the licence is under, such as 1.0.",
"type": "string"
},
"type": {
"description": "multi_use_12m (12 month multi-use, every plan) or outright (1.8 credits a record, proposed).",
"enum": [
"multi_use_12m",
"outright"
],
"type": "string"
},
"warranty_url": {
"format": "uri",
"type": "string"
}
},
"required": [
"type",
"reuse_until",
"resale_prohibited",
"permitted_channels",
"warranty_url",
"terms_version"
],
"type": "object"
},
"ReceiptClaims": {
"description": "The decoded payload of a compliance receipt.",
"properties": {
"content_sha256": {
"description": "SHA-256 of the delivered file, lower case hex.",
"pattern": "^[0-9a-f]{64}$",
"type": "string"
},
"counts": {
"properties": {
"article14_status": {
"properties": {
"notified": {
"minimum": 0,
"type": "integer"
},
"pending_within_window": {
"minimum": 0,
"type": "integer"
},
"publicly_notified_disproportionate_effort": {
"minimum": 0,
"type": "integer"
}
},
"required": [
"notified",
"publicly_notified_disproportionate_effort",
"pending_within_window"
],
"type": "object"
},
"subscriber_class": {
"properties": {
"charity_incorporated": {
"minimum": 0,
"type": "integer"
},
"llp": {
"minimum": 0,
"type": "integer"
},
"ltd": {
"minimum": 0,
"type": "integer"
},
"ordinary_partnership": {
"minimum": 0,
"type": "integer"
},
"plc": {
"minimum": 0,
"type": "integer"
},
"public_body": {
"minimum": 0,
"type": "integer"
},
"scottish_partnership": {
"minimum": 0,
"type": "integer"
},
"sole_trader": {
"minimum": 0,
"type": "integer"
},
"unknown": {
"minimum": 0,
"type": "integer"
}
},
"required": [
"ltd",
"plc",
"llp",
"scottish_partnership",
"public_body",
"charity_incorporated",
"sole_trader",
"ordinary_partnership",
"unknown"
],
"type": "object"
},
"tps_ctps_status": {
"properties": {
"clear": {
"minimum": 0,
"type": "integer"
},
"ctps_registered": {
"minimum": 0,
"type": "integer"
},
"not_screened": {
"minimum": 0,
"type": "integer"
},
"tps_or_ctps_registered": {
"minimum": 0,
"type": "integer"
},
"tps_registered": {
"minimum": 0,
"type": "integer"
}
},
"required": [
"clear",
"tps_registered",
"ctps_registered",
"tps_or_ctps_registered",
"not_screened"
],
"type": "object"
}
},
"required": [
"subscriber_class",
"tps_ctps_status",
"article14_status"
],
"type": "object"
},
"dataset_version": {
"description": "The immutable weekly build a count is bound to, such as 2026-W39. The last 52 stay queryable.",
"examples": [
"2026-W39"
],
"pattern": "^[0-9]{4}-W(0[1-9]|[1-4][0-9]|5[0-3])$",
"type": "string"
},
"issued_at": {
"format": "date-time",
"type": "string"
},
"lawful_basis": {
"enum": [
"legitimate_interests_art6_1_f"
],
"type": "string"
},
"lia_ref": {
"type": "string"
},
"licence": {
"$ref": "#/$defs/Licence"
},
"order_id": {
"description": "Format: an order id: ord_ followed by a 26 character ULID in upper case Crockford base32, such as ord_01JB4N9S3W2X6Y7Z8A1B2C3D4E.",
"examples": [
"ord_01JB4N9S3W2X6Y7Z8A1B2C3D4E"
],
"pattern": "^ord_[0-7][0-9A-HJKMNP-TV-Z]{25}$",
"type": "string"
},
"receipt_id": {
"description": "Format: a compliance receipt id: rcpt_ followed by a 26 character ULID in upper case Crockford base32, such as rcpt_01JB4NA2Q5W8ZAK8Q2V7XN3M9R.",
"examples": [
"rcpt_01JB4NA2Q5W8ZAK8Q2V7XN3M9R"
],
"pattern": "^rcpt_[0-7][0-9A-HJKMNP-TV-Z]{25}$",
"type": "string"
},
"records_delivered": {
"minimum": 0,
"type": "integer"
},
"removed_by_suppression": {
"minimum": 0,
"type": "integer"
},
"residency_statement_version": {
"type": "string"
},
"sub_processor_list_version": {
"type": "string"
},
"test": {
"const": true,
"description": "The receipt of a test mode order (a test key, or a demo organisation): its records are invented and it grants no licence. Absent on a live order's receipt.",
"type": "boolean"
},
"verified_within_days": {
"description": "Share of delivered emails verified within 30, 60 and 90 days.",
"properties": {
"within_30_days": {
"maximum": 100,
"minimum": 0,
"type": "number"
},
"within_60_days": {
"maximum": 100,
"minimum": 0,
"type": "number"
},
"within_90_days": {
"maximum": 100,
"minimum": 0,
"type": "number"
}
},
"required": [
"within_30_days",
"within_60_days",
"within_90_days"
],
"type": "object"
}
},
"required": [
"receipt_id",
"order_id",
"issued_at",
"dataset_version",
"records_delivered",
"removed_by_suppression",
"counts",
"lawful_basis",
"lia_ref",
"licence",
"residency_statement_version",
"sub_processor_list_version",
"verified_within_days",
"content_sha256"
],
"type": "object"
}
},
"description": "A signed compliance receipt for an order, verifiable by anyone with POST /v1/compliance/receipts/verify.",
"properties": {
"alg": {
"const": "ES256",
"type": "string"
},
"claims": {
"$ref": "#/$defs/ReceiptClaims"
},
"id": {
"description": "Format: a compliance receipt id: rcpt_ followed by a 26 character ULID in upper case Crockford base32, such as rcpt_01JB4NA2Q5W8ZAK8Q2V7XN3M9R.",
"examples": [
"rcpt_01JB4NA2Q5W8ZAK8Q2V7XN3M9R"
],
"pattern": "^rcpt_[0-7][0-9A-HJKMNP-TV-Z]{25}$",
"type": "string"
},
"jwks_url": {
"format": "uri",
"type": "string"
},
"jws": {
"description": "The receipt as a compact JWS signed with ES256.",
"pattern": "^[A-Za-z0-9_-]+\\.[A-Za-z0-9_-]+\\.[A-Za-z0-9_-]+$",
"type": "string"
},
"kid": {
"description": "The signing key id in jwks_url.",
"type": "string"
},
"order_id": {
"description": "Format: an order id: ord_ followed by a 26 character ULID in upper case Crockford base32, such as ord_01JB4N9S3W2X6Y7Z8A1B2C3D4E.",
"examples": [
"ord_01JB4N9S3W2X6Y7Z8A1B2C3D4E"
],
"pattern": "^ord_[0-7][0-9A-HJKMNP-TV-Z]{25}$",
"type": "string"
},
"pdf_url": {
"description": "The PDF twin at mydatahub.emailmovers.com/receipts/{id}.",
"format": "uri",
"type": "string"
}
},
"required": [
"id",
"order_id",
"jws",
"alg",
"kid",
"jwks_url",
"pdf_url",
"claims"
],
"type": "object"
}
},
{
"description": "Returns one order's status (queued, building, verifying, ready, failed or cancelled), counts, charges, licence and links to its records, download and receipt, or the recent orders when order_id is left out. Use it after create_order to wait for ready, or rely on the order.ready webhook. Free; it needs orders:read. Call fetch_order_records once the status is ready. Lawful basis is UK GDPR Article 6(1)(f) legitimate interests; email audiences include corporate subscribers only by default (PECR), so sole traders and ordinary partnerships are left out unless the toggle is changed.",
"inputSchema": {
"additionalProperties": false,
"properties": {
"cursor": {
"description": "An opaque cursor from next_cursor. Pass it back unchanged.",
"maxLength": 512,
"minLength": 1,
"type": "string"
},
"limit": {
"default": 25,
"description": "Items per page, 1 to 100. Default 25.",
"maximum": 100,
"minimum": 1,
"type": "integer"
},
"order_id": {
"description": "The order to return. Leave it out for the recent orders, newest first.",
"examples": [
"ord_01JB4N9S3W2X6Y7Z8A1B2C3D4E"
],
"pattern": "^ord_[0-7][0-9A-HJKMNP-TV-Z]{25}$",
"type": "string"
},
"status": {
"description": "queued, building, verifying, ready; failed if processing failed; cancelled (only while queued).",
"enum": [
"queued",
"building",
"verifying",
"ready",
"failed",
"cancelled"
],
"type": "string"
}
},
"type": "object"
},
"name": "get_order",
"outputSchema": {
"$defs": {
"BuyerKit": {
"description": "Four signed documents that help the buyer use the list lawfully.",
"properties": {
"article30_stub_url": {
"format": "uri",
"type": "string"
},
"draft_lia_url": {
"format": "uri",
"type": "string"
},
"due_diligence_file_url": {
"format": "uri",
"type": "string"
},
"first_email_wording_url": {
"format": "uri",
"type": "string"
}
},
"required": [
"draft_lia_url",
"first_email_wording_url",
"article30_stub_url",
"due_diligence_file_url"
],
"type": "object"
},
"ConfirmedBy": {
"description": "Who approved the spend and from which client, recorded in the audit trail and on invoices.",
"properties": {
"client_id": {
"description": "The OAuth client, such as a Client ID Metadata Document URL.",
"type": "string"
},
"confirmed_at": {
"format": "date-time",
"type": "string"
},
"key_id": {
"description": "The agent key, for agent_key.",
"examples": [
"key_01JB3Z4Q2V7XN3M9R6T1Y5W8ZA"
],
"pattern": "^key_[0-7][0-9A-HJKMNP-TV-Z]{25}$",
"type": "string"
},
"method": {
"description": "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).",
"enum": [
"elicitation_form",
"approval_url",
"agent_key",
"app"
],
"type": "string"
},
"mtls_certificate_fingerprint": {
"description": "SHA-256 of the client certificate when one was presented (ChatGPT's mTLS).",
"type": [
"string",
"null"
]
},
"user_agent": {
"description": "The calling client's User-Agent.",
"type": [
"string",
"null"
]
},
"user_id": {
"description": "The person who confirmed.",
"examples": [
"usr_01JA0Q3V7XN3M9R6T1Y5W8ZAK8"
],
"pattern": "^usr_[0-7][0-9A-HJKMNP-TV-Z]{25}$",
"type": "string"
},
"web_bot_auth_signature_agent": {
"description": "The Signature-Agent of a verified Web Bot Auth signature, when present.",
"type": [
"string",
"null"
]
}
},
"required": [
"method"
],
"type": "object"
},
"Licence": {
"description": "Licence terms as data, on every quote, order, records page and receipt. Records stay usable, pushable and re-downloadable free until reuse_until.",
"properties": {
"permitted_channels": {
"description": "email, telephone and post on standard terms.",
"items": {
"enum": [
"email",
"telephone",
"post"
],
"type": "string"
},
"type": "array"
},
"resale_prohibited": {
"type": "boolean"
},
"reuse_until": {
"anyOf": [
{
"format": "date",
"type": "string"
},
{
"type": "null"
}
],
"description": "Order date plus 12 months; null for outright."
},
"terms_url": {
"description": "Where that version of the Data Licence and Sharing Agreement is published.",
"format": "uri",
"type": "string"
},
"terms_version": {
"description": "The version of the Data Licence and Sharing Agreement the licence is under, such as 1.0.",
"type": "string"
},
"type": {
"description": "multi_use_12m (12 month multi-use, every plan) or outright (1.8 credits a record, proposed).",
"enum": [
"multi_use_12m",
"outright"
],
"type": "string"
},
"warranty_url": {
"format": "uri",
"type": "string"
}
},
"required": [
"type",
"reuse_until",
"resale_prohibited",
"permitted_channels",
"warranty_url",
"terms_version"
],
"type": "object"
},
"Order": {
"description": "The purchase and its delivery: status, records, charges, the licence, links to records, download, the validation report and the signed compliance receipt.",
"properties": {
"buyer_kit": {
"$ref": "#/$defs/BuyerKit"
},
"confirmed_by": {
"$ref": "#/$defs/ConfirmedBy"
},
"cost_gbp": {
"description": "The charge in GBP excluding VAT at your plan's rate.",
"minimum": 0,
"type": "number"
},
"count_id": {
"description": "The count the machine quote was priced from.",
"examples": [
"cnt_7K2PQ4MAXN3R6TBY5WDZ"
],
"pattern": "^cnt_[A-Z2-7]{20}$",
"type": "string"
},
"created_at": {
"format": "date-time",
"type": "string"
},
"credits_charged": {
"description": "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).",
"minimum": 0,
"type": "number"
},
"credits_remaining": {
"description": "The balance right after this order was charged.",
"minimum": 0,
"type": "number"
},
"dataset_version": {
"description": "The immutable weekly build a count is bound to, such as 2026-W39. The last 52 stay queryable.",
"examples": [
"2026-W39"
],
"pattern": "^[0-9]{4}-W(0[1-9]|[1-4][0-9]|5[0-3])$",
"type": "string"
},
"delivery": {
"items": {
"enum": [
"api",
"csv",
"google_sheets"
],
"type": "string"
},
"type": "array"
},
"download_url": {
"description": "302 to a single-use signed URL that lives 5 minutes.",
"format": "uri-reference",
"pattern": "^\\/v1\\/[A-Za-z0-9_\\-./]+$",
"type": "string"
},
"failure": {
"type": [
"string",
"null"
]
},
"field_set": {
"pattern": "^[a-z0-9]+(_[a-z0-9]+)*$",
"type": "string"
},
"id": {
"description": "Format: an order id: ord_ followed by a 26 character ULID in upper case Crockford base32, such as ord_01JB4N9S3W2X6Y7Z8A1B2C3D4E.",
"examples": [
"ord_01JB4N9S3W2X6Y7Z8A1B2C3D4E"
],
"pattern": "^ord_[0-7][0-9A-HJKMNP-TV-Z]{25}$",
"type": "string"
},
"licence": {
"$ref": "#/$defs/Licence"
},
"licence_expires_at": {
"anyOf": [
{
"format": "date",
"type": "string"
},
{
"type": "null"
}
],
"description": "When the licence ends; null for outright ownership."
},
"name": {
"type": "string"
},
"quote_id": {
"description": "The machine quote the order settled.",
"examples": [
"qte_01JB4M2R6T1Y5W8ZAK8Q2V7XN3"
],
"pattern": "^qte_[0-7][0-9A-HJKMNP-TV-Z]{25}$",
"type": "string"
},
"ready_at": {
"anyOf": [
{
"format": "date-time",
"type": "string"
},
{
"type": "null"
}
]
},
"receipt_url": {
"description": "A path on https://mydatahub.emailmovers.com starting /v1/. Resolve it against the origin (RFC 3986), not by appending it to the server URL.",
"format": "uri-reference",
"pattern": "^\\/v1\\/[A-Za-z0-9_\\-./]+$",
"type": "string"
},
"records": {
"minimum": 0,
"type": "integer"
},
"records_url": {
"description": "A path on https://mydatahub.emailmovers.com starting /v1/. Resolve it against the origin (RFC 3986), not by appending it to the server URL.",
"format": "uri-reference",
"pattern": "^\\/v1\\/[A-Za-z0-9_\\-./]+$",
"type": "string"
},
"status": {
"description": "queued, building, verifying, ready; failed if processing failed; cancelled (only while queued).",
"enum": [
"queued",
"building",
"verifying",
"ready",
"failed",
"cancelled"
],
"type": "string"
},
"test": {
"const": true,
"description": "A test mode order (a test key, or anyone in a demo organisation): no credits were charged, the records are invented and no licence is granted. Absent on a live order.",
"type": "boolean"
},
"validation_report": {
"$ref": "#/$defs/ValidationReportLinks",
"description": "Present once the order is ready."
},
"verification": {
"description": "The real-time check at delivery, such as 4,102 checked, 4,071 passed.",
"properties": {
"checked": {
"minimum": 0,
"type": "integer"
},
"passed": {
"minimum": 0,
"type": "integer"
},
"replaced": {
"minimum": 0,
"type": "integer"
}
},
"required": [
"checked",
"passed",
"replaced"
],
"type": "object"
}
},
"required": [
"id",
"status",
"quote_id",
"count_id",
"records",
"credits_charged",
"credits_remaining",
"cost_gbp",
"licence_expires_at",
"licence",
"confirmed_by",
"records_url"
],
"type": "object"
},
"OrderList": {
"description": "A page of orders, newest first.",
"properties": {
"data": {
"items": {
"$ref": "#/$defs/Order"
},
"type": "array"
},
"has_more": {
"description": "Whether another page follows.",
"type": "boolean"
},
"next_cursor": {
"anyOf": [
{
"description": "An opaque cursor from next_cursor. Pass it back unchanged.",
"maxLength": 512,
"minLength": 1,
"type": "string"
},
{
"type": "null"
}
],
"description": "Pass as cursor to fetch the next page; null on the last page."
}
},
"required": [
"data",
"has_more",
"next_cursor"
],
"type": "object"
},
"ValidationReportLinks": {
"description": "The per-order validation report: dataset version, status distribution, verification age, expected bounce band, TPS screen date, provider locations and the guarantee window.",
"properties": {
"json_url": {
"format": "uri",
"type": "string"
},
"pdf_url": {
"format": "uri",
"type": "string"
}
},
"required": [
"pdf_url",
"json_url"
],
"type": "object"
}
},
"anyOf": [
{
"$ref": "#/$defs/Order"
},
{
"$ref": "#/$defs/OrderList"
}
],
"type": "object"
}
},
{
"description": "Returns the plans of MyDataHub by Emailmovers, the UK B2B count engine: credit packs, credit rules, licence terms, the bounce warranty and the free trial, in GBP excluding VAT. Use it when the user asks what a list costs or which plan fits; it is free and needs no account. One credit buys one complete UK record at the same price in the app, the API and here. Call get_account for the caller's own balance, or count_audience to size a list. Lawful basis is UK GDPR Article 6(1)(f) legitimate interests; email audiences include corporate subscribers only by default (PECR), so sole traders and ordinary partnerships are left out unless the toggle is changed.",
"inputSchema": {
"additionalProperties": false,
"properties": {},
"type": "object"
},
"name": "get_plans",
"outputSchema": {
"$defs": {
"ActionPathStep": {
"description": "One step from a price to a delivered order.",
"properties": {
"action": {
"description": "An MCP tool, a REST operation or a URL.",
"type": "string"
},
"description": {
"type": "string"
},
"rest": {
"description": "The REST operation, such as POST /v1/quotes.",
"type": [
"string",
"null"
]
},
"step": {
"minimum": 1,
"type": "integer"
}
},
"required": [
"step",
"action",
"rest",
"description"
],
"type": "object"
},
"CreditPack": {
"description": "A one-off prepaid bundle of credits, usable on any plan. Credit pack credits never expire and survive cancellation.",
"properties": {
"annual_price_gbp_ex_vat": {
"anyOf": [
{
"description": "Pounds sterling excluding VAT, to two decimal places.",
"minimum": 0,
"type": "number"
},
{
"type": "null"
}
]
},
"available_to": {
"description": "everyone; new_customers only (the subscription); existing_customers only, who keep their prices (pay as you go and the 12-month plan).",
"enum": [
"everyone",
"new_customers",
"existing_customers"
],
"type": "string"
},
"billing_period": {
"const": "once",
"type": "string"
},
"contract_months": {
"anyOf": [
{
"minimum": 0,
"type": "integer"
},
{
"type": "null"
}
],
"description": "The contract's length in months, such as 12; absent when there is none."
},
"credits": {
"description": "Credits per billing period, or once.",
"minimum": 0,
"type": "integer"
},
"credits_expire": {
"type": "boolean"
},
"for_whom": {
"type": "string"
},
"id": {
"description": "Such as free, pay_as_you_go or plan_12_month.",
"pattern": "^[a-z0-9]+(_[a-z0-9]+)*$",
"type": "string"
},
"kind": {
"const": "pack",
"type": "string"
},
"name": {
"type": "string"
},
"notes": {
"type": "string"
},
"per_record_gbp": {
"anyOf": [
{
"description": "Pounds sterling excluding VAT, to two decimal places.",
"minimum": 0,
"type": "number"
},
{
"type": "null"
}
],
"description": "Price per record at full use of the allowance; null for the free plan."
},
"price_gbp_ex_vat": {
"description": "Pounds sterling excluding VAT, to two decimal places.",
"minimum": 0,
"type": "number"
},
"rollover_cap_credits": {
"anyOf": [
{
"minimum": 0,
"type": "integer"
},
{
"type": "null"
}
],
"description": "Subscription credits roll over while subscribed, up to this many; 0 when each period's credits are used or lost."
},
"status": {
"description": "confirmed is in force; proposed awaits a decision; to_confirm is a figure still being checked.",
"enum": [
"confirmed",
"proposed",
"to_confirm"
],
"type": "string"
}
},
"required": [
"id",
"name",
"kind",
"status",
"available_to",
"price_gbp_ex_vat",
"billing_period",
"credits",
"per_record_gbp",
"credits_expire",
"for_whom"
],
"type": "object"
},
"CreditRule": {
"description": "What one action costs in credits.",
"properties": {
"action": {
"pattern": "^[a-z0-9]+(_[a-z0-9]+)*$",
"type": "string"
},
"credits": {
"description": "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).",
"minimum": 0,
"type": "number"
},
"label": {
"type": "string"
},
"note": {
"type": "string"
},
"status": {
"description": "confirmed is in force; proposed awaits a decision; to_confirm is a figure still being checked.",
"enum": [
"confirmed",
"proposed",
"to_confirm"
],
"type": "string"
},
"unit": {
"enum": [
"call",
"record",
"match"
],
"type": "string"
}
},
"required": [
"action",
"label",
"credits",
"unit",
"status"
],
"type": "object"
},
"LicenceTerms": {
"description": "Licence terms for a plan, as in licence.json.",
"properties": {
"credits_per_record": {
"exclusiveMinimum": 0,
"type": "number"
},
"licence_type": {
"description": "multi_use_12m (12 month multi-use, every plan) or outright (1.8 credits a record, proposed).",
"enum": [
"multi_use_12m",
"outright"
],
"type": "string"
},
"permitted_channels": {
"items": {
"enum": [
"email",
"telephone",
"post"
],
"type": "string"
},
"type": "array"
},
"resale_prohibited": {
"type": "boolean"
},
"reuse_months": {
"anyOf": [
{
"exclusiveMinimum": 0,
"type": "integer"
},
{
"type": "null"
}
],
"description": "12 for multi_use_12m; null for outright."
},
"status": {
"enum": [
"confirmed",
"proposed"
],
"type": "string"
},
"terms_version": {
"type": "string"
},
"warranty_url": {
"format": "uri",
"type": "string"
}
},
"required": [
"licence_type",
"status",
"credits_per_record",
"permitted_channels",
"reuse_months",
"resale_prohibited",
"warranty_url",
"terms_version"
],
"type": "object"
},
"Meter": {
"description": "One metered action and its price in credits.",
"properties": {
"action": {
"description": "What is metered, such as record or enrich_contact.",
"pattern": "^[a-z0-9]+(_[a-z0-9]+)*$",
"type": "string"
},
"credits": {
"description": "Credits per unit.",
"minimum": 0,
"type": "number"
},
"status": {
"description": "confirmed is in force; proposed awaits a decision; to_confirm is a figure still being checked.",
"enum": [
"confirmed",
"proposed",
"to_confirm"
],
"type": "string"
},
"unit": {
"enum": [
"record",
"match",
"call"
],
"type": "string"
}
},
"required": [
"action",
"unit",
"credits",
"status"
],
"type": "object"
},
"Plan": {
"description": "A plan: free, a rolling subscription or a credit pack. No seats on any plan.",
"properties": {
"annual_price_gbp_ex_vat": {
"anyOf": [
{
"description": "Pounds sterling excluding VAT, to two decimal places.",
"minimum": 0,
"type": "number"
},
{
"type": "null"
}
]
},
"available_to": {
"description": "everyone; new_customers only (the subscription); existing_customers only, who keep their prices (pay as you go and the 12-month plan).",
"enum": [
"everyone",
"new_customers",
"existing_customers"
],
"type": "string"
},
"billing_period": {
"enum": [
"once",
"month",
"year"
],
"type": "string"
},
"contract_months": {
"anyOf": [
{
"minimum": 0,
"type": "integer"
},
{
"type": "null"
}
],
"description": "The contract's length in months, such as 12; absent when there is none."
},
"credits": {
"description": "Credits per billing period, or once.",
"minimum": 0,
"type": "integer"
},
"credits_expire": {
"type": "boolean"
},
"for_whom": {
"type": "string"
},
"id": {
"description": "Such as free, pay_as_you_go or plan_12_month.",
"pattern": "^[a-z0-9]+(_[a-z0-9]+)*$",
"type": "string"
},
"kind": {
"enum": [
"free",
"subscription",
"pack"
],
"type": "string"
},
"name": {
"type": "string"
},
"notes": {
"type": "string"
},
"per_record_gbp": {
"anyOf": [
{
"description": "Pounds sterling excluding VAT, to two decimal places.",
"minimum": 0,
"type": "number"
},
{
"type": "null"
}
],
"description": "Price per record at full use of the allowance; null for the free plan."
},
"price_gbp_ex_vat": {
"description": "Pounds sterling excluding VAT, to two decimal places.",
"minimum": 0,
"type": "number"
},
"rollover_cap_credits": {
"anyOf": [
{
"minimum": 0,
"type": "integer"
},
{
"type": "null"
}
],
"description": "Subscription credits roll over while subscribed, up to this many; 0 when each period's credits are used or lost."
},
"status": {
"description": "confirmed is in force; proposed awaits a decision; to_confirm is a figure still being checked.",
"enum": [
"confirmed",
"proposed",
"to_confirm"
],
"type": "string"
}
},
"required": [
"id",
"name",
"kind",
"status",
"available_to",
"price_gbp_ex_vat",
"billing_period",
"credits",
"per_record_gbp",
"credits_expire",
"for_whom"
],
"type": "object"
},
"PriceBand": {
"description": "One band of the per-contact scale.",
"properties": {
"from_records": {
"minimum": 0,
"type": "integer"
},
"gbp_per_record": {
"description": "Pounds sterling excluding VAT, to two decimal places.",
"minimum": 0,
"type": "number"
},
"to_records": {
"anyOf": [
{
"minimum": 0,
"type": "integer"
},
{
"type": "null"
}
],
"description": "null for the last band."
}
},
"required": [
"from_records",
"to_records",
"gbp_per_record"
],
"type": "object"
},
"PriceScale": {
"description": "The per-contact scale: 1 credit buys 1 record at the rate of the band the purchase falls in. A quote's purchase options compare it with the credit pack and lead with the cheapest.",
"properties": {
"available_to": {
"description": "everyone; new_customers only (the subscription); existing_customers only, who keep their prices (pay as you go and the 12-month plan).",
"enum": [
"everyone",
"new_customers",
"existing_customers"
],
"type": "string"
},
"bands": {
"items": {
"$ref": "#/$defs/PriceBand"
},
"minItems": 1,
"type": "array"
},
"id": {
"const": "per_contact_scale",
"type": "string"
},
"minimum_order_records": {
"minimum": 0,
"type": "integer"
},
"name": {
"type": "string"
},
"rule": {
"description": "How a purchase is priced, in words.",
"type": "string"
},
"status": {
"description": "confirmed is in force; proposed awaits a decision; to_confirm is a figure still being checked.",
"enum": [
"confirmed",
"proposed",
"to_confirm"
],
"type": "string"
}
},
"required": [
"id",
"name",
"status",
"available_to",
"minimum_order_records",
"rule",
"bands"
],
"type": "object"
},
"PricingPromise": {
"description": "One of the seven promises on the pricing page.",
"properties": {
"in_practice": {
"type": "string"
},
"key": {
"pattern": "^[a-z0-9]+(_[a-z0-9]+)*$",
"type": "string"
},
"statement": {
"type": "string"
}
},
"required": [
"key",
"statement",
"in_practice"
],
"type": "object"
},
"Warranty": {
"allOf": [
{
"else": {
"not": {
"properties": {
"threshold_percent": true
},
"required": [
"threshold_percent"
],
"type": "object"
},
"type": "object"
},
"if": {
"properties": {
"policy": {
"const": "replace_over_threshold_hard_bounce"
}
},
"required": [
"policy"
],
"type": "object"
},
"then": {
"properties": {
"threshold_percent": true
},
"required": [
"threshold_percent"
],
"type": "object"
}
}
],
"description": "The bounce warranty that covers delivered records, with the threshold it was issued under.",
"properties": {
"policy": {
"description": "replace_over_threshold_hard_bounce is the current policy: records are replaced when hard bounces exceed threshold_percent of an order. replace_any_hard_bounce_30d is proposed and not yet in force. The current policy's id replaced one that named the threshold, a change to this public enum made before v2 went live.",
"enum": [
"replace_over_threshold_hard_bounce",
"replace_any_hard_bounce_30d"
],
"type": "string"
},
"threshold_percent": {
"description": "replace_over_threshold_hard_bounce only, and required there: the share of an order, in percent, that hard bounces must exceed before records are replaced. It is the threshold the document was issued under.",
"maximum": 100,
"minimum": 0,
"type": "number"
},
"url": {
"format": "uri",
"type": "string"
}
},
"required": [
"policy",
"url"
],
"type": "object"
}
},
"description": "The per-contact scale, plans, credit packs, credit rules, licence terms, the guarantee and the promises, in GBP excluding VAT. The same content as https://mydatahub.emailmovers.com/pricing.json.",
"properties": {
"action_path": {
"description": "How to buy: quote_order for a machine quote, create_order with a confirmation, and the top-up page when the balance is short.",
"items": {
"$ref": "#/$defs/ActionPathStep"
},
"type": "array"
},
"credit_definition": {
"type": "string"
},
"credit_packs": {
"items": {
"$ref": "#/$defs/CreditPack"
},
"type": "array"
},
"credit_rules": {
"items": {
"$ref": "#/$defs/CreditRule"
},
"type": "array"
},
"currency": {
"const": "GBP",
"type": "string"
},
"guarantee": {
"properties": {
"current": {
"$ref": "#/$defs/Warranty"
},
"proposed": {
"anyOf": [
{
"$ref": "#/$defs/Warranty"
},
{
"type": "null"
}
]
},
"refunds": {
"items": {
"type": "string"
},
"type": "array"
}
},
"required": [
"current",
"proposed",
"refunds"
],
"type": "object"
},
"licence": {
"items": {
"$ref": "#/$defs/LicenceTerms"
},
"type": "array"
},
"meters": {
"description": "What agents and code are metered on, in credits, the same on every surface.",
"items": {
"$ref": "#/$defs/Meter"
},
"type": "array"
},
"plans": {
"items": {
"$ref": "#/$defs/Plan"
},
"type": "array"
},
"price_scale": {
"$ref": "#/$defs/PriceScale"
},
"promises": {
"items": {
"$ref": "#/$defs/PricingPromise"
},
"type": "array"
},
"trial": {
"properties": {
"card_required": {
"type": "boolean"
},
"credits": {
"minimum": 0,
"type": "integer"
},
"expires": {
"type": "boolean"
}
},
"required": [
"credits",
"card_required",
"expires"
],
"type": "object"
},
"valid_from": {
"format": "date",
"type": "string"
},
"vat_treatment": {
"type": "string"
},
"version": {
"type": "string"
}
},
"required": [
"version",
"valid_from",
"currency",
"vat_treatment",
"credit_definition",
"price_scale",
"plans",
"credit_packs",
"credit_rules",
"licence",
"guarantee",
"trial",
"promises",
"meters",
"action_path"
],
"type": "object"
}
},
{
"description": "Lists the organisation's saved audiences with their current counts and last refresh, newest first, optionally filtered by name. Use it to find an aud_ id to count, quote or share. Free; it needs audiences:read. Pass an aud_ id to count_audience for a fresh count. Lawful basis is UK GDPR Article 6(1)(f) legitimate interests; email audiences include corporate subscribers only by default (PECR), so sole traders and ordinary partnerships are left out unless the toggle is changed.",
"inputSchema": {
"additionalProperties": false,
"properties": {
"cursor": {
"description": "An opaque cursor from next_cursor. Pass it back unchanged.",
"maxLength": 512,
"minLength": 1,
"type": "string"
},
"limit": {
"default": 25,
"description": "Items per page, 1 to 100. Default 25.",
"maximum": 100,
"minimum": 1,
"type": "integer"
},
"q": {
"description": "Filter by name.",
"maxLength": 100,
"type": "string"
}
},
"type": "object"
},
"name": "list_audiences",
"outputSchema": {
"$defs": {
"AllGroup": {
"additionalProperties": false,
"description": "AND: every node inside must match.",
"properties": {
"all": {
"items": {
"$ref": "#/$defs/WhereNode"
},
"minItems": 1,
"type": "array"
}
},
"required": [
"all"
],
"type": "object"
},
"AnyGroup": {
"additionalProperties": false,
"description": "OR: at least one node inside must match.",
"properties": {
"any": {
"items": {
"$ref": "#/$defs/WhereNode"
},
"minItems": 1,
"type": "array"
}
},
"required": [
"any"
],
"type": "object"
},
"Audience": {
"additionalProperties": false,
"description": "Who you want, as filters grouped by entity (company., site., contact., email., phone., signal.). The server fills its defaults (active companies, named emails, corporate subscribers, the current dataset_version) and returns the effective definition with every count.",
"properties": {
"dataset": {
"description": "The dataset an audience draws from. uk_contacts is live; ie_contacts and global_contacts are listed but not yet served.",
"enum": [
"uk_contacts",
"ie_contacts",
"global_contacts"
],
"type": "string"
},
"dataset_version": {
"description": "The weekly build to count against, such as 2026-W39. Left out, the current version is filled in and returned.",
"examples": [
"2026-W39"
],
"pattern": "^[0-9]{4}-W(0[1-9]|[1-4][0-9]|5[0-3])$",
"type": "string"
},
"dedupe": {
"description": "none keeps every matching contact, one_per_company keeps one contact per company, one_per_site keeps one per site. Default none.",
"enum": [
"none",
"one_per_company",
"one_per_site"
],
"type": "string"
},
"email_policy": {
"$ref": "#/$defs/EmailPolicy"
},
"schema": {
"const": "mydatahub.audience/1",
"description": "The definition's namespace and version. Older versions are upgraded by a pure function.",
"type": "string"
},
"where": {
"$ref": "#/$defs/WhereNode",
"description": "The filters. Left out, the audience is the whole dataset after the defaults."
}
},
"required": [
"schema"
],
"title": "MyDataHub audience definition (mydatahub.audience/1)",
"type": "object"
},
"AudienceCountSummary": {
"description": "The headline numbers of one count of an audience.",
"properties": {
"companies": {
"minimum": 0,
"type": "integer"
},
"contacts": {
"minimum": 0,
"type": "integer"
},
"count_id": {
"description": "Format: a count id: cnt_ followed by 20 base32 characters (A to Z and 2 to 7), such as cnt_7K2PQ4MAXN3R6TBY5WDZ.",
"examples": [
"cnt_7K2PQ4MAXN3R6TBY5WDZ"
],
"pattern": "^cnt_[A-Z2-7]{20}$",
"type": "string"
},
"counted_at": {
"format": "date-time",
"type": "string"
},
"dataset_version": {
"description": "The immutable weekly build a count is bound to, such as 2026-W39. The last 52 stay queryable.",
"examples": [
"2026-W39"
],
"pattern": "^[0-9]{4}-W(0[1-9]|[1-4][0-9]|5[0-3])$",
"type": "string"
},
"emailable": {
"minimum": 0,
"type": "integer"
}
},
"required": [
"count_id",
"dataset_version",
"contacts",
"companies",
"emailable",
"counted_at"
],
"type": "object"
},
"BetweenFilter": {
"additionalProperties": false,
"description": "The field lies from one value to another inclusive, over the field's order.",
"examples": [
{
"field": "company.employee_band",
"from": "10-19",
"op": "between",
"to": "200-349"
}
],
"properties": {
"field": {
"enum": [
"company.employee_band",
"company.turnover_band",
"company.fleet_band",
"contact.job_level_rank",
"email.deliverability_score"
],
"type": "string"
},
"from": {
"anyOf": [
{
"maxLength": 200,
"minLength": 1,
"type": "string"
},
{
"type": "number"
}
],
"description": "A band code or a number from the field's order."
},
"op": {
"const": "between",
"type": "string"
},
"to": {
"anyOf": [
{
"maxLength": 200,
"minLength": 1,
"type": "string"
},
{
"type": "number"
}
],
"description": "A band code or a number from the field's order."
}
},
"required": [
"field",
"op",
"from",
"to"
],
"type": "object"
},
"BundleNode": {
"additionalProperties": false,
"description": "A title bundle, resolved to its filters in the effective definition: sdm (senior decision makers), manager_and_above (managers and above), owner_managed (owner managed).",
"properties": {
"bundle": {
"enum": [
"sdm",
"manager_and_above",
"owner_managed"
],
"type": "string"
}
},
"required": [
"bundle"
],
"type": "object"
},
"EmailPolicy": {
"additionalProperties": false,
"description": "Email quality floor. Defaults: min_deliverability_score 70, allow_catch_all false.",
"properties": {
"allow_catch_all": {
"description": "Whether catch-all addresses count. Default false.",
"type": "boolean"
},
"min_deliverability_score": {
"description": "Lowest deliverability score counted, 0 to 100. Default 70.",
"maximum": 100,
"minimum": 0,
"type": "integer"
}
},
"type": "object"
},
"Filter": {
"description": "One criterion: a field from GET /v1/catalogue/filters, an operator and its operands. Exclusions nest under not.",
"oneOf": [
{
"$ref": "#/$defs/InFilter"
},
{
"$ref": "#/$defs/BetweenFilter"
},
{
"$ref": "#/$defs/GteFilter"
},
{
"$ref": "#/$defs/LteFilter"
},
{
"$ref": "#/$defs/MatchesFilter"
},
{
"$ref": "#/$defs/WithinRadiusFilter"
},
{
"$ref": "#/$defs/InListFilter"
},
{
"$ref": "#/$defs/SinceFilter"
}
]
},
"GteFilter": {
"additionalProperties": false,
"description": "The field is at or after the value in its order: for bands, the band and every larger one.",
"examples": [
{
"field": "company.employee_band",
"op": "gte",
"value": "50-99"
}
],
"properties": {
"field": {
"enum": [
"company.employee_band",
"company.turnover_band",
"company.fleet_band",
"contact.job_level_rank",
"email.deliverability_score"
],
"type": "string"
},
"op": {
"const": "gte",
"type": "string"
},
"value": {
"anyOf": [
{
"maxLength": 200,
"minLength": 1,
"type": "string"
},
{
"type": "number"
}
],
"description": "A band code or a number from the field's order."
}
},
"required": [
"field",
"op",
"value"
],
"type": "object"
},
"InFilter": {
"additionalProperties": false,
"description": "The field holds one of the listed codes.",
"examples": [
{
"field": "company.sic_2007",
"op": "in",
"values": [
"C"
]
}
],
"properties": {
"field": {
"enum": [
"company.sic_2007",
"company.business_class",
"company.employee_band",
"company.turnover_band",
"company.fleet_band",
"company.type",
"company.status",
"company.subscriber_class",
"company.companies_house_number",
"site.region",
"site.county",
"site.town",
"site.postcode",
"contact.title_family",
"contact.job_function",
"contact.job_level_rank",
"contact.premium",
"email.exists",
"email.type",
"phone.exists",
"phone.tps_ctps_status"
],
"type": "string"
},
"op": {
"const": "in",
"type": "string"
},
"values": {
"items": {
"anyOf": [
{
"maxLength": 200,
"minLength": 1,
"type": "string"
},
{
"type": "number"
},
{
"type": "boolean"
}
],
"description": "A code, a rank or a boolean, as the field's catalogue lists it."
},
"maxItems": 10000,
"minItems": 1,
"type": "array"
}
},
"required": [
"field",
"op",
"values"
],
"type": "object"
},
"InListFilter": {
"additionalProperties": false,
"description": "The record's hashed email, domain, phone, company number or title term is on a suppression list. Usually nested under not; each list reports the records it removed.",
"examples": [
{
"field": "email.address_sha256",
"list_id": "sup_01JB4H7Q2V7XN3M9R6T1Y5W8ZA",
"op": "in_list"
}
],
"properties": {
"field": {
"enum": [
"company.companies_house_number",
"contact.title",
"email.address_sha256",
"email.domain_sha256",
"phone.e164_sha256"
],
"type": "string"
},
"list_id": {
"description": "Format: a suppression list id: sup_ followed by a 26 character ULID in upper case Crockford base32, such as sup_01JB4H7Q2V7XN3M9R6T1Y5W8ZA.",
"examples": [
"sup_01JB4H7Q2V7XN3M9R6T1Y5W8ZA"
],
"pattern": "^sup_[0-7][0-9A-HJKMNP-TV-Z]{25}$",
"type": "string"
},
"op": {
"const": "in_list",
"type": "string"
}
},
"required": [
"field",
"op",
"list_id"
],
"type": "object"
},
"LteFilter": {
"additionalProperties": false,
"description": "The field is at or before the value in its order. Rank 1 is the most senior, so Director and above is contact.job_level_rank lte 6.",
"examples": [
{
"field": "contact.job_level_rank",
"op": "lte",
"value": 6
}
],
"properties": {
"field": {
"enum": [
"company.employee_band",
"company.turnover_band",
"company.fleet_band",
"contact.job_level_rank",
"contact.company_contact_rank",
"email.deliverability_score"
],
"type": "string"
},
"op": {
"const": "lte",
"type": "string"
},
"value": {
"anyOf": [
{
"maxLength": 200,
"minLength": 1,
"type": "string"
},
{
"type": "number"
}
],
"description": "A band code or a number from the field's order."
}
},
"required": [
"field",
"op",
"value"
],
"type": "object"
},
"MatchesFilter": {
"additionalProperties": false,
"allOf": [
{
"if": {
"properties": {
"mode": {
"const": "exact"
}
},
"required": [
"mode"
],
"type": "object"
},
"then": {
"properties": {
"exclude_terms": {
"maxItems": 0,
"type": "array"
},
"expand": {
"maxItems": 0,
"type": "array"
}
},
"type": "object"
}
}
],
"description": "Job title keyword match. mode contains (the default) or starts_with expands each term with the expansion sets; mode exact matches verbatim titles. Every expanded term is returned with the count.",
"examples": [
{
"expand": [
"plural_singular",
"department_synonyms",
"ampersand_and",
"abbreviations"
],
"field": "contact.title",
"mode": "contains",
"op": "matches",
"terms": [
"marketing manager"
]
}
],
"properties": {
"exclude_terms": {
"description": "Expanded terms removed by hand. Kept in the definition so the count stays reproducible when the title dictionary changes.",
"items": {
"maxLength": 200,
"minLength": 1,
"type": "string"
},
"maxItems": 500,
"type": "array"
},
"expand": {
"description": "Expansion sets to apply, each once: plural_singular, department_synonyms, ampersand_and, abbreviations, permutations. Left out, the first four apply; an empty list applies none. Not used with mode exact.",
"items": {
"enum": [
"plural_singular",
"department_synonyms",
"ampersand_and",
"abbreviations",
"permutations"
],
"type": "string"
},
"maxItems": 5,
"type": "array",
"uniqueItems": true
},
"field": {
"enum": [
"contact.title"
],
"type": "string"
},
"mode": {
"description": "contains (the default) matches titles containing a term, starts_with matches titles beginning with it, exact takes verbatim titles with no expansion.",
"enum": [
"contains",
"starts_with",
"exact"
],
"type": "string"
},
"op": {
"const": "matches",
"type": "string"
},
"terms": {
"items": {
"maxLength": 200,
"minLength": 1,
"type": "string"
},
"maxItems": 500,
"minItems": 1,
"type": "array"
}
},
"required": [
"field",
"op",
"terms"
],
"type": "object"
},
"NotGroup": {
"additionalProperties": false,
"description": "Negation: the single node inside must not match.",
"properties": {
"not": {
"$ref": "#/$defs/WhereNode"
}
},
"required": [
"not"
],
"type": "object"
},
"PlaceCentre": {
"additionalProperties": false,
"description": "A named place. Ambiguous names come back from resolve_location as candidates, never a silent choice.",
"properties": {
"code": {
"description": "The ONS geography code of the chosen candidate when resolve_location found more than one, such as E08000035 for the Leeds district.",
"maxLength": 20,
"minLength": 1,
"type": "string"
},
"place": {
"description": "A place name, resolved with resolve_location, such as Leeds.",
"maxLength": 100,
"minLength": 1,
"type": "string"
}
},
"required": [
"place"
],
"type": "object"
},
"PointCentre": {
"additionalProperties": false,
"description": "A latitude and longitude in WGS84 degrees.",
"properties": {
"lat": {
"maximum": 61,
"minimum": 49,
"type": "number"
},
"lon": {
"maximum": 2,
"minimum": -9,
"type": "number"
}
},
"required": [
"lat",
"lon"
],
"type": "object"
},
"PostcodeCentre": {
"additionalProperties": false,
"description": "A postcode centroid from ONSPD.",
"properties": {
"postcode": {
"description": "The centroid of a postcode unit, sector, district or area, such as LS1 4AP.",
"pattern": "^[A-Za-z]{1,2}([0-9][0-9A-Za-z]?( [0-9]([A-Za-z]{2})?| ?[0-9][A-Za-z]{2})?)?$",
"type": "string"
}
},
"required": [
"postcode"
],
"type": "object"
},
"RadiusCentre": {
"anyOf": [
{
"$ref": "#/$defs/PlaceCentre"
},
{
"$ref": "#/$defs/PostcodeCentre"
},
{
"$ref": "#/$defs/PointCentre"
}
],
"description": "The centre of a radius: a place, a postcode or a latitude and longitude."
},
"SavedAudience": {
"description": "A named audience shared across the organisation, with its current count.",
"properties": {
"audience": {
"$ref": "#/$defs/Audience"
},
"brief": {
"description": "The brief it was compiled from, if any.",
"type": [
"string",
"null"
]
},
"created_at": {
"format": "date-time",
"type": "string"
},
"created_by": {
"description": "Format: a user id: usr_ followed by a 26 character ULID in upper case Crockford base32, such as usr_01JA0Q3V7XN3M9R6T1Y5W8ZAK8.",
"examples": [
"usr_01JA0Q3V7XN3M9R6T1Y5W8ZAK8"
],
"pattern": "^usr_[0-7][0-9A-HJKMNP-TV-Z]{25}$",
"type": "string"
},
"current_count": {
"anyOf": [
{
"$ref": "#/$defs/AudienceCountSummary"
},
{
"type": "null"
}
]
},
"id": {
"description": "Format: an audience id: aud_ followed by a 26 character ULID in upper case Crockford base32, such as aud_01JB4H2K9V6XN3M9R6T1Y5W8ZA.",
"examples": [
"aud_01JB4H2K9V6XN3M9R6T1Y5W8ZA"
],
"pattern": "^aud_[0-7][0-9A-HJKMNP-TV-Z]{25}$",
"type": "string"
},
"last_refreshed_at": {
"anyOf": [
{
"format": "date-time",
"type": "string"
},
{
"type": "null"
}
]
},
"name": {
"type": "string"
},
"updated_at": {
"format": "date-time",
"type": "string"
},
"url": {
"description": "The audience in the app, mydatahub.emailmovers.com/audiences/{id}.",
"format": "uri",
"type": "string"
}
},
"required": [
"id",
"name",
"audience",
"brief",
"current_count",
"last_refreshed_at",
"created_at",
"updated_at",
"created_by",
"url"
],
"type": "object"
},
"SinceFilter": {
"additionalProperties": false,
"description": "Within the last N days: a date field, or a Companies House signal of the listed types on signal.type.",
"examples": [
{
"days": 90,
"field": "signal.type",
"op": "since",
"values": [
"company.incorporated"
]
}
],
"properties": {
"days": {
"maximum": 3650,
"minimum": 1,
"type": "integer"
},
"field": {
"enum": [
"contact.last_validated_at",
"email.last_verified_at",
"signal.type",
"signal.observed_at"
],
"type": "string"
},
"op": {
"const": "since",
"type": "string"
},
"values": {
"description": "For signal.type only: the signal types to look for, such as company.incorporated.",
"items": {
"maxLength": 200,
"minLength": 1,
"type": "string"
},
"maxItems": 10000,
"minItems": 1,
"type": "array"
}
},
"required": [
"field",
"op",
"days"
],
"type": "object"
},
"WhereNode": {
"anyOf": [
{
"$ref": "#/$defs/AllGroup"
},
{
"$ref": "#/$defs/AnyGroup"
},
{
"$ref": "#/$defs/NotGroup"
},
{
"$ref": "#/$defs/BundleNode"
},
{
"$ref": "#/$defs/Filter"
}
],
"description": "A group (all, any, not), a title bundle or a filter. Groups nest up to 32 deep, and a where tree holds up to 1,000 filters, groups and bundles."
},
"WithinRadiusFilter": {
"additionalProperties": false,
"description": "Sites within radius_miles of the centre. The count reports the centroid used and the postcodes matched.",
"examples": [
{
"centre": {
"place": "Leeds"
},
"field": "site.location",
"op": "within_radius",
"radius_miles": 20
}
],
"properties": {
"centre": {
"$ref": "#/$defs/RadiusCentre"
},
"field": {
"enum": [
"site.location"
],
"type": "string"
},
"op": {
"const": "within_radius",
"type": "string"
},
"radius_miles": {
"description": "Radius in miles, 1 to 100. Under 5 miles needs an account.",
"maximum": 100,
"minimum": 1,
"type": "number"
}
},
"required": [
"field",
"op",
"centre",
"radius_miles"
],
"type": "object"
}
},
"description": "A page of saved audiences, newest first.",
"properties": {
"data": {
"items": {
"$ref": "#/$defs/SavedAudience"
},
"type": "array"
},
"has_more": {
"description": "Whether another page follows.",
"type": "boolean"
},
"next_cursor": {
"anyOf": [
{
"description": "An opaque cursor from next_cursor. Pass it back unchanged.",
"maxLength": 512,
"minLength": 1,
"type": "string"
},
{
"type": "null"
}
],
"description": "Pass as cursor to fetch the next page; null on the last page."
}
},
"required": [
"data",
"has_more",
"next_cursor"
],
"type": "object"
}
},
{
"description": "Lists the field sets an order can deliver, such as standard or standard_telephone, with their exact columns. Every field set costs 1 credit a record, with no telephone, download or API surcharge. Use it to pick the field_set for quote_order; it is free and needs no account. Lawful basis is UK GDPR Article 6(1)(f) legitimate interests; email audiences include corporate subscribers only by default (PECR), so sole traders and ordinary partnerships are left out unless the toggle is changed.",
"inputSchema": {
"additionalProperties": false,
"properties": {
"cursor": {
"description": "An opaque cursor from next_cursor. Pass it back unchanged.",
"maxLength": 512,
"minLength": 1,
"type": "string"
},
"limit": {
"default": 25,
"description": "Items per page, 1 to 100. Default 25.",
"maximum": 100,
"minimum": 1,
"type": "integer"
}
},
"type": "object"
},
"name": "list_field_sets",
"outputSchema": {
"$defs": {
"FieldSet": {
"description": "The named bundle of fields delivered with an order, with its exact columns.",
"properties": {
"columns": {
"items": {
"properties": {
"description": {
"type": "string"
},
"name": {
"type": "string"
}
},
"required": [
"name",
"description"
],
"type": "object"
},
"type": "array"
},
"credits_per_record": {
"description": "Every field set costs 1 credit a record.",
"minimum": 0,
"type": "number"
},
"description": {
"type": "string"
},
"id": {
"description": "Such as standard, standard_telephone or full.",
"pattern": "^[a-z0-9]+(_[a-z0-9]+)*$",
"type": "string"
},
"name": {
"type": "string"
}
},
"required": [
"id",
"name",
"description",
"credits_per_record",
"columns"
],
"type": "object"
}
},
"description": "A page of field sets, newest first.",
"properties": {
"data": {
"items": {
"$ref": "#/$defs/FieldSet"
},
"type": "array"
},
"has_more": {
"description": "Whether another page follows.",
"type": "boolean"
},
"next_cursor": {
"anyOf": [
{
"description": "An opaque cursor from next_cursor. Pass it back unchanged.",
"maxLength": 512,
"minLength": 1,
"type": "string"
},
{
"type": "null"
}
],
"description": "Pass as cursor to fetch the next page; null on the last page."
}
},
"required": [
"data",
"has_more",
"next_cursor"
],
"type": "object"
}
},
{
"description": "Lists every filterable field of the audience definition (mydatahub.audience/1) with its group, type, operators, value count and default, plus the datasets. Use it first to learn field names such as company.employee_band or site.town before building an audience by hand. Free and needs no account; the same catalogue is the mydatahub://catalogue resource. Call search_filter_values to find the codes for one field. Lawful basis is UK GDPR Article 6(1)(f) legitimate interests; email audiences include corporate subscribers only by default (PECR), so sole traders and ordinary partnerships are left out unless the toggle is changed.",
"inputSchema": {
"additionalProperties": false,
"properties": {
"dataset": {
"description": "The dataset an audience draws from. uk_contacts is live; ie_contacts and global_contacts are listed but not yet served.",
"enum": [
"uk_contacts",
"ie_contacts",
"global_contacts"
],
"type": "string"
}
},
"type": "object"
},
"name": "list_filters",
"outputSchema": {
"$defs": {
"Dataset": {
"description": "A dataset with owner, source, licence, refresh, residency, regulator, warranty and credits per record.",
"properties": {
"credits_per_record": {
"description": "1 for owned UK and Irish data.",
"minimum": 0,
"type": "number"
},
"credits_status": {
"enum": [
"confirmed",
"proposed"
],
"type": "string"
},
"current_version": {
"anyOf": [
{
"description": "The immutable weekly build a count is bound to, such as 2026-W39. The last 52 stay queryable.",
"examples": [
"2026-W39"
],
"pattern": "^[0-9]{4}-W(0[1-9]|[1-4][0-9]|5[0-3])$",
"type": "string"
},
{
"type": "null"
}
]
},
"id": {
"description": "The dataset an audience draws from. uk_contacts is live; ie_contacts and global_contacts are listed but not yet served.",
"enum": [
"uk_contacts",
"ie_contacts",
"global_contacts"
],
"type": "string"
},
"licence": {
"type": "string"
},
"name": {
"type": "string"
},
"owner": {
"type": "string"
},
"refresh": {
"type": "string"
},
"regulator": {
"type": "string"
},
"residency": {
"type": "string"
},
"source": {
"type": "string"
},
"status": {
"description": "live is served; planned is not yet served; through_our_team is sold through the bespoke service only.",
"enum": [
"live",
"planned",
"through_our_team"
],
"type": "string"
},
"versions_available": {
"description": "Immutable weekly versions still queryable (the last 52).",
"minimum": 0,
"type": "integer"
},
"warranty": {
"type": "string"
}
},
"required": [
"id",
"name",
"status",
"owner",
"source",
"licence",
"refresh",
"residency",
"regulator",
"warranty",
"credits_per_record",
"credits_status",
"current_version",
"versions_available"
],
"type": "object"
},
"FilterDimension": {
"description": "One filterable field.",
"properties": {
"default": {
"type": [
"string",
"null"
]
},
"description": {
"type": "string"
},
"examples": {
"items": {
"anyOf": [
{
"type": "string"
},
{
"type": "number"
},
{
"type": "boolean"
}
]
},
"type": "array"
},
"facet": {
"description": "Usable in breakdown_by.",
"type": "boolean"
},
"field": {
"description": "The field name, also the dimension slug.",
"type": "string"
},
"group": {
"enum": [
"company",
"site",
"contact",
"email",
"phone",
"signal"
],
"type": "string"
},
"label": {
"type": "string"
},
"operators": {
"items": {
"enum": [
"in",
"between",
"gte",
"lte",
"matches",
"within_radius",
"in_list",
"since"
],
"type": "string"
},
"type": "array"
},
"type": {
"enum": [
"enum",
"text",
"number",
"date",
"geo",
"hashed_list",
"boolean",
"band"
],
"type": "string"
},
"value_count": {
"anyOf": [
{
"minimum": 0,
"type": "integer"
},
{
"type": "null"
}
],
"description": "Distinct values in this dataset version; null for free text and numbers."
},
"values_url": {
"description": "Where to search the values, or null when the field has none to list.",
"type": [
"string",
"null"
]
}
},
"required": [
"field",
"group",
"type",
"label",
"description",
"operators",
"facet",
"value_count",
"default",
"examples",
"values_url"
],
"type": "object"
},
"OperatorInfo": {
"description": "An operator of the audience definition.",
"properties": {
"applies_to": {
"type": "string"
},
"description": {
"type": "string"
},
"op": {
"enum": [
"in",
"between",
"gte",
"lte",
"matches",
"within_radius",
"in_list",
"since",
"all",
"any",
"not"
],
"type": "string"
}
},
"required": [
"op",
"applies_to",
"description"
],
"type": "object"
}
},
"description": "Every filterable field with its type, operators and value count, plus the datasets.",
"properties": {
"dataset": {
"description": "The dataset an audience draws from. uk_contacts is live; ie_contacts and global_contacts are listed but not yet served.",
"enum": [
"uk_contacts",
"ie_contacts",
"global_contacts"
],
"type": "string"
},
"dataset_version": {
"description": "The immutable weekly build a count is bound to, such as 2026-W39. The last 52 stay queryable.",
"examples": [
"2026-W39"
],
"pattern": "^[0-9]{4}-W(0[1-9]|[1-4][0-9]|5[0-3])$",
"type": "string"
},
"datasets": {
"items": {
"$ref": "#/$defs/Dataset"
},
"type": "array"
},
"fields": {
"items": {
"$ref": "#/$defs/FilterDimension"
},
"type": "array"
},
"operators": {
"items": {
"$ref": "#/$defs/OperatorInfo"
},
"type": "array"
}
},
"required": [
"dataset",
"dataset_version",
"fields",
"operators",
"datasets"
],
"type": "object"
}
},
{
"description": "Looks up one company by Companies House number, domain or name and returns its Companies House fields and compliance facts, and for a signed-in caller the contacts held there by job level. It returns no contact details: use enrich_contact for one known person, or count_audience for everyone at the company. Free and needs no account, though the contacts held are a single company count that needs an account (null when signed out). Lawful basis is UK GDPR Article 6(1)(f) legitimate interests; email audiences include corporate subscribers only by default (PECR), so sole traders and ordinary partnerships are left out unless the toggle is changed.",
"inputSchema": {
"additionalProperties": false,
"description": "A company by exactly one of number, domain or name.",
"oneOf": [
{
"properties": {
"company_number": true
},
"required": [
"company_number"
],
"type": "object"
},
{
"properties": {
"domain": true
},
"required": [
"domain"
],
"type": "object"
},
{
"properties": {
"name": true
},
"required": [
"name"
],
"type": "object"
}
],
"properties": {
"company_number": {
"description": "Eight characters in upper case, such as 05046417 or SC123456.",
"pattern": "^[A-Z0-9]{8}$",
"type": "string"
},
"domain": {
"maxLength": 253,
"minLength": 3,
"type": "string"
},
"name": {
"maxLength": 200,
"minLength": 2,
"type": "string"
},
"town": {
"description": "Narrows a name search.",
"maxLength": 100,
"type": "string"
}
},
"type": "object"
},
"name": "lookup_company",
"outputSchema": {
"$defs": {
"CellCount": {
"anyOf": [
{
"minimum": 0,
"type": "integer"
},
{
"const": "under 10",
"type": "string"
},
{
"const": "suppressed",
"type": "string"
}
],
"description": "A whole number; \"under 10\" when disclosure control withholds a small cell; or \"suppressed\" when secondary suppression hides a cell of 10 or more in a cross-tab or breakdown, so totals cannot be differenced. Anonymous and trial callers see cells rounded to the nearest 5.",
"examples": [
4120,
"under 10",
"suppressed"
]
},
"CompanyCompliance": {
"description": "The company facts of the compliance object, for results with no contact.",
"properties": {
"attribution": {
"type": [
"string",
"null"
]
},
"corporate_subscriber": {
"type": "boolean"
},
"email_marketing_basis": {
"enum": [
"pecr_corporate_subscriber",
"consent_required"
],
"type": "string"
},
"lawful_basis": {
"enum": [
"legitimate_interests_art6_1_f"
],
"type": "string"
},
"provenance": {
"properties": {
"company": {
"properties": {
"as_of": {
"format": "date",
"type": "string"
},
"source": {
"enum": [
"emailmovers_research",
"companies_house",
"onspd",
"ukbizdirectory",
"partner_rampedup"
],
"type": "string"
}
},
"required": [
"source",
"as_of"
],
"type": "object"
}
},
"required": [
"company"
],
"type": "object"
},
"subscriber_class": {
"enum": [
"ltd",
"plc",
"llp",
"scottish_partnership",
"public_body",
"charity_incorporated",
"sole_trader",
"ordinary_partnership",
"unknown"
],
"type": "string"
},
"subscriber_evidence": {
"properties": {
"companies_house_number": {
"type": [
"string",
"null"
]
},
"company_type": {
"type": "string"
}
},
"required": [
"companies_house_number",
"company_type"
],
"type": "object"
}
},
"required": [
"lawful_basis",
"subscriber_class",
"corporate_subscriber",
"email_marketing_basis",
"subscriber_evidence",
"provenance",
"attribution"
],
"type": "object"
},
"Disclosure": {
"description": "Whether these numbers are exact or protected: \"under 10\" cells, rounding to 5 and secondary suppression for anonymous and trial callers.",
"properties": {
"level": {
"description": "exact for authenticated paid callers; rounded for anonymous and trial callers, whose counts under 100 and every cell are rounded to the nearest 5.",
"enum": [
"exact",
"rounded"
],
"type": "string"
},
"notes": {
"items": {
"type": "string"
},
"type": "array"
},
"rounded_to": {
"anyOf": [
{
"exclusiveMinimum": 0,
"type": "integer"
},
{
"type": "null"
}
],
"description": "5 when numbers are rounded; null when they are exact."
},
"secondary_suppression": {
"description": "True when cross-tab or breakdown cells of 10 or more were hidden as \"suppressed\" so totals cannot be differenced.",
"type": "boolean"
}
},
"required": [
"level",
"rounded_to",
"secondary_suppression",
"notes"
],
"type": "object"
},
"LevelCount": {
"description": "Contacts at one job level.",
"properties": {
"contacts": {
"$ref": "#/$defs/CellCount"
},
"level": {
"type": "string"
}
},
"required": [
"level",
"contacts"
],
"type": "object"
},
"SicCode": {
"description": "A SIC 2007 code and its label, such as 25620 Machining.",
"properties": {
"code": {
"type": "string"
},
"label": {
"type": "string"
}
},
"required": [
"code",
"label"
],
"type": "object"
}
},
"description": "Companies House fields for one company and, for signed-in callers, the contacts held there. No contact details.",
"properties": {
"company": {
"properties": {
"companies_house_number": {
"type": [
"string",
"null"
]
},
"employee_band": {
"type": [
"string",
"null"
]
},
"incorporation_date": {
"anyOf": [
{
"format": "date",
"type": "string"
},
{
"type": "null"
}
]
},
"name": {
"type": "string"
},
"registered_office": {
"properties": {
"postcode": {
"type": [
"string",
"null"
]
},
"town": {
"type": [
"string",
"null"
]
}
},
"required": [
"town",
"postcode"
],
"type": "object"
},
"sic_2007": {
"items": {
"$ref": "#/$defs/SicCode"
},
"type": "array"
},
"status": {
"type": "string"
},
"subscriber_class": {
"enum": [
"ltd",
"plc",
"llp",
"scottish_partnership",
"public_body",
"charity_incorporated",
"sole_trader",
"ordinary_partnership",
"unknown"
],
"type": "string"
},
"turnover_band": {
"type": [
"string",
"null"
]
},
"type": {
"type": "string"
},
"website_domain": {
"type": [
"string",
"null"
]
}
},
"required": [
"companies_house_number",
"name",
"status",
"type",
"subscriber_class",
"incorporation_date",
"sic_2007",
"employee_band",
"turnover_band",
"website_domain",
"registered_office"
],
"type": "object"
},
"compliance": {
"$ref": "#/$defs/CompanyCompliance"
},
"contacts_by_level": {
"anyOf": [
{
"items": {
"$ref": "#/$defs/LevelCount"
},
"type": "array"
},
{
"type": "null"
}
],
"description": "The same count by job level, most senior first, with Level not known last; null when signed out."
},
"contacts_held": {
"anyOf": [
{
"$ref": "#/$defs/CellCount"
},
{
"type": "null"
}
],
"description": "Contacts we hold at the company: a single-company count, so signed-in callers only (null otherwise) and logged. Trial callers see it rounded."
},
"credits_charged": {
"const": 0,
"type": "number"
},
"dataset_version": {
"description": "The immutable weekly build a count is bound to, such as 2026-W39. The last 52 stay queryable.",
"examples": [
"2026-W39"
],
"pattern": "^[0-9]{4}-W(0[1-9]|[1-4][0-9]|5[0-3])$",
"type": "string"
},
"disclosure": {
"$ref": "#/$defs/Disclosure"
},
"match_confidence": {
"maximum": 1,
"minimum": 0,
"type": "number"
}
},
"required": [
"match_confidence",
"dataset_version",
"company",
"contacts_held",
"contacts_by_level",
"disclosure",
"compliance",
"credits_charged"
],
"type": "object"
}
},
{
"description": "Returns up to 25 masked sample rows (10 by default) for an audience or a count id, each with verification badges, why it matches and a provenance card. Use it after count_audience to show the user what the records look like before quoting. Free: emails and phones are masked on the server, a repeat returns the same rows, and no rows come back when the count is under 25. Call quote_order next to price the records. Lawful basis is UK GDPR Article 6(1)(f) legitimate interests; email audiences include corporate subscribers only by default (PECR), so sole traders and ordinary partnerships are left out unless the toggle is changed.",
"inputSchema": {
"$defs": {
"AllGroup": {
"additionalProperties": false,
"description": "AND: every node inside must match.",
"properties": {
"all": {
"items": {
"$ref": "#/$defs/WhereNode"
},
"minItems": 1,
"type": "array"
}
},
"required": [
"all"
],
"type": "object"
},
"AnyGroup": {
"additionalProperties": false,
"description": "OR: at least one node inside must match.",
"properties": {
"any": {
"items": {
"$ref": "#/$defs/WhereNode"
},
"minItems": 1,
"type": "array"
}
},
"required": [
"any"
],
"type": "object"
},
"Audience": {
"additionalProperties": false,
"description": "Who you want, as filters grouped by entity (company., site., contact., email., phone., signal.). The server fills its defaults (active companies, named emails, corporate subscribers, the current dataset_version) and returns the effective definition with every count.",
"properties": {
"dataset": {
"description": "The dataset an audience draws from. uk_contacts is live; ie_contacts and global_contacts are listed but not yet served.",
"enum": [
"uk_contacts",
"ie_contacts",
"global_contacts"
],
"type": "string"
},
"dataset_version": {
"description": "The weekly build to count against, such as 2026-W39. Left out, the current version is filled in and returned.",
"examples": [
"2026-W39"
],
"pattern": "^[0-9]{4}-W(0[1-9]|[1-4][0-9]|5[0-3])$",
"type": "string"
},
"dedupe": {
"description": "none keeps every matching contact, one_per_company keeps one contact per company, one_per_site keeps one per site. Default none.",
"enum": [
"none",
"one_per_company",
"one_per_site"
],
"type": "string"
},
"email_policy": {
"$ref": "#/$defs/EmailPolicy"
},
"schema": {
"const": "mydatahub.audience/1",
"description": "The definition's namespace and version. Older versions are upgraded by a pure function.",
"type": "string"
},
"where": {
"$ref": "#/$defs/WhereNode",
"description": "The filters. Left out, the audience is the whole dataset after the defaults."
}
},
"required": [
"schema"
],
"title": "MyDataHub audience definition (mydatahub.audience/1)",
"type": "object"
},
"AudienceRef": {
"anyOf": [
{
"description": "Format: an audience id: aud_ followed by a 26 character ULID in upper case Crockford base32, such as aud_01JB4H2K9V6XN3M9R6T1Y5W8ZA.",
"examples": [
"aud_01JB4H2K9V6XN3M9R6T1Y5W8ZA"
],
"pattern": "^aud_[0-7][0-9A-HJKMNP-TV-Z]{25}$",
"type": "string"
},
{
"$ref": "#/$defs/Audience"
}
],
"description": "An audience definition (mydatahub.audience/1) inline, or the aud_ id of a saved audience."
},
"BetweenFilter": {
"additionalProperties": false,
"description": "The field lies from one value to another inclusive, over the field's order.",
"examples": [
{
"field": "company.employee_band",
"from": "10-19",
"op": "between",
"to": "200-349"
}
],
"properties": {
"field": {
"enum": [
"company.employee_band",
"company.turnover_band",
"company.fleet_band",
"contact.job_level_rank",
"email.deliverability_score"
],
"type": "string"
},
"from": {
"anyOf": [
{
"maxLength": 200,
"minLength": 1,
"type": "string"
},
{
"type": "number"
}
],
"description": "A band code or a number from the field's order."
},
"op": {
"const": "between",
"type": "string"
},
"to": {
"anyOf": [
{
"maxLength": 200,
"minLength": 1,
"type": "string"
},
{
"type": "number"
}
],
"description": "A band code or a number from the field's order."
}
},
"required": [
"field",
"op",
"from",
"to"
],
"type": "object"
},
"BundleNode": {
"additionalProperties": false,
"description": "A title bundle, resolved to its filters in the effective definition: sdm (senior decision makers), manager_and_above (managers and above), owner_managed (owner managed).",
"properties": {
"bundle": {
"enum": [
"sdm",
"manager_and_above",
"owner_managed"
],
"type": "string"
}
},
"required": [
"bundle"
],
"type": "object"
},
"EmailPolicy": {
"additionalProperties": false,
"description": "Email quality floor. Defaults: min_deliverability_score 70, allow_catch_all false.",
"properties": {
"allow_catch_all": {
"description": "Whether catch-all addresses count. Default false.",
"type": "boolean"
},
"min_deliverability_score": {
"description": "Lowest deliverability score counted, 0 to 100. Default 70.",
"maximum": 100,
"minimum": 0,
"type": "integer"
}
},
"type": "object"
},
"Filter": {
"description": "One criterion: a field from GET /v1/catalogue/filters, an operator and its operands. Exclusions nest under not.",
"oneOf": [
{
"$ref": "#/$defs/InFilter"
},
{
"$ref": "#/$defs/BetweenFilter"
},
{
"$ref": "#/$defs/GteFilter"
},
{
"$ref": "#/$defs/LteFilter"
},
{
"$ref": "#/$defs/MatchesFilter"
},
{
"$ref": "#/$defs/WithinRadiusFilter"
},
{
"$ref": "#/$defs/InListFilter"
},
{
"$ref": "#/$defs/SinceFilter"
}
]
},
"GteFilter": {
"additionalProperties": false,
"description": "The field is at or after the value in its order: for bands, the band and every larger one.",
"examples": [
{
"field": "company.employee_band",
"op": "gte",
"value": "50-99"
}
],
"properties": {
"field": {
"enum": [
"company.employee_band",
"company.turnover_band",
"company.fleet_band",
"contact.job_level_rank",
"email.deliverability_score"
],
"type": "string"
},
"op": {
"const": "gte",
"type": "string"
},
"value": {
"anyOf": [
{
"maxLength": 200,
"minLength": 1,
"type": "string"
},
{
"type": "number"
}
],
"description": "A band code or a number from the field's order."
}
},
"required": [
"field",
"op",
"value"
],
"type": "object"
},
"InFilter": {
"additionalProperties": false,
"description": "The field holds one of the listed codes.",
"examples": [
{
"field": "company.sic_2007",
"op": "in",
"values": [
"C"
]
}
],
"properties": {
"field": {
"enum": [
"company.sic_2007",
"company.business_class",
"company.employee_band",
"company.turnover_band",
"company.fleet_band",
"company.type",
"company.status",
"company.subscriber_class",
"company.companies_house_number",
"site.region",
"site.county",
"site.town",
"site.postcode",
"contact.title_family",
"contact.job_function",
"contact.job_level_rank",
"contact.premium",
"email.exists",
"email.type",
"phone.exists",
"phone.tps_ctps_status"
],
"type": "string"
},
"op": {
"const": "in",
"type": "string"
},
"values": {
"items": {
"anyOf": [
{
"maxLength": 200,
"minLength": 1,
"type": "string"
},
{
"type": "number"
},
{
"type": "boolean"
}
],
"description": "A code, a rank or a boolean, as the field's catalogue lists it."
},
"maxItems": 10000,
"minItems": 1,
"type": "array"
}
},
"required": [
"field",
"op",
"values"
],
"type": "object"
},
"InListFilter": {
"additionalProperties": false,
"description": "The record's hashed email, domain, phone, company number or title term is on a suppression list. Usually nested under not; each list reports the records it removed.",
"examples": [
{
"field": "email.address_sha256",
"list_id": "sup_01JB4H7Q2V7XN3M9R6T1Y5W8ZA",
"op": "in_list"
}
],
"properties": {
"field": {
"enum": [
"company.companies_house_number",
"contact.title",
"email.address_sha256",
"email.domain_sha256",
"phone.e164_sha256"
],
"type": "string"
},
"list_id": {
"description": "Format: a suppression list id: sup_ followed by a 26 character ULID in upper case Crockford base32, such as sup_01JB4H7Q2V7XN3M9R6T1Y5W8ZA.",
"examples": [
"sup_01JB4H7Q2V7XN3M9R6T1Y5W8ZA"
],
"pattern": "^sup_[0-7][0-9A-HJKMNP-TV-Z]{25}$",
"type": "string"
},
"op": {
"const": "in_list",
"type": "string"
}
},
"required": [
"field",
"op",
"list_id"
],
"type": "object"
},
"LteFilter": {
"additionalProperties": false,
"description": "The field is at or before the value in its order. Rank 1 is the most senior, so Director and above is contact.job_level_rank lte 6.",
"examples": [
{
"field": "contact.job_level_rank",
"op": "lte",
"value": 6
}
],
"properties": {
"field": {
"enum": [
"company.employee_band",
"company.turnover_band",
"company.fleet_band",
"contact.job_level_rank",
"contact.company_contact_rank",
"email.deliverability_score"
],
"type": "string"
},
"op": {
"const": "lte",
"type": "string"
},
"value": {
"anyOf": [
{
"maxLength": 200,
"minLength": 1,
"type": "string"
},
{
"type": "number"
}
],
"description": "A band code or a number from the field's order."
}
},
"required": [
"field",
"op",
"value"
],
"type": "object"
},
"MatchesFilter": {
"additionalProperties": false,
"allOf": [
{
"if": {
"properties": {
"mode": {
"const": "exact"
}
},
"required": [
"mode"
],
"type": "object"
},
"then": {
"properties": {
"exclude_terms": {
"maxItems": 0,
"type": "array"
},
"expand": {
"maxItems": 0,
"type": "array"
}
},
"type": "object"
}
}
],
"description": "Job title keyword match. mode contains (the default) or starts_with expands each term with the expansion sets; mode exact matches verbatim titles. Every expanded term is returned with the count.",
"examples": [
{
"expand": [
"plural_singular",
"department_synonyms",
"ampersand_and",
"abbreviations"
],
"field": "contact.title",
"mode": "contains",
"op": "matches",
"terms": [
"marketing manager"
]
}
],
"properties": {
"exclude_terms": {
"description": "Expanded terms removed by hand. Kept in the definition so the count stays reproducible when the title dictionary changes.",
"items": {
"maxLength": 200,
"minLength": 1,
"type": "string"
},
"maxItems": 500,
"type": "array"
},
"expand": {
"description": "Expansion sets to apply, each once: plural_singular, department_synonyms, ampersand_and, abbreviations, permutations. Left out, the first four apply; an empty list applies none. Not used with mode exact.",
"items": {
"enum": [
"plural_singular",
"department_synonyms",
"ampersand_and",
"abbreviations",
"permutations"
],
"type": "string"
},
"maxItems": 5,
"type": "array",
"uniqueItems": true
},
"field": {
"enum": [
"contact.title"
],
"type": "string"
},
"mode": {
"description": "contains (the default) matches titles containing a term, starts_with matches titles beginning with it, exact takes verbatim titles with no expansion.",
"enum": [
"contains",
"starts_with",
"exact"
],
"type": "string"
},
"op": {
"const": "matches",
"type": "string"
},
"terms": {
"items": {
"maxLength": 200,
"minLength": 1,
"type": "string"
},
"maxItems": 500,
"minItems": 1,
"type": "array"
}
},
"required": [
"field",
"op",
"terms"
],
"type": "object"
},
"NotGroup": {
"additionalProperties": false,
"description": "Negation: the single node inside must not match.",
"properties": {
"not": {
"$ref": "#/$defs/WhereNode"
}
},
"required": [
"not"
],
"type": "object"
},
"PlaceCentre": {
"additionalProperties": false,
"description": "A named place. Ambiguous names come back from resolve_location as candidates, never a silent choice.",
"properties": {
"code": {
"description": "The ONS geography code of the chosen candidate when resolve_location found more than one, such as E08000035 for the Leeds district.",
"maxLength": 20,
"minLength": 1,
"type": "string"
},
"place": {
"description": "A place name, resolved with resolve_location, such as Leeds.",
"maxLength": 100,
"minLength": 1,
"type": "string"
}
},
"required": [
"place"
],
"type": "object"
},
"PointCentre": {
"additionalProperties": false,
"description": "A latitude and longitude in WGS84 degrees.",
"properties": {
"lat": {
"maximum": 61,
"minimum": 49,
"type": "number"
},
"lon": {
"maximum": 2,
"minimum": -9,
"type": "number"
}
},
"required": [
"lat",
"lon"
],
"type": "object"
},
"PostcodeCentre": {
"additionalProperties": false,
"description": "A postcode centroid from ONSPD.",
"properties": {
"postcode": {
"description": "The centroid of a postcode unit, sector, district or area, such as LS1 4AP.",
"pattern": "^[A-Za-z]{1,2}([0-9][0-9A-Za-z]?( [0-9]([A-Za-z]{2})?| ?[0-9][A-Za-z]{2})?)?$",
"type": "string"
}
},
"required": [
"postcode"
],
"type": "object"
},
"RadiusCentre": {
"anyOf": [
{
"$ref": "#/$defs/PlaceCentre"
},
{
"$ref": "#/$defs/PostcodeCentre"
},
{
"$ref": "#/$defs/PointCentre"
}
],
"description": "The centre of a radius: a place, a postcode or a latitude and longitude."
},
"SinceFilter": {
"additionalProperties": false,
"description": "Within the last N days: a date field, or a Companies House signal of the listed types on signal.type.",
"examples": [
{
"days": 90,
"field": "signal.type",
"op": "since",
"values": [
"company.incorporated"
]
}
],
"properties": {
"days": {
"maximum": 3650,
"minimum": 1,
"type": "integer"
},
"field": {
"enum": [
"contact.last_validated_at",
"email.last_verified_at",
"signal.type",
"signal.observed_at"
],
"type": "string"
},
"op": {
"const": "since",
"type": "string"
},
"values": {
"description": "For signal.type only: the signal types to look for, such as company.incorporated.",
"items": {
"maxLength": 200,
"minLength": 1,
"type": "string"
},
"maxItems": 10000,
"minItems": 1,
"type": "array"
}
},
"required": [
"field",
"op",
"days"
],
"type": "object"
},
"WhereNode": {
"anyOf": [
{
"$ref": "#/$defs/AllGroup"
},
{
"$ref": "#/$defs/AnyGroup"
},
{
"$ref": "#/$defs/NotGroup"
},
{
"$ref": "#/$defs/BundleNode"
},
{
"$ref": "#/$defs/Filter"
}
],
"description": "A group (all, any, not), a title bundle or a filter. Groups nest up to 32 deep, and a where tree holds up to 1,000 filters, groups and bundles."
},
"WithinRadiusFilter": {
"additionalProperties": false,
"description": "Sites within radius_miles of the centre. The count reports the centroid used and the postcodes matched.",
"examples": [
{
"centre": {
"place": "Leeds"
},
"field": "site.location",
"op": "within_radius",
"radius_miles": 20
}
],
"properties": {
"centre": {
"$ref": "#/$defs/RadiusCentre"
},
"field": {
"enum": [
"site.location"
],
"type": "string"
},
"op": {
"const": "within_radius",
"type": "string"
},
"radius_miles": {
"description": "Radius in miles, 1 to 100. Under 5 miles needs an account.",
"maximum": 100,
"minimum": 1,
"type": "number"
}
},
"required": [
"field",
"op",
"centre",
"radius_miles"
],
"type": "object"
}
},
"additionalProperties": false,
"description": "The audience or count to sample: exactly one of audience or count_id.",
"oneOf": [
{
"properties": {
"audience": true
},
"required": [
"audience"
],
"type": "object"
},
{
"properties": {
"count_id": true
},
"required": [
"count_id"
],
"type": "object"
}
],
"properties": {
"audience": {
"$ref": "#/$defs/AudienceRef",
"type": [
"string",
"object"
]
},
"count_id": {
"description": "A count id instead of an audience.",
"examples": [
"cnt_7K2PQ4MAXN3R6TBY5WDZ"
],
"pattern": "^cnt_[A-Za-z2-7]{20}$",
"type": "string"
},
"limit": {
"default": 10,
"description": "Rows to return, 1 to 25. Default 10.",
"maximum": 25,
"minimum": 1,
"type": "integer"
},
"shuffle": {
"default": false,
"description": "Draw a new seed. Counts against your rate budget and is logged. Default false, so a repeat returns the same rows.",
"type": "boolean"
}
},
"type": "object"
},
"name": "preview_records",
"outputSchema": {
"$defs": {
"ComplianceObject": {
"description": "Carried by every preview row, order record, lookup and enrichment, and repeated as CSV columns and as the MyDataHub property group on CRM push.",
"examples": [
{
"article14_notified_at": "2026-06-14",
"article14_status": "notified",
"attribution": "Contains public sector information licensed under the Open Government Licence v3.0",
"corporate_subscriber": true,
"email_marketing_basis": "pecr_corporate_subscriber",
"lawful_basis": "legitimate_interests_art6_1_f",
"lia_ref": "EM-LIA-2026-03",
"notice_version": "2026-02",
"provenance": {
"company": {
"as_of": "2026-09-21",
"source": "companies_house"
},
"contact": {
"compiled_at": "2026-05-02",
"last_verified_at": "2026-08-30",
"method": "telephone",
"source": "emailmovers_research"
},
"email": {
"provider_location": "EU",
"result": "ok",
"verified_at": "2026-09-10"
}
},
"record_age_days": 147,
"subscriber_class": "ltd",
"subscriber_evidence": {
"companies_house_number": "05046417",
"company_type": "ltd"
},
"suppression_status": "none",
"tps_ctps_screened_at": "2026-09-12",
"tps_ctps_status": "clear",
"tps_ctps_valid_until": "2026-10-10"
}
],
"properties": {
"article14_notified_at": {
"anyOf": [
{
"format": "date",
"type": "string"
},
{
"type": "null"
}
]
},
"article14_status": {
"description": "Article 14 notice status: notified, publicly_notified_disproportionate_effort, pending_within_window.",
"enum": [
"notified",
"publicly_notified_disproportionate_effort",
"pending_within_window"
],
"type": "string"
},
"attribution": {
"description": "The OGL v3.0 attribution for Companies House company data. Officer names are personal data outside the OGL, so they carry article14_status instead.",
"type": [
"string",
"null"
]
},
"corporate_subscriber": {
"description": "True for companies, LLPs, Scottish partnerships and public bodies, where the PECR regulation 22 consent rule does not apply.",
"type": "boolean"
},
"email_marketing_basis": {
"enum": [
"pecr_corporate_subscriber",
"consent_required"
],
"type": "string"
},
"lawful_basis": {
"description": "UK GDPR Article 6(1)(f) legitimate interests, with the LIA in lia_ref.",
"enum": [
"legitimate_interests_art6_1_f"
],
"type": "string"
},
"lia_ref": {
"description": "The published legitimate interests assessment.",
"type": "string"
},
"notice_version": {
"description": "The privacy notice version sent.",
"type": "string"
},
"provenance": {
"$ref": "#/$defs/Provenance"
},
"record_age_days": {
"description": "Days since the record was compiled.",
"minimum": 0,
"type": "integer"
},
"subscriber_class": {
"description": "PECR subscriber class: ltd, plc, llp, scottish_partnership, public_body, charity_incorporated, sole_trader, ordinary_partnership, unknown.",
"enum": [
"ltd",
"plc",
"llp",
"scottish_partnership",
"public_body",
"charity_incorporated",
"sole_trader",
"ordinary_partnership",
"unknown"
],
"type": "string"
},
"subscriber_evidence": {
"description": "The register entry behind subscriber_class.",
"properties": {
"companies_house_number": {
"type": [
"string",
"null"
]
},
"company_type": {
"type": "string"
}
},
"required": [
"companies_house_number",
"company_type"
],
"type": "object"
},
"suppression_status": {
"enum": [
"none",
"objected_to_emailmovers",
"objected_to_licensee",
"deceased",
"left_company"
],
"type": "string"
},
"tps_ctps_screened_at": {
"anyOf": [
{
"format": "date",
"type": "string"
},
{
"type": "null"
}
],
"description": "The date of the screen the status is as of; null when not screened."
},
"tps_ctps_status": {
"description": "Telephone screen: clear, tps_registered, ctps_registered, tps_or_ctps_registered, not_screened. The result of the screen on tps_ctps_screened_at, valid until tps_ctps_valid_until. In a sample, an order's records (each time they are fetched, downloaded or pushed) and an enrichment, a clear number reads not_screened, with no dates, once that screen is more than 28 days before the day the record is served; a registered number stays registered.",
"enum": [
"clear",
"tps_registered",
"ctps_registered",
"tps_or_ctps_registered",
"not_screened"
],
"type": "string"
},
"tps_ctps_valid_until": {
"anyOf": [
{
"format": "date",
"type": "string"
},
{
"type": "null"
}
],
"description": "28 days after tps_ctps_screened_at, when this screen stops being valid. Null when not screened. Screen the numbers you are supplied yourself before calling, and again every 28 days."
}
},
"required": [
"lawful_basis",
"lia_ref",
"subscriber_class",
"corporate_subscriber",
"email_marketing_basis",
"subscriber_evidence",
"article14_status",
"article14_notified_at",
"notice_version",
"provenance",
"tps_ctps_status",
"tps_ctps_screened_at",
"tps_ctps_valid_until",
"suppression_status",
"record_age_days",
"attribution"
],
"type": "object"
},
"Disclosure": {
"description": "Whether these numbers are exact or protected: \"under 10\" cells, rounding to 5 and secondary suppression for anonymous and trial callers.",
"properties": {
"level": {
"description": "exact for authenticated paid callers; rounded for anonymous and trial callers, whose counts under 100 and every cell are rounded to the nearest 5.",
"enum": [
"exact",
"rounded"
],
"type": "string"
},
"notes": {
"items": {
"type": "string"
},
"type": "array"
},
"rounded_to": {
"anyOf": [
{
"exclusiveMinimum": 0,
"type": "integer"
},
{
"type": "null"
}
],
"description": "5 when numbers are rounded; null when they are exact."
},
"secondary_suppression": {
"description": "True when cross-tab or breakdown cells of 10 or more were hidden as \"suppressed\" so totals cannot be differenced.",
"type": "boolean"
}
},
"required": [
"level",
"rounded_to",
"secondary_suppression",
"notes"
],
"type": "object"
},
"OtherBadge": {
"description": "Re-checking, unverified or suppressed.",
"properties": {
"badge": {
"enum": [
"re_checking",
"unverified",
"suppressed"
],
"type": "string"
},
"date": {
"anyOf": [
{
"format": "date",
"type": "string"
},
{
"type": "null"
}
],
"description": "The date behind the badge, if any."
},
"label": {
"description": "Such as Verified 12 September 2026.",
"type": "string"
}
},
"required": [
"badge",
"date",
"label"
],
"type": "object"
},
"PreviewRow": {
"description": "One masked sample record.",
"properties": {
"badges": {
"items": {
"$ref": "#/$defs/VerificationBadge"
},
"type": "array"
},
"company": {
"properties": {
"companies_house_number": {
"type": [
"string",
"null"
]
},
"employee_band": {
"type": [
"string",
"null"
]
},
"name": {
"type": "string"
},
"sic_2007": {
"items": {
"type": "string"
},
"type": "array"
},
"status": {
"type": "string"
}
},
"required": [
"name",
"companies_house_number",
"status",
"employee_band",
"sic_2007"
],
"type": "object"
},
"compliance": {
"$ref": "#/$defs/ComplianceObject"
},
"email_masked": {
"description": "First character of the local part plus the top level domain, such as j••••@••••.co.uk.",
"type": [
"string",
"null"
]
},
"email_type": {
"anyOf": [
{
"enum": [
"named",
"generic_local_part",
"generic_domain"
],
"type": "string"
},
{
"type": "null"
}
]
},
"id": {
"description": "A session-scoped id standing in for the record. It never reveals contact_ ids.",
"examples": [
"prv_01JB4H3M7Q2V7XN3M9R6T1Y5W8"
],
"pattern": "^prv_[0-7][0-9A-HJKMNP-TV-Z]{25}$",
"type": "string"
},
"job_function": {
"type": [
"string",
"null"
]
},
"job_level": {
"description": "The level, such as Director; null when the level is not known.",
"type": [
"string",
"null"
]
},
"phone_masked": {
"description": "To the area code, such as 0113 ••• •••1.",
"type": [
"string",
"null"
]
},
"provenance": {
"$ref": "#/$defs/ProvenanceCard"
},
"site": {
"properties": {
"postcode_district": {
"type": [
"string",
"null"
]
},
"region": {
"type": "string"
},
"town": {
"type": [
"string",
"null"
]
}
},
"required": [
"town",
"postcode_district",
"region"
],
"type": "object"
},
"title": {
"type": "string"
},
"tps_ctps_status": {
"anyOf": [
{
"enum": [
"clear",
"tps_registered",
"ctps_registered",
"tps_or_ctps_registered",
"not_screened"
],
"type": "string"
},
{
"type": "null"
}
]
},
"why_it_matches": {
"items": {
"$ref": "#/$defs/WhyItMatches"
},
"type": "array"
}
},
"required": [
"id",
"title",
"job_level",
"job_function",
"company",
"site",
"email_masked",
"email_type",
"phone_masked",
"tps_ctps_status",
"badges",
"why_it_matches",
"provenance",
"compliance"
],
"type": "object"
},
"Provenance": {
"description": "Source per entity, answering the ICO questions who compiled it and where from.",
"properties": {
"company": {
"description": "Where the company facts came from and the snapshot date.",
"properties": {
"as_of": {
"format": "date",
"type": "string"
},
"source": {
"enum": [
"emailmovers_research",
"companies_house",
"onspd",
"ukbizdirectory",
"partner_rampedup"
],
"type": "string"
}
},
"required": [
"source",
"as_of"
],
"type": "object"
},
"contact": {
"anyOf": [
{
"properties": {
"compiled_at": {
"format": "date",
"type": "string"
},
"last_verified_at": {
"anyOf": [
{
"format": "date",
"type": "string"
},
{
"type": "null"
}
]
},
"method": {
"enum": [
"telephone",
"web",
"register"
],
"type": "string"
},
"source": {
"enum": [
"emailmovers_research",
"companies_house",
"onspd",
"ukbizdirectory",
"partner_rampedup"
],
"type": "string"
}
},
"required": [
"source",
"compiled_at",
"last_verified_at",
"method"
],
"type": "object"
},
{
"type": "null"
}
],
"description": "Who compiled the contact, when, and how it was last confirmed."
},
"email": {
"anyOf": [
{
"properties": {
"provider_location": {
"enum": [
"UK",
"EU",
"US"
],
"type": "string"
},
"result": {
"enum": [
"ok",
"catch_all",
"unknown",
"invalid",
"disposable"
],
"type": "string"
},
"verified_at": {
"format": "date",
"type": "string"
}
},
"required": [
"verified_at",
"result",
"provider_location"
],
"type": "object"
},
{
"type": "null"
}
],
"description": "The latest email verification: date, provider result and location."
}
},
"required": [
"company",
"contact"
],
"type": "object"
},
"ProvenanceCard": {
"description": "The ICO due diligence answers for one record, as shown on the sample row.",
"properties": {
"article14_status": {
"enum": [
"notified",
"publicly_notified_disproportionate_effort",
"pending_within_window"
],
"type": "string"
},
"companies_house_number": {
"type": [
"string",
"null"
]
},
"company_status": {
"type": "string"
},
"first_seen_at": {
"format": "date",
"type": "string"
},
"last_verified_at": {
"anyOf": [
{
"format": "date",
"type": "string"
},
{
"type": "null"
}
]
},
"lawful_basis": {
"enum": [
"legitimate_interests_art6_1_f"
],
"type": "string"
},
"method": {
"enum": [
"telephone",
"web",
"register"
],
"type": "string"
},
"sources": {
"additionalProperties": {
"enum": [
"emailmovers_research",
"companies_house",
"onspd",
"ukbizdirectory",
"partner_rampedup"
],
"type": "string"
},
"description": "The source of each field shown, such as title: emailmovers_research.",
"propertyNames": {
"type": "string"
},
"type": "object"
},
"tps_ctps_screened_at": {
"anyOf": [
{
"format": "date",
"type": "string"
},
{
"type": "null"
}
]
}
},
"required": [
"sources",
"first_seen_at",
"last_verified_at",
"method",
"companies_house_number",
"company_status",
"article14_status",
"tps_ctps_screened_at",
"lawful_basis"
],
"type": "object"
},
"VerificationBadge": {
"description": "A badge on a sample row. Every verified has a date.",
"oneOf": [
{
"$ref": "#/$defs/VerifiedBadge"
},
{
"$ref": "#/$defs/OtherBadge"
}
]
},
"VerifiedBadge": {
"description": "Verified, with the date it was verified.",
"properties": {
"badge": {
"const": "verified",
"type": "string"
},
"date": {
"description": "The verification date. Every verified has one.",
"format": "date",
"type": "string"
},
"label": {
"description": "Such as Verified 12 September 2026.",
"type": "string"
}
},
"required": [
"badge",
"date",
"label"
],
"type": "object"
},
"WhyItMatches": {
"description": "One predicate the record satisfies, with its value.",
"properties": {
"explanation": {
"description": "Such as Marketing Director matched marketing manager through expansion.",
"type": "string"
},
"field": {
"type": "string"
},
"pointer": {
"description": "JSON pointer to the filter in the audience.",
"type": "string"
},
"value": {
"anyOf": [
{
"type": "string"
},
{
"type": "number"
},
{
"type": "boolean"
}
],
"description": "The record's actual value."
}
},
"required": [
"pointer",
"field",
"value",
"explanation"
],
"type": "object"
}
},
"description": "A free, masked sample of up to 25 rows. Repeating a sample returns the same rows.",
"properties": {
"count": {
"description": "The count the rows were drawn from, rounded as disclosure says.",
"minimum": 0,
"type": "integer"
},
"count_id": {
"description": "Format: a count id: cnt_ followed by 20 base32 characters (A to Z and 2 to 7), such as cnt_7K2PQ4MAXN3R6TBY5WDZ.",
"examples": [
"cnt_7K2PQ4MAXN3R6TBY5WDZ"
],
"pattern": "^cnt_[A-Z2-7]{20}$",
"type": "string"
},
"created_at": {
"format": "date-time",
"type": "string"
},
"dataset_version": {
"description": "The immutable weekly build a count is bound to, such as 2026-W39. The last 52 stay queryable.",
"examples": [
"2026-W39"
],
"pattern": "^[0-9]{4}-W(0[1-9]|[1-4][0-9]|5[0-3])$",
"type": "string"
},
"disclosure": {
"$ref": "#/$defs/Disclosure"
},
"id": {
"description": "Format: a preview id: prv_ followed by a 26 character ULID in upper case Crockford base32, such as prv_01JB4H3M7Q2V7XN3M9R6T1Y5W8.",
"examples": [
"prv_01JB4H3M7Q2V7XN3M9R6T1Y5W8"
],
"pattern": "^prv_[0-7][0-9A-HJKMNP-TV-Z]{25}$",
"type": "string"
},
"masked": {
"const": true,
"type": "boolean"
},
"rows": {
"items": {
"$ref": "#/$defs/PreviewRow"
},
"maxItems": 25,
"type": "array"
},
"seed": {
"description": "The seed the rows came from; the same audience gives the same seed.",
"type": "string"
},
"watermark": {
"description": "The account id watermarked into sample CSVs; null when signed out.",
"type": [
"string",
"null"
]
},
"withheld": {
"anyOf": [
{
"properties": {
"reason": {
"type": "string"
},
"rows": {
"minimum": 0,
"type": "integer"
}
},
"required": [
"rows",
"reason"
],
"type": "object"
},
{
"type": "null"
}
],
"description": "Rows held back: all of them when the count is under 25, or rows whose title fewer than 10 people hold."
}
},
"required": [
"id",
"count_id",
"dataset_version",
"seed",
"count",
"disclosure",
"rows",
"withheld",
"masked",
"watermark",
"created_at"
],
"type": "object"
}
},
{
"description": "Pushes an order's records to a connected CRM such as HubSpot or Salesforce, keyed on mydatahub_record_id, as record operations only: nothing is ever sent to the contacts. dry_run defaults to true and reports what would be created, updated or skipped; a live push needs the user's confirmation or an agent key allowed push_to_crm on that connection, or it returns confirmation-required. Free; it needs pushes:write and a connection made in the app. Show the dry run to the user before a live push. Lawful basis is UK GDPR Article 6(1)(f) legitimate interests; email audiences include corporate subscribers only by default (PECR), so sole traders and ordinary partnerships are left out unless the toggle is changed.",
"inputSchema": {
"additionalProperties": false,
"properties": {
"confirmation_token": {
"description": "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.",
"maxLength": 2000,
"minLength": 16,
"type": "string"
},
"connection_id": {
"description": "Format: a CRM connection id: conn_ followed by a 26 character ULID in upper case Crockford base32, such as conn_01JB3Y2X6Y7Z8A1B2C3D4E5F6G.",
"examples": [
"conn_01JB3Y2X6Y7Z8A1B2C3D4E5F6G"
],
"pattern": "^conn_[0-7][0-9A-HJKMNP-TV-Z]{25}$",
"type": "string"
},
"dry_run": {
"default": true,
"description": "Default true: report what would change without writing. A live push needs approval: a person's confirmation, or an agent key allowed push_to_crm on this connection.",
"type": "boolean"
},
"order_id": {
"description": "The order whose records to push.",
"examples": [
"ord_01JB4N9S3W2X6Y7Z8A1B2C3D4E"
],
"pattern": "^ord_[0-7][0-9A-HJKMNP-TV-Z]{25}$",
"type": "string"
},
"update_existing": {
"default": true,
"description": "Update records already in the CRM, matched on mydatahub_record_id. Default true.",
"type": "boolean"
}
},
"required": [
"order_id",
"connection_id"
],
"type": "object"
},
"name": "push_to_crm",
"outputSchema": {
"$defs": {
"CrmPropertyGroup": {
"description": "The MyDataHub property group written on every pushed record, so licence expiry and suppression are enforced in the CRM by field flags.",
"properties": {
"article14_status": {
"enum": [
"notified",
"publicly_notified_disproportionate_effort",
"pending_within_window"
],
"type": "string"
},
"compliance_receipt_url": {
"format": "uri",
"type": "string"
},
"lawful_basis": {
"enum": [
"legitimate_interests_art6_1_f"
],
"type": "string"
},
"licence_expires_at": {
"anyOf": [
{
"format": "date",
"type": "string"
},
{
"type": "null"
}
]
},
"mydatahub_record_id": {
"description": "The record id: a Salesforce External ID, a HubSpot unique property, a Pipedrive custom field.",
"examples": [
"contact_01JA9X2V7XN3M9R6T1Y5W8ZAK8"
],
"pattern": "^contact_[0-7][0-9A-HJKMNP-TV-Z]{25}$",
"type": "string"
},
"subscriber_class": {
"enum": [
"ltd",
"plc",
"llp",
"scottish_partnership",
"public_body",
"charity_incorporated",
"sole_trader",
"ordinary_partnership",
"unknown"
],
"type": "string"
},
"suppression_status": {
"description": "Kept current: an objection reaching the record updates it in the CRM.",
"enum": [
"none",
"objected_to_emailmovers",
"objected_to_licensee",
"deceased",
"left_company"
],
"type": "string"
},
"tps_ctps_screened_at": {
"anyOf": [
{
"format": "date",
"type": "string"
},
{
"type": "null"
}
]
}
},
"required": [
"mydatahub_record_id",
"licence_expires_at",
"lawful_basis",
"article14_status",
"tps_ctps_screened_at",
"subscriber_class",
"suppression_status",
"compliance_receipt_url"
],
"type": "object"
}
},
"description": "A CRM push or its dry run, such as 4,102 to create and 0 already in your HubSpot.",
"properties": {
"completed_at": {
"anyOf": [
{
"format": "date-time",
"type": "string"
},
{
"type": "null"
}
]
},
"connection_id": {
"description": "Format: a CRM connection id: conn_ followed by a 26 character ULID in upper case Crockford base32, such as conn_01JB3Y2X6Y7Z8A1B2C3D4E5F6G.",
"examples": [
"conn_01JB3Y2X6Y7Z8A1B2C3D4E5F6G"
],
"pattern": "^conn_[0-7][0-9A-HJKMNP-TV-Z]{25}$",
"type": "string"
},
"created_at": {
"format": "date-time",
"type": "string"
},
"dry_run": {
"type": "boolean"
},
"errors": {
"items": {
"properties": {
"message": {
"type": "string"
},
"record_id": {
"type": "string"
}
},
"required": [
"record_id",
"message"
],
"type": "object"
},
"type": "array"
},
"id": {
"description": "Format: a CRM push id: psh_ followed by a 26 character ULID in upper case Crockford base32, such as psh_01JB4NC3W2X6Y7Z8A1B2C3D4E5.",
"examples": [
"psh_01JB4NC3W2X6Y7Z8A1B2C3D4E5"
],
"pattern": "^psh_[0-7][0-9A-HJKMNP-TV-Z]{25}$",
"type": "string"
},
"order_id": {
"description": "Format: an order id: ord_ followed by a 26 character ULID in upper case Crockford base32, such as ord_01JB4N9S3W2X6Y7Z8A1B2C3D4E.",
"examples": [
"ord_01JB4N9S3W2X6Y7Z8A1B2C3D4E"
],
"pattern": "^ord_[0-7][0-9A-HJKMNP-TV-Z]{25}$",
"type": "string"
},
"property_group": {
"description": "The MyDataHub property group written on every record (CrmPropertyGroup).",
"items": {
"enum": [
"mydatahub_record_id",
"licence_expires_at",
"lawful_basis",
"article14_status",
"tps_ctps_screened_at",
"subscriber_class",
"suppression_status",
"compliance_receipt_url"
],
"type": "string"
},
"type": "array"
},
"sample": {
"anyOf": [
{
"$ref": "#/$defs/CrmPropertyGroup"
},
{
"type": "null"
}
],
"description": "On a dry run: the property group the first record would carry."
},
"status": {
"enum": [
"queued",
"running",
"completed",
"partial",
"failed"
],
"type": "string"
},
"summary": {
"properties": {
"already_present": {
"minimum": 0,
"type": "integer"
},
"failed": {
"minimum": 0,
"type": "integer"
},
"skipped": {
"minimum": 0,
"type": "integer"
},
"to_create": {
"minimum": 0,
"type": "integer"
},
"to_update": {
"minimum": 0,
"type": "integer"
}
},
"required": [
"to_create",
"to_update",
"already_present",
"skipped",
"failed"
],
"type": "object"
}
},
"required": [
"id",
"order_id",
"connection_id",
"dry_run",
"status",
"summary",
"property_group",
"sample",
"errors",
"created_at",
"completed_at"
],
"type": "object"
}
},
{
"description": "Creates a machine quote for a count: the records you would receive after removing ones already held and suppressed, the credits and GBP price, the licence, the warranty and any blockers. The quote_id lasts 24 hours and is bound to the dataset version; it is not a human sales quote, which is a 14 day PDF made in the app. Free and needs no account, and nothing is charged. Show the credits and price to the user, then call create_order with the quote_id. Lawful basis is UK GDPR Article 6(1)(f) legitimate interests; email audiences include corporate subscribers only by default (PECR), so sole traders and ordinary partnerships are left out unless the toggle is changed.",
"inputSchema": {
"additionalProperties": false,
"allOf": [
{
"if": {
"properties": {
"dedupe_against": {
"enum": [
"crm",
"previous_orders_and_crm"
]
}
},
"required": [
"dedupe_against"
],
"type": "object"
},
"then": {
"properties": {
"connection_id": true
},
"required": [
"connection_id"
],
"type": "object"
}
},
{
"if": {
"properties": {
"connection_id": true
},
"required": [
"connection_id"
],
"type": "object"
},
"then": {
"properties": {
"dedupe_against": {
"enum": [
"crm",
"previous_orders_and_crm"
]
}
},
"required": [
"dedupe_against"
],
"type": "object"
}
}
],
"description": "What to price: a count, a field set, how many records and the licence. Free, and needs no account.",
"properties": {
"connection_id": {
"description": "The CRM connection to check, only with dedupe_against crm or previous_orders_and_crm.",
"examples": [
"conn_01JB3Y2X6Y7Z8A1B2C3D4E5F6G"
],
"pattern": "^conn_[0-7][0-9A-HJKMNP-TV-Z]{25}$",
"type": "string"
},
"count_id": {
"description": "A count id from POST /v1/counts or count_audience. Either case is accepted; responses use upper case.",
"examples": [
"cnt_7K2PQ4MAXN3R6TBY5WDZ"
],
"pattern": "^cnt_[A-Za-z2-7]{20}$",
"type": "string"
},
"dedupe_against": {
"default": "previous_orders",
"description": "Remove records you already hold: from earlier orders, from a connected CRM, or both. Default previous_orders when signed in. crm and previous_orders_and_crm need connection_id.",
"enum": [
"none",
"previous_orders",
"crm",
"previous_orders_and_crm"
],
"type": "string"
},
"field_set": {
"description": "A field set id from GET /v1/field-sets, such as standard.",
"pattern": "^[a-z0-9]+(_[a-z0-9]+)*$",
"type": "string"
},
"licence": {
"default": "multi_use_12m",
"description": "multi_use_12m (12 month multi-use, every plan) or outright (1.8 credits a record, proposed).",
"enum": [
"multi_use_12m",
"outright"
],
"type": "string"
},
"limit": {
"description": "Records to buy; left out, the whole count.",
"maximum": 1000000,
"minimum": 1,
"type": "integer"
}
},
"required": [
"count_id",
"field_set"
],
"type": "object"
},
"name": "quote_order",
"outputSchema": {
"$defs": {
"Licence": {
"description": "Licence terms as data, on every quote, order, records page and receipt. Records stay usable, pushable and re-downloadable free until reuse_until.",
"properties": {
"permitted_channels": {
"description": "email, telephone and post on standard terms.",
"items": {
"enum": [
"email",
"telephone",
"post"
],
"type": "string"
},
"type": "array"
},
"resale_prohibited": {
"type": "boolean"
},
"reuse_until": {
"anyOf": [
{
"format": "date",
"type": "string"
},
{
"type": "null"
}
],
"description": "Order date plus 12 months; null for outright."
},
"terms_url": {
"description": "Where that version of the Data Licence and Sharing Agreement is published.",
"format": "uri",
"type": "string"
},
"terms_version": {
"description": "The version of the Data Licence and Sharing Agreement the licence is under, such as 1.0.",
"type": "string"
},
"type": {
"description": "multi_use_12m (12 month multi-use, every plan) or outright (1.8 credits a record, proposed).",
"enum": [
"multi_use_12m",
"outright"
],
"type": "string"
},
"warranty_url": {
"format": "uri",
"type": "string"
}
},
"required": [
"type",
"reuse_until",
"resale_prohibited",
"permitted_channels",
"warranty_url",
"terms_version"
],
"type": "object"
},
"Purchase": {
"description": "How to buy the credits the order needs, worked out by one function (cheapestPurchase) everywhere a price is shown. The caller's own, like the balance: read fresh on every read of the quote.",
"properties": {
"cheapest": {
"anyOf": [
{
"pattern": "^[a-z0-9]+(_[a-z0-9]+)*$",
"type": "string"
},
{
"type": "null"
}
],
"description": "The id of the cheapest option; null when nothing needs buying."
},
"credits_to_buy": {
"description": "credits_required less the balance: all of it when signed out, 0 when the balance covers the order.",
"minimum": 0,
"type": "integer"
},
"gbp_ex_vat": {
"description": "What the cheapest option costs, excluding VAT; 0 when nothing needs buying.",
"minimum": 0,
"type": "number"
},
"options": {
"description": "Cheapest first: the per-contact scale, and the credit pack (with any rest at the scale) when it is on sale. At the same price, the option that buys more credits comes first.",
"items": {
"$ref": "#/$defs/PurchaseOption"
},
"type": "array"
}
},
"required": [
"credits_to_buy",
"cheapest",
"gbp_ex_vat",
"options"
],
"type": "object"
},
"PurchaseLine": {
"description": "One thing bought: credit packs, or credits at the scale.",
"properties": {
"credits": {
"minimum": 0,
"type": "integer"
},
"gbp_ex_vat": {
"description": "Pounds sterling excluding VAT, to two decimal places.",
"minimum": 0,
"type": "number"
},
"id": {
"description": "A credit pack id, or per_contact_scale.",
"pattern": "^[a-z0-9]+(_[a-z0-9]+)*$",
"type": "string"
},
"quantity": {
"description": "Credit packs bought, or credits bought at the scale.",
"minimum": 0,
"type": "integer"
}
},
"required": [
"id",
"quantity",
"credits",
"gbp_ex_vat"
],
"type": "object"
},
"PurchaseOption": {
"description": "One way to buy the credits the order needs.",
"properties": {
"credits": {
"description": "Credits the option buys.",
"minimum": 0,
"type": "integer"
},
"credits_left_over": {
"description": "Credits that stay in the balance after the order.",
"minimum": 0,
"type": "integer"
},
"gbp_ex_vat": {
"description": "Pounds sterling excluding VAT, to two decimal places.",
"minimum": 0,
"type": "number"
},
"id": {
"description": "per_contact_scale, or the id of the credit pack the option is built on (with any rest at the scale). The same between quotes, so a choice survives a fresh quote.",
"pattern": "^[a-z0-9]+(_[a-z0-9]+)*$",
"type": "string"
},
"label": {
"description": "Such as 12,000 records at 22p.",
"type": "string"
},
"lines": {
"items": {
"$ref": "#/$defs/PurchaseLine"
},
"type": "array"
}
},
"required": [
"id",
"label",
"credits",
"gbp_ex_vat",
"credits_left_over",
"lines"
],
"type": "object"
},
"QuoteBlocker": {
"description": "Something that stops create_order until it is fixed.",
"properties": {
"code": {
"enum": [
"insufficient_credits",
"account_required",
"agent_budget_exceeded",
"dataset_unavailable",
"count_expired"
],
"type": "string"
},
"detail": {
"type": "string"
},
"top_up_url": {
"format": "uri",
"type": "string"
}
},
"required": [
"code",
"detail"
],
"type": "object"
},
"QuoteSignature": {
"description": "The signature over the machine quote's price, so an agent can hand the quote to another agent and both can check it. Verify it with the key at jwks_url.",
"properties": {
"alg": {
"const": "ES256",
"type": "string"
},
"jwks_url": {
"format": "uri",
"type": "string"
},
"jws": {
"description": "A compact JWS whose payload is the quote's id, organisation_id, count_id, dataset_version, records, credits_required, gbp_ex_vat, licence, expires_at.",
"pattern": "^[A-Za-z0-9_-]+\\.[A-Za-z0-9_-]+\\.[A-Za-z0-9_-]+$",
"type": "string"
},
"kid": {
"description": "The signing key id in jwks_url.",
"type": "string"
}
},
"required": [
"alg",
"kid",
"jwks_url",
"jws"
],
"type": "object"
},
"Warranty": {
"allOf": [
{
"else": {
"not": {
"properties": {
"threshold_percent": true
},
"required": [
"threshold_percent"
],
"type": "object"
},
"type": "object"
},
"if": {
"properties": {
"policy": {
"const": "replace_over_threshold_hard_bounce"
}
},
"required": [
"policy"
],
"type": "object"
},
"then": {
"properties": {
"threshold_percent": true
},
"required": [
"threshold_percent"
],
"type": "object"
}
}
],
"description": "The bounce warranty that covers delivered records, with the threshold it was issued under.",
"properties": {
"policy": {
"description": "replace_over_threshold_hard_bounce is the current policy: records are replaced when hard bounces exceed threshold_percent of an order. replace_any_hard_bounce_30d is proposed and not yet in force. The current policy's id replaced one that named the threshold, a change to this public enum made before v2 went live.",
"enum": [
"replace_over_threshold_hard_bounce",
"replace_any_hard_bounce_30d"
],
"type": "string"
},
"threshold_percent": {
"description": "replace_over_threshold_hard_bounce only, and required there: the share of an order, in percent, that hard bounces must exceed before records are replaced. It is the threshold the document was issued under.",
"maximum": 100,
"minimum": 0,
"type": "number"
},
"url": {
"format": "uri",
"type": "string"
}
},
"required": [
"policy",
"url"
],
"type": "object"
}
},
"description": "A machine quote: a signed price, valid 24 hours, bound to a dataset version and an organisation. create_order needs its id plus a human confirmation or a pre-authorised agent key; a confirmed flag set by a model is never consent.",
"properties": {
"balance_after": {
"description": "credits_available less credits_required; negative means a top-up is needed; null when signed out.",
"type": [
"number",
"null"
]
},
"blockers": {
"items": {
"$ref": "#/$defs/QuoteBlocker"
},
"type": "array"
},
"count_id": {
"description": "The count the quote was priced from.",
"examples": [
"cnt_7K2PQ4MAXN3R6TBY5WDZ"
],
"pattern": "^cnt_[A-Z2-7]{20}$",
"type": "string"
},
"created_at": {
"format": "date-time",
"type": "string"
},
"credits_available": {
"anyOf": [
{
"description": "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).",
"minimum": 0,
"type": "number"
},
{
"type": "null"
}
],
"description": "Your balance; null when signed out."
},
"credits_per_record": {
"description": "1 for a complete UK record; 1.8 outright (proposed).",
"minimum": 0,
"type": "number"
},
"credits_required": {
"description": "records times credits_per_record (creditsFor).",
"minimum": 0,
"type": "number"
},
"dataset": {
"description": "The dataset an audience draws from. uk_contacts is live; ie_contacts and global_contacts are listed but not yet served.",
"enum": [
"uk_contacts",
"ie_contacts",
"global_contacts"
],
"type": "string"
},
"dataset_version": {
"description": "The immutable weekly build a count is bound to, such as 2026-W39. The last 52 stay queryable.",
"examples": [
"2026-W39"
],
"pattern": "^[0-9]{4}-W(0[1-9]|[1-4][0-9]|5[0-3])$",
"type": "string"
},
"expires_at": {
"description": "24 hours after creation.",
"format": "date-time",
"type": "string"
},
"field_set": {
"pattern": "^[a-z0-9]+(_[a-z0-9]+)*$",
"type": "string"
},
"gbp_ex_vat": {
"description": "What credits_required cost bought the cheapest way, at the per-contact scale or with credit packs, excluding VAT. The same for every caller; purchase says what this caller needs to buy.",
"minimum": 0,
"type": "number"
},
"id": {
"description": "Format: a quote id: qte_ followed by a 26 character ULID in upper case Crockford base32, such as qte_01JB4M2R6T1Y5W8ZAK8Q2V7XN3.",
"examples": [
"qte_01JB4M2R6T1Y5W8ZAK8Q2V7XN3"
],
"pattern": "^qte_[0-7][0-9A-HJKMNP-TV-Z]{25}$",
"type": "string"
},
"kind": {
"const": "machine",
"type": "string"
},
"licence": {
"$ref": "#/$defs/Licence"
},
"organisation_id": {
"anyOf": [
{
"description": "Format: an organisation id: org_ followed by a 26 character ULID in upper case Crockford base32, such as org_01JA0Q2V7XN3M9R6T1Y5W8ZAK8.",
"examples": [
"org_01JA0Q2V7XN3M9R6T1Y5W8ZAK8"
],
"pattern": "^org_[0-7][0-9A-HJKMNP-TV-Z]{25}$",
"type": "string"
},
{
"type": "null"
}
],
"description": "The organisation the quote belongs to; create_order settles it only there. null for a quote made without an account, which the first organisation to confirm it takes."
},
"purchase": {
"$ref": "#/$defs/Purchase"
},
"records": {
"description": "Records after overlap and suppression; what you would receive.",
"minimum": 0,
"type": "integer"
},
"removed": {
"description": "Records left out and never charged.",
"properties": {
"already_held": {
"minimum": 0,
"type": "integer"
},
"suppressed": {
"minimum": 0,
"type": "integer"
}
},
"required": [
"already_held",
"suppressed"
],
"type": "object"
},
"signature": {
"$ref": "#/$defs/QuoteSignature"
},
"warranty": {
"$ref": "#/$defs/Warranty"
}
},
"required": [
"id",
"kind",
"organisation_id",
"count_id",
"dataset_version",
"records",
"removed",
"credits_per_record",
"credits_required",
"credits_available",
"balance_after",
"gbp_ex_vat",
"purchase",
"licence",
"warranty",
"expires_at",
"blockers",
"signature"
],
"type": "object"
}
},
{
"description": "Records an objection to direct marketing for one record, by record id or email hash. Scope licensee suppresses it for your organisation at once; scope emailmovers suppresses it database-wide within one working day and tells every licensee holding it. Free; it needs suppressions:write, and repeating the same objection returns the same suppression. Call it whenever a contact objects, in any channel. Lawful basis is UK GDPR Article 6(1)(f) legitimate interests; email audiences include corporate subscribers only by default (PECR), so sole traders and ordinary partnerships are left out unless the toggle is changed.",
"inputSchema": {
"additionalProperties": false,
"description": "An objection to direct marketing, to record and propagate: exactly one of record_id or email_sha256.",
"oneOf": [
{
"properties": {
"record_id": true
},
"required": [
"record_id"
],
"type": "object"
},
{
"properties": {
"email_sha256": true
},
"required": [
"email_sha256"
],
"type": "object"
}
],
"properties": {
"channel": {
"enum": [
"email",
"telephone",
"post",
"web_form",
"other"
],
"type": "string"
},
"email_sha256": {
"description": "SHA-256 of the trimmed, lower cased address, when the record id is not known.",
"pattern": "^[0-9a-f]{64}$",
"type": "string"
},
"note": {
"maxLength": 2000,
"type": "string"
},
"received_at": {
"description": "RFC 3339 date and time, with Z or an offset such as +01:00.",
"format": "date-time",
"type": "string"
},
"record_id": {
"description": "Format: a contact id: contact_ followed by a 26 character ULID in upper case Crockford base32, such as contact_01JA9X2V7XN3M9R6T1Y5W8ZAK8.",
"examples": [
"contact_01JA9X2V7XN3M9R6T1Y5W8ZAK8"
],
"pattern": "^contact_[0-7][0-9A-HJKMNP-TV-Z]{25}$",
"type": "string"
},
"scope": {
"description": "licensee suppresses the record for your organisation at once; emailmovers suppresses it database-wide within one working day.",
"enum": [
"licensee",
"emailmovers"
],
"type": "string"
}
},
"required": [
"channel",
"received_at",
"scope"
],
"type": "object"
},
"name": "report_objection",
"outputSchema": {
"description": "The suppression an objection created. Database-wide objections reach every licensee holding the record through the suppression.created webhook.",
"properties": {
"effective_by": {
"format": "date-time",
"type": "string"
},
"record_id": {
"anyOf": [
{
"description": "Format: a contact id: contact_ followed by a 26 character ULID in upper case Crockford base32, such as contact_01JA9X2V7XN3M9R6T1Y5W8ZAK8.",
"examples": [
"contact_01JA9X2V7XN3M9R6T1Y5W8ZAK8"
],
"pattern": "^contact_[0-7][0-9A-HJKMNP-TV-Z]{25}$",
"type": "string"
},
{
"type": "null"
}
]
},
"scope": {
"enum": [
"licensee",
"emailmovers"
],
"type": "string"
},
"status": {
"description": "suppressed now, or pending until the database-wide overlay applies.",
"enum": [
"suppressed",
"pending"
],
"type": "string"
},
"suppressed_at": {
"anyOf": [
{
"format": "date-time",
"type": "string"
},
{
"type": "null"
}
]
},
"suppression_id": {
"description": "The list the record now sits on.",
"examples": [
"sup_01JB4H7Q2V7XN3M9R6T1Y5W8ZA"
],
"pattern": "^sup_[0-7][0-9A-HJKMNP-TV-Z]{25}$",
"type": "string"
}
},
"required": [
"suppression_id",
"record_id",
"scope",
"status",
"suppressed_at",
"effective_by"
],
"type": "object"
}
},
{
"description": "Turns free text such as 20 miles of Leeds, Yorkshire or LS1 into region, county, town, postcode or radius filters, each with a count and a ready filter. Ambiguous places come back as candidates with a question, so ask the user which they meant rather than choosing. Free and needs no account, though a radius under 5 miles needs an account. Add the chosen filter to the audience, then call count_audience. Lawful basis is UK GDPR Article 6(1)(f) legitimate interests; email audiences include corporate subscribers only by default (PECR), so sole traders and ordinary partnerships are left out unless the toggle is changed.",
"inputSchema": {
"additionalProperties": false,
"description": "A place to resolve into geography filters.",
"properties": {
"dataset": {
"description": "The dataset an audience draws from. uk_contacts is live; ie_contacts and global_contacts are listed but not yet served.",
"enum": [
"uk_contacts",
"ie_contacts",
"global_contacts"
],
"type": "string"
},
"radius_miles": {
"maximum": 100,
"minimum": 1,
"type": "number"
},
"text": {
"description": "Free text such as \"20 miles of Leeds\", \"Yorkshire\" or \"SW1\".",
"maxLength": 200,
"minLength": 1,
"type": "string"
}
},
"required": [
"text"
],
"type": "object"
},
"name": "resolve_location",
"outputSchema": {
"$defs": {
"BetweenFilter": {
"additionalProperties": false,
"description": "The field lies from one value to another inclusive, over the field's order.",
"examples": [
{
"field": "company.employee_band",
"from": "10-19",
"op": "between",
"to": "200-349"
}
],
"properties": {
"field": {
"enum": [
"company.employee_band",
"company.turnover_band",
"company.fleet_band",
"contact.job_level_rank",
"email.deliverability_score"
],
"type": "string"
},
"from": {
"anyOf": [
{
"maxLength": 200,
"minLength": 1,
"type": "string"
},
{
"type": "number"
}
],
"description": "A band code or a number from the field's order."
},
"op": {
"const": "between",
"type": "string"
},
"to": {
"anyOf": [
{
"maxLength": 200,
"minLength": 1,
"type": "string"
},
{
"type": "number"
}
],
"description": "A band code or a number from the field's order."
}
},
"required": [
"field",
"op",
"from",
"to"
],
"type": "object"
},
"CellCount": {
"anyOf": [
{
"minimum": 0,
"type": "integer"
},
{
"const": "under 10",
"type": "string"
},
{
"const": "suppressed",
"type": "string"
}
],
"description": "A whole number; \"under 10\" when disclosure control withholds a small cell; or \"suppressed\" when secondary suppression hides a cell of 10 or more in a cross-tab or breakdown, so totals cannot be differenced. Anonymous and trial callers see cells rounded to the nearest 5.",
"examples": [
4120,
"under 10",
"suppressed"
]
},
"Disclosure": {
"description": "Whether these numbers are exact or protected: \"under 10\" cells, rounding to 5 and secondary suppression for anonymous and trial callers.",
"properties": {
"level": {
"description": "exact for authenticated paid callers; rounded for anonymous and trial callers, whose counts under 100 and every cell are rounded to the nearest 5.",
"enum": [
"exact",
"rounded"
],
"type": "string"
},
"notes": {
"items": {
"type": "string"
},
"type": "array"
},
"rounded_to": {
"anyOf": [
{
"exclusiveMinimum": 0,
"type": "integer"
},
{
"type": "null"
}
],
"description": "5 when numbers are rounded; null when they are exact."
},
"secondary_suppression": {
"description": "True when cross-tab or breakdown cells of 10 or more were hidden as \"suppressed\" so totals cannot be differenced.",
"type": "boolean"
}
},
"required": [
"level",
"rounded_to",
"secondary_suppression",
"notes"
],
"type": "object"
},
"Filter": {
"description": "One criterion: a field from GET /v1/catalogue/filters, an operator and its operands. Exclusions nest under not.",
"oneOf": [
{
"$ref": "#/$defs/InFilter"
},
{
"$ref": "#/$defs/BetweenFilter"
},
{
"$ref": "#/$defs/GteFilter"
},
{
"$ref": "#/$defs/LteFilter"
},
{
"$ref": "#/$defs/MatchesFilter"
},
{
"$ref": "#/$defs/WithinRadiusFilter"
},
{
"$ref": "#/$defs/InListFilter"
},
{
"$ref": "#/$defs/SinceFilter"
}
]
},
"GteFilter": {
"additionalProperties": false,
"description": "The field is at or after the value in its order: for bands, the band and every larger one.",
"examples": [
{
"field": "company.employee_band",
"op": "gte",
"value": "50-99"
}
],
"properties": {
"field": {
"enum": [
"company.employee_band",
"company.turnover_band",
"company.fleet_band",
"contact.job_level_rank",
"email.deliverability_score"
],
"type": "string"
},
"op": {
"const": "gte",
"type": "string"
},
"value": {
"anyOf": [
{
"maxLength": 200,
"minLength": 1,
"type": "string"
},
{
"type": "number"
}
],
"description": "A band code or a number from the field's order."
}
},
"required": [
"field",
"op",
"value"
],
"type": "object"
},
"InFilter": {
"additionalProperties": false,
"description": "The field holds one of the listed codes.",
"examples": [
{
"field": "company.sic_2007",
"op": "in",
"values": [
"C"
]
}
],
"properties": {
"field": {
"enum": [
"company.sic_2007",
"company.business_class",
"company.employee_band",
"company.turnover_band",
"company.fleet_band",
"company.type",
"company.status",
"company.subscriber_class",
"company.companies_house_number",
"site.region",
"site.county",
"site.town",
"site.postcode",
"contact.title_family",
"contact.job_function",
"contact.job_level_rank",
"contact.premium",
"email.exists",
"email.type",
"phone.exists",
"phone.tps_ctps_status"
],
"type": "string"
},
"op": {
"const": "in",
"type": "string"
},
"values": {
"items": {
"anyOf": [
{
"maxLength": 200,
"minLength": 1,
"type": "string"
},
{
"type": "number"
},
{
"type": "boolean"
}
],
"description": "A code, a rank or a boolean, as the field's catalogue lists it."
},
"maxItems": 10000,
"minItems": 1,
"type": "array"
}
},
"required": [
"field",
"op",
"values"
],
"type": "object"
},
"InListFilter": {
"additionalProperties": false,
"description": "The record's hashed email, domain, phone, company number or title term is on a suppression list. Usually nested under not; each list reports the records it removed.",
"examples": [
{
"field": "email.address_sha256",
"list_id": "sup_01JB4H7Q2V7XN3M9R6T1Y5W8ZA",
"op": "in_list"
}
],
"properties": {
"field": {
"enum": [
"company.companies_house_number",
"contact.title",
"email.address_sha256",
"email.domain_sha256",
"phone.e164_sha256"
],
"type": "string"
},
"list_id": {
"description": "Format: a suppression list id: sup_ followed by a 26 character ULID in upper case Crockford base32, such as sup_01JB4H7Q2V7XN3M9R6T1Y5W8ZA.",
"examples": [
"sup_01JB4H7Q2V7XN3M9R6T1Y5W8ZA"
],
"pattern": "^sup_[0-7][0-9A-HJKMNP-TV-Z]{25}$",
"type": "string"
},
"op": {
"const": "in_list",
"type": "string"
}
},
"required": [
"field",
"op",
"list_id"
],
"type": "object"
},
"LocationCandidate": {
"description": "One reading of the text.",
"properties": {
"centre": {
"anyOf": [
{
"properties": {
"lat": {
"type": "number"
},
"lon": {
"type": "number"
}
},
"required": [
"lat",
"lon"
],
"type": "object"
},
{
"type": "null"
}
]
},
"code": {
"description": "The filter code, or the ONS code for a centre.",
"type": "string"
},
"contacts": {
"$ref": "#/$defs/CellCount"
},
"filter": {
"$ref": "#/$defs/Filter",
"description": "A ready filter for this candidate."
},
"kind": {
"enum": [
"region",
"county",
"town",
"local_authority",
"postcode_area",
"postcode_district",
"postcode_sector",
"postcode_unit",
"geography_set",
"radius"
],
"type": "string"
},
"label": {
"type": "string"
}
},
"required": [
"kind",
"code",
"label",
"contacts",
"centre",
"filter"
],
"type": "object"
},
"LteFilter": {
"additionalProperties": false,
"description": "The field is at or before the value in its order. Rank 1 is the most senior, so Director and above is contact.job_level_rank lte 6.",
"examples": [
{
"field": "contact.job_level_rank",
"op": "lte",
"value": 6
}
],
"properties": {
"field": {
"enum": [
"company.employee_band",
"company.turnover_band",
"company.fleet_band",
"contact.job_level_rank",
"contact.company_contact_rank",
"email.deliverability_score"
],
"type": "string"
},
"op": {
"const": "lte",
"type": "string"
},
"value": {
"anyOf": [
{
"maxLength": 200,
"minLength": 1,
"type": "string"
},
{
"type": "number"
}
],
"description": "A band code or a number from the field's order."
}
},
"required": [
"field",
"op",
"value"
],
"type": "object"
},
"MatchesFilter": {
"additionalProperties": false,
"allOf": [
{
"if": {
"properties": {
"mode": {
"const": "exact"
}
},
"required": [
"mode"
],
"type": "object"
},
"then": {
"properties": {
"exclude_terms": {
"maxItems": 0,
"type": "array"
},
"expand": {
"maxItems": 0,
"type": "array"
}
},
"type": "object"
}
}
],
"description": "Job title keyword match. mode contains (the default) or starts_with expands each term with the expansion sets; mode exact matches verbatim titles. Every expanded term is returned with the count.",
"examples": [
{
"expand": [
"plural_singular",
"department_synonyms",
"ampersand_and",
"abbreviations"
],
"field": "contact.title",
"mode": "contains",
"op": "matches",
"terms": [
"marketing manager"
]
}
],
"properties": {
"exclude_terms": {
"description": "Expanded terms removed by hand. Kept in the definition so the count stays reproducible when the title dictionary changes.",
"items": {
"maxLength": 200,
"minLength": 1,
"type": "string"
},
"maxItems": 500,
"type": "array"
},
"expand": {
"description": "Expansion sets to apply, each once: plural_singular, department_synonyms, ampersand_and, abbreviations, permutations. Left out, the first four apply; an empty list applies none. Not used with mode exact.",
"items": {
"enum": [
"plural_singular",
"department_synonyms",
"ampersand_and",
"abbreviations",
"permutations"
],
"type": "string"
},
"maxItems": 5,
"type": "array",
"uniqueItems": true
},
"field": {
"enum": [
"contact.title"
],
"type": "string"
},
"mode": {
"description": "contains (the default) matches titles containing a term, starts_with matches titles beginning with it, exact takes verbatim titles with no expansion.",
"enum": [
"contains",
"starts_with",
"exact"
],
"type": "string"
},
"op": {
"const": "matches",
"type": "string"
},
"terms": {
"items": {
"maxLength": 200,
"minLength": 1,
"type": "string"
},
"maxItems": 500,
"minItems": 1,
"type": "array"
}
},
"required": [
"field",
"op",
"terms"
],
"type": "object"
},
"PlaceCentre": {
"additionalProperties": false,
"description": "A named place. Ambiguous names come back from resolve_location as candidates, never a silent choice.",
"properties": {
"code": {
"description": "The ONS geography code of the chosen candidate when resolve_location found more than one, such as E08000035 for the Leeds district.",
"maxLength": 20,
"minLength": 1,
"type": "string"
},
"place": {
"description": "A place name, resolved with resolve_location, such as Leeds.",
"maxLength": 100,
"minLength": 1,
"type": "string"
}
},
"required": [
"place"
],
"type": "object"
},
"PointCentre": {
"additionalProperties": false,
"description": "A latitude and longitude in WGS84 degrees.",
"properties": {
"lat": {
"maximum": 61,
"minimum": 49,
"type": "number"
},
"lon": {
"maximum": 2,
"minimum": -9,
"type": "number"
}
},
"required": [
"lat",
"lon"
],
"type": "object"
},
"PostcodeCentre": {
"additionalProperties": false,
"description": "A postcode centroid from ONSPD.",
"properties": {
"postcode": {
"description": "The centroid of a postcode unit, sector, district or area, such as LS1 4AP.",
"pattern": "^[A-Za-z]{1,2}([0-9][0-9A-Za-z]?( [0-9]([A-Za-z]{2})?| ?[0-9][A-Za-z]{2})?)?$",
"type": "string"
}
},
"required": [
"postcode"
],
"type": "object"
},
"RadiusCentre": {
"anyOf": [
{
"$ref": "#/$defs/PlaceCentre"
},
{
"$ref": "#/$defs/PostcodeCentre"
},
{
"$ref": "#/$defs/PointCentre"
}
],
"description": "The centre of a radius: a place, a postcode or a latitude and longitude."
},
"SinceFilter": {
"additionalProperties": false,
"description": "Within the last N days: a date field, or a Companies House signal of the listed types on signal.type.",
"examples": [
{
"days": 90,
"field": "signal.type",
"op": "since",
"values": [
"company.incorporated"
]
}
],
"properties": {
"days": {
"maximum": 3650,
"minimum": 1,
"type": "integer"
},
"field": {
"enum": [
"contact.last_validated_at",
"email.last_verified_at",
"signal.type",
"signal.observed_at"
],
"type": "string"
},
"op": {
"const": "since",
"type": "string"
},
"values": {
"description": "For signal.type only: the signal types to look for, such as company.incorporated.",
"items": {
"maxLength": 200,
"minLength": 1,
"type": "string"
},
"maxItems": 10000,
"minItems": 1,
"type": "array"
}
},
"required": [
"field",
"op",
"days"
],
"type": "object"
},
"WithinRadiusFilter": {
"additionalProperties": false,
"description": "Sites within radius_miles of the centre. The count reports the centroid used and the postcodes matched.",
"examples": [
{
"centre": {
"place": "Leeds"
},
"field": "site.location",
"op": "within_radius",
"radius_miles": 20
}
],
"properties": {
"centre": {
"$ref": "#/$defs/RadiusCentre"
},
"field": {
"enum": [
"site.location"
],
"type": "string"
},
"op": {
"const": "within_radius",
"type": "string"
},
"radius_miles": {
"description": "Radius in miles, 1 to 100. Under 5 miles needs an account.",
"maximum": 100,
"minimum": 1,
"type": "number"
}
},
"required": [
"field",
"op",
"centre",
"radius_miles"
],
"type": "object"
}
},
"description": "Candidates for a place. Ambiguous names come back as candidates, never a silent choice.",
"properties": {
"ambiguous": {
"description": "True when more than one candidate fits; ask the person which they meant.",
"type": "boolean"
},
"candidates": {
"items": {
"$ref": "#/$defs/LocationCandidate"
},
"type": "array"
},
"disclosure": {
"$ref": "#/$defs/Disclosure"
},
"question": {
"type": [
"string",
"null"
]
},
"text": {
"type": "string"
}
},
"required": [
"text",
"ambiguous",
"question",
"candidates",
"disclosure"
],
"type": "object"
}
},
{
"description": "Saves an audience definition under a name, shared across the organisation, or updates a saved one when audience_id is given. Use it when the user wants to keep, share or recount a list later; saving is free and needs audiences:write. Repeating the same call returns the same saved audience. Call list_audiences to find it again, or count_audience with its aud_ id. Lawful basis is UK GDPR Article 6(1)(f) legitimate interests; email audiences include corporate subscribers only by default (PECR), so sole traders and ordinary partnerships are left out unless the toggle is changed.",
"inputSchema": {
"$defs": {
"AllGroup": {
"additionalProperties": false,
"description": "AND: every node inside must match.",
"properties": {
"all": {
"items": {
"$ref": "#/$defs/WhereNode"
},
"minItems": 1,
"type": "array"
}
},
"required": [
"all"
],
"type": "object"
},
"AnyGroup": {
"additionalProperties": false,
"description": "OR: at least one node inside must match.",
"properties": {
"any": {
"items": {
"$ref": "#/$defs/WhereNode"
},
"minItems": 1,
"type": "array"
}
},
"required": [
"any"
],
"type": "object"
},
"Audience": {
"additionalProperties": false,
"description": "Who you want, as filters grouped by entity (company., site., contact., email., phone., signal.). The server fills its defaults (active companies, named emails, corporate subscribers, the current dataset_version) and returns the effective definition with every count.",
"properties": {
"dataset": {
"description": "The dataset an audience draws from. uk_contacts is live; ie_contacts and global_contacts are listed but not yet served.",
"enum": [
"uk_contacts",
"ie_contacts",
"global_contacts"
],
"type": "string"
},
"dataset_version": {
"description": "The weekly build to count against, such as 2026-W39. Left out, the current version is filled in and returned.",
"examples": [
"2026-W39"
],
"pattern": "^[0-9]{4}-W(0[1-9]|[1-4][0-9]|5[0-3])$",
"type": "string"
},
"dedupe": {
"description": "none keeps every matching contact, one_per_company keeps one contact per company, one_per_site keeps one per site. Default none.",
"enum": [
"none",
"one_per_company",
"one_per_site"
],
"type": "string"
},
"email_policy": {
"$ref": "#/$defs/EmailPolicy"
},
"schema": {
"const": "mydatahub.audience/1",
"description": "The definition's namespace and version. Older versions are upgraded by a pure function.",
"type": "string"
},
"where": {
"$ref": "#/$defs/WhereNode",
"description": "The filters. Left out, the audience is the whole dataset after the defaults."
}
},
"required": [
"schema"
],
"title": "MyDataHub audience definition (mydatahub.audience/1)",
"type": "object"
},
"BetweenFilter": {
"additionalProperties": false,
"description": "The field lies from one value to another inclusive, over the field's order.",
"examples": [
{
"field": "company.employee_band",
"from": "10-19",
"op": "between",
"to": "200-349"
}
],
"properties": {
"field": {
"enum": [
"company.employee_band",
"company.turnover_band",
"company.fleet_band",
"contact.job_level_rank",
"email.deliverability_score"
],
"type": "string"
},
"from": {
"anyOf": [
{
"maxLength": 200,
"minLength": 1,
"type": "string"
},
{
"type": "number"
}
],
"description": "A band code or a number from the field's order."
},
"op": {
"const": "between",
"type": "string"
},
"to": {
"anyOf": [
{
"maxLength": 200,
"minLength": 1,
"type": "string"
},
{
"type": "number"
}
],
"description": "A band code or a number from the field's order."
}
},
"required": [
"field",
"op",
"from",
"to"
],
"type": "object"
},
"BundleNode": {
"additionalProperties": false,
"description": "A title bundle, resolved to its filters in the effective definition: sdm (senior decision makers), manager_and_above (managers and above), owner_managed (owner managed).",
"properties": {
"bundle": {
"enum": [
"sdm",
"manager_and_above",
"owner_managed"
],
"type": "string"
}
},
"required": [
"bundle"
],
"type": "object"
},
"EmailPolicy": {
"additionalProperties": false,
"description": "Email quality floor. Defaults: min_deliverability_score 70, allow_catch_all false.",
"properties": {
"allow_catch_all": {
"description": "Whether catch-all addresses count. Default false.",
"type": "boolean"
},
"min_deliverability_score": {
"description": "Lowest deliverability score counted, 0 to 100. Default 70.",
"maximum": 100,
"minimum": 0,
"type": "integer"
}
},
"type": "object"
},
"Filter": {
"description": "One criterion: a field from GET /v1/catalogue/filters, an operator and its operands. Exclusions nest under not.",
"oneOf": [
{
"$ref": "#/$defs/InFilter"
},
{
"$ref": "#/$defs/BetweenFilter"
},
{
"$ref": "#/$defs/GteFilter"
},
{
"$ref": "#/$defs/LteFilter"
},
{
"$ref": "#/$defs/MatchesFilter"
},
{
"$ref": "#/$defs/WithinRadiusFilter"
},
{
"$ref": "#/$defs/InListFilter"
},
{
"$ref": "#/$defs/SinceFilter"
}
]
},
"GteFilter": {
"additionalProperties": false,
"description": "The field is at or after the value in its order: for bands, the band and every larger one.",
"examples": [
{
"field": "company.employee_band",
"op": "gte",
"value": "50-99"
}
],
"properties": {
"field": {
"enum": [
"company.employee_band",
"company.turnover_band",
"company.fleet_band",
"contact.job_level_rank",
"email.deliverability_score"
],
"type": "string"
},
"op": {
"const": "gte",
"type": "string"
},
"value": {
"anyOf": [
{
"maxLength": 200,
"minLength": 1,
"type": "string"
},
{
"type": "number"
}
],
"description": "A band code or a number from the field's order."
}
},
"required": [
"field",
"op",
"value"
],
"type": "object"
},
"InFilter": {
"additionalProperties": false,
"description": "The field holds one of the listed codes.",
"examples": [
{
"field": "company.sic_2007",
"op": "in",
"values": [
"C"
]
}
],
"properties": {
"field": {
"enum": [
"company.sic_2007",
"company.business_class",
"company.employee_band",
"company.turnover_band",
"company.fleet_band",
"company.type",
"company.status",
"company.subscriber_class",
"company.companies_house_number",
"site.region",
"site.county",
"site.town",
"site.postcode",
"contact.title_family",
"contact.job_function",
"contact.job_level_rank",
"contact.premium",
"email.exists",
"email.type",
"phone.exists",
"phone.tps_ctps_status"
],
"type": "string"
},
"op": {
"const": "in",
"type": "string"
},
"values": {
"items": {
"anyOf": [
{
"maxLength": 200,
"minLength": 1,
"type": "string"
},
{
"type": "number"
},
{
"type": "boolean"
}
],
"description": "A code, a rank or a boolean, as the field's catalogue lists it."
},
"maxItems": 10000,
"minItems": 1,
"type": "array"
}
},
"required": [
"field",
"op",
"values"
],
"type": "object"
},
"InListFilter": {
"additionalProperties": false,
"description": "The record's hashed email, domain, phone, company number or title term is on a suppression list. Usually nested under not; each list reports the records it removed.",
"examples": [
{
"field": "email.address_sha256",
"list_id": "sup_01JB4H7Q2V7XN3M9R6T1Y5W8ZA",
"op": "in_list"
}
],
"properties": {
"field": {
"enum": [
"company.companies_house_number",
"contact.title",
"email.address_sha256",
"email.domain_sha256",
"phone.e164_sha256"
],
"type": "string"
},
"list_id": {
"description": "Format: a suppression list id: sup_ followed by a 26 character ULID in upper case Crockford base32, such as sup_01JB4H7Q2V7XN3M9R6T1Y5W8ZA.",
"examples": [
"sup_01JB4H7Q2V7XN3M9R6T1Y5W8ZA"
],
"pattern": "^sup_[0-7][0-9A-HJKMNP-TV-Z]{25}$",
"type": "string"
},
"op": {
"const": "in_list",
"type": "string"
}
},
"required": [
"field",
"op",
"list_id"
],
"type": "object"
},
"LteFilter": {
"additionalProperties": false,
"description": "The field is at or before the value in its order. Rank 1 is the most senior, so Director and above is contact.job_level_rank lte 6.",
"examples": [
{
"field": "contact.job_level_rank",
"op": "lte",
"value": 6
}
],
"properties": {
"field": {
"enum": [
"company.employee_band",
"company.turnover_band",
"company.fleet_band",
"contact.job_level_rank",
"contact.company_contact_rank",
"email.deliverability_score"
],
"type": "string"
},
"op": {
"const": "lte",
"type": "string"
},
"value": {
"anyOf": [
{
"maxLength": 200,
"minLength": 1,
"type": "string"
},
{
"type": "number"
}
],
"description": "A band code or a number from the field's order."
}
},
"required": [
"field",
"op",
"value"
],
"type": "object"
},
"MatchesFilter": {
"additionalProperties": false,
"allOf": [
{
"if": {
"properties": {
"mode": {
"const": "exact"
}
},
"required": [
"mode"
],
"type": "object"
},
"then": {
"properties": {
"exclude_terms": {
"maxItems": 0,
"type": "array"
},
"expand": {
"maxItems": 0,
"type": "array"
}
},
"type": "object"
}
}
],
"description": "Job title keyword match. mode contains (the default) or starts_with expands each term with the expansion sets; mode exact matches verbatim titles. Every expanded term is returned with the count.",
"examples": [
{
"expand": [
"plural_singular",
"department_synonyms",
"ampersand_and",
"abbreviations"
],
"field": "contact.title",
"mode": "contains",
"op": "matches",
"terms": [
"marketing manager"
]
}
],
"properties": {
"exclude_terms": {
"description": "Expanded terms removed by hand. Kept in the definition so the count stays reproducible when the title dictionary changes.",
"items": {
"maxLength": 200,
"minLength": 1,
"type": "string"
},
"maxItems": 500,
"type": "array"
},
"expand": {
"description": "Expansion sets to apply, each once: plural_singular, department_synonyms, ampersand_and, abbreviations, permutations. Left out, the first four apply; an empty list applies none. Not used with mode exact.",
"items": {
"enum": [
"plural_singular",
"department_synonyms",
"ampersand_and",
"abbreviations",
"permutations"
],
"type": "string"
},
"maxItems": 5,
"type": "array",
"uniqueItems": true
},
"field": {
"enum": [
"contact.title"
],
"type": "string"
},
"mode": {
"description": "contains (the default) matches titles containing a term, starts_with matches titles beginning with it, exact takes verbatim titles with no expansion.",
"enum": [
"contains",
"starts_with",
"exact"
],
"type": "string"
},
"op": {
"const": "matches",
"type": "string"
},
"terms": {
"items": {
"maxLength": 200,
"minLength": 1,
"type": "string"
},
"maxItems": 500,
"minItems": 1,
"type": "array"
}
},
"required": [
"field",
"op",
"terms"
],
"type": "object"
},
"NotGroup": {
"additionalProperties": false,
"description": "Negation: the single node inside must not match.",
"properties": {
"not": {
"$ref": "#/$defs/WhereNode"
}
},
"required": [
"not"
],
"type": "object"
},
"PlaceCentre": {
"additionalProperties": false,
"description": "A named place. Ambiguous names come back from resolve_location as candidates, never a silent choice.",
"properties": {
"code": {
"description": "The ONS geography code of the chosen candidate when resolve_location found more than one, such as E08000035 for the Leeds district.",
"maxLength": 20,
"minLength": 1,
"type": "string"
},
"place": {
"description": "A place name, resolved with resolve_location, such as Leeds.",
"maxLength": 100,
"minLength": 1,
"type": "string"
}
},
"required": [
"place"
],
"type": "object"
},
"PointCentre": {
"additionalProperties": false,
"description": "A latitude and longitude in WGS84 degrees.",
"properties": {
"lat": {
"maximum": 61,
"minimum": 49,
"type": "number"
},
"lon": {
"maximum": 2,
"minimum": -9,
"type": "number"
}
},
"required": [
"lat",
"lon"
],
"type": "object"
},
"PostcodeCentre": {
"additionalProperties": false,
"description": "A postcode centroid from ONSPD.",
"properties": {
"postcode": {
"description": "The centroid of a postcode unit, sector, district or area, such as LS1 4AP.",
"pattern": "^[A-Za-z]{1,2}([0-9][0-9A-Za-z]?( [0-9]([A-Za-z]{2})?| ?[0-9][A-Za-z]{2})?)?$",
"type": "string"
}
},
"required": [
"postcode"
],
"type": "object"
},
"RadiusCentre": {
"anyOf": [
{
"$ref": "#/$defs/PlaceCentre"
},
{
"$ref": "#/$defs/PostcodeCentre"
},
{
"$ref": "#/$defs/PointCentre"
}
],
"description": "The centre of a radius: a place, a postcode or a latitude and longitude."
},
"SinceFilter": {
"additionalProperties": false,
"description": "Within the last N days: a date field, or a Companies House signal of the listed types on signal.type.",
"examples": [
{
"days": 90,
"field": "signal.type",
"op": "since",
"values": [
"company.incorporated"
]
}
],
"properties": {
"days": {
"maximum": 3650,
"minimum": 1,
"type": "integer"
},
"field": {
"enum": [
"contact.last_validated_at",
"email.last_verified_at",
"signal.type",
"signal.observed_at"
],
"type": "string"
},
"op": {
"const": "since",
"type": "string"
},
"values": {
"description": "For signal.type only: the signal types to look for, such as company.incorporated.",
"items": {
"maxLength": 200,
"minLength": 1,
"type": "string"
},
"maxItems": 10000,
"minItems": 1,
"type": "array"
}
},
"required": [
"field",
"op",
"days"
],
"type": "object"
},
"WhereNode": {
"anyOf": [
{
"$ref": "#/$defs/AllGroup"
},
{
"$ref": "#/$defs/AnyGroup"
},
{
"$ref": "#/$defs/NotGroup"
},
{
"$ref": "#/$defs/BundleNode"
},
{
"$ref": "#/$defs/Filter"
}
],
"description": "A group (all, any, not), a title bundle or a filter. Groups nest up to 32 deep, and a where tree holds up to 1,000 filters, groups and bundles."
},
"WithinRadiusFilter": {
"additionalProperties": false,
"description": "Sites within radius_miles of the centre. The count reports the centroid used and the postcodes matched.",
"examples": [
{
"centre": {
"place": "Leeds"
},
"field": "site.location",
"op": "within_radius",
"radius_miles": 20
}
],
"properties": {
"centre": {
"$ref": "#/$defs/RadiusCentre"
},
"field": {
"enum": [
"site.location"
],
"type": "string"
},
"op": {
"const": "within_radius",
"type": "string"
},
"radius_miles": {
"description": "Radius in miles, 1 to 100. Under 5 miles needs an account.",
"maximum": 100,
"minimum": 1,
"type": "number"
}
},
"required": [
"field",
"op",
"centre",
"radius_miles"
],
"type": "object"
}
},
"additionalProperties": false,
"anyOf": [
{
"not": {
"properties": {
"audience_id": true
},
"required": [
"audience_id"
],
"type": "object"
},
"properties": {
"audience": true,
"brief": {
"type": "string"
},
"name": true
},
"required": [
"name",
"audience"
],
"type": "object"
},
{
"anyOf": [
{
"properties": {
"name": true
},
"required": [
"name"
],
"type": "object"
},
{
"properties": {
"audience": true
},
"required": [
"audience"
],
"type": "object"
},
{
"properties": {
"brief": true
},
"required": [
"brief"
],
"type": "object"
}
],
"properties": {
"audience_id": true
},
"required": [
"audience_id"
],
"type": "object"
}
],
"description": "Save a new audience (name and audience, brief optional) or update one (audience_id and at least one of name, audience or brief).",
"properties": {
"audience": {
"$ref": "#/$defs/Audience",
"type": "object"
},
"audience_id": {
"description": "A saved audience to update. Leave it out to save a new one.",
"examples": [
"aud_01JB4H2K9V6XN3M9R6T1Y5W8ZA"
],
"pattern": "^aud_[0-7][0-9A-HJKMNP-TV-Z]{25}$",
"type": "string"
},
"brief": {
"anyOf": [
{
"maxLength": 2000,
"type": "string"
},
{
"type": "null"
}
]
},
"name": {
"maxLength": 200,
"minLength": 1,
"type": "string"
}
},
"type": "object"
},
"name": "save_audience",
"outputSchema": {
"$defs": {
"AllGroup": {
"additionalProperties": false,
"description": "AND: every node inside must match.",
"properties": {
"all": {
"items": {
"$ref": "#/$defs/WhereNode"
},
"minItems": 1,
"type": "array"
}
},
"required": [
"all"
],
"type": "object"
},
"AnyGroup": {
"additionalProperties": false,
"description": "OR: at least one node inside must match.",
"properties": {
"any": {
"items": {
"$ref": "#/$defs/WhereNode"
},
"minItems": 1,
"type": "array"
}
},
"required": [
"any"
],
"type": "object"
},
"Audience": {
"additionalProperties": false,
"description": "Who you want, as filters grouped by entity (company., site., contact., email., phone., signal.). The server fills its defaults (active companies, named emails, corporate subscribers, the current dataset_version) and returns the effective definition with every count.",
"properties": {
"dataset": {
"description": "The dataset an audience draws from. uk_contacts is live; ie_contacts and global_contacts are listed but not yet served.",
"enum": [
"uk_contacts",
"ie_contacts",
"global_contacts"
],
"type": "string"
},
"dataset_version": {
"description": "The weekly build to count against, such as 2026-W39. Left out, the current version is filled in and returned.",
"examples": [
"2026-W39"
],
"pattern": "^[0-9]{4}-W(0[1-9]|[1-4][0-9]|5[0-3])$",
"type": "string"
},
"dedupe": {
"description": "none keeps every matching contact, one_per_company keeps one contact per company, one_per_site keeps one per site. Default none.",
"enum": [
"none",
"one_per_company",
"one_per_site"
],
"type": "string"
},
"email_policy": {
"$ref": "#/$defs/EmailPolicy"
},
"schema": {
"const": "mydatahub.audience/1",
"description": "The definition's namespace and version. Older versions are upgraded by a pure function.",
"type": "string"
},
"where": {
"$ref": "#/$defs/WhereNode",
"description": "The filters. Left out, the audience is the whole dataset after the defaults."
}
},
"required": [
"schema"
],
"title": "MyDataHub audience definition (mydatahub.audience/1)",
"type": "object"
},
"AudienceCountSummary": {
"description": "The headline numbers of one count of an audience.",
"properties": {
"companies": {
"minimum": 0,
"type": "integer"
},
"contacts": {
"minimum": 0,
"type": "integer"
},
"count_id": {
"description": "Format: a count id: cnt_ followed by 20 base32 characters (A to Z and 2 to 7), such as cnt_7K2PQ4MAXN3R6TBY5WDZ.",
"examples": [
"cnt_7K2PQ4MAXN3R6TBY5WDZ"
],
"pattern": "^cnt_[A-Z2-7]{20}$",
"type": "string"
},
"counted_at": {
"format": "date-time",
"type": "string"
},
"dataset_version": {
"description": "The immutable weekly build a count is bound to, such as 2026-W39. The last 52 stay queryable.",
"examples": [
"2026-W39"
],
"pattern": "^[0-9]{4}-W(0[1-9]|[1-4][0-9]|5[0-3])$",
"type": "string"
},
"emailable": {
"minimum": 0,
"type": "integer"
}
},
"required": [
"count_id",
"dataset_version",
"contacts",
"companies",
"emailable",
"counted_at"
],
"type": "object"
},
"BetweenFilter": {
"additionalProperties": false,
"description": "The field lies from one value to another inclusive, over the field's order.",
"examples": [
{
"field": "company.employee_band",
"from": "10-19",
"op": "between",
"to": "200-349"
}
],
"properties": {
"field": {
"enum": [
"company.employee_band",
"company.turnover_band",
"company.fleet_band",
"contact.job_level_rank",
"email.deliverability_score"
],
"type": "string"
},
"from": {
"anyOf": [
{
"maxLength": 200,
"minLength": 1,
"type": "string"
},
{
"type": "number"
}
],
"description": "A band code or a number from the field's order."
},
"op": {
"const": "between",
"type": "string"
},
"to": {
"anyOf": [
{
"maxLength": 200,
"minLength": 1,
"type": "string"
},
{
"type": "number"
}
],
"description": "A band code or a number from the field's order."
}
},
"required": [
"field",
"op",
"from",
"to"
],
"type": "object"
},
"BundleNode": {
"additionalProperties": false,
"description": "A title bundle, resolved to its filters in the effective definition: sdm (senior decision makers), manager_and_above (managers and above), owner_managed (owner managed).",
"properties": {
"bundle": {
"enum": [
"sdm",
"manager_and_above",
"owner_managed"
],
"type": "string"
}
},
"required": [
"bundle"
],
"type": "object"
},
"EmailPolicy": {
"additionalProperties": false,
"description": "Email quality floor. Defaults: min_deliverability_score 70, allow_catch_all false.",
"properties": {
"allow_catch_all": {
"description": "Whether catch-all addresses count. Default false.",
"type": "boolean"
},
"min_deliverability_score": {
"description": "Lowest deliverability score counted, 0 to 100. Default 70.",
"maximum": 100,
"minimum": 0,
"type": "integer"
}
},
"type": "object"
},
"Filter": {
"description": "One criterion: a field from GET /v1/catalogue/filters, an operator and its operands. Exclusions nest under not.",
"oneOf": [
{
"$ref": "#/$defs/InFilter"
},
{
"$ref": "#/$defs/BetweenFilter"
},
{
"$ref": "#/$defs/GteFilter"
},
{
"$ref": "#/$defs/LteFilter"
},
{
"$ref": "#/$defs/MatchesFilter"
},
{
"$ref": "#/$defs/WithinRadiusFilter"
},
{
"$ref": "#/$defs/InListFilter"
},
{
"$ref": "#/$defs/SinceFilter"
}
]
},
"GteFilter": {
"additionalProperties": false,
"description": "The field is at or after the value in its order: for bands, the band and every larger one.",
"examples": [
{
"field": "company.employee_band",
"op": "gte",
"value": "50-99"
}
],
"properties": {
"field": {
"enum": [
"company.employee_band",
"company.turnover_band",
"company.fleet_band",
"contact.job_level_rank",
"email.deliverability_score"
],
"type": "string"
},
"op": {
"const": "gte",
"type": "string"
},
"value": {
"anyOf": [
{
"maxLength": 200,
"minLength": 1,
"type": "string"
},
{
"type": "number"
}
],
"description": "A band code or a number from the field's order."
}
},
"required": [
"field",
"op",
"value"
],
"type": "object"
},
"InFilter": {
"additionalProperties": false,
"description": "The field holds one of the listed codes.",
"examples": [
{
"field": "company.sic_2007",
"op": "in",
"values": [
"C"
]
}
],
"properties": {
"field": {
"enum": [
"company.sic_2007",
"company.business_class",
"company.employee_band",
"company.turnover_band",
"company.fleet_band",
"company.type",
"company.status",
"company.subscriber_class",
"company.companies_house_number",
"site.region",
"site.county",
"site.town",
"site.postcode",
"contact.title_family",
"contact.job_function",
"contact.job_level_rank",
"contact.premium",
"email.exists",
"email.type",
"phone.exists",
"phone.tps_ctps_status"
],
"type": "string"
},
"op": {
"const": "in",
"type": "string"
},
"values": {
"items": {
"anyOf": [
{
"maxLength": 200,
"minLength": 1,
"type": "string"
},
{
"type": "number"
},
{
"type": "boolean"
}
],
"description": "A code, a rank or a boolean, as the field's catalogue lists it."
},
"maxItems": 10000,
"minItems": 1,
"type": "array"
}
},
"required": [
"field",
"op",
"values"
],
"type": "object"
},
"InListFilter": {
"additionalProperties": false,
"description": "The record's hashed email, domain, phone, company number or title term is on a suppression list. Usually nested under not; each list reports the records it removed.",
"examples": [
{
"field": "email.address_sha256",
"list_id": "sup_01JB4H7Q2V7XN3M9R6T1Y5W8ZA",
"op": "in_list"
}
],
"properties": {
"field": {
"enum": [
"company.companies_house_number",
"contact.title",
"email.address_sha256",
"email.domain_sha256",
"phone.e164_sha256"
],
"type": "string"
},
"list_id": {
"description": "Format: a suppression list id: sup_ followed by a 26 character ULID in upper case Crockford base32, such as sup_01JB4H7Q2V7XN3M9R6T1Y5W8ZA.",
"examples": [
"sup_01JB4H7Q2V7XN3M9R6T1Y5W8ZA"
],
"pattern": "^sup_[0-7][0-9A-HJKMNP-TV-Z]{25}$",
"type": "string"
},
"op": {
"const": "in_list",
"type": "string"
}
},
"required": [
"field",
"op",
"list_id"
],
"type": "object"
},
"LteFilter": {
"additionalProperties": false,
"description": "The field is at or before the value in its order. Rank 1 is the most senior, so Director and above is contact.job_level_rank lte 6.",
"examples": [
{
"field": "contact.job_level_rank",
"op": "lte",
"value": 6
}
],
"properties": {
"field": {
"enum": [
"company.employee_band",
"company.turnover_band",
"company.fleet_band",
"contact.job_level_rank",
"contact.company_contact_rank",
"email.deliverability_score"
],
"type": "string"
},
"op": {
"const": "lte",
"type": "string"
},
"value": {
"anyOf": [
{
"maxLength": 200,
"minLength": 1,
"type": "string"
},
{
"type": "number"
}
],
"description": "A band code or a number from the field's order."
}
},
"required": [
"field",
"op",
"value"
],
"type": "object"
},
"MatchesFilter": {
"additionalProperties": false,
"allOf": [
{
"if": {
"properties": {
"mode": {
"const": "exact"
}
},
"required": [
"mode"
],
"type": "object"
},
"then": {
"properties": {
"exclude_terms": {
"maxItems": 0,
"type": "array"
},
"expand": {
"maxItems": 0,
"type": "array"
}
},
"type": "object"
}
}
],
"description": "Job title keyword match. mode contains (the default) or starts_with expands each term with the expansion sets; mode exact matches verbatim titles. Every expanded term is returned with the count.",
"examples": [
{
"expand": [
"plural_singular",
"department_synonyms",
"ampersand_and",
"abbreviations"
],
"field": "contact.title",
"mode": "contains",
"op": "matches",
"terms": [
"marketing manager"
]
}
],
"properties": {
"exclude_terms": {
"description": "Expanded terms removed by hand. Kept in the definition so the count stays reproducible when the title dictionary changes.",
"items": {
"maxLength": 200,
"minLength": 1,
"type": "string"
},
"maxItems": 500,
"type": "array"
},
"expand": {
"description": "Expansion sets to apply, each once: plural_singular, department_synonyms, ampersand_and, abbreviations, permutations. Left out, the first four apply; an empty list applies none. Not used with mode exact.",
"items": {
"enum": [
"plural_singular",
"department_synonyms",
"ampersand_and",
"abbreviations",
"permutations"
],
"type": "string"
},
"maxItems": 5,
"type": "array",
"uniqueItems": true
},
"field": {
"enum": [
"contact.title"
],
"type": "string"
},
"mode": {
"description": "contains (the default) matches titles containing a term, starts_with matches titles beginning with it, exact takes verbatim titles with no expansion.",
"enum": [
"contains",
"starts_with",
"exact"
],
"type": "string"
},
"op": {
"const": "matches",
"type": "string"
},
"terms": {
"items": {
"maxLength": 200,
"minLength": 1,
"type": "string"
},
"maxItems": 500,
"minItems": 1,
"type": "array"
}
},
"required": [
"field",
"op",
"terms"
],
"type": "object"
},
"NotGroup": {
"additionalProperties": false,
"description": "Negation: the single node inside must not match.",
"properties": {
"not": {
"$ref": "#/$defs/WhereNode"
}
},
"required": [
"not"
],
"type": "object"
},
"PlaceCentre": {
"additionalProperties": false,
"description": "A named place. Ambiguous names come back from resolve_location as candidates, never a silent choice.",
"properties": {
"code": {
"description": "The ONS geography code of the chosen candidate when resolve_location found more than one, such as E08000035 for the Leeds district.",
"maxLength": 20,
"minLength": 1,
"type": "string"
},
"place": {
"description": "A place name, resolved with resolve_location, such as Leeds.",
"maxLength": 100,
"minLength": 1,
"type": "string"
}
},
"required": [
"place"
],
"type": "object"
},
"PointCentre": {
"additionalProperties": false,
"description": "A latitude and longitude in WGS84 degrees.",
"properties": {
"lat": {
"maximum": 61,
"minimum": 49,
"type": "number"
},
"lon": {
"maximum": 2,
"minimum": -9,
"type": "number"
}
},
"required": [
"lat",
"lon"
],
"type": "object"
},
"PostcodeCentre": {
"additionalProperties": false,
"description": "A postcode centroid from ONSPD.",
"properties": {
"postcode": {
"description": "The centroid of a postcode unit, sector, district or area, such as LS1 4AP.",
"pattern": "^[A-Za-z]{1,2}([0-9][0-9A-Za-z]?( [0-9]([A-Za-z]{2})?| ?[0-9][A-Za-z]{2})?)?$",
"type": "string"
}
},
"required": [
"postcode"
],
"type": "object"
},
"RadiusCentre": {
"anyOf": [
{
"$ref": "#/$defs/PlaceCentre"
},
{
"$ref": "#/$defs/PostcodeCentre"
},
{
"$ref": "#/$defs/PointCentre"
}
],
"description": "The centre of a radius: a place, a postcode or a latitude and longitude."
},
"SinceFilter": {
"additionalProperties": false,
"description": "Within the last N days: a date field, or a Companies House signal of the listed types on signal.type.",
"examples": [
{
"days": 90,
"field": "signal.type",
"op": "since",
"values": [
"company.incorporated"
]
}
],
"properties": {
"days": {
"maximum": 3650,
"minimum": 1,
"type": "integer"
},
"field": {
"enum": [
"contact.last_validated_at",
"email.last_verified_at",
"signal.type",
"signal.observed_at"
],
"type": "string"
},
"op": {
"const": "since",
"type": "string"
},
"values": {
"description": "For signal.type only: the signal types to look for, such as company.incorporated.",
"items": {
"maxLength": 200,
"minLength": 1,
"type": "string"
},
"maxItems": 10000,
"minItems": 1,
"type": "array"
}
},
"required": [
"field",
"op",
"days"
],
"type": "object"
},
"WhereNode": {
"anyOf": [
{
"$ref": "#/$defs/AllGroup"
},
{
"$ref": "#/$defs/AnyGroup"
},
{
"$ref": "#/$defs/NotGroup"
},
{
"$ref": "#/$defs/BundleNode"
},
{
"$ref": "#/$defs/Filter"
}
],
"description": "A group (all, any, not), a title bundle or a filter. Groups nest up to 32 deep, and a where tree holds up to 1,000 filters, groups and bundles."
},
"WithinRadiusFilter": {
"additionalProperties": false,
"description": "Sites within radius_miles of the centre. The count reports the centroid used and the postcodes matched.",
"examples": [
{
"centre": {
"place": "Leeds"
},
"field": "site.location",
"op": "within_radius",
"radius_miles": 20
}
],
"properties": {
"centre": {
"$ref": "#/$defs/RadiusCentre"
},
"field": {
"enum": [
"site.location"
],
"type": "string"
},
"op": {
"const": "within_radius",
"type": "string"
},
"radius_miles": {
"description": "Radius in miles, 1 to 100. Under 5 miles needs an account.",
"maximum": 100,
"minimum": 1,
"type": "number"
}
},
"required": [
"field",
"op",
"centre",
"radius_miles"
],
"type": "object"
}
},
"description": "A named audience shared across the organisation, with its current count.",
"properties": {
"audience": {
"$ref": "#/$defs/Audience"
},
"brief": {
"description": "The brief it was compiled from, if any.",
"type": [
"string",
"null"
]
},
"created_at": {
"format": "date-time",
"type": "string"
},
"created_by": {
"description": "Format: a user id: usr_ followed by a 26 character ULID in upper case Crockford base32, such as usr_01JA0Q3V7XN3M9R6T1Y5W8ZAK8.",
"examples": [
"usr_01JA0Q3V7XN3M9R6T1Y5W8ZAK8"
],
"pattern": "^usr_[0-7][0-9A-HJKMNP-TV-Z]{25}$",
"type": "string"
},
"current_count": {
"anyOf": [
{
"$ref": "#/$defs/AudienceCountSummary"
},
{
"type": "null"
}
]
},
"id": {
"description": "Format: an audience id: aud_ followed by a 26 character ULID in upper case Crockford base32, such as aud_01JB4H2K9V6XN3M9R6T1Y5W8ZA.",
"examples": [
"aud_01JB4H2K9V6XN3M9R6T1Y5W8ZA"
],
"pattern": "^aud_[0-7][0-9A-HJKMNP-TV-Z]{25}$",
"type": "string"
},
"last_refreshed_at": {
"anyOf": [
{
"format": "date-time",
"type": "string"
},
{
"type": "null"
}
]
},
"name": {
"type": "string"
},
"updated_at": {
"format": "date-time",
"type": "string"
},
"url": {
"description": "The audience in the app, mydatahub.emailmovers.com/audiences/{id}.",
"format": "uri",
"type": "string"
}
},
"required": [
"id",
"name",
"audience",
"brief",
"current_count",
"last_refreshed_at",
"created_at",
"updated_at",
"created_by",
"url"
],
"type": "object"
}
},
{
"description": "Searches the values of one field by text, such as towns matching leeds, and returns each code with its contact and company counts plus did_you_mean for near misses. Use the returned code in a filter rather than guessing one. Free and needs no account; results are paged with next_cursor. Call count_audience once the filters are chosen. Lawful basis is UK GDPR Article 6(1)(f) legitimate interests; email audiences include corporate subscribers only by default (PECR), so sole traders and ordinary partnerships are left out unless the toggle is changed.",
"inputSchema": {
"additionalProperties": false,
"properties": {
"cursor": {
"description": "An opaque cursor from next_cursor. Pass it back unchanged.",
"maxLength": 512,
"minLength": 1,
"type": "string"
},
"dataset": {
"description": "The dataset an audience draws from. uk_contacts is live; ie_contacts and global_contacts are listed but not yet served.",
"enum": [
"uk_contacts",
"ie_contacts",
"global_contacts"
],
"type": "string"
},
"dimension": {
"description": "A field name from list_filters, such as site.town or company.sic_2007.",
"pattern": "^(company|site|contact|email|phone|signal)\\.[a-z0-9_]+$",
"type": "string"
},
"limit": {
"default": 25,
"description": "Items per page, 1 to 100. Default 25.",
"maximum": 100,
"minimum": 1,
"type": "integer"
},
"q": {
"description": "Text to search for.",
"maxLength": 100,
"minLength": 1,
"type": "string"
}
},
"required": [
"dimension"
],
"type": "object"
},
"name": "search_filter_values",
"outputSchema": {
"$defs": {
"CellCount": {
"anyOf": [
{
"minimum": 0,
"type": "integer"
},
{
"const": "under 10",
"type": "string"
},
{
"const": "suppressed",
"type": "string"
}
],
"description": "A whole number; \"under 10\" when disclosure control withholds a small cell; or \"suppressed\" when secondary suppression hides a cell of 10 or more in a cross-tab or breakdown, so totals cannot be differenced. Anonymous and trial callers see cells rounded to the nearest 5.",
"examples": [
4120,
"under 10",
"suppressed"
]
},
"Disclosure": {
"description": "Whether these numbers are exact or protected: \"under 10\" cells, rounding to 5 and secondary suppression for anonymous and trial callers.",
"properties": {
"level": {
"description": "exact for authenticated paid callers; rounded for anonymous and trial callers, whose counts under 100 and every cell are rounded to the nearest 5.",
"enum": [
"exact",
"rounded"
],
"type": "string"
},
"notes": {
"items": {
"type": "string"
},
"type": "array"
},
"rounded_to": {
"anyOf": [
{
"exclusiveMinimum": 0,
"type": "integer"
},
{
"type": "null"
}
],
"description": "5 when numbers are rounded; null when they are exact."
},
"secondary_suppression": {
"description": "True when cross-tab or breakdown cells of 10 or more were hidden as \"suppressed\" so totals cannot be differenced.",
"type": "boolean"
}
},
"required": [
"level",
"rounded_to",
"secondary_suppression",
"notes"
],
"type": "object"
},
"FilterValue": {
"description": "One value of a field, with its counts.",
"properties": {
"code": {
"anyOf": [
{
"type": "string"
},
{
"type": "number"
},
{
"type": "boolean"
}
],
"description": "The value to use in a filter."
},
"companies": {
"$ref": "#/$defs/CellCount"
},
"contacts": {
"$ref": "#/$defs/CellCount"
},
"label": {
"type": "string"
},
"parent": {
"description": "The parent code for hierarchical fields, such as SIC division 62 under J.",
"type": [
"string",
"null"
]
}
},
"required": [
"code",
"label",
"contacts",
"companies"
],
"type": "object"
}
},
"description": "A page of values in one field, best match first when q is given.",
"properties": {
"data": {
"items": {
"$ref": "#/$defs/FilterValue"
},
"type": "array"
},
"dataset_version": {
"description": "The immutable weekly build a count is bound to, such as 2026-W39. The last 52 stay queryable.",
"examples": [
"2026-W39"
],
"pattern": "^[0-9]{4}-W(0[1-9]|[1-4][0-9]|5[0-3])$",
"type": "string"
},
"did_you_mean": {
"items": {
"type": "string"
},
"type": "array"
},
"disclosure": {
"$ref": "#/$defs/Disclosure"
},
"field": {
"type": "string"
},
"has_more": {
"type": "boolean"
},
"next_cursor": {
"anyOf": [
{
"description": "An opaque cursor from next_cursor. Pass it back unchanged.",
"maxLength": 512,
"minLength": 1,
"type": "string"
},
{
"type": "null"
}
]
}
},
"required": [
"field",
"dataset_version",
"data",
"has_more",
"next_cursor",
"disclosure"
],
"type": "object"
}
}
]
}Verify it yourself
curl -s https://api.teppi.xyz/v1/evidence/sha256:b9724f9ef3ac53b3dec2e11a8a6c90f14b7ea37d0f7bc438fcc33900d4b17f27 | sha256sum