{ "openapi": "3.1.1", "info": { "title": "MyDataHub API", "version": "2.0.0", "summary": "UK B2B contact counts, quotes and lists, by Emailmovers.", "description": "MyDataHub by Emailmovers, the UK B2B count engine. Looking is free: the catalogue, counts, breakdowns, masked previews, machine quotes and plans need no account. One credit buys one complete UK record at the same price here, in the app and in the MCP server at https://mydatahub.emailmovers.com/mcp.\n\nEvery spend follows a signed machine quote (24 hours) and a human confirmation or a pre-authorised agent key; a confirmed flag set by a model is never consent, and a standard API key or OAuth token alone never spends. x-cost-credits on every operation gives its credit cost, and x-free marks the free ones.\n\nErrors are RFC 9457 problem details with next_step and did_you_mean. Rate limits use the IETF RateLimit and RateLimit-Policy fields, with Retry-After on 429 and 503. Lists return {data, has_more, next_cursor}. Response objects may gain members in a later MyDataHub-Version: ignore members you do not know.", "contact": { "name": "MyDataHub by Emailmovers Ltd", "url": "https://emailmovers.com/mydatahub/docs" }, "license": { "name": "MyDataHub Data Licence and Sharing Agreement (terms version 2026-09)", "url": "https://mydatahub.emailmovers.com/licence.json" }, "x-mydatahub-version": "2027-01-15" }, "servers": [ { "url": "https://mydatahub.emailmovers.com/v1", "description": "Production. Test keys (mdh_test_) return synthetic data and never charge." } ], "security": [ { "OAuth2": [] }, { "ApiKey": [] } ], "tags": [ { "name": "Catalogue", "description": "Free and public: plans, datasets, filter fields and values, field sets, title expansion, location resolution and compiling a brief." }, { "name": "Counts", "description": "Free and public: counts with breakdowns, and masked samples (previews)." }, { "name": "Samples", "description": "A sample of a counted audience, sent only after a person confirms a work email address, and downloaded once." }, { "name": "Audiences", "description": "Saved audiences shared across the organisation." }, { "name": "Quotes", "description": "Machine quotes (24 hours, free and public) and human sales quotes (14 days)." }, { "name": "Orders", "description": "Spend credits against a machine quote; status, cancellation and the signed compliance receipt." }, { "name": "Records", "description": "Delivered records under licence, as pages or a signed download. Free." }, { "name": "Lookups", "description": "Company lookup (free) and contact enrichment (1 credit on a confident match)." }, { "name": "Suppressions", "description": "Suppression lists, checks before a send, and objections." }, { "name": "Compliance", "description": "Public: the trust document, the LIA and compliance receipt verification." }, { "name": "Account", "description": "Balance, plan, usage, credits bought by card, and ending a rolling plan." }, { "name": "Keys", "description": "API keys and agent keys with budgets." }, { "name": "CRM push", "description": "CRM connections, the New to you overlap check and record pushes." }, { "name": "Webhooks", "description": "Webhook endpoints and the 30 day event log." }, { "name": "Meta", "description": "This document and the health check." } ], "externalDocs": { "description": "Guides and the MCP server", "url": "https://emailmovers.com/mydatahub/docs" }, "x-rate-limits": [ { "tier": "anonymous", "counts": "60 an hour and 600 a day per IP and fingerprint", "other": "Challenge after 20; at most 6 filters an audience; no single company counts, free text title search or radius under 5 miles; counts under 100 and breakdown cells rounded to the nearest 5", "status": "confirmed" }, { "tier": "free", "counts": "60 a minute and 1,000 a day per organisation", "other": "Counts under 100 and breakdown cells rounded to the nearest 5", "status": "to_confirm" }, { "tier": "paid", "counts": "Published per plan", "other": "Exact counts", "status": "confirmed" } ], "paths": { "/plans": { "get": { "operationId": "getPlans", "summary": "Get plans and prices", "description": "Plans, credit packs, credit rules, licence terms, the guarantee and the free trial, in GBP excluding VAT. The same content as https://mydatahub.emailmovers.com/pricing.json. One credit buys one complete UK record at the same price in the app, API and MCP server.", "tags": [ "Catalogue" ], "security": [], "parameters": [ { "$ref": "#/components/parameters/MyDataHubVersion" } ], "responses": { "200": { "description": "Plans and prices.", "headers": { "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Pricing" }, "examples": { "illustrative": { "summary": "Today's plans and credit packs", "value": { "version": "2026-10", "valid_from": "2026-10-13", "currency": "GBP", "vat_treatment": "Prices exclude VAT at 20 percent.", "credit_definition": "1 credit buys 1 complete UK record, delivered once, at the per-contact scale's rate, the same in the app, API and MCP server.", "price_scale": { "id": "per_contact_scale", "name": "Per-contact scale", "status": "confirmed", "available_to": "everyone", "minimum_order_records": 0, "rule": "The credits bought, after any balance, pick one band, and every credit in the purchase is at its rate. A quote compares the scale with the credit pack and leads with the cheaper.", "bands": [ { "from_records": 1, "to_records": 2999, "gbp_per_record": 0.25 }, { "from_records": 3000, "to_records": 9999, "gbp_per_record": 0.25 }, { "from_records": 10000, "to_records": 24999, "gbp_per_record": 0.22 }, { "from_records": 25000, "to_records": 49999, "gbp_per_record": 0.195 }, { "from_records": 50000, "to_records": null, "gbp_per_record": 0.17 } ] }, "plans": [ { "id": "free", "name": "Free", "kind": "free", "status": "confirmed", "available_to": "everyone", "price_gbp_ex_vat": 0, "billing_period": "once", "credits": 100, "per_record_gbp": null, "credits_expire": false, "for_whom": "Triallists, human or agent", "notes": "No card" }, { "id": "pay_as_you_go", "name": "Pay as you go", "kind": "subscription", "status": "confirmed", "available_to": "existing_customers", "price_gbp_ex_vat": 299, "billing_period": "month", "credits": 1000, "per_record_gbp": 0.299, "rollover_cap_credits": 12000, "credits_expire": false, "for_whom": "Existing customers, who keep this price", "notes": "Cancel any time. Not sold to new customers since 13 October 2026." }, { "id": "plan_12_month", "name": "12-month plan", "kind": "subscription", "status": "confirmed", "available_to": "existing_customers", "price_gbp_ex_vat": 249, "billing_period": "month", "annual_price_gbp_ex_vat": 2988, "credits": 1000, "per_record_gbp": 0.249, "rollover_cap_credits": 12000, "credits_expire": false, "for_whom": "Existing customers, who keep this price", "notes": "Not sold to new customers since 13 October 2026." }, { "id": "subscription_2000", "name": "Subscription", "kind": "subscription", "status": "confirmed", "available_to": "new_customers", "price_gbp_ex_vat": 500, "billing_period": "month", "contract_months": 12, "annual_price_gbp_ex_vat": 6000, "credits": 2000, "per_record_gbp": 0.25, "rollover_cap_credits": 0, "credits_expire": true, "for_whom": "Teams that buy every month", "notes": "A 12-month contract. Each month's 2,000 records are used or lost; records beyond them cost the quote's cheapest purchase." } ], "credit_packs": [ { "id": "credit_pack_40000", "name": "Credit pack 40,000", "kind": "pack", "status": "confirmed", "available_to": "everyone", "price_gbp_ex_vat": 1249, "billing_period": "once", "credits": 40000, "per_record_gbp": 0.031, "credits_expire": false, "for_whom": "Anyone buying about 5,000 records or more" } ], "credit_rules": [ { "action": "count", "label": "Count, breakdown, preview, machine quote, catalogue, title expansion", "credits": 0, "unit": "call", "status": "confirmed" }, { "action": "record", "label": "Full UK contact record delivered, any channel or field set", "credits": 1, "unit": "record", "status": "confirmed" }, { "action": "company_only_record", "label": "Company-only record (no named contact)", "credits": 0.1, "unit": "record", "status": "proposed" }, { "action": "enrich_contact", "label": "Contact enrichment, match found", "credits": 1, "unit": "match", "status": "confirmed", "note": "0 if already licensed" }, { "action": "lookup_company", "label": "Company lookup, no contact details", "credits": 0, "unit": "call", "status": "to_confirm" }, { "action": "outright", "label": "Outright ownership", "credits": 1.8, "unit": "record", "status": "proposed" } ], "licence": [ { "licence_type": "multi_use_12m", "status": "confirmed", "credits_per_record": 1, "permitted_channels": [ "email", "telephone", "post" ], "reuse_months": 12, "resale_prohibited": true, "warranty_url": "https://emailmovers.com/trust/warranty", "terms_version": "2026-09" } ], "guarantee": { "current": { "policy": "replace_over_threshold_hard_bounce", "threshold_percent": 10, "url": "https://emailmovers.com/trust/warranty" }, "proposed": { "policy": "replace_any_hard_bounce_30d", "url": "https://emailmovers.com/trust/warranty" }, "refunds": [ "Credits and credit packs are not refundable once bought, except where the law requires.", "Existing customers keep what their signed agreement says until it renews." ] }, "trial": { "credits": 100, "card_required": false, "expires": false }, "meters": [ { "action": "record", "unit": "record", "credits": 1, "status": "confirmed" }, { "action": "enrich_contact", "unit": "match", "credits": 1, "status": "confirmed" }, { "action": "company_only_record", "unit": "record", "credits": 0.1, "status": "proposed" }, { "action": "outright", "unit": "record", "credits": 1.8, "status": "proposed" }, { "action": "count", "unit": "call", "credits": 0, "status": "confirmed" } ], "action_path": [ { "step": 1, "action": "quote_order", "rest": "POST /v1/quotes", "description": "Get a signed machine quote for a count, valid 24 hours. Free." }, { "step": 2, "action": "create_order", "rest": "POST /v1/orders", "description": "Spend credits against the quote_id with a person's confirmation or an agent key within its limits." }, { "step": 3, "action": "https://mydatahub.emailmovers.com/billing/top-up", "rest": null, "description": "When the balance is short, buy one of the quote's purchase options (the cheapest comes first) through Stripe Checkout, then retry step 2." } ], "promises": [ { "key": "looking_is_free", "statement": "Looking is free forever", "in_practice": "Filters, counts, breakdowns, masked previews, machine quotes, plans and trust documents need no account or card." }, { "key": "never_pay_twice", "statement": "Never pay twice", "in_practice": "Re-downloads under licence, duplicates, suppressed records, records you already hold and failed lookups cost 0." } ] } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "429": { "$ref": "#/components/responses/RateLimited" }, "default": { "$ref": "#/components/responses/ServerError" } }, "x-cost-credits": 0, "x-free": true, "x-anonymous": true, "x-mcp-tool": "get_plans" } }, "/datasets": { "get": { "operationId": "listDatasets", "summary": "List datasets", "description": "Every dataset with owner, source, licence, refresh, residency, regulator, warranty and credits per record. v2.0 serves uk_contacts; the others are listed with their status.", "tags": [ "Catalogue" ], "security": [], "parameters": [ { "$ref": "#/components/parameters/MyDataHubVersion" }, { "name": "limit", "in": "query", "required": false, "description": "Items per page, 1 to 100. Default 25.", "schema": { "default": 25, "type": "integer", "minimum": 1, "maximum": 100 } }, { "name": "cursor", "in": "query", "required": false, "description": "An opaque cursor from next_cursor. Pass it back unchanged.", "schema": { "type": "string", "minLength": 1, "maxLength": 512 } } ], "responses": { "200": { "description": "A page of datasets.", "headers": { "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DatasetList" }, "examples": { "illustrative": { "summary": "The UK dataset", "value": { "data": [ { "id": "uk_contacts", "name": "UK contacts", "status": "live", "owner": "Emailmovers Ltd", "source": "Emailmovers research; Companies House (OGL v3.0); ONSPD (OGL v3.0)", "licence": "12 month multi-use licence; resale prohibited", "refresh": "Immutable weekly build every Monday; same-day suppression overlay", "residency": "Held in the UK (Google Cloud London)", "regulator": "ICO", "warranty": "Replacement when hard bounces exceed 10 percent of an order", "credits_per_record": 1, "credits_status": "confirmed", "current_version": "2026-W39", "versions_available": 52 } ], "has_more": false, "next_cursor": null } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "422": { "$ref": "#/components/responses/ValidationFailed" }, "429": { "$ref": "#/components/responses/RateLimited" }, "default": { "$ref": "#/components/responses/ServerError" } }, "x-cost-credits": 0, "x-free": true, "x-anonymous": true } }, "/datasets/{dataset}/versions/{version}": { "get": { "operationId": "getDatasetVersion", "summary": "Get a dataset version changelog", "description": "What changed in one immutable weekly build: records added, retired and re-verified, companies dissolved, job changes confirmed, suppressions applied, coverage by field and the input snapshots.", "tags": [ "Catalogue" ], "security": [], "parameters": [ { "$ref": "#/components/parameters/MyDataHubVersion" }, { "name": "dataset", "in": "path", "required": true, "description": "The dataset an audience draws from. uk_contacts is live; ie_contacts and global_contacts are listed but not yet served.", "schema": { "type": "string", "enum": [ "uk_contacts", "ie_contacts", "global_contacts" ] }, "example": "uk_contacts" }, { "name": "version", "in": "path", "required": true, "description": "The immutable weekly build a count is bound to, such as 2026-W39. The last 52 stay queryable.", "schema": { "type": "string", "pattern": "^[0-9]{4}-W(0[1-9]|[1-4][0-9]|5[0-3])$", "examples": [ "2026-W39" ] }, "example": "2026-W39" } ], "responses": { "200": { "description": "The version's changelog.", "headers": { "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DatasetVersionChangelog" }, "examples": { "illustrative": { "summary": "The 2026-W39 build", "value": { "dataset": "uk_contacts", "version": "2026-W39", "built_at": "2026-09-21T04:00:00Z", "checksum": "b94d27b9934d3e08a52e52d7da7dabfac484efe37a5380ee9088f7ace2efcde9", "row_counts": { "companies": 5689369, "sites": 3232415, "contacts": 9028587, "emails": 1660190, "phones": 1210000 }, "changes": { "records_added": 4120, "records_retired": 1870, "records_reverified": 118400, "companies_dissolved": 15130, "job_changes_confirmed": 210, "suppressions_applied": 96 }, "coverage_pct": { "named_email": 17.8, "email": 18.4 }, "input_snapshots": [ { "source": "companies_house", "as_of": "2026-09-01" }, { "source": "onspd", "as_of": "2026-08-01" } ] } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/RateLimited" }, "default": { "$ref": "#/components/responses/ServerError" } }, "x-cost-credits": 0, "x-free": true, "x-anonymous": true } }, "/catalogue/filters": { "get": { "operationId": "listFilters", "summary": "List filter fields", "description": "Every filterable field of mydatahub.audience/1 with its group, type, operators, value count and default, plus the operators and the dataset list. Free and public, cached for 24 hours.", "tags": [ "Catalogue" ], "security": [], "parameters": [ { "$ref": "#/components/parameters/MyDataHubVersion" }, { "name": "dataset", "in": "query", "required": false, "description": "The dataset an audience draws from. uk_contacts is live; ie_contacts and global_contacts are listed but not yet served.", "schema": { "type": "string", "enum": [ "uk_contacts", "ie_contacts", "global_contacts" ] } } ], "responses": { "200": { "description": "The filter catalogue.", "headers": { "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FilterCatalogue" }, "examples": { "illustrative": { "summary": "Filter catalogue", "value": { "dataset": "uk_contacts", "dataset_version": "2026-W39", "fields": [ { "field": "company.employee_band", "group": "company", "type": "band", "label": "Employee band", "description": "Company size in 13 bands, 1-5 to 10000+.", "operators": [ "in", "between", "gte", "lte" ], "facet": true, "value_count": 14, "default": null, "examples": [ "50-99" ], "values_url": "/v1/catalogue/filters/company.employee_band/values" } ], "operators": [ { "op": "gte", "applies_to": "banded and ranked fields", "description": "The value and everything after it in the order (for bands, larger bands)." } ], "datasets": [ { "id": "uk_contacts", "name": "UK contacts", "status": "live", "owner": "Emailmovers Ltd", "source": "Emailmovers research; Companies House (OGL v3.0); ONSPD (OGL v3.0)", "licence": "12 month multi-use licence; resale prohibited", "refresh": "Immutable weekly build every Monday; same-day suppression overlay", "residency": "Held in the UK (Google Cloud London)", "regulator": "ICO", "warranty": "Replacement when hard bounces exceed 10 percent of an order", "credits_per_record": 1, "credits_status": "confirmed", "current_version": "2026-W39", "versions_available": 52 } ] } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "422": { "$ref": "#/components/responses/ValidationFailed" }, "429": { "$ref": "#/components/responses/RateLimited" }, "default": { "$ref": "#/components/responses/ServerError" } }, "x-cost-credits": 0, "x-free": true, "x-anonymous": true, "x-mcp-tool": "list_filters" } }, "/catalogue/filters/{dimension}/values": { "get": { "operationId": "searchFilterValues", "summary": "Search filter values", "description": "Values of one field, searched by text, each with its contact and company count, plus did_you_mean for a near miss. The dimension is the field name, such as site.town.", "tags": [ "Catalogue" ], "security": [], "parameters": [ { "$ref": "#/components/parameters/MyDataHubVersion" }, { "name": "dimension", "in": "path", "required": true, "description": "A field name from GET /v1/catalogue/filters, such as site.town.", "schema": { "type": "string", "pattern": "^(company|site|contact|email|phone|signal)\\.[a-z0-9_]+$" }, "example": "site.town" }, { "name": "q", "in": "query", "required": false, "description": "Text to search for.", "schema": { "type": "string", "minLength": 1, "maxLength": 100 }, "example": "leeds" }, { "name": "dataset", "in": "query", "required": false, "description": "The dataset an audience draws from. uk_contacts is live; ie_contacts and global_contacts are listed but not yet served.", "schema": { "type": "string", "enum": [ "uk_contacts", "ie_contacts", "global_contacts" ] } }, { "name": "limit", "in": "query", "required": false, "description": "Items per page, 1 to 100. Default 25.", "schema": { "default": 25, "type": "integer", "minimum": 1, "maximum": 100 } }, { "name": "cursor", "in": "query", "required": false, "description": "An opaque cursor from next_cursor. Pass it back unchanged.", "schema": { "type": "string", "minLength": 1, "maxLength": 512 } } ], "responses": { "200": { "description": "A page of values.", "headers": { "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FilterValueList" }, "examples": { "illustrative": { "summary": "Towns matching leeds", "value": { "field": "site.town", "dataset_version": "2026-W39", "data": [ { "code": "leeds", "label": "Leeds", "contacts": 41210, "companies": 9870, "parent": "west_yorkshire" } ], "has_more": false, "next_cursor": null, "disclosure": { "level": "rounded", "rounded_to": 5, "secondary_suppression": false, "notes": [ "Counts under 100 and every breakdown cell are rounded to the nearest 5 for anonymous and trial callers." ] } } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/ValidationFailed" }, "429": { "$ref": "#/components/responses/RateLimited" }, "default": { "$ref": "#/components/responses/ServerError" } }, "x-cost-credits": 0, "x-free": true, "x-anonymous": true, "x-mcp-tool": "search_filter_values" } }, "/field-sets": { "get": { "operationId": "listFieldSets", "summary": "List field sets", "description": "The named bundles of fields an order can deliver, with their exact columns. Every field set costs 1 credit a record: no telephone, export or API surcharge.", "tags": [ "Catalogue" ], "security": [], "parameters": [ { "$ref": "#/components/parameters/MyDataHubVersion" }, { "name": "limit", "in": "query", "required": false, "description": "Items per page, 1 to 100. Default 25.", "schema": { "default": 25, "type": "integer", "minimum": 1, "maximum": 100 } }, { "name": "cursor", "in": "query", "required": false, "description": "An opaque cursor from next_cursor. Pass it back unchanged.", "schema": { "type": "string", "minLength": 1, "maxLength": 512 } } ], "responses": { "200": { "description": "A page of field sets.", "headers": { "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FieldSetList" }, "examples": { "illustrative": { "summary": "The standard field set", "value": { "data": [ { "id": "standard", "name": "Standard", "description": "Named email, postal address and company fields with Companies House number and SIC.", "credits_per_record": 1, "columns": [ { "name": "first_name", "description": "First name" }, { "name": "email", "description": "Named business email" }, { "name": "companies_house_number", "description": "Companies House number" } ] } ], "has_more": false, "next_cursor": null } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "422": { "$ref": "#/components/responses/ValidationFailed" }, "429": { "$ref": "#/components/responses/RateLimited" }, "default": { "$ref": "#/components/responses/ServerError" } }, "x-cost-credits": 0, "x-free": true, "x-anonymous": true, "x-mcp-tool": "list_field_sets" } }, "/job-titles/expand": { "post": { "operationId": "expandJobTitles", "summary": "Expand job titles", "description": "Show every title a keyword matches through the expansion sets (plurals, department synonyms, ampersands, abbreviations, word order), each with a count, or what a bundle such as sdm resolves to. Nothing is resolved silently.", "tags": [ "Catalogue" ], "security": [], "parameters": [ { "$ref": "#/components/parameters/MyDataHubVersion" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TitleExpansionRequest" }, "examples": { "illustrative": { "summary": "Expand marketing manager", "value": { "terms": [ "marketing manager" ], "mode": "contains" } } } } } }, "responses": { "200": { "description": "The expanded titles.", "headers": { "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TitleExpansion" }, "examples": { "illustrative": { "summary": "Expand marketing manager", "value": { "dataset_version": "2026-W39", "mode": "contains", "expand": [ "plural_singular", "department_synonyms", "ampersand_and", "abbreviations" ], "terms": [ { "term": "Marketing Manager", "from_term": "marketing manager", "expansion_set": "input", "contacts": 6210 }, { "term": "Marketing Managers", "from_term": "marketing manager", "expansion_set": "plural_singular", "contacts": 14 }, { "term": "Mktg Manager", "from_term": "marketing manager", "expansion_set": "abbreviations", "contacts": "under 10" } ], "total_contacts": 6230, "bundle": null, "filter": { "field": "contact.title", "op": "matches", "terms": [ "marketing manager" ], "mode": "contains", "expand": [ "plural_singular", "department_synonyms", "ampersand_and", "abbreviations" ] }, "disclosure": { "level": "rounded", "rounded_to": 5, "secondary_suppression": false, "notes": [ "Counts under 100 and every breakdown cell are rounded to the nearest 5 for anonymous and trial callers." ] } } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "422": { "$ref": "#/components/responses/ValidationFailed" }, "429": { "$ref": "#/components/responses/RateLimited" }, "default": { "$ref": "#/components/responses/ServerError" } }, "x-cost-credits": 0, "x-free": true, "x-anonymous": true, "x-mcp-tool": "expand_job_titles" } }, "/locations/resolve": { "post": { "operationId": "resolveLocation", "summary": "Resolve a location", "description": "Turn free text into region, county, town, postcode or radius filters. Ambiguous names come back as candidates with a question, never a silent choice. A radius under 5 miles needs an account (401 account-required).", "tags": [ "Catalogue" ], "security": [ {}, { "OAuth2": [ "counts:read" ] }, { "ApiKey": [ "counts:read" ] } ], "parameters": [ { "$ref": "#/components/parameters/MyDataHubVersion" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LocationRequest" }, "examples": { "illustrative": { "summary": "Twenty miles of Leeds", "value": { "text": "20 miles of Leeds" } } } } } }, "responses": { "200": { "description": "Candidates for the place.", "headers": { "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LocationResolution" }, "examples": { "illustrative": { "summary": "Twenty miles of Leeds", "value": { "text": "20 miles of Leeds", "ambiguous": true, "question": "Leeds: city centre or the metropolitan district?", "candidates": [ { "kind": "radius", "code": "E08000035", "label": "Within 20 miles of Leeds (metropolitan district centroid)", "contacts": 42318, "centre": { "lat": 53.7997, "lon": -1.5492 }, "filter": { "field": "site.location", "op": "within_radius", "centre": { "place": "Leeds", "code": "E08000035" }, "radius_miles": 20 } }, { "kind": "radius", "code": "LS1", "label": "Within 20 miles of Leeds city centre (LS1)", "contacts": 41960, "centre": { "lat": 53.7974, "lon": -1.5438 }, "filter": { "field": "site.location", "op": "within_radius", "centre": { "postcode": "LS1" }, "radius_miles": 20 } } ], "disclosure": { "level": "rounded", "rounded_to": 5, "secondary_suppression": false, "notes": [ "Counts under 100 and every breakdown cell are rounded to the nearest 5 for anonymous and trial callers." ] } } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "422": { "$ref": "#/components/responses/ValidationFailed" }, "429": { "$ref": "#/components/responses/RateLimited" }, "default": { "$ref": "#/components/responses/ServerError" } }, "x-cost-credits": 0, "x-free": true, "x-anonymous": true, "x-mcp-tool": "resolve_location" } }, "/audiences/compile": { "post": { "operationId": "compileAudience", "summary": "Compile a brief", "description": "Turn a plain English brief into an audience definition with a one-sentence readback, the chips it made and any questions to answer first. Words that match no filter are returned, not guessed.", "tags": [ "Catalogue" ], "security": [], "parameters": [ { "$ref": "#/components/parameters/MyDataHubVersion" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BriefRequest" }, "examples": { "illustrative": { "summary": "Finance directors at law firms in Manchester", "value": { "brief": "300 finance directors at law firms in Manchester" } } } } } }, "responses": { "200": { "description": "The compiled audience.", "headers": { "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CompiledBrief" }, "examples": { "illustrative": { "summary": "Finance directors at law firms in Manchester", "value": { "audience": { "schema": "mydatahub.audience/1", "dataset": "uk_contacts", "where": { "all": [ { "field": "contact.title", "op": "matches", "terms": [ "finance director" ] }, { "field": "company.sic_2007", "op": "in", "values": [ "69102" ] }, { "field": "site.town", "op": "in", "values": [ "manchester" ] } ] } }, "readback": "Finance directors at solicitors (SIC 69102) in Manchester.", "chips": [ { "label": "Job title: finance director plus expansions", "pointer": "/where/all/0", "from_brief": "finance directors" }, { "label": "Industry: solicitors (SIC 69102)", "pointer": "/where/all/1", "from_brief": "law firms" }, { "label": "Town: Manchester", "pointer": "/where/all/2", "from_brief": "in Manchester" } ], "questions": [], "unrecognised": [], "quantity": 300 } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "422": { "$ref": "#/components/responses/ValidationFailed" }, "429": { "$ref": "#/components/responses/RateLimited" }, "default": { "$ref": "#/components/responses/ServerError" } }, "x-cost-credits": 0, "x-free": true, "x-anonymous": true, "x-mcp-tool": "compile_audience" } }, "/counts": { "post": { "operationId": "createCount", "summary": "Count an audience", "description": "Count an audience, inline or by aud_ id, at contact or company level with up to three breakdown fields. Returns Total, New to you (signed in) and Emailable with companies, breakdowns, quality, the compliance summary, a price estimate and a content-addressed count id (also the ETag). Free, and needs no account; anonymous and trial callers see counts under 100 and every breakdown cell rounded to the nearest 5. Lawful basis for named work emails is UK GDPR Article 6(1)(f) legitimate interests; sole traders and ordinary partnerships are individual subscribers and are left out of email audiences by default.", "tags": [ "Counts" ], "security": [ {}, { "OAuth2": [ "counts:read" ] }, { "ApiKey": [ "counts:read" ] } ], "parameters": [ { "$ref": "#/components/parameters/MyDataHubVersion" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CountRequest" }, "examples": { "spec": { "summary": "Marketing managers and above at manufacturers within 20 miles of Leeds", "value": { "audience": { "schema": "mydatahub.audience/1", "dataset": "uk_contacts", "where": { "all": [ { "field": "contact.title", "op": "matches", "terms": [ "marketing manager" ], "mode": "contains" }, { "field": "contact.job_level_rank", "op": "in", "values": [ 1, 2, 3, 4, 5, 6, 8, 9 ] }, { "field": "company.sic_2007", "op": "in", "values": [ "C" ] }, { "field": "company.employee_band", "op": "gte", "value": "50-99" }, { "field": "site.location", "op": "within_radius", "centre": { "place": "Leeds" }, "radius_miles": 20 }, { "not": { "field": "email.address_sha256", "op": "in_list", "list_id": "sup_01JB4H7Q2V7XN3M9R6T1Y5W8ZA" } } ] } }, "level": "contact", "breakdown_by": [ "contact.job_level_rank" ] } } } } } }, "responses": { "200": { "description": "The count.", "headers": { "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" }, "ETag": { "$ref": "#/components/headers/ETag" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Count" }, "examples": { "spec": { "summary": "Marketing managers and above at manufacturers within 20 miles of Leeds", "value": { "id": "cnt_7K2PQ4MAXN3R6TBY5WDZ", "dataset": "uk_contacts", "dataset_version": "2026-W39", "credits_per_record": 1, "contacts": 12840, "companies": 3115, "emailable": 12310, "new_to_you": null, "quality": { "email_coverage_pct": 96.8, "verified_90d_pct": 88.4 }, "breakdowns": [ { "by": "contact.job_level_rank", "cells": [ { "value": "director", "contacts": 4120 } ] } ], "compliance_summary": { "lawful_basis": "legitimate_interests_art6_1_f", "corporate_subscriber": 12310, "individual_subscriber_excluded": 530, "tps_ctps_excluded": 1120, "article14_notified": 12290, "article14_pending_within_window": 20, "suppressed_removed": [ { "list_id": "sup_01JB4H7Q2V7XN3M9R6T1Y5W8ZA", "removed": 260 } ] }, "estimate": { "credits": 12310, "gbp_ex_vat": { "per_contact_scale": 2708.2, "cheapest": 1249 } }, "expires_at": "2027-09-26T10:14:00Z", "engine_rules_version": "2026.09.1", "defaults": [ { "id": "active_companies", "applied": true, "views": [ "total", "new_to_you", "emailable" ], "removed": 2210 }, { "id": "named_emails", "applied": true, "views": [ "emailable" ], "removed": 410 }, { "id": "corporate_subscribers", "applied": true, "views": [ "emailable" ], "removed": 530 }, { "id": "no_registered_phones", "applied": false, "views": [ "total", "new_to_you", "emailable" ], "removed": 1120, "screened_at": "2026-09-25" } ], "disclosure": { "level": "rounded", "rounded_to": 5, "secondary_suppression": false, "notes": [ "Counts under 100 and every breakdown cell are rounded to the nearest 5 for anonymous and trial callers." ] }, "premium": 8120, "all_records": 12840, "premium_note": "Premium at launch: in the premium export of 2026-09-28, this dataset version's as-of date." } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "422": { "$ref": "#/components/responses/ValidationFailed" }, "429": { "$ref": "#/components/responses/RateLimited" }, "default": { "$ref": "#/components/responses/ServerError" } }, "x-cost-credits": 0, "x-free": true, "x-anonymous": true, "x-mcp-tool": "count_audience" } }, "/counts/{id}": { "get": { "operationId": "getCount", "summary": "Get a count", "description": "Replay a count by id for 12 months: the effective definition, the compiled plan (expanded terms, resolved centres, SIC codes, suppression checksums), the pinned dataset and engine rules versions, all three views, breakdowns, the compliance summary, quality, the estimate and the number on the current dataset. The ETag equals the id.", "tags": [ "Counts" ], "security": [ {}, { "OAuth2": [ "counts:read" ] }, { "ApiKey": [ "counts:read" ] } ], "parameters": [ { "$ref": "#/components/parameters/MyDataHubVersion" }, { "name": "id", "in": "path", "required": true, "description": "A count id from POST /v1/counts or count_audience. Either case is accepted; responses use upper case.", "schema": { "type": "string", "pattern": "^cnt_[A-Za-z2-7]{20}$", "examples": [ "cnt_7K2PQ4MAXN3R6TBY5WDZ" ] }, "example": "cnt_7K2PQ4MAXN3R6TBY5WDZ" } ], "responses": { "200": { "description": "The count as it ran.", "headers": { "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" }, "ETag": { "$ref": "#/components/headers/ETag" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CountReplay" }, "examples": { "illustrative": { "summary": "Replay of the Leeds count", "value": { "id": "cnt_7K2PQ4MAXN3R6TBY5WDZ", "dataset": "uk_contacts", "dataset_version": "2026-W39", "credits_per_record": 1, "contacts": 12840, "companies": 3115, "emailable": 12310, "new_to_you": null, "quality": { "email_coverage_pct": 96.8, "verified_90d_pct": 88.4, "verified_measured_at": "2026-09-28", "deliverability": { "good": 91.2, "risky": 6.1, "poor": 2.7 }, "avg_days_since_verification": 41 }, "breakdowns": [ { "by": "contact.job_level_rank", "cells": [ { "value": "director", "contacts": 4120 } ] } ], "compliance_summary": { "lawful_basis": "legitimate_interests_art6_1_f", "corporate_subscriber": 12310, "individual_subscriber_excluded": 530, "tps_ctps_excluded": 1120, "article14_notified": 12290, "article14_pending_within_window": 20, "suppressed_removed": [ { "list_id": "sup_01JB4H7Q2V7XN3M9R6T1Y5W8ZA", "removed": 260 } ] }, "estimate": { "credits": 12310, "gbp_ex_vat": { "per_contact_scale": 2708.2, "cheapest": 1249 } }, "expires_at": "2027-09-26T10:14:00Z", "engine_rules_version": "2026.09.1", "defaults": [ { "id": "active_companies", "applied": true, "views": [ "total", "new_to_you", "emailable" ], "removed": 2210 }, { "id": "named_emails", "applied": true, "views": [ "emailable" ], "removed": 410 }, { "id": "corporate_subscribers", "applied": true, "views": [ "emailable" ], "removed": 530 }, { "id": "no_registered_phones", "applied": false, "views": [ "total", "new_to_you", "emailable" ], "removed": 1120, "screened_at": "2026-09-25" } ], "disclosure": { "level": "exact", "rounded_to": null, "secondary_suppression": false, "notes": [] }, "premium": 8120, "all_records": 12840, "premium_note": "Premium at launch: in the premium export of 2026-09-28, this dataset version's as-of date.", "as_of": "2026-09-28", "level": "contact", "views": { "total": { "contacts": 12840, "companies": 3115 }, "new_to_you": null, "emailable": { "contacts": 12310, "companies": 3002 }, "premium": { "contacts": 8120, "companies": 2240 }, "all_records": { "contacts": 12840, "companies": 3115 } }, "expanded_terms": [ { "term": "Marketing Manager", "from_term": "marketing manager", "expansion_set": "input", "contacts": 6210 }, { "term": "Marketing Managers", "from_term": "marketing manager", "expansion_set": "plural_singular", "contacts": 14 }, { "term": "Mktg Manager", "from_term": "marketing manager", "expansion_set": "abbreviations", "contacts": "under 10" } ], "effective_audience": { "schema": "mydatahub.audience/1", "dataset": "uk_contacts", "dataset_version": "2026-W39", "where": { "all": [ { "field": "site.location", "op": "within_radius", "centre": { "place": "Leeds" }, "radius_miles": 20 }, { "field": "contact.title", "op": "matches", "terms": [ "marketing manager" ], "mode": "contains", "expand": [ "plural_singular", "department_synonyms", "ampersand_and", "abbreviations" ] }, { "field": "company.employee_band", "op": "gte", "value": "50-99" }, { "field": "company.sic_2007", "op": "in", "values": [ "C" ] }, { "field": "company.status", "op": "in", "values": [ "active" ] }, { "field": "contact.job_level_rank", "op": "in", "values": [ 1, 2, 3, 4, 5, 6, 8, 9 ] }, { "not": { "field": "email.address_sha256", "op": "in_list", "list_id": "sup_01JB4H7Q2V7XN3M9R6T1Y5W8ZA" } } ] }, "email_policy": { "min_deliverability_score": 70, "allow_catch_all": false }, "dedupe": "none" }, "plan": { "engine_rules_version": "2026.09.1", "defaults_applied": [ "active_companies", "named_emails", "corporate_subscribers" ], "expanded_terms": [ { "term": "Marketing Manager", "from_term": "marketing manager", "expansion_set": "input", "contacts": 6210 }, { "term": "Marketing Managers", "from_term": "marketing manager", "expansion_set": "plural_singular", "contacts": 14 }, { "term": "Mktg Manager", "from_term": "marketing manager", "expansion_set": "abbreviations", "contacts": "under 10" } ], "centres": [ { "label": "Leeds", "code": "E08000035", "lat": 53.7997, "lon": -1.5492, "radius_miles": 20, "postcode_districts_matched": 64 } ], "sic_codes": [], "geography_sets": [], "suppressions": [ { "list_id": "sup_01JB4H7Q2V7XN3M9R6T1Y5W8ZA", "checksum": "9f2c4e0a1b7d3c5e8f6a2b4c6d8e0f1a3b5c7d9e1f2a4b6c8d0e2f4a6b8c0d2e", "row_count": 1198 } ] }, "current": { "dataset_version": "2026-W40", "contacts": 12861, "companies": 3119 }, "removed_since": 3, "created_at": "2026-09-26T10:14:00Z" } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/RateLimited" }, "default": { "$ref": "#/components/responses/ServerError" } }, "x-cost-credits": 0, "x-free": true, "x-anonymous": true } }, "/previews": { "post": { "operationId": "createPreview", "summary": "Preview sample records", "description": "Up to 25 masked sample rows from a seed fixed per audience, so a repeat returns the same rows. Each row has verification badges, why it matches and a provenance card with the compliance object. No rows when the count is under 25. Free.", "tags": [ "Counts" ], "security": [ {}, { "OAuth2": [ "previews:read" ] }, { "ApiKey": [ "previews:read" ] } ], "parameters": [ { "$ref": "#/components/parameters/MyDataHubVersion" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PreviewRequest" }, "examples": { "illustrative": { "summary": "Ten rows of the Leeds count", "value": { "count_id": "cnt_7K2PQ4MAXN3R6TBY5WDZ", "limit": 10 } } } } } }, "responses": { "200": { "description": "The sample.", "headers": { "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Preview" }, "examples": { "illustrative": { "summary": "Ten rows of the Leeds count", "value": { "id": "prv_01JB4H3M7Q2V7XN3M9R6T1Y5W8", "count_id": "cnt_7K2PQ4MAXN3R6TBY5WDZ", "dataset_version": "2026-W39", "seed": "7k2pq4ma", "count": 12840, "rows": [ { "id": "prv_01JB4H3N2V7XN3M9R6T1Y5W8ZA", "title": "Marketing Director", "job_level": "Director", "job_function": "Marketing", "company": { "name": "Example Manufacturing Ltd", "companies_house_number": "12345678", "status": "active", "employee_band": "100-199", "sic_2007": [ "C" ] }, "site": { "town": "Leeds", "postcode_district": "LS11", "region": "yorkshire_and_the_humber" }, "email_masked": "j••••@••••.co.uk", "email_type": "named", "phone_masked": "0113 ••• •••1", "tps_ctps_status": "clear", "badges": [ { "badge": "verified", "date": "2026-09-10", "label": "Verified 10 September 2026" } ], "why_it_matches": [ { "pointer": "/where/all/0", "field": "contact.title", "value": "Marketing Director", "explanation": "Marketing Director matched marketing manager through expansion." }, { "pointer": "/where/all/3", "field": "company.employee_band", "value": "100-199", "explanation": "Employees 120, inside 50 or more." } ], "provenance": { "sources": { "title": "emailmovers_research", "company": "companies_house", "email": "emailmovers_research" }, "first_seen_at": "2026-05-02", "last_verified_at": "2026-08-30", "method": "telephone", "companies_house_number": "12345678", "company_status": "active", "article14_status": "notified", "tps_ctps_screened_at": "2026-09-12", "lawful_basis": "legitimate_interests_art6_1_f" }, "compliance": { "lawful_basis": "legitimate_interests_art6_1_f", "lia_ref": "EM-LIA-2026-03", "subscriber_class": "ltd", "corporate_subscriber": true, "email_marketing_basis": "pecr_corporate_subscriber", "subscriber_evidence": { "companies_house_number": "12345678", "company_type": "ltd" }, "article14_status": "notified", "article14_notified_at": "2026-06-14", "notice_version": "2026-02", "provenance": { "company": { "source": "companies_house", "as_of": "2026-09-21" }, "contact": { "source": "emailmovers_research", "compiled_at": "2026-05-02", "last_verified_at": "2026-08-30", "method": "telephone" }, "email": { "verified_at": "2026-09-10", "result": "ok", "provider_location": "EU" } }, "tps_ctps_status": "clear", "tps_ctps_screened_at": "2026-09-12", "tps_ctps_valid_until": "2026-10-10", "suppression_status": "none", "record_age_days": 147, "attribution": "Contains public sector information licensed under the Open Government Licence v3.0" } } ], "withheld": null, "masked": true, "watermark": null, "created_at": "2026-09-26T10:15:00Z", "disclosure": { "level": "rounded", "rounded_to": 5, "secondary_suppression": false, "notes": [ "Counts under 100 and every breakdown cell are rounded to the nearest 5 for anonymous and trial callers." ] } } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "422": { "$ref": "#/components/responses/ValidationFailed" }, "429": { "$ref": "#/components/responses/RateLimited" }, "default": { "$ref": "#/components/responses/ServerError" } }, "x-cost-credits": 0, "x-free": true, "x-anonymous": true, "x-mcp-tool": "preview_records" } }, "/sample-requests": { "post": { "operationId": "createSampleRequest", "summary": "Ask for a sample of a count", "description": "Starts a sample of about 10 records of a counted audience: the person then confirms a work email address and downloads it once. The count must allow a sample under the caller's rules (25 records or more, not one company). Never returns records.", "tags": [ "Samples" ], "security": [ { "OAuth2": [ "samples:request" ] }, { "ApiKey": [ "samples:request" ] } ], "parameters": [ { "$ref": "#/components/parameters/MyDataHubVersion" }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SampleRequestCreate" }, "examples": { "illustrative": { "summary": "A sample of the Leeds count", "value": { "count_id": "cnt_7K2PQ4MAXN3R6TBY5WDZ" } } } } } }, "responses": { "201": { "description": "The request, waiting for the address.", "headers": { "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" }, "Location": { "$ref": "#/components/headers/Location" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SampleRequest" }, "examples": { "illustrative": { "summary": "A sample of the Leeds count", "value": { "id": "smr_01JB4P2Q5W8ZAK8Q2V7XN3M9R6", "count_id": "cnt_7K2PQ4MAXN3R6TBY5WDZ", "status": "awaiting_email", "created_at": "2026-10-11T10:00:00Z", "expires_at": "2026-10-12T10:00:00Z" } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "422": { "$ref": "#/components/responses/ValidationFailed" }, "429": { "$ref": "#/components/responses/RateLimited" }, "default": { "$ref": "#/components/responses/ServerError" } }, "x-cost-credits": 0, "x-free": true, "x-anonymous": false, "x-idempotency-key": "optional" } }, "/sample-requests/{id}/email": { "post": { "operationId": "createSampleRequestEmail", "summary": "Send the confirmation link for a sample", "description": "The person's work email address, from the calling server's own form, never through a model. A one-time link is emailed; the answer is the same whether the address was accepted or refused (suppressed, objecting, over a limit), so it cannot be used to test addresses. Free webmail and malformed addresses get 422.", "tags": [ "Samples" ], "security": [ { "OAuth2": [ "samples:request" ] }, { "ApiKey": [ "samples:request" ] } ], "parameters": [ { "$ref": "#/components/parameters/MyDataHubVersion" }, { "name": "id", "in": "path", "required": true, "description": "Format: a sample request id: smr_ followed by a 26 character ULID in upper case Crockford base32, such as smr_01JB4P2Q5W8ZAK8Q2V7XN3M9R6.", "schema": { "type": "string", "pattern": "^smr_[0-7][0-9A-HJKMNP-TV-Z]{25}$", "examples": [ "smr_01JB4P2Q5W8ZAK8Q2V7XN3M9R6" ] }, "example": "smr_01JB4P2Q5W8ZAK8Q2V7XN3M9R6" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SampleRequestEmail" }, "examples": { "illustrative": { "summary": "The address from the form", "value": { "email": "jordan.hale@example.co.uk", "follow_up": false, "wording": "2026-10-11" } } } } } }, "responses": { "202": { "description": "Taken: the person checks their inbox.", "headers": { "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SampleRequestEmailAccepted" }, "examples": { "illustrative": { "summary": "The address from the form", "value": { "status": "check_your_inbox" } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/ValidationFailed" }, "429": { "$ref": "#/components/responses/RateLimited" }, "default": { "$ref": "#/components/responses/ServerError" } }, "x-cost-credits": 0, "x-free": true, "x-anonymous": false } }, "/sample-requests/{id}": { "get": { "operationId": "getSampleRequest", "summary": "Get a sample request", "description": "The request's status only: never the address or the records.", "tags": [ "Samples" ], "security": [ { "OAuth2": [ "samples:request" ] }, { "ApiKey": [ "samples:request" ] } ], "parameters": [ { "$ref": "#/components/parameters/MyDataHubVersion" }, { "name": "id", "in": "path", "required": true, "description": "Format: a sample request id: smr_ followed by a 26 character ULID in upper case Crockford base32, such as smr_01JB4P2Q5W8ZAK8Q2V7XN3M9R6.", "schema": { "type": "string", "pattern": "^smr_[0-7][0-9A-HJKMNP-TV-Z]{25}$", "examples": [ "smr_01JB4P2Q5W8ZAK8Q2V7XN3M9R6" ] }, "example": "smr_01JB4P2Q5W8ZAK8Q2V7XN3M9R6" } ], "responses": { "200": { "description": "The request.", "headers": { "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SampleRequest" }, "examples": { "illustrative": { "summary": "Waiting for the person to confirm", "value": { "id": "smr_01JB4P2Q5W8ZAK8Q2V7XN3M9R6", "count_id": "cnt_7K2PQ4MAXN3R6TBY5WDZ", "status": "email_sent", "created_at": "2026-10-11T10:00:00Z", "expires_at": "2026-10-12T10:00:00Z" } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/RateLimited" }, "default": { "$ref": "#/components/responses/ServerError" } }, "x-cost-credits": 0, "x-free": true, "x-anonymous": false } }, "/sample-downloads": { "post": { "operationId": "createSampleDownload", "summary": "Confirm a sample and get its download link", "description": "Sent by the confirmation page when the person presses its button, with the token from the emailed link; the token is the credential, so no key or session is needed. The first press confirms the address and chooses up to 10 records (verified named emails with an Article 14 notice, none at the person's own domain, at most 2 a company), read afresh against every suppression. Each press until the download gives a new single-use link for 5 minutes; after it, the answer says the sample was already downloaded. An unknown or expired token gets 404.", "tags": [ "Samples" ], "security": [], "parameters": [ { "$ref": "#/components/parameters/MyDataHubVersion" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SampleDownloadCreate" }, "examples": { "illustrative": { "summary": "The person presses Download your sample", "value": { "token": "q3V8xN2fK7mR1tY6pL0sD4hJ9wZ5cB8eA2gU7iO3nQ1" } } } } } }, "responses": { "200": { "description": "The sample's link, or why there is none.", "headers": { "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SampleDownload" }, "examples": { "illustrative": { "summary": "The person presses Download your sample", "value": { "status": "ready", "records": 10, "download_url": "/files/samples/sdl_Xr4mP8qT2vN6kJ1wL9sF3hD7bG5cZ0yA8eU2iO6nQ4t", "expires_at": "2026-10-11T10:20:00Z" } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/ValidationFailed" }, "429": { "$ref": "#/components/responses/RateLimited" }, "default": { "$ref": "#/components/responses/ServerError" } }, "x-cost-credits": 0, "x-free": true, "x-anonymous": true } }, "/audiences": { "get": { "operationId": "listAudiences", "summary": "List saved audiences", "description": "Saved audiences shared across the organisation, with current counts and last refresh.", "tags": [ "Audiences" ], "security": [ { "OAuth2": [ "audiences:read" ] }, { "ApiKey": [ "audiences:read" ] } ], "parameters": [ { "$ref": "#/components/parameters/MyDataHubVersion" }, { "name": "q", "in": "query", "required": false, "description": "Filter by name.", "schema": { "type": "string", "maxLength": 100 } }, { "name": "limit", "in": "query", "required": false, "description": "Items per page, 1 to 100. Default 25.", "schema": { "default": 25, "type": "integer", "minimum": 1, "maximum": 100 } }, { "name": "cursor", "in": "query", "required": false, "description": "An opaque cursor from next_cursor. Pass it back unchanged.", "schema": { "type": "string", "minLength": 1, "maxLength": 512 } } ], "responses": { "200": { "description": "A page of saved audiences.", "headers": { "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SavedAudienceList" }, "examples": { "illustrative": { "summary": "One saved audience", "value": { "data": [ { "id": "aud_01JB4H2K9V6XN3M9R6T1Y5W8ZA", "name": "Marketing directors, Leeds", "audience": { "schema": "mydatahub.audience/1", "dataset": "uk_contacts", "dataset_version": "2026-W39", "where": { "all": [ { "field": "contact.title", "op": "matches", "terms": [ "marketing manager" ], "mode": "contains", "expand": [ "plural_singular", "department_synonyms", "ampersand_and", "abbreviations" ] }, { "field": "contact.job_level_rank", "op": "in", "values": [ 1, 2, 3, 4, 5, 6, 8, 9 ] }, { "field": "company.sic_2007", "op": "in", "values": [ "C" ] }, { "field": "company.employee_band", "op": "gte", "value": "50-99" }, { "field": "site.location", "op": "within_radius", "centre": { "place": "Leeds" }, "radius_miles": 20 }, { "not": { "field": "email.address_sha256", "op": "in_list", "list_id": "sup_01JB4H7Q2V7XN3M9R6T1Y5W8ZA" } } ] }, "email_policy": { "min_deliverability_score": 70, "allow_catch_all": false }, "dedupe": "none" }, "brief": "Marketing managers and above at manufacturers within 20 miles of Leeds", "current_count": { "count_id": "cnt_7K2PQ4MAXN3R6TBY5WDZ", "dataset_version": "2026-W39", "contacts": 12840, "companies": 3115, "emailable": 12310, "counted_at": "2026-09-26T10:14:00Z" }, "last_refreshed_at": "2026-09-28T06:00:00Z", "created_at": "2026-09-26T10:20:00Z", "updated_at": "2026-09-26T10:20:00Z", "created_by": "usr_01JA0Q3V7XN3M9R6T1Y5W8ZAK8", "url": "https://mydatahub.emailmovers.com/audiences/aud_01JB4H2K9V6XN3M9R6T1Y5W8ZA" } ], "has_more": false, "next_cursor": null } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "422": { "$ref": "#/components/responses/ValidationFailed" }, "429": { "$ref": "#/components/responses/RateLimited" }, "default": { "$ref": "#/components/responses/ServerError" } }, "x-cost-credits": 0, "x-free": true, "x-anonymous": false, "x-mcp-tool": "list_audiences" }, "post": { "operationId": "createAudience", "summary": "Save an audience", "description": "Save a named audience definition, shared across the organisation. Saving is free; it is counted at once and on every refresh.", "tags": [ "Audiences" ], "security": [ { "OAuth2": [ "audiences:write" ] }, { "ApiKey": [ "audiences:write" ] } ], "parameters": [ { "$ref": "#/components/parameters/MyDataHubVersion" }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SavedAudienceRequest" }, "examples": { "illustrative": { "summary": "Save the Leeds audience", "value": { "name": "Marketing directors, Leeds", "audience": { "schema": "mydatahub.audience/1", "dataset": "uk_contacts", "dataset_version": "2026-W39", "where": { "all": [ { "field": "contact.title", "op": "matches", "terms": [ "marketing manager" ], "mode": "contains", "expand": [ "plural_singular", "department_synonyms", "ampersand_and", "abbreviations" ] }, { "field": "contact.job_level_rank", "op": "in", "values": [ 1, 2, 3, 4, 5, 6, 8, 9 ] }, { "field": "company.sic_2007", "op": "in", "values": [ "C" ] }, { "field": "company.employee_band", "op": "gte", "value": "50-99" }, { "field": "site.location", "op": "within_radius", "centre": { "place": "Leeds" }, "radius_miles": 20 }, { "not": { "field": "email.address_sha256", "op": "in_list", "list_id": "sup_01JB4H7Q2V7XN3M9R6T1Y5W8ZA" } } ] }, "email_policy": { "min_deliverability_score": 70, "allow_catch_all": false }, "dedupe": "none" } } } } } } }, "responses": { "201": { "description": "The saved audience.", "headers": { "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" }, "Location": { "$ref": "#/components/headers/Location" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SavedAudience" }, "examples": { "illustrative": { "summary": "Save the Leeds audience", "value": { "id": "aud_01JB4H2K9V6XN3M9R6T1Y5W8ZA", "name": "Marketing directors, Leeds", "audience": { "schema": "mydatahub.audience/1", "dataset": "uk_contacts", "dataset_version": "2026-W39", "where": { "all": [ { "field": "contact.title", "op": "matches", "terms": [ "marketing manager" ], "mode": "contains", "expand": [ "plural_singular", "department_synonyms", "ampersand_and", "abbreviations" ] }, { "field": "contact.job_level_rank", "op": "in", "values": [ 1, 2, 3, 4, 5, 6, 8, 9 ] }, { "field": "company.sic_2007", "op": "in", "values": [ "C" ] }, { "field": "company.employee_band", "op": "gte", "value": "50-99" }, { "field": "site.location", "op": "within_radius", "centre": { "place": "Leeds" }, "radius_miles": 20 }, { "not": { "field": "email.address_sha256", "op": "in_list", "list_id": "sup_01JB4H7Q2V7XN3M9R6T1Y5W8ZA" } } ] }, "email_policy": { "min_deliverability_score": 70, "allow_catch_all": false }, "dedupe": "none" }, "brief": "Marketing managers and above at manufacturers within 20 miles of Leeds", "current_count": { "count_id": "cnt_7K2PQ4MAXN3R6TBY5WDZ", "dataset_version": "2026-W39", "contacts": 12840, "companies": 3115, "emailable": 12310, "counted_at": "2026-09-26T10:14:00Z" }, "last_refreshed_at": "2026-09-28T06:00:00Z", "created_at": "2026-09-26T10:20:00Z", "updated_at": "2026-09-26T10:20:00Z", "created_by": "usr_01JA0Q3V7XN3M9R6T1Y5W8ZAK8", "url": "https://mydatahub.emailmovers.com/audiences/aud_01JB4H2K9V6XN3M9R6T1Y5W8ZA" } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "409": { "$ref": "#/components/responses/Conflict" }, "422": { "$ref": "#/components/responses/ValidationFailed" }, "429": { "$ref": "#/components/responses/RateLimited" }, "default": { "$ref": "#/components/responses/ServerError" } }, "x-cost-credits": 0, "x-free": true, "x-anonymous": false, "x-idempotency-key": "optional", "x-mcp-tool": "save_audience" } }, "/audiences/{id}": { "get": { "operationId": "getAudience", "summary": "Get a saved audience", "description": "One saved audience with its definition and current count.", "tags": [ "Audiences" ], "security": [ { "OAuth2": [ "audiences:read" ] }, { "ApiKey": [ "audiences:read" ] } ], "parameters": [ { "$ref": "#/components/parameters/MyDataHubVersion" }, { "name": "id", "in": "path", "required": true, "description": "Format: an audience id: aud_ followed by a 26 character ULID in upper case Crockford base32, such as aud_01JB4H2K9V6XN3M9R6T1Y5W8ZA.", "schema": { "type": "string", "pattern": "^aud_[0-7][0-9A-HJKMNP-TV-Z]{25}$", "examples": [ "aud_01JB4H2K9V6XN3M9R6T1Y5W8ZA" ] }, "example": "aud_01JB4H2K9V6XN3M9R6T1Y5W8ZA" } ], "responses": { "200": { "description": "The saved audience.", "headers": { "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SavedAudience" }, "examples": { "illustrative": { "summary": "The Leeds audience", "value": { "id": "aud_01JB4H2K9V6XN3M9R6T1Y5W8ZA", "name": "Marketing directors, Leeds", "audience": { "schema": "mydatahub.audience/1", "dataset": "uk_contacts", "dataset_version": "2026-W39", "where": { "all": [ { "field": "contact.title", "op": "matches", "terms": [ "marketing manager" ], "mode": "contains", "expand": [ "plural_singular", "department_synonyms", "ampersand_and", "abbreviations" ] }, { "field": "contact.job_level_rank", "op": "in", "values": [ 1, 2, 3, 4, 5, 6, 8, 9 ] }, { "field": "company.sic_2007", "op": "in", "values": [ "C" ] }, { "field": "company.employee_band", "op": "gte", "value": "50-99" }, { "field": "site.location", "op": "within_radius", "centre": { "place": "Leeds" }, "radius_miles": 20 }, { "not": { "field": "email.address_sha256", "op": "in_list", "list_id": "sup_01JB4H7Q2V7XN3M9R6T1Y5W8ZA" } } ] }, "email_policy": { "min_deliverability_score": 70, "allow_catch_all": false }, "dedupe": "none" }, "brief": "Marketing managers and above at manufacturers within 20 miles of Leeds", "current_count": { "count_id": "cnt_7K2PQ4MAXN3R6TBY5WDZ", "dataset_version": "2026-W39", "contacts": 12840, "companies": 3115, "emailable": 12310, "counted_at": "2026-09-26T10:14:00Z" }, "last_refreshed_at": "2026-09-28T06:00:00Z", "created_at": "2026-09-26T10:20:00Z", "updated_at": "2026-09-26T10:20:00Z", "created_by": "usr_01JA0Q3V7XN3M9R6T1Y5W8ZAK8", "url": "https://mydatahub.emailmovers.com/audiences/aud_01JB4H2K9V6XN3M9R6T1Y5W8ZA" } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/RateLimited" }, "default": { "$ref": "#/components/responses/ServerError" } }, "x-cost-credits": 0, "x-free": true, "x-anonymous": false }, "patch": { "operationId": "updateAudience", "summary": "Update a saved audience", "description": "Rename a saved audience or replace its definition. The next count uses the new definition.", "tags": [ "Audiences" ], "security": [ { "OAuth2": [ "audiences:write" ] }, { "ApiKey": [ "audiences:write" ] } ], "parameters": [ { "$ref": "#/components/parameters/MyDataHubVersion" }, { "name": "id", "in": "path", "required": true, "description": "Format: an audience id: aud_ followed by a 26 character ULID in upper case Crockford base32, such as aud_01JB4H2K9V6XN3M9R6T1Y5W8ZA.", "schema": { "type": "string", "pattern": "^aud_[0-7][0-9A-HJKMNP-TV-Z]{25}$", "examples": [ "aud_01JB4H2K9V6XN3M9R6T1Y5W8ZA" ] }, "example": "aud_01JB4H2K9V6XN3M9R6T1Y5W8ZA" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SavedAudienceUpdate" }, "examples": { "illustrative": { "summary": "Rename the Leeds audience", "value": { "name": "Marketing directors, Leeds" } } } } } }, "responses": { "200": { "description": "The updated audience.", "headers": { "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SavedAudience" }, "examples": { "illustrative": { "summary": "Rename the Leeds audience", "value": { "id": "aud_01JB4H2K9V6XN3M9R6T1Y5W8ZA", "name": "Marketing directors, Leeds", "audience": { "schema": "mydatahub.audience/1", "dataset": "uk_contacts", "dataset_version": "2026-W39", "where": { "all": [ { "field": "contact.title", "op": "matches", "terms": [ "marketing manager" ], "mode": "contains", "expand": [ "plural_singular", "department_synonyms", "ampersand_and", "abbreviations" ] }, { "field": "contact.job_level_rank", "op": "in", "values": [ 1, 2, 3, 4, 5, 6, 8, 9 ] }, { "field": "company.sic_2007", "op": "in", "values": [ "C" ] }, { "field": "company.employee_band", "op": "gte", "value": "50-99" }, { "field": "site.location", "op": "within_radius", "centre": { "place": "Leeds" }, "radius_miles": 20 }, { "not": { "field": "email.address_sha256", "op": "in_list", "list_id": "sup_01JB4H7Q2V7XN3M9R6T1Y5W8ZA" } } ] }, "email_policy": { "min_deliverability_score": 70, "allow_catch_all": false }, "dedupe": "none" }, "brief": "Marketing managers and above at manufacturers within 20 miles of Leeds", "current_count": { "count_id": "cnt_7K2PQ4MAXN3R6TBY5WDZ", "dataset_version": "2026-W39", "contacts": 12840, "companies": 3115, "emailable": 12310, "counted_at": "2026-09-26T10:14:00Z" }, "last_refreshed_at": "2026-09-28T06:00:00Z", "created_at": "2026-09-26T10:20:00Z", "updated_at": "2026-09-26T10:20:00Z", "created_by": "usr_01JA0Q3V7XN3M9R6T1Y5W8ZAK8", "url": "https://mydatahub.emailmovers.com/audiences/aud_01JB4H2K9V6XN3M9R6T1Y5W8ZA" } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/ValidationFailed" }, "429": { "$ref": "#/components/responses/RateLimited" }, "default": { "$ref": "#/components/responses/ServerError" } }, "x-cost-credits": 0, "x-free": true, "x-anonymous": false, "x-mcp-tool": "save_audience" }, "delete": { "operationId": "deleteAudience", "summary": "Delete a saved audience", "description": "Delete a saved audience. Counts, quotes and orders made from it keep their own ids and still replay.", "tags": [ "Audiences" ], "security": [ { "OAuth2": [ "audiences:write" ] }, { "ApiKey": [ "audiences:write" ] } ], "parameters": [ { "$ref": "#/components/parameters/MyDataHubVersion" }, { "name": "id", "in": "path", "required": true, "description": "Format: an audience id: aud_ followed by a 26 character ULID in upper case Crockford base32, such as aud_01JB4H2K9V6XN3M9R6T1Y5W8ZA.", "schema": { "type": "string", "pattern": "^aud_[0-7][0-9A-HJKMNP-TV-Z]{25}$", "examples": [ "aud_01JB4H2K9V6XN3M9R6T1Y5W8ZA" ] }, "example": "aud_01JB4H2K9V6XN3M9R6T1Y5W8ZA" } ], "responses": { "204": { "description": "Deleted.", "headers": { "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/RateLimited" }, "default": { "$ref": "#/components/responses/ServerError" } }, "x-cost-credits": 0, "x-free": true, "x-anonymous": false } }, "/audiences/{id}/refresh": { "post": { "operationId": "refreshAudience", "summary": "Refresh a saved audience", "description": "Recount a saved audience on the current dataset version and return the difference. The audience.refreshed webhook carries the same object. Free.", "tags": [ "Audiences" ], "security": [ { "OAuth2": [ "audiences:write" ] }, { "ApiKey": [ "audiences:write" ] } ], "parameters": [ { "$ref": "#/components/parameters/MyDataHubVersion" }, { "name": "id", "in": "path", "required": true, "description": "Format: an audience id: aud_ followed by a 26 character ULID in upper case Crockford base32, such as aud_01JB4H2K9V6XN3M9R6T1Y5W8ZA.", "schema": { "type": "string", "pattern": "^aud_[0-7][0-9A-HJKMNP-TV-Z]{25}$", "examples": [ "aud_01JB4H2K9V6XN3M9R6T1Y5W8ZA" ] }, "example": "aud_01JB4H2K9V6XN3M9R6T1Y5W8ZA" } ], "responses": { "200": { "description": "The refresh and its diff.", "headers": { "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AudienceRefresh" }, "examples": { "illustrative": { "summary": "Refresh the Leeds audience", "value": { "audience_id": "aud_01JB4H2K9V6XN3M9R6T1Y5W8ZA", "previous": { "count_id": "cnt_7K2PQ4MAXN3R6TBY5WDZ", "dataset_version": "2026-W39", "contacts": 12840, "companies": 3115, "emailable": 12310, "counted_at": "2026-09-26T10:14:00Z" }, "current": { "count_id": "cnt_Q3N5X2M7K4P6R2T4V4W6", "dataset_version": "2026-W40", "contacts": 13054, "companies": 3160, "emailable": 12520, "counted_at": "2026-10-05T06:00:00Z" }, "diff": { "contacts": 214, "companies": 45, "emailable": 210, "new_records": 231, "removed_records": 17 } } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/RateLimited" }, "default": { "$ref": "#/components/responses/ServerError" } }, "x-cost-credits": 0, "x-free": true, "x-anonymous": false } }, "/quotes": { "post": { "operationId": "createQuote", "summary": "Quote an order", "description": "A signed machine quote for a count, field set, quantity and licence: records after overlap and suppression, credits per record, credits, the GBP price, the balance after, the licence and warranty, and blockers. Valid 24 hours and bound to a dataset version and the caller's organisation. Free, and needs no account. This is not a human sales quote, which is a 14 day PDF made in the app.", "tags": [ "Quotes" ], "security": [ {}, { "OAuth2": [ "quotes:read" ] }, { "ApiKey": [ "quotes:read" ] } ], "parameters": [ { "$ref": "#/components/parameters/MyDataHubVersion" }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/QuoteRequest" }, "examples": { "spec": { "summary": "5,000 of the Leeds records on the standard field set", "value": { "count_id": "cnt_7K2PQ4MAXN3R6TBY5WDZ", "field_set": "standard", "limit": 5000, "dedupe_against": "previous_orders", "licence": "multi_use_12m" } } } } } }, "responses": { "201": { "description": "The machine quote.", "headers": { "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" }, "Location": { "$ref": "#/components/headers/Location" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MachineQuote" }, "examples": { "spec": { "summary": "5,000 of the Leeds records on the standard field set", "value": { "id": "qte_01JB4M2R6T1Y5W8ZAK8Q2V7XN3", "kind": "machine", "dataset_version": "2026-W39", "records": 5000, "removed": { "already_held": 312, "suppressed": 41 }, "credits_required": 5000, "credits_available": 6200, "gbp_ex_vat": 1249, "licence": { "type": "multi_use_12m", "reuse_until": "2027-09-26", "resale_prohibited": true, "permitted_channels": [ "email", "telephone", "post" ], "warranty_url": "https://emailmovers.com/trust/warranty", "terms_version": "2026-09" }, "warranty": { "policy": "replace_over_threshold_hard_bounce", "threshold_percent": 10, "url": "https://emailmovers.com/trust/warranty" }, "expires_at": "2026-09-27T10:14:00Z", "blockers": [], "organisation_id": "org_01JA0Q2V7XN3M9R6T1Y5W8ZAK8", "count_id": "cnt_7K2PQ4MAXN3R6TBY5WDZ", "credits_per_record": 1, "balance_after": 1200, "purchase": { "credits_to_buy": 0, "cheapest": null, "gbp_ex_vat": 0, "options": [] }, "signature": { "alg": "ES256", "kid": "qte-2026-09", "jwks_url": "https://mydatahub.emailmovers.com/.well-known/jwks.json", "jws": "eyJhbGciOiJFUzI1NiIsImtpZCI6InF0ZS0yMDI2LTA5In0.eyJpZCI6InF0ZV8wMUpCNE0yUjZUMVk1VzhaQUs4UTJWN1hOMyJ9.MEUCIQDexampleSignatureOnly" } } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "409": { "$ref": "#/components/responses/Conflict" }, "422": { "$ref": "#/components/responses/ValidationFailed" }, "429": { "$ref": "#/components/responses/RateLimited" }, "default": { "$ref": "#/components/responses/ServerError" } }, "x-cost-credits": 0, "x-free": true, "x-anonymous": true, "x-idempotency-key": "optional", "x-mcp-tool": "quote_order" } }, "/quotes/{id}": { "get": { "operationId": "getQuote", "summary": "Get a quote", "description": "A machine quote (kind machine, 24 hours) or a human sales quote (kind sales, 14 days). An agent in the same organisation can settle another agent's machine quote after checking its signature, dataset version and expiry; outside the organisation, re-quote.", "tags": [ "Quotes" ], "security": [ {}, { "OAuth2": [ "quotes:read" ] }, { "ApiKey": [ "quotes:read" ] } ], "parameters": [ { "$ref": "#/components/parameters/MyDataHubVersion" }, { "name": "id", "in": "path", "required": true, "description": "Format: a quote id: qte_ followed by a 26 character ULID in upper case Crockford base32, such as qte_01JB4M2R6T1Y5W8ZAK8Q2V7XN3.", "schema": { "type": "string", "pattern": "^qte_[0-7][0-9A-HJKMNP-TV-Z]{25}$", "examples": [ "qte_01JB4M2R6T1Y5W8ZAK8Q2V7XN3" ] }, "example": "qte_01JB4P2V7XN3M9R6T1Y5W8ZAK8" } ], "responses": { "200": { "description": "The quote.", "headers": { "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Quote" }, "examples": { "illustrative": { "summary": "A human sales quote", "value": { "id": "qte_01JB4P2V7XN3M9R6T1Y5W8ZAK8", "kind": "sales", "status": "sent", "created_at": "2026-09-26T11:00:00Z", "valid_until": "2026-10-10", "created_by": { "role": "account_manager", "name": "Jordan Hale" }, "customer": "Example Agency Ltd", "count_id": "cnt_7K2PQ4MAXN3R6TBY5WDZ", "field_set": "standard", "records": 12310, "credits_per_record": 1, "lines": [ { "description": "12,310 UK records, standard field set, 12-month multi-use licence", "quantity": 12310, "unit_price_gbp": 0.22, "amount_gbp": 2708.2 } ], "subtotal_gbp_ex_vat": 2708.2, "vat_gbp": 541.64, "total_gbp_inc_vat": 3249.84, "balance_after": 6200, "licence": { "type": "multi_use_12m", "reuse_until": "2027-09-26", "resale_prohibited": true, "permitted_channels": [ "email", "telephone", "post" ], "warranty_url": "https://emailmovers.com/trust/warranty", "terms_version": "2026-09" }, "warranty": { "policy": "replace_over_threshold_hard_bounce", "threshold_percent": 10, "url": "https://emailmovers.com/trust/warranty" }, "payment_methods": [ "card", "invoice" ], "pay_url": "https://mydatahub.emailmovers.com/quotes/qte_01JB4P2V7XN3M9R6T1Y5W8ZAK8/pay", "pdf_url": "https://mydatahub.emailmovers.com/quotes/qte_01JB4P2V7XN3M9R6T1Y5W8ZAK8.pdf" } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/RateLimited" }, "default": { "$ref": "#/components/responses/ServerError" } }, "x-cost-credits": 0, "x-free": true, "x-anonymous": true } }, "/orders": { "post": { "operationId": "createOrder", "summary": "Create an order (spends credits)", "description": "Spend credits against a live machine quote: 1 credit per complete UK record. Needs the quote_id plus a human confirmation (MCP elicitation, the confirmation_token from the approval page, or a person ordering in the app itself) or a pre-authorised agent key within its per-order cap and monthly budget; a model-set confirmed flag is never consent. A standard API key or an OAuth token with no confirmation gets 403 confirmation-required carrying the approval_url, and nothing is charged. Idempotent on quote_id plus the Idempotency-Key header, so a retry never double charges. Returns 402 with the machine quote and a top_up_url when the balance is short, 403 agent-budget-exceeded when a key's limits do not cover it, 403 business-details-required when an account made by self-serve sign-up has not yet confirmed its business name and that it is a UK business (PATCH /v1/account), and 403 licence-acceptance-required, with the approval_url, when the Data Licence and Sharing Agreement in force was not accepted (licence_accepted_version from a person in the app, the approval page's token, or the agent key's own acceptance). Lawful basis for named work emails is UK GDPR Article 6(1)(f) legitimate interests; sole traders and ordinary partnerships are individual subscribers and are left out of email audiences by default.", "tags": [ "Orders" ], "security": [ { "OAuth2": [ "orders:write" ] }, { "ApiKey": [ "orders:write" ] } ], "parameters": [ { "$ref": "#/components/parameters/MyDataHubVersion" }, { "$ref": "#/components/parameters/IdempotencyKeyRequired" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OrderRequest" }, "examples": { "spec": { "summary": "Order the quoted 5,000 records", "value": { "quote_id": "qte_01JB4M2R6T1Y5W8ZAK8Q2V7XN3", "name": "Leeds marketing Q4", "delivery": [ "api", "csv" ] } } } } } }, "responses": { "202": { "description": "The order, queued.", "headers": { "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" }, "Location": { "$ref": "#/components/headers/Location" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Order" }, "examples": { "spec": { "summary": "Order the quoted 5,000 records", "value": { "id": "ord_01JB4N9S3W2X6Y7Z8A1B2C3D4E", "status": "queued", "credits_charged": 5000, "records": 5000, "confirmed_by": { "method": "agent_key", "key_id": "key_01JB3Z4Q2V7XN3M9R6T1Y5W8ZA", "client_id": "https://claude.ai/oauth/claude-code-client-metadata" }, "records_url": "/v1/orders/ord_01JB4N9S3W2X6Y7Z8A1B2C3D4E/records", "quote_id": "qte_01JB4M2R6T1Y5W8ZAK8Q2V7XN3", "count_id": "cnt_7K2PQ4MAXN3R6TBY5WDZ", "credits_remaining": 1200, "cost_gbp": 1495, "licence_expires_at": "2027-09-26", "licence": { "type": "multi_use_12m", "reuse_until": "2027-09-26", "resale_prohibited": true, "permitted_channels": [ "email", "telephone", "post" ], "warranty_url": "https://emailmovers.com/trust/warranty", "terms_version": "2026-09" } } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "402": { "$ref": "#/components/responses/InsufficientCredits" }, "403": { "$ref": "#/components/responses/Forbidden" }, "409": { "$ref": "#/components/responses/Conflict" }, "422": { "$ref": "#/components/responses/ValidationFailed" }, "429": { "$ref": "#/components/responses/RateLimited" }, "default": { "$ref": "#/components/responses/ServerError" } }, "x-cost-credits": 1, "x-cost-unit": "record", "x-cost-note": "1 credit per complete UK record (uk_contacts). Suppressed, duplicate and already held records cost 0.", "x-free": false, "x-anonymous": false, "x-idempotency-key": "required", "x-mcp-tool": "create_order" }, "get": { "operationId": "listOrders", "summary": "List orders", "description": "Recent orders with status, counts and links, newest first.", "tags": [ "Orders" ], "security": [ { "OAuth2": [ "orders:read" ] }, { "ApiKey": [ "orders:read" ] } ], "parameters": [ { "$ref": "#/components/parameters/MyDataHubVersion" }, { "name": "status", "in": "query", "required": false, "description": "queued, building, verifying, ready; failed if processing failed; cancelled (only while queued).", "schema": { "type": "string", "enum": [ "queued", "building", "verifying", "ready", "failed", "cancelled" ] } }, { "name": "limit", "in": "query", "required": false, "description": "Items per page, 1 to 100. Default 25.", "schema": { "default": 25, "type": "integer", "minimum": 1, "maximum": 100 } }, { "name": "cursor", "in": "query", "required": false, "description": "An opaque cursor from next_cursor. Pass it back unchanged.", "schema": { "type": "string", "minLength": 1, "maxLength": 512 } } ], "responses": { "200": { "description": "A page of orders.", "headers": { "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OrderList" }, "examples": { "illustrative": { "summary": "Recent orders", "value": { "data": [ { "id": "ord_01JB4N9S3W2X6Y7Z8A1B2C3D4E", "status": "ready", "credits_charged": 5000, "records": 5000, "confirmed_by": { "method": "agent_key", "key_id": "key_01JB3Z4Q2V7XN3M9R6T1Y5W8ZA", "client_id": "https://claude.ai/oauth/claude-code-client-metadata", "user_agent": "claude-code/2.1", "mtls_certificate_fingerprint": null, "web_bot_auth_signature_agent": null, "confirmed_at": "2026-09-26T10:16:00Z" }, "records_url": "/v1/orders/ord_01JB4N9S3W2X6Y7Z8A1B2C3D4E/records", "quote_id": "qte_01JB4M2R6T1Y5W8ZAK8Q2V7XN3", "count_id": "cnt_7K2PQ4MAXN3R6TBY5WDZ", "credits_remaining": 1200, "cost_gbp": 1495, "licence_expires_at": "2027-09-26", "licence": { "type": "multi_use_12m", "reuse_until": "2027-09-26", "resale_prohibited": true, "permitted_channels": [ "email", "telephone", "post" ], "warranty_url": "https://emailmovers.com/trust/warranty", "terms_version": "2026-09" }, "name": "Leeds marketing Q4", "dataset_version": "2026-W39", "field_set": "standard", "delivery": [ "api", "csv" ], "verification": { "checked": 5000, "passed": 4962, "replaced": 38 }, "download_url": "/v1/orders/ord_01JB4N9S3W2X6Y7Z8A1B2C3D4E/download", "receipt_url": "/v1/orders/ord_01JB4N9S3W2X6Y7Z8A1B2C3D4E/receipt", "validation_report": { "pdf_url": "https://mydatahub.emailmovers.com/orders/ord_01JB4N9S3W2X6Y7Z8A1B2C3D4E/validation-report.pdf", "json_url": "https://mydatahub.emailmovers.com/orders/ord_01JB4N9S3W2X6Y7Z8A1B2C3D4E/validation-report.json" }, "buyer_kit": { "draft_lia_url": "https://mydatahub.emailmovers.com/orders/ord_01JB4N9S3W2X6Y7Z8A1B2C3D4E/kit/lia", "first_email_wording_url": "https://mydatahub.emailmovers.com/orders/ord_01JB4N9S3W2X6Y7Z8A1B2C3D4E/kit/first-email", "article30_stub_url": "https://mydatahub.emailmovers.com/orders/ord_01JB4N9S3W2X6Y7Z8A1B2C3D4E/kit/article30", "due_diligence_file_url": "https://mydatahub.emailmovers.com/orders/ord_01JB4N9S3W2X6Y7Z8A1B2C3D4E/kit/due-diligence" }, "created_at": "2026-09-26T10:16:00Z", "ready_at": "2026-09-26T10:16:04Z", "failure": null } ], "has_more": false, "next_cursor": null } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "422": { "$ref": "#/components/responses/ValidationFailed" }, "429": { "$ref": "#/components/responses/RateLimited" }, "default": { "$ref": "#/components/responses/ServerError" } }, "x-cost-credits": 0, "x-free": true, "x-anonymous": false, "x-mcp-tool": "get_order" } }, "/orders/{id}": { "get": { "operationId": "getOrder", "summary": "Get an order", "description": "Status (queued, building, verifying, ready, failed, cancelled), counts, charges, the licence, the buyer kit and the links to records, download and receipt.", "tags": [ "Orders" ], "security": [ { "OAuth2": [ "orders:read" ] }, { "ApiKey": [ "orders:read" ] } ], "parameters": [ { "$ref": "#/components/parameters/MyDataHubVersion" }, { "name": "id", "in": "path", "required": true, "description": "Format: an order id: ord_ followed by a 26 character ULID in upper case Crockford base32, such as ord_01JB4N9S3W2X6Y7Z8A1B2C3D4E.", "schema": { "type": "string", "pattern": "^ord_[0-7][0-9A-HJKMNP-TV-Z]{25}$", "examples": [ "ord_01JB4N9S3W2X6Y7Z8A1B2C3D4E" ] }, "example": "ord_01JB4N9S3W2X6Y7Z8A1B2C3D4E" } ], "responses": { "200": { "description": "The order.", "headers": { "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Order" }, "examples": { "illustrative": { "summary": "A ready order", "value": { "id": "ord_01JB4N9S3W2X6Y7Z8A1B2C3D4E", "status": "ready", "credits_charged": 5000, "records": 5000, "confirmed_by": { "method": "agent_key", "key_id": "key_01JB3Z4Q2V7XN3M9R6T1Y5W8ZA", "client_id": "https://claude.ai/oauth/claude-code-client-metadata", "user_agent": "claude-code/2.1", "mtls_certificate_fingerprint": null, "web_bot_auth_signature_agent": null, "confirmed_at": "2026-09-26T10:16:00Z" }, "records_url": "/v1/orders/ord_01JB4N9S3W2X6Y7Z8A1B2C3D4E/records", "quote_id": "qte_01JB4M2R6T1Y5W8ZAK8Q2V7XN3", "count_id": "cnt_7K2PQ4MAXN3R6TBY5WDZ", "credits_remaining": 1200, "cost_gbp": 1495, "licence_expires_at": "2027-09-26", "licence": { "type": "multi_use_12m", "reuse_until": "2027-09-26", "resale_prohibited": true, "permitted_channels": [ "email", "telephone", "post" ], "warranty_url": "https://emailmovers.com/trust/warranty", "terms_version": "2026-09" }, "name": "Leeds marketing Q4", "dataset_version": "2026-W39", "field_set": "standard", "delivery": [ "api", "csv" ], "verification": { "checked": 5000, "passed": 4962, "replaced": 38 }, "download_url": "/v1/orders/ord_01JB4N9S3W2X6Y7Z8A1B2C3D4E/download", "receipt_url": "/v1/orders/ord_01JB4N9S3W2X6Y7Z8A1B2C3D4E/receipt", "validation_report": { "pdf_url": "https://mydatahub.emailmovers.com/orders/ord_01JB4N9S3W2X6Y7Z8A1B2C3D4E/validation-report.pdf", "json_url": "https://mydatahub.emailmovers.com/orders/ord_01JB4N9S3W2X6Y7Z8A1B2C3D4E/validation-report.json" }, "buyer_kit": { "draft_lia_url": "https://mydatahub.emailmovers.com/orders/ord_01JB4N9S3W2X6Y7Z8A1B2C3D4E/kit/lia", "first_email_wording_url": "https://mydatahub.emailmovers.com/orders/ord_01JB4N9S3W2X6Y7Z8A1B2C3D4E/kit/first-email", "article30_stub_url": "https://mydatahub.emailmovers.com/orders/ord_01JB4N9S3W2X6Y7Z8A1B2C3D4E/kit/article30", "due_diligence_file_url": "https://mydatahub.emailmovers.com/orders/ord_01JB4N9S3W2X6Y7Z8A1B2C3D4E/kit/due-diligence" }, "created_at": "2026-09-26T10:16:00Z", "ready_at": "2026-09-26T10:16:04Z", "failure": null } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/RateLimited" }, "default": { "$ref": "#/components/responses/ServerError" } }, "x-cost-credits": 0, "x-free": true, "x-anonymous": false, "x-mcp-tool": "get_order" } }, "/orders/{id}/cancel": { "post": { "operationId": "cancelOrder", "summary": "Cancel a queued order", "description": "Cancel an order while it is queued; its credits are refunded in full. Later statuses return 409.", "tags": [ "Orders" ], "security": [ { "OAuth2": [ "orders:write" ] }, { "ApiKey": [ "orders:write" ] } ], "parameters": [ { "$ref": "#/components/parameters/MyDataHubVersion" }, { "$ref": "#/components/parameters/IdempotencyKey" }, { "name": "id", "in": "path", "required": true, "description": "Format: an order id: ord_ followed by a 26 character ULID in upper case Crockford base32, such as ord_01JB4N9S3W2X6Y7Z8A1B2C3D4E.", "schema": { "type": "string", "pattern": "^ord_[0-7][0-9A-HJKMNP-TV-Z]{25}$", "examples": [ "ord_01JB4N9S3W2X6Y7Z8A1B2C3D4E" ] }, "example": "ord_01JB4N9S3W2X6Y7Z8A1B2C3D4E" } ], "responses": { "200": { "description": "The cancelled order.", "headers": { "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Order" }, "examples": { "illustrative": { "summary": "Cancel a queued order", "value": { "id": "ord_01JB4N9S3W2X6Y7Z8A1B2C3D4E", "status": "cancelled", "credits_charged": 0, "records": 5000, "confirmed_by": { "method": "agent_key", "key_id": "key_01JB3Z4Q2V7XN3M9R6T1Y5W8ZA", "client_id": "https://claude.ai/oauth/claude-code-client-metadata" }, "records_url": "/v1/orders/ord_01JB4N9S3W2X6Y7Z8A1B2C3D4E/records", "quote_id": "qte_01JB4M2R6T1Y5W8ZAK8Q2V7XN3", "count_id": "cnt_7K2PQ4MAXN3R6TBY5WDZ", "credits_remaining": 6200, "cost_gbp": 0, "licence_expires_at": "2027-09-26", "licence": { "type": "multi_use_12m", "reuse_until": "2027-09-26", "resale_prohibited": true, "permitted_channels": [ "email", "telephone", "post" ], "warranty_url": "https://emailmovers.com/trust/warranty", "terms_version": "2026-09" } } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "429": { "$ref": "#/components/responses/RateLimited" }, "default": { "$ref": "#/components/responses/ServerError" } }, "x-cost-credits": 0, "x-free": true, "x-anonymous": false, "x-idempotency-key": "optional" } }, "/orders/{id}/receipt": { "get": { "operationId": "getComplianceReceipt", "summary": "Get the compliance receipt", "description": "The order's compliance receipt as an ES256 JWS with its decoded claims and a PDF twin: records delivered, suppression removals, counts by subscriber class, TPS status and Article 14 status, the licence and the file hash.", "tags": [ "Orders" ], "security": [ { "OAuth2": [ "orders:read" ] }, { "ApiKey": [ "orders:read" ] } ], "parameters": [ { "$ref": "#/components/parameters/MyDataHubVersion" }, { "name": "id", "in": "path", "required": true, "description": "Format: an order id: ord_ followed by a 26 character ULID in upper case Crockford base32, such as ord_01JB4N9S3W2X6Y7Z8A1B2C3D4E.", "schema": { "type": "string", "pattern": "^ord_[0-7][0-9A-HJKMNP-TV-Z]{25}$", "examples": [ "ord_01JB4N9S3W2X6Y7Z8A1B2C3D4E" ] }, "example": "ord_01JB4N9S3W2X6Y7Z8A1B2C3D4E" } ], "responses": { "200": { "description": "The receipt.", "headers": { "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ComplianceReceipt" }, "examples": { "illustrative": { "summary": "Receipt for the Leeds order", "value": { "id": "rcpt_01JB4NA2Q5W8ZAK8Q2V7XN3M9R", "order_id": "ord_01JB4N9S3W2X6Y7Z8A1B2C3D4E", "jws": "eyJhbGciOiJFUzI1NiIsImtpZCI6InJjcHQtMjAyNi0wOSJ9.eyJyZWNlaXB0X2lkIjoicmNwdF8wMUpCNE5BMlE1VzhaQUs4UTJWN1hOM005UiJ9.MEUCIQDexampleSignatureOnly", "alg": "ES256", "kid": "rcpt-2026-09", "jwks_url": "https://mydatahub.emailmovers.com/.well-known/jwks.json", "pdf_url": "https://mydatahub.emailmovers.com/receipts/rcpt_01JB4NA2Q5W8ZAK8Q2V7XN3M9R", "claims": { "receipt_id": "rcpt_01JB4NA2Q5W8ZAK8Q2V7XN3M9R", "order_id": "ord_01JB4N9S3W2X6Y7Z8A1B2C3D4E", "issued_at": "2026-09-26T10:16:04Z", "dataset_version": "2026-W39", "records_delivered": 5000, "removed_by_suppression": 41, "counts": { "subscriber_class": { "ltd": 4610, "plc": 120, "llp": 180, "scottish_partnership": 0, "public_body": 60, "charity_incorporated": 30, "sole_trader": 0, "ordinary_partnership": 0, "unknown": 0 }, "tps_ctps_status": { "clear": 4380, "tps_registered": 0, "ctps_registered": 0, "tps_or_ctps_registered": 0, "not_screened": 620 }, "article14_status": { "notified": 4990, "publicly_notified_disproportionate_effort": 0, "pending_within_window": 10 } }, "lawful_basis": "legitimate_interests_art6_1_f", "lia_ref": "EM-LIA-2026-03", "licence": { "type": "multi_use_12m", "reuse_until": "2027-09-26", "resale_prohibited": true, "permitted_channels": [ "email", "telephone", "post" ], "warranty_url": "https://emailmovers.com/trust/warranty", "terms_version": "2026-09" }, "residency_statement_version": "2026-10", "sub_processor_list_version": "2026-10", "verified_within_days": { "within_30_days": 61.2, "within_60_days": 79.5, "within_90_days": 88.4 }, "content_sha256": "3a7bd3e2360a3d29eea436fcfb7e44c735d117c42d1c1835420b6b9942dd4f1b" } } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "429": { "$ref": "#/components/responses/RateLimited" }, "default": { "$ref": "#/components/responses/ServerError" } }, "x-cost-credits": 0, "x-free": true, "x-anonymous": false, "x-mcp-tool": "get_compliance_receipt" } }, "/orders/{id}/records": { "get": { "operationId": "listOrderRecords", "summary": "Fetch order records", "description": "Delivered records in token-budgeted pages (default 50, up to 500), as JSON with the licence block on every page or as CSV. Fetching again under licence costs 0 credits.", "tags": [ "Records" ], "security": [ { "OAuth2": [ "records:read" ] }, { "ApiKey": [ "records:read" ] } ], "parameters": [ { "$ref": "#/components/parameters/MyDataHubVersion" }, { "name": "id", "in": "path", "required": true, "description": "Format: an order id: ord_ followed by a 26 character ULID in upper case Crockford base32, such as ord_01JB4N9S3W2X6Y7Z8A1B2C3D4E.", "schema": { "type": "string", "pattern": "^ord_[0-7][0-9A-HJKMNP-TV-Z]{25}$", "examples": [ "ord_01JB4N9S3W2X6Y7Z8A1B2C3D4E" ] }, "example": "ord_01JB4N9S3W2X6Y7Z8A1B2C3D4E" }, { "name": "cursor", "in": "query", "required": false, "description": "An opaque cursor from next_cursor. Pass it back unchanged.", "schema": { "type": "string", "minLength": 1, "maxLength": 512 } }, { "name": "limit", "in": "query", "required": false, "description": "Records per page, 1 to 500. Default 50.", "schema": { "default": 50, "type": "integer", "minimum": 1, "maximum": 500 }, "example": 50 }, { "name": "format", "in": "query", "required": false, "description": "json (default) or csv.", "schema": { "default": "json", "type": "string", "enum": [ "json", "csv" ] } }, { "name": "fields", "in": "query", "required": false, "description": "Columns to return, comma separated; default the order's field set.", "schema": { "type": "array", "items": { "type": "string", "pattern": "^[a-z0-9_]+$" } }, "style": "form", "explode": false } ], "responses": { "200": { "description": "A page of records.", "headers": { "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RecordsPage" }, "examples": { "illustrative": { "summary": "The first page of the Leeds order", "value": { "order_id": "ord_01JB4N9S3W2X6Y7Z8A1B2C3D4E", "format": "json", "fields": [ "first_name", "last_name", "title", "email", "phone", "company_name", "postcode" ], "data": [ { "id": "contact_01JA9X2V7XN3M9R6T1Y5W8ZAK8", "dataset_version": "2026-W39", "contact": { "first_name": "Jo", "last_name": "Example", "title": "Marketing Director", "title_family": "Marketing Director", "job_function": "Marketing", "job_level_rank": 6, "job_level": "Director" }, "email": { "address": "jo.example@example.co.uk", "type": "named", "deliverability_score": 88, "verified_at": "2026-09-10", "result": "ok" }, "phone": { "e164": "+441130000001", "line_type": "landline", "tps_ctps_status": "clear", "screened_at": "2026-09-12" }, "company": { "name": "Example Manufacturing Ltd", "companies_house_number": "12345678", "status": "active", "type": "ltd", "subscriber_class": "ltd", "sic_2007": [ { "code": "25620", "label": "Machining" } ], "employee_band": "100-199", "turnover_band": "11M-20M", "website_domain": "example.co.uk" }, "site": { "address_lines": [ "1 Example Street" ], "town": "Leeds", "county": "West Yorkshire", "postcode": "LS11 5AA", "region": "yorkshire_and_the_humber" }, "compliance": { "lawful_basis": "legitimate_interests_art6_1_f", "lia_ref": "EM-LIA-2026-03", "subscriber_class": "ltd", "corporate_subscriber": true, "email_marketing_basis": "pecr_corporate_subscriber", "subscriber_evidence": { "companies_house_number": "12345678", "company_type": "ltd" }, "article14_status": "notified", "article14_notified_at": "2026-06-14", "notice_version": "2026-02", "provenance": { "company": { "source": "companies_house", "as_of": "2026-09-21" }, "contact": { "source": "emailmovers_research", "compiled_at": "2026-05-02", "last_verified_at": "2026-08-30", "method": "telephone" }, "email": { "verified_at": "2026-09-10", "result": "ok", "provider_location": "EU" } }, "tps_ctps_status": "clear", "tps_ctps_screened_at": "2026-09-12", "tps_ctps_valid_until": "2026-10-10", "suppression_status": "none", "record_age_days": 147, "attribution": "Contains public sector information licensed under the Open Government Licence v3.0" }, "licence_expires_at": "2027-09-26" } ], "has_more": true, "next_cursor": "b3JkXzAxSkI0TjlTM1cyWDZZN1o4QTFCMkMzRDRFOjUw", "remaining": 4950, "approx_tokens": 7400, "licence": { "type": "multi_use_12m", "reuse_until": "2027-09-26", "resale_prohibited": true, "permitted_channels": [ "email", "telephone", "post" ], "warranty_url": "https://emailmovers.com/trust/warranty", "terms_version": "2026-09" } } } } }, "text/csv": { "schema": { "type": "string", "description": "CSV with a header row; compliance fields as columns." }, "example": "mydatahub_record_id,first_name,last_name,title,email,company_name,postcode,lawful_basis,article14_status\ncontact_01JA9X2V7XN3M9R6T1Y5W8ZAK8,Jo,Example,Marketing Director,jo.example@example.co.uk,Example Manufacturing Ltd,LS11 5AA,legitimate_interests_art6_1_f,notified\n" } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "422": { "$ref": "#/components/responses/ValidationFailed" }, "429": { "$ref": "#/components/responses/RateLimited" }, "default": { "$ref": "#/components/responses/ServerError" } }, "x-cost-credits": 0, "x-free": true, "x-anonymous": false, "x-mcp-tool": "fetch_order_records" } }, "/orders/{id}/download": { "get": { "operationId": "downloadOrder", "summary": "Download order records", "description": "Redirects to a single-use signed URL for the CSV that lives 5 minutes, bound to the account and logged. Re-downloads under licence cost 0 credits.", "tags": [ "Records" ], "security": [ { "OAuth2": [ "records:read" ] }, { "ApiKey": [ "records:read" ] } ], "parameters": [ { "$ref": "#/components/parameters/MyDataHubVersion" }, { "name": "id", "in": "path", "required": true, "description": "Format: an order id: ord_ followed by a 26 character ULID in upper case Crockford base32, such as ord_01JB4N9S3W2X6Y7Z8A1B2C3D4E.", "schema": { "type": "string", "pattern": "^ord_[0-7][0-9A-HJKMNP-TV-Z]{25}$", "examples": [ "ord_01JB4N9S3W2X6Y7Z8A1B2C3D4E" ] }, "example": "ord_01JB4N9S3W2X6Y7Z8A1B2C3D4E" } ], "responses": { "302": { "description": "Found: follow Location to the signed file.", "headers": { "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" }, "Location": { "$ref": "#/components/headers/Location" } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "429": { "$ref": "#/components/responses/RateLimited" }, "default": { "$ref": "#/components/responses/ServerError" } }, "x-cost-credits": 0, "x-free": true, "x-anonymous": false } }, "/companies/lookup": { "post": { "operationId": "lookupCompany", "summary": "Look up a company", "description": "Companies House fields for one company, by number, domain or name, and for signed-in callers the contacts we hold there by job level (a single company count needs an account and is logged; signed out, the counts are null). No contact details, and no charge (to confirm).", "tags": [ "Lookups" ], "security": [ {}, { "OAuth2": [ "counts:read" ] }, { "ApiKey": [ "counts:read" ] } ], "parameters": [ { "$ref": "#/components/parameters/MyDataHubVersion" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CompanyLookupRequest" }, "examples": { "illustrative": { "summary": "By Companies House number", "value": { "company_number": "12345678" } } } } } }, "responses": { "200": { "description": "The company.", "headers": { "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CompanyLookup" }, "examples": { "illustrative": { "summary": "By Companies House number", "value": { "match_confidence": 1, "dataset_version": "2026-W39", "company": { "companies_house_number": "12345678", "name": "Example Manufacturing Ltd", "status": "active", "type": "ltd", "subscriber_class": "ltd", "incorporation_date": "2004-02-19", "sic_2007": [ { "code": "25620", "label": "Machining" } ], "employee_band": "100-199", "turnover_band": "11M-20M", "website_domain": "example.co.uk", "registered_office": { "town": "Leeds", "postcode": "LS11 5AA" } }, "contacts_held": 14, "contacts_by_level": [ { "level": "Director", "contacts": 3 }, { "level": "Manager", "contacts": 6 } ], "compliance": { "lawful_basis": "legitimate_interests_art6_1_f", "subscriber_class": "ltd", "corporate_subscriber": true, "email_marketing_basis": "pecr_corporate_subscriber", "subscriber_evidence": { "companies_house_number": "12345678", "company_type": "ltd" }, "provenance": { "company": { "source": "companies_house", "as_of": "2026-09-21" } }, "attribution": "Contains public sector information licensed under the Open Government Licence v3.0" }, "disclosure": { "level": "exact", "rounded_to": null, "secondary_suppression": false, "notes": [] }, "credits_charged": 0 } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "422": { "$ref": "#/components/responses/ValidationFailed" }, "429": { "$ref": "#/components/responses/RateLimited" }, "default": { "$ref": "#/components/responses/ServerError" } }, "x-cost-credits": 0, "x-free": true, "x-anonymous": true, "x-mcp-tool": "lookup_company" } }, "/contacts/enrich": { "post": { "operationId": "enrichContact", "summary": "Enrich a contact (spends credits)", "description": "The full record for one known person, by email or by name and company. Charges 1 credit only on a confident match, and 0 when you already hold the record under licence or nothing matches. It spends, so it needs a human confirmation (MCP elicitation or a confirmation_token) or an agent key whose allowed_tools include enrich_contact, within its per-order cap and remaining monthly budget; otherwise 403 confirmation-required or agent-budget-exceeded, and 402 when the balance is short. An account made by self-serve sign-up confirms its business name and that it is a UK business first (PATCH /v1/account), or the answer is 403 business-details-required. The record comes under the Data Licence and Sharing Agreement, so the version in force is accepted as for an order, or the answer is 403 licence-acceptance-required with the approval_url. Nothing is charged on a refusal. Lawful basis for named work emails is UK GDPR Article 6(1)(f) legitimate interests; sole traders and ordinary partnerships are individual subscribers and are left out of email audiences by default.", "tags": [ "Lookups" ], "security": [ { "OAuth2": [ "enrich:write" ] }, { "ApiKey": [ "enrich:write" ] } ], "parameters": [ { "$ref": "#/components/parameters/MyDataHubVersion" }, { "$ref": "#/components/parameters/IdempotencyKeyRequired" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EnrichRequest" }, "examples": { "illustrative": { "summary": "Enrich by name and company number", "value": { "first_name": "Jo", "last_name": "Example", "company_number": "12345678" } } } } } }, "responses": { "200": { "description": "The match, or no match.", "headers": { "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Enrichment" }, "examples": { "illustrative": { "summary": "Enrich by name and company number", "value": { "matched": true, "match_confidence": 0.97, "already_licensed": false, "record": { "id": "contact_01JA9X2V7XN3M9R6T1Y5W8ZAK8", "dataset_version": "2026-W39", "contact": { "first_name": "Jo", "last_name": "Example", "title": "Marketing Director", "title_family": "Marketing Director", "job_function": "Marketing", "job_level_rank": 6, "job_level": "Director" }, "email": { "address": "jo.example@example.co.uk", "type": "named", "deliverability_score": 88, "verified_at": "2026-09-10", "result": "ok" }, "phone": { "e164": "+441130000001", "line_type": "landline", "tps_ctps_status": "clear", "screened_at": "2026-09-12" }, "company": { "name": "Example Manufacturing Ltd", "companies_house_number": "12345678", "status": "active", "type": "ltd", "subscriber_class": "ltd", "sic_2007": [ { "code": "25620", "label": "Machining" } ], "employee_band": "100-199", "turnover_band": "11M-20M", "website_domain": "example.co.uk" }, "site": { "address_lines": [ "1 Example Street" ], "town": "Leeds", "county": "West Yorkshire", "postcode": "LS11 5AA", "region": "yorkshire_and_the_humber" }, "compliance": { "lawful_basis": "legitimate_interests_art6_1_f", "lia_ref": "EM-LIA-2026-03", "subscriber_class": "ltd", "corporate_subscriber": true, "email_marketing_basis": "pecr_corporate_subscriber", "subscriber_evidence": { "companies_house_number": "12345678", "company_type": "ltd" }, "article14_status": "notified", "article14_notified_at": "2026-06-14", "notice_version": "2026-02", "provenance": { "company": { "source": "companies_house", "as_of": "2026-09-21" }, "contact": { "source": "emailmovers_research", "compiled_at": "2026-05-02", "last_verified_at": "2026-08-30", "method": "telephone" }, "email": { "verified_at": "2026-09-10", "result": "ok", "provider_location": "EU" } }, "tps_ctps_status": "clear", "tps_ctps_screened_at": "2026-09-12", "tps_ctps_valid_until": "2026-10-10", "suppression_status": "none", "record_age_days": 147, "attribution": "Contains public sector information licensed under the Open Government Licence v3.0" }, "licence_expires_at": "2027-09-26" }, "credits_charged": 1, "credits_remaining": 1199, "cost_gbp": 0.3, "licence_expires_at": "2027-09-26" } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "402": { "$ref": "#/components/responses/InsufficientCredits" }, "403": { "$ref": "#/components/responses/Forbidden" }, "409": { "$ref": "#/components/responses/Conflict" }, "422": { "$ref": "#/components/responses/ValidationFailed" }, "429": { "$ref": "#/components/responses/RateLimited" }, "default": { "$ref": "#/components/responses/ServerError" } }, "x-cost-credits": 1, "x-cost-unit": "match", "x-cost-note": "1 credit on a confident match; 0 on no match or when already licensed.", "x-free": false, "x-anonymous": false, "x-idempotency-key": "required", "x-mcp-tool": "enrich_contact" } }, "/suppressions": { "get": { "operationId": "listSuppressions", "summary": "List suppression lists", "description": "The organisation's suppression lists. With since, only lists changed after that time, each with the records added since, so objections that reach records you hold can be pulled as well as received by webhook.", "tags": [ "Suppressions" ], "security": [ { "OAuth2": [ "suppressions:read" ] }, { "ApiKey": [ "suppressions:read" ] } ], "parameters": [ { "$ref": "#/components/parameters/MyDataHubVersion" }, { "name": "since", "in": "query", "required": false, "description": "Only lists changed after this time.", "schema": { "type": "string", "format": "date-time" } }, { "name": "limit", "in": "query", "required": false, "description": "Items per page, 1 to 100. Default 25.", "schema": { "default": 25, "type": "integer", "minimum": 1, "maximum": 100 } }, { "name": "cursor", "in": "query", "required": false, "description": "An opaque cursor from next_cursor. Pass it back unchanged.", "schema": { "type": "string", "minLength": 1, "maxLength": 512 } } ], "responses": { "200": { "description": "A page of suppression lists.", "headers": { "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SuppressionListPage" }, "examples": { "illustrative": { "summary": "One uploaded list", "value": { "data": [ { "id": "sup_01JB4H7Q2V7XN3M9R6T1Y5W8ZA", "name": "Existing customers", "kind": "email", "source": "upload", "row_count": 1198, "created_at": "2026-09-20T14:02:00Z", "updated_at": "2026-09-20T14:02:00Z", "created_by": "usr_01JA0Q3V7XN3M9R6T1Y5W8ZAK8" } ], "has_more": false, "next_cursor": null } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "422": { "$ref": "#/components/responses/ValidationFailed" }, "429": { "$ref": "#/components/responses/RateLimited" }, "default": { "$ref": "#/components/responses/ServerError" } }, "x-cost-credits": 0, "x-free": true, "x-anonymous": false }, "post": { "operationId": "createSuppressionList", "summary": "Upload a suppression list", "description": "Upload emails, domains, phones, company numbers or title terms, raw or already hashed. Values are normalised and stored as SHA-256 hashes only. The list applies to every later count and order at no charge, and each count reports what it removed. The organisation accepts the Article 28 data processing agreement in force first (POST /v1/account/agreements, or dpa_accepted_version on this upload from a signed-in person); until then the answer is 403 dpa-acceptance-required and nothing is uploaded.", "tags": [ "Suppressions" ], "security": [ { "OAuth2": [ "suppressions:write" ] }, { "ApiKey": [ "suppressions:write" ] } ], "parameters": [ { "$ref": "#/components/parameters/MyDataHubVersion" }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SuppressionListRequest" }, "examples": { "illustrative": { "summary": "Upload existing customers", "value": { "name": "Existing customers", "kind": "email", "values": [ "jo.example@example.co.uk", "sam@example.org" ] } } } } } }, "responses": { "201": { "description": "The saved list and what was read.", "headers": { "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" }, "Location": { "$ref": "#/components/headers/Location" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SuppressionUpload" }, "examples": { "illustrative": { "summary": "Upload existing customers", "value": { "list": { "id": "sup_01JB4H7Q2V7XN3M9R6T1Y5W8ZA", "name": "Existing customers", "kind": "email", "source": "upload", "row_count": 1198, "created_at": "2026-09-20T14:02:00Z", "updated_at": "2026-09-20T14:02:00Z", "created_by": "usr_01JA0Q3V7XN3M9R6T1Y5W8ZAK8" }, "rows_read": 1204, "rows_valid": 1198, "rows_skipped": [ { "row": 17, "reason": "Not an email address." } ] } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "409": { "$ref": "#/components/responses/Conflict" }, "422": { "$ref": "#/components/responses/ValidationFailed" }, "429": { "$ref": "#/components/responses/RateLimited" }, "default": { "$ref": "#/components/responses/ServerError" } }, "x-cost-credits": 0, "x-free": true, "x-anonymous": false, "x-idempotency-key": "optional" } }, "/suppressions/check": { "post": { "operationId": "checkSuppression", "summary": "Check suppression", "description": "Suppression status per record id, as of now. Run it before any send.", "tags": [ "Suppressions" ], "security": [ { "OAuth2": [ "suppressions:read" ] }, { "ApiKey": [ "suppressions:read" ] } ], "parameters": [ { "$ref": "#/components/parameters/MyDataHubVersion" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SuppressionCheckRequest" }, "examples": { "illustrative": { "summary": "Check one record", "value": { "record_ids": [ "contact_01JA9X2V7XN3M9R6T1Y5W8ZAK8" ] } } } } } }, "responses": { "200": { "description": "Status per record.", "headers": { "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SuppressionCheck" }, "examples": { "illustrative": { "summary": "Check one record", "value": { "checked_at": "2026-10-01T09:00:00Z", "results": [ { "record_id": "contact_01JA9X2V7XN3M9R6T1Y5W8ZAK8", "suppressed": false, "suppression_status": "none", "list_ids": [] } ] } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "422": { "$ref": "#/components/responses/ValidationFailed" }, "429": { "$ref": "#/components/responses/RateLimited" }, "default": { "$ref": "#/components/responses/ServerError" } }, "x-cost-credits": 0, "x-free": true, "x-anonymous": false, "x-mcp-tool": "check_suppression" } }, "/objections": { "post": { "operationId": "reportObjection", "summary": "Report an objection", "description": "Record an objection to direct marketing. Scope licensee suppresses the record for your organisation at once; scope emailmovers suppresses it database-wide within one working day and tells every licensee holding it.", "tags": [ "Suppressions" ], "security": [ { "OAuth2": [ "suppressions:write" ] }, { "ApiKey": [ "suppressions:write" ] } ], "parameters": [ { "$ref": "#/components/parameters/MyDataHubVersion" }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ObjectionRequest" }, "examples": { "illustrative": { "summary": "An objection received by email", "value": { "record_id": "contact_01JA9X2V7XN3M9R6T1Y5W8ZAK8", "channel": "email", "received_at": "2026-10-01T08:30:00Z", "scope": "emailmovers", "note": "Replied asking not to be contacted again." } } } } } }, "responses": { "201": { "description": "The suppression it created.", "headers": { "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Objection" }, "examples": { "illustrative": { "summary": "An objection received by email", "value": { "suppression_id": "sup_01JA0Q5V7XN3M9R6T1Y5W8ZAK8", "record_id": "contact_01JA9X2V7XN3M9R6T1Y5W8ZAK8", "scope": "emailmovers", "status": "pending", "suppressed_at": null, "effective_by": "2026-10-02T17:00:00Z" } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "409": { "$ref": "#/components/responses/Conflict" }, "422": { "$ref": "#/components/responses/ValidationFailed" }, "429": { "$ref": "#/components/responses/RateLimited" }, "default": { "$ref": "#/components/responses/ServerError" } }, "x-cost-credits": 0, "x-free": true, "x-anonymous": false, "x-idempotency-key": "optional", "x-mcp-tool": "report_objection" } }, "/trust": { "get": { "operationId": "getTrust", "summary": "Get the trust document", "description": "The trust page as data: ICO registration, lawful basis and LIA, privacy notice, residency statement, sub-processors, retention, complaints and security. Mirrored at https://mydatahub.emailmovers.com/trust.json.", "tags": [ "Compliance" ], "security": [], "parameters": [ { "$ref": "#/components/parameters/MyDataHubVersion" } ], "responses": { "200": { "description": "The trust document.", "headers": { "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TrustDocument" }, "examples": { "illustrative": { "summary": "The trust document", "value": { "updated_at": "2026-09-26T09:00:00Z", "company": { "legal_name": "Emailmovers Limited", "company_number": "05046417", "trading_as": "Emailmovers Ltd" }, "ico_registration": { "number": "Z9714386", "expires_on": "2026-12-18", "register_url": "https://ico.org.uk/ESDWebPages/Entry/Z9714386" }, "lawful_basis": { "basis": "legitimate_interests_art6_1_f", "lia_ref": "EM-LIA-2026-03", "lia_url": "https://emailmovers.com/trust/lia" }, "privacy_notice": { "version": "2026-02", "url": "https://emailmovers.com/trust/privacy-notice", "versions": [ { "version": "2026-02", "published_at": "2026-02-05", "url": "https://emailmovers.com/trust/privacy-notice/2026-02" } ] }, "residency": { "statement": "Data is held in the UK (Google Cloud London). Email addresses are verified in the EU by Millionverifier, with some verification traffic passing through US providers under standard contractual clauses. Telephone numbers are checked by Telnyx in the United States under the UK Extension to the Data Privacy Framework. Every telephone number is screened against the TPS and CTPS each night through a licensed screening service based in the UK, which processes the numbers in the UK. Payments are processed by Stripe.", "version": "2026-10" }, "sub_processors": { "version": "2026-10", "notice_days": 30, "notice_channels": [ "email", "webhook" ], "list": [ { "name": "Millionverifier", "purpose": "Email verification", "location": "EU (Hungary), some US network traffic", "transfer_mechanism": "Standard contractual clauses", "added_at": "2026-09-01" }, { "name": "Telnyx", "purpose": "Telephone line type checks", "location": "United States", "transfer_mechanism": "UK Extension to the Data Privacy Framework", "added_at": "2026-09-01" }, { "name": "A licensed TPS and CTPS screening service", "purpose": "TPS and CTPS screening of every telephone number each night", "location": "United Kingdom", "transfer_mechanism": "No transfer outside the UK", "added_at": "2026-10-18" } ], "changes": [ { "date": "2026-09-01", "name": "Telnyx", "change": "added", "summary": "Telephone line type and carrier checks at ingest and every 180 days." }, { "date": "2026-10-18", "name": "A licensed TPS and CTPS screening service", "change": "added", "summary": "Every telephone number screened against the TPS and CTPS each night, in the UK." } ] }, "retention": [ { "category": "Audit logs", "period": "Licence term plus 12 months", "status": "to_confirm" } ], "complaints": { "url": "https://emailmovers.com/trust/complaints", "email": null, "acknowledgement_days": 30 }, "data_protection_lead": null, "datasets": [ { "id": "uk_contacts", "name": "UK contacts", "status": "live", "owner": "Emailmovers Ltd", "source": "Emailmovers research; Companies House (OGL v3.0); ONSPD (OGL v3.0)", "licence": "12 month multi-use licence; resale prohibited", "refresh": "Immutable weekly build every Monday; same-day suppression overlay", "residency": "Held in the UK (Google Cloud London)", "regulator": "ICO", "warranty": "Replacement when hard bounces exceed 10 percent of an order", "credits_per_record": 1, "credits_status": "confirmed", "current_version": "2026-W39", "versions_available": 52 } ], "security": { "certifications": [ { "name": "Cyber Essentials", "status": "target", "date": "2026-10" }, { "name": "Cyber Essentials Plus", "status": "target", "date": "2027-01" } ], "encryption": { "at_rest": "AES-256", "in_transit_minimum": "TLS 1.2", "key_rotation": "KMS managed key rotation" }, "data_flow_diagram_url": null, "pen_test_summary_url": null, "caiq_url": null, "status_page": "https://status.emailmovers.com", "security_txt": "https://mydatahub.emailmovers.com/.well-known/security.txt" } } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "429": { "$ref": "#/components/responses/RateLimited" }, "default": { "$ref": "#/components/responses/ServerError" } }, "x-cost-credits": 0, "x-free": true, "x-anonymous": true } }, "/compliance/lia": { "get": { "operationId": "getLia", "summary": "Get the legitimate interests assessment", "description": "The published LIA (EM-LIA-2026-03) with its version history.", "tags": [ "Compliance" ], "security": [], "parameters": [ { "$ref": "#/components/parameters/MyDataHubVersion" } ], "responses": { "200": { "description": "The LIA.", "headers": { "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LiaDocument" }, "examples": { "illustrative": { "summary": "The current LIA", "value": { "ref": "EM-LIA-2026-03", "version": "2026-03", "published_at": "2026-11-30", "url": "https://emailmovers.com/trust/lia", "lawful_basis": "legitimate_interests_art6_1_f", "summary": "Emailmovers relies on UK GDPR Article 6(1)(f) legitimate interests for named business contacts, with direct marketing as an Article 6(1)(f) example since 5 February 2026.", "versions": [ { "ref": "EM-LIA-2026-03", "published_at": "2026-11-30", "url": "https://emailmovers.com/trust/lia" } ] } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "429": { "$ref": "#/components/responses/RateLimited" }, "default": { "$ref": "#/components/responses/ServerError" } }, "x-cost-credits": 0, "x-free": true, "x-anonymous": true } }, "/compliance/receipts/verify": { "post": { "operationId": "verifyComplianceReceipt", "summary": "Verify a compliance receipt", "description": "Check a receipt's JWS against the published key without an account, and learn whether the order exists, until when its licence is in force and whether it was revoked. One agent can prove to another that a list is licensed and screened. REST only.", "tags": [ "Compliance" ], "security": [], "parameters": [ { "$ref": "#/components/parameters/MyDataHubVersion" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ReceiptVerifyRequest" }, "examples": { "illustrative": { "summary": "A valid receipt", "value": { "jws": "eyJhbGciOiJFUzI1NiIsImtpZCI6InJjcHQtMjAyNi0wOSJ9.eyJyZWNlaXB0X2lkIjoicmNwdF8wMUpCNE5BMlE1VzhaQUs4UTJWN1hOM005UiJ9.MEUCIQDexampleSignatureOnly" } } } } } }, "responses": { "200": { "description": "The verdict.", "headers": { "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ReceiptVerification" }, "examples": { "illustrative": { "summary": "A valid receipt", "value": { "valid": true, "order_exists": true, "licence_in_force_until": "2027-09-26", "revoked": false, "receipt_id": "rcpt_01JB4NA2Q5W8ZAK8Q2V7XN3M9R", "checked_at": "2026-10-01T09:00:00Z" } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "422": { "$ref": "#/components/responses/ValidationFailed" }, "429": { "$ref": "#/components/responses/RateLimited" }, "default": { "$ref": "#/components/responses/ServerError" } }, "x-cost-credits": 0, "x-free": true, "x-anonymous": true } }, "/account": { "get": { "operationId": "getAccount", "summary": "Get the account", "description": "Balance by source, plan, per-action prices, the rate limit and, for an agent key, its budget and per-order cap.", "tags": [ "Account" ], "security": [ { "OAuth2": [ "account:read" ] }, { "ApiKey": [ "account:read" ] } ], "parameters": [ { "$ref": "#/components/parameters/MyDataHubVersion" } ], "responses": { "200": { "description": "The account.", "headers": { "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Account" }, "examples": { "illustrative": { "summary": "Called with an agent key", "value": { "organisation": { "id": "org_01JA0Q2V7XN3M9R6T1Y5W8ZAK8", "name": "Example Agency Ltd", "business_details": { "confirmed_at": null, "required_before_order": false, "name_editable": false } }, "user": null, "mode": "live", "plan": { "id": "pay_as_you_go", "name": "Pay as you go", "kind": "subscription", "renews_at": "2026-10-26", "cancel_at_period_end": false }, "balance": { "credits": 6200, "pack_credits": 5000, "subscription_credits": 1200, "rollover_cap": 12000, "low_threshold": 500 }, "prices": [ { "action": "count", "label": "Count, breakdown, preview, machine quote, catalogue, title expansion", "credits": 0, "unit": "call", "status": "confirmed" }, { "action": "record", "label": "Full UK contact record delivered, any channel or field set", "credits": 1, "unit": "record", "status": "confirmed" }, { "action": "company_only_record", "label": "Company-only record (no named contact)", "credits": 0.1, "unit": "record", "status": "proposed" }, { "action": "enrich_contact", "label": "Contact enrichment, match found", "credits": 1, "unit": "match", "status": "confirmed", "note": "0 if already licensed" }, { "action": "lookup_company", "label": "Company lookup, no contact details", "credits": 0, "unit": "call", "status": "to_confirm" }, { "action": "outright", "label": "Outright ownership", "credits": 1.8, "unit": "record", "status": "proposed" } ], "gbp_per_credit": 0.299, "rate_limit": { "tier": "paid", "counts_per_minute": 600, "counts_per_hour": null, "counts_per_day": null, "remaining": 598, "resets_at": "2026-09-26T10:15:00Z", "status": "to_confirm" }, "key": { "id": "key_01JB3Z9R6T1Y5W8ZAK8Q2V7XN3", "kind": "agent", "budget": { "monthly_credits": 1000, "spent": 400, "remaining": 600, "resets_at": "2026-10-01T00:00:00Z" }, "per_order_max_credits": 500, "expires_at": "2027-03-31T00:00:00Z" }, "account_manager": { "name": "Jordan Hale", "calendar_url": "https://emailmovers.com/talk-to-us" }, "agreements": { "dlsa": { "name": "Data Licence and Sharing Agreement", "version": "1.0", "url": "https://emailmovers.com/data-licence/", "accepted": { "version": "1.0", "accepted_at": "2026-11-02T10:12:00Z", "accepted_by": "usr_01JB4H8Q2V7XN3M9R6T1Y5W8ZA" } }, "dpa": { "name": "Article 28 data processing agreement", "version": "1.0", "url": "https://emailmovers.com/dpa/", "accepted": null } } } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" }, "default": { "$ref": "#/components/responses/ServerError" } }, "x-cost-credits": 0, "x-free": true, "x-anonymous": false, "x-mcp-tool": "get_account" }, "patch": { "operationId": "updateAccount", "summary": "Confirm the business details", "description": "Set the organisation's business name and confirm that it is a UK business. An organisation made by self-serve sign-up needs both before its first order or enrichment, free or paid: until then POST /v1/orders and POST /v1/contacts/enrich answer 403 business-details-required and charge nothing. A signed-in person who owns the account confirms them, through OAuth (with account:write, or admin) or in the app; an API key cannot. An organisation Emailmovers set up keeps the name staff gave it and needs no business details, so it is refused with 422 (organisation.business_details.name_editable is false).", "tags": [ "Account" ], "security": [ { "OAuth2": [ "account:write" ] } ], "parameters": [ { "$ref": "#/components/parameters/MyDataHubVersion" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AccountUpdateRequest" }, "examples": { "illustrative": { "summary": "Confirm the business name and that it is a UK business", "value": { "business_name": "Example Trading Ltd", "uk_business": true } } } } } }, "responses": { "200": { "description": "The account.", "headers": { "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Account" }, "examples": { "illustrative": { "summary": "Confirm the business name and that it is a UK business", "value": { "organisation": { "id": "org_01JA0Q2V7XN3M9R6T1Y5W8ZAK8", "name": "Example Trading Ltd", "business_details": { "confirmed_at": "2026-10-18T09:30:00Z", "required_before_order": false, "name_editable": true } }, "user": { "id": "usr_01JA0Q3V7XN3M9R6T1Y5W8ZAK8", "name": "jo@example-trading.co.uk" }, "mode": "live", "plan": { "id": "free", "name": "Free", "kind": "free", "renews_at": null, "cancel_at_period_end": false }, "balance": { "credits": 100, "pack_credits": 100, "subscription_credits": 0, "rollover_cap": null, "low_threshold": null }, "prices": [ { "action": "count", "label": "Count, breakdown, preview, machine quote, catalogue, title expansion", "credits": 0, "unit": "call", "status": "confirmed" }, { "action": "record", "label": "Full UK contact record delivered, any channel or field set", "credits": 1, "unit": "record", "status": "confirmed" }, { "action": "company_only_record", "label": "Company-only record (no named contact)", "credits": 0.1, "unit": "record", "status": "proposed" }, { "action": "enrich_contact", "label": "Contact enrichment, match found", "credits": 1, "unit": "match", "status": "confirmed", "note": "0 if already licensed" }, { "action": "lookup_company", "label": "Company lookup, no contact details", "credits": 0, "unit": "call", "status": "to_confirm" }, { "action": "outright", "label": "Outright ownership", "credits": 1.8, "unit": "record", "status": "proposed" } ], "gbp_per_credit": 0.299, "rate_limit": { "tier": "free", "counts_per_minute": 60, "counts_per_hour": null, "counts_per_day": 1000, "remaining": 59, "resets_at": "2026-09-26T10:15:00Z", "status": "to_confirm" }, "key": null, "account_manager": null, "agreements": { "dlsa": { "name": "Data Licence and Sharing Agreement", "version": "1.0", "url": "https://emailmovers.com/data-licence/", "accepted": { "version": "1.0", "accepted_at": "2026-11-02T10:12:00Z", "accepted_by": "usr_01JB4H8Q2V7XN3M9R6T1Y5W8ZA" } }, "dpa": { "name": "Article 28 data processing agreement", "version": "1.0", "url": "https://emailmovers.com/dpa/", "accepted": null } } } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "422": { "$ref": "#/components/responses/ValidationFailed" }, "429": { "$ref": "#/components/responses/RateLimited" }, "default": { "$ref": "#/components/responses/ServerError" } }, "x-cost-credits": 0, "x-free": true, "x-anonymous": false } }, "/account/agreements": { "post": { "operationId": "acceptAccountAgreements", "summary": "Accept the data processing agreement", "description": "Accept the Article 28 data processing agreement at the version in force (the account's agreements.dpa). A suppression upload needs it first: until it is accepted POST /v1/suppressions answers 403 dpa-acceptance-required and uploads nothing, unless a person accepts it with that upload. A signed-in person who owns the account accepts it, through OAuth (with account:write, or admin) or in the app's Settings; an API key cannot. The account keeps the version, the person and the time, and a later version is accepted again.", "tags": [ "Account" ], "security": [ { "OAuth2": [ "account:write" ] } ], "parameters": [ { "$ref": "#/components/parameters/MyDataHubVersion" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AccountAgreementsRequest" }, "examples": { "illustrative": { "summary": "Accept the data processing agreement", "value": { "dpa_accepted_version": "1.0" } } } } } }, "responses": { "200": { "description": "The account, with its agreements.", "headers": { "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Account" }, "examples": { "illustrative": { "summary": "Accept the data processing agreement", "value": { "organisation": { "id": "org_01JA0Q2V7XN3M9R6T1Y5W8ZAK8", "name": "Example Agency Ltd", "business_details": { "confirmed_at": null, "required_before_order": false, "name_editable": false } }, "user": null, "mode": "live", "plan": { "id": "pay_as_you_go", "name": "Pay as you go", "kind": "subscription", "renews_at": "2026-10-26", "cancel_at_period_end": false }, "balance": { "credits": 6200, "pack_credits": 5000, "subscription_credits": 1200, "rollover_cap": 12000, "low_threshold": 500 }, "prices": [ { "action": "count", "label": "Count, breakdown, preview, machine quote, catalogue, title expansion", "credits": 0, "unit": "call", "status": "confirmed" }, { "action": "record", "label": "Full UK contact record delivered, any channel or field set", "credits": 1, "unit": "record", "status": "confirmed" }, { "action": "company_only_record", "label": "Company-only record (no named contact)", "credits": 0.1, "unit": "record", "status": "proposed" }, { "action": "enrich_contact", "label": "Contact enrichment, match found", "credits": 1, "unit": "match", "status": "confirmed", "note": "0 if already licensed" }, { "action": "lookup_company", "label": "Company lookup, no contact details", "credits": 0, "unit": "call", "status": "to_confirm" }, { "action": "outright", "label": "Outright ownership", "credits": 1.8, "unit": "record", "status": "proposed" } ], "gbp_per_credit": 0.299, "rate_limit": { "tier": "paid", "counts_per_minute": 600, "counts_per_hour": null, "counts_per_day": null, "remaining": 598, "resets_at": "2026-09-26T10:15:00Z", "status": "to_confirm" }, "key": { "id": "key_01JB3Z9R6T1Y5W8ZAK8Q2V7XN3", "kind": "agent", "budget": { "monthly_credits": 1000, "spent": 400, "remaining": 600, "resets_at": "2026-10-01T00:00:00Z" }, "per_order_max_credits": 500, "expires_at": "2027-03-31T00:00:00Z" }, "account_manager": { "name": "Jordan Hale", "calendar_url": "https://emailmovers.com/talk-to-us" }, "agreements": { "dlsa": { "name": "Data Licence and Sharing Agreement", "version": "1.0", "url": "https://emailmovers.com/data-licence/", "accepted": { "version": "1.0", "accepted_at": "2026-11-02T10:12:00Z", "accepted_by": "usr_01JB4H8Q2V7XN3M9R6T1Y5W8ZA" } }, "dpa": { "name": "Article 28 data processing agreement", "version": "1.0", "url": "https://emailmovers.com/dpa/", "accepted": { "version": "1.0", "accepted_at": "2026-11-03T09:00:00Z", "accepted_by": "usr_01JB4H8Q2V7XN3M9R6T1Y5W8ZA" } } } } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "422": { "$ref": "#/components/responses/ValidationFailed" }, "429": { "$ref": "#/components/responses/RateLimited" }, "default": { "$ref": "#/components/responses/ServerError" } }, "x-cost-credits": 0, "x-free": true, "x-anonymous": false } }, "/account/usage": { "get": { "operationId": "getAccountUsage", "summary": "Get account usage", "description": "Credits charged, refunded and added in a period, by action and by key.", "tags": [ "Account" ], "security": [ { "OAuth2": [ "account:read" ] }, { "ApiKey": [ "account:read" ] } ], "parameters": [ { "$ref": "#/components/parameters/MyDataHubVersion" }, { "name": "from", "in": "query", "required": false, "description": "First day, inclusive. Default 30 days ago.", "schema": { "type": "string", "format": "date" }, "example": "2026-09-01" }, { "name": "to", "in": "query", "required": false, "description": "Last day, inclusive. Default today.", "schema": { "type": "string", "format": "date" }, "example": "2026-09-30" } ], "responses": { "200": { "description": "Usage in the period.", "headers": { "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AccountUsage" }, "examples": { "illustrative": { "summary": "September 2026", "value": { "from": "2026-09-01", "to": "2026-09-30", "credits_charged": 5400, "credits_refunded": 0, "credits_added": 6000, "by_action": [ { "action": "count", "calls": 1840, "credits": 0 }, { "action": "record", "calls": 2, "credits": 5400 } ], "by_key": [ { "key_id": "key_01JB3Z9R6T1Y5W8ZAK8Q2V7XN3", "label": "SDR agent", "credits": 400 } ] } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "422": { "$ref": "#/components/responses/ValidationFailed" }, "429": { "$ref": "#/components/responses/RateLimited" }, "default": { "$ref": "#/components/responses/ServerError" } }, "x-cost-credits": 0, "x-free": true, "x-anonymous": false } }, "/account/cancel": { "post": { "operationId": "cancelAccount", "summary": "Cancel the plan", "description": "End a rolling plan at the end of its period, in one call, with no reason required; any notice terms in your agreement still apply. Credit pack credits never expire and survive cancellation, and delivered records stay licensed to the end of their term.", "tags": [ "Account" ], "security": [ { "OAuth2": [ "admin" ] }, { "ApiKey": [ "admin" ] } ], "parameters": [ { "$ref": "#/components/parameters/MyDataHubVersion" } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AccountCancellationRequest" }, "examples": { "illustrative": { "summary": "Cancel pay as you go", "value": { "reason": "Campaign finished." } } } } } }, "responses": { "200": { "description": "When the plan ends and what is kept.", "headers": { "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AccountCancellation" }, "examples": { "illustrative": { "summary": "Cancel pay as you go", "value": { "plan": "pay_as_you_go", "cancel_at_period_end": true, "ends_at": "2026-10-26", "pack_credits_kept": 5000, "subscription_credits_usable_until": "2026-10-26", "licences_unaffected": true } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "422": { "$ref": "#/components/responses/ValidationFailed" }, "429": { "$ref": "#/components/responses/RateLimited" }, "default": { "$ref": "#/components/responses/ServerError" } }, "x-cost-credits": 0, "x-free": true, "x-anonymous": false } }, "/account/purchases": { "post": { "operationId": "createCreditPurchase", "summary": "Buy credits by card", "description": "Start a card payment in Stripe Checkout for credits at the per-contact scale (the size of the line picks its band), the 40,000 credit pack, or a quote's purchase option line by line. Prices exclude VAT; 20 percent UK VAT is added at checkout, which takes cards only (Apple Pay and Google Pay through the card method) and a UK billing address. Answers with the checkout_url to send the person to. The credits are added once, when Stripe says the payment is paid. Credits and credit packs are not refundable once bought, except where the law requires. A signed-in person with the admin scope buys; an API key cannot. The subscription is not bought here. 503 when card payments are not switched on.", "tags": [ "Account" ], "security": [ { "OAuth2": [ "admin" ] } ], "parameters": [ { "$ref": "#/components/parameters/MyDataHubVersion" }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreditPurchaseRequest" }, "examples": { "illustrative": { "summary": "Buy the 40,000 credit pack", "value": { "lines": [ { "id": "credit_pack_40000", "quantity": 1 } ] } } } } } }, "responses": { "201": { "description": "The pending purchase and its checkout_url.", "headers": { "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" }, "Location": { "$ref": "#/components/headers/Location" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreditPurchase" }, "examples": { "illustrative": { "summary": "Buy the 40,000 credit pack", "value": { "id": "pur_01JB4R7K2V7XN3M9R6T1Y5W8ZA", "label": "1 credit pack of 40,000", "lines": [ { "id": "credit_pack_40000", "quantity": 1, "credits": 40000, "gbp_ex_vat": 1249 } ], "credits": 40000, "gbp_ex_vat": 1249, "vat_rate_percent": 20, "vat_gbp": 249.8, "total_gbp": 1498.8, "currency": "GBP", "gbp_per_credit": 0.031225, "test_mode": true, "created_at": "2026-10-16T10:00:00Z", "expires_at": "2026-10-17T10:00:00Z", "attention": null, "status": "pending", "credits_added": 0, "checkout_url": "https://checkout.stripe.com/c/pay/cs_test_EXAMPLE", "paid_at": null, "receipt": null } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "409": { "$ref": "#/components/responses/Conflict" }, "422": { "$ref": "#/components/responses/ValidationFailed" }, "429": { "$ref": "#/components/responses/RateLimited" }, "default": { "$ref": "#/components/responses/ServerError" } }, "x-cost-credits": 0, "x-free": true, "x-anonymous": false, "x-idempotency-key": "optional" }, "get": { "operationId": "listCreditPurchases", "summary": "List credit purchases", "description": "Credits bought by card, newest first, each with its price excluding VAT, the VAT, the total and, once paid, its payment receipt. payments says whether card payments are switched on here and whether they are Stripe test mode.", "tags": [ "Account" ], "security": [ { "OAuth2": [ "account:read" ] }, { "ApiKey": [ "account:read" ] } ], "parameters": [ { "$ref": "#/components/parameters/MyDataHubVersion" }, { "name": "limit", "in": "query", "required": false, "description": "Items per page, 1 to 100. Default 25.", "schema": { "default": 25, "type": "integer", "minimum": 1, "maximum": 100 } }, { "name": "cursor", "in": "query", "required": false, "description": "An opaque cursor from next_cursor. Pass it back unchanged.", "schema": { "type": "string", "minLength": 1, "maxLength": 512 } } ], "responses": { "200": { "description": "A page of credit purchases.", "headers": { "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreditPurchaseList" }, "examples": { "illustrative": { "summary": "One paid credit pack", "value": { "data": [ { "id": "pur_01JB4R7K2V7XN3M9R6T1Y5W8ZA", "label": "1 credit pack of 40,000", "lines": [ { "id": "credit_pack_40000", "quantity": 1, "credits": 40000, "gbp_ex_vat": 1249 } ], "credits": 40000, "gbp_ex_vat": 1249, "vat_rate_percent": 20, "vat_gbp": 249.8, "total_gbp": 1498.8, "currency": "GBP", "gbp_per_credit": 0.031225, "test_mode": true, "created_at": "2026-10-16T10:00:00Z", "expires_at": "2026-10-17T10:00:00Z", "attention": null, "status": "paid", "credits_added": 40000, "checkout_url": null, "paid_at": "2026-10-16T10:03:12Z", "receipt": { "number": "MDH-000042", "issued_at": "2026-10-16T10:03:12Z", "supplier": { "name": "Example Supplier Limited", "company_number": "00000000", "registered_office": "1 Example Street, Exampletown, EX1 1EX, England", "vat_number": "GB000000000" }, "customer": { "organisation_id": "org_01JA0Q2V7XN3M9R6T1Y5W8ZAK8", "organisation_name": "Example Agency Ltd", "business_name": "Example Agency Ltd", "name": "Example Agency Ltd", "address": { "line1": "2 Sample Road", "line2": null, "city": "Exampletown", "postal_code": "EX2 2EX", "state": null, "country": "GB" }, "vat_number": "GB999999999" }, "description": "1 credit pack of 40,000", "credits": 40000, "gbp_per_credit": 0.031225, "gbp_ex_vat": 1249, "vat_rate_percent": 20, "vat_gbp": 249.8, "total_gbp": 1498.8, "paid_by": "card", "payment_reference": "pi_test_EXAMPLE", "refunds": "Credits and credit packs are not refundable once bought, except where the law requires.", "test_mode": true } } ], "has_more": false, "next_cursor": null, "payments": { "available": true, "test_mode": true, "vat_rate_percent": 20 } } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "422": { "$ref": "#/components/responses/ValidationFailed" }, "429": { "$ref": "#/components/responses/RateLimited" }, "default": { "$ref": "#/components/responses/ServerError" } }, "x-cost-credits": 0, "x-free": true, "x-anonymous": false } }, "/account/purchases/{id}": { "get": { "operationId": "getCreditPurchase", "summary": "Get a credit purchase", "description": "One purchase of credits by card. Reading a pending purchase asks Stripe for its checkout and, once the payment is paid, adds the credits exactly once and writes the payment receipt, so the page Checkout returns to can show the credits added. Until then it stays pending. 503 when card payments are switched off and the purchase is still pending.", "tags": [ "Account" ], "security": [ { "OAuth2": [ "account:read" ] }, { "ApiKey": [ "account:read" ] } ], "parameters": [ { "$ref": "#/components/parameters/MyDataHubVersion" }, { "name": "id", "in": "path", "required": true, "description": "Format: a credit purchase id: pur_ followed by a 26 character ULID in upper case Crockford base32, such as pur_01JB4R7K2V7XN3M9R6T1Y5W8ZA.", "schema": { "type": "string", "pattern": "^pur_[0-7][0-9A-HJKMNP-TV-Z]{25}$", "examples": [ "pur_01JB4R7K2V7XN3M9R6T1Y5W8ZA" ] }, "example": "pur_01JB4R7K2V7XN3M9R6T1Y5W8ZA" } ], "responses": { "200": { "description": "The purchase.", "headers": { "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreditPurchase" }, "examples": { "illustrative": { "summary": "Paid, with its receipt", "value": { "id": "pur_01JB4R7K2V7XN3M9R6T1Y5W8ZA", "label": "1 credit pack of 40,000", "lines": [ { "id": "credit_pack_40000", "quantity": 1, "credits": 40000, "gbp_ex_vat": 1249 } ], "credits": 40000, "gbp_ex_vat": 1249, "vat_rate_percent": 20, "vat_gbp": 249.8, "total_gbp": 1498.8, "currency": "GBP", "gbp_per_credit": 0.031225, "test_mode": true, "created_at": "2026-10-16T10:00:00Z", "expires_at": "2026-10-17T10:00:00Z", "attention": null, "status": "paid", "credits_added": 40000, "checkout_url": null, "paid_at": "2026-10-16T10:03:12Z", "receipt": { "number": "MDH-000042", "issued_at": "2026-10-16T10:03:12Z", "supplier": { "name": "Example Supplier Limited", "company_number": "00000000", "registered_office": "1 Example Street, Exampletown, EX1 1EX, England", "vat_number": "GB000000000" }, "customer": { "organisation_id": "org_01JA0Q2V7XN3M9R6T1Y5W8ZAK8", "organisation_name": "Example Agency Ltd", "business_name": "Example Agency Ltd", "name": "Example Agency Ltd", "address": { "line1": "2 Sample Road", "line2": null, "city": "Exampletown", "postal_code": "EX2 2EX", "state": null, "country": "GB" }, "vat_number": "GB999999999" }, "description": "1 credit pack of 40,000", "credits": 40000, "gbp_per_credit": 0.031225, "gbp_ex_vat": 1249, "vat_rate_percent": 20, "vat_gbp": 249.8, "total_gbp": 1498.8, "paid_by": "card", "payment_reference": "pi_test_EXAMPLE", "refunds": "Credits and credit packs are not refundable once bought, except where the law requires.", "test_mode": true } } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/RateLimited" }, "default": { "$ref": "#/components/responses/ServerError" } }, "x-cost-credits": 0, "x-free": true, "x-anonymous": false } }, "/api-keys": { "get": { "operationId": "listApiKeys", "summary": "List API keys", "description": "API keys and agent keys, with each agent key's live spend meter. Secrets are never shown again.", "tags": [ "Keys" ], "security": [ { "OAuth2": [ "admin" ] }, { "ApiKey": [ "admin" ] } ], "parameters": [ { "$ref": "#/components/parameters/MyDataHubVersion" }, { "name": "limit", "in": "query", "required": false, "description": "Items per page, 1 to 100. Default 25.", "schema": { "default": 25, "type": "integer", "minimum": 1, "maximum": 100 } }, { "name": "cursor", "in": "query", "required": false, "description": "An opaque cursor from next_cursor. Pass it back unchanged.", "schema": { "type": "string", "minLength": 1, "maxLength": 512 } } ], "responses": { "200": { "description": "A page of keys.", "headers": { "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiKeyList" }, "examples": { "illustrative": { "summary": "One agent key", "value": { "data": [ { "id": "key_01JB3Z9R6T1Y5W8ZAK8Q2V7XN3", "kind": "agent", "label": "SDR agent", "mode": "live", "prefix": "mdh_live_7Kq2", "scopes": [ "counts:read", "quotes:read", "orders:write", "orders:read", "records:read", "pushes:write" ], "ip_allowlist": [], "created_at": "2026-09-20T09:00:00Z", "created_by": "usr_01JA0Q3V7XN3M9R6T1Y5W8ZAK8", "last_used_at": "2026-09-26T02:00:00Z", "expires_at": "2027-03-31T00:00:00Z", "revoked_at": null, "allowed_tools": [ "count_audience", "quote_order", "create_order", "fetch_order_records", "push_to_crm" ], "allowed_connection_ids": [ "conn_01JB3Y2X6Y7Z8A1B2C3D4E5F6G" ], "monthly_budget_credits": 1000, "per_order_max_credits": 500, "budget": { "monthly_credits": 1000, "spent": 400, "remaining": 600, "resets_at": "2026-10-01T00:00:00Z" }, "webhook_url": "https://agent.example.com/mydatahub/events", "disclosure": "account" } ], "has_more": false, "next_cursor": null } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "422": { "$ref": "#/components/responses/ValidationFailed" }, "429": { "$ref": "#/components/responses/RateLimited" }, "default": { "$ref": "#/components/responses/ServerError" } }, "x-cost-credits": 0, "x-free": true, "x-anonymous": false }, "post": { "operationId": "createApiKey", "summary": "Create an API key", "description": "Create a standard key or an agent key. An agent key has a label, allowed tools, a monthly budget, a per-order cap, an expiry and a webhook, and is created by a signed-in person through OAuth, never by a key. An agent key needs allowed_tools and per_order_max_credits and never takes admin. Unlimited keys on every plan; the secret is shown once.", "tags": [ "Keys" ], "security": [ { "OAuth2": [ "admin" ] } ], "parameters": [ { "$ref": "#/components/parameters/MyDataHubVersion" }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiKeyRequest" }, "examples": { "illustrative": { "summary": "An agent key with a 1,000 credit monthly budget", "value": { "kind": "agent", "label": "SDR agent", "scopes": [ "counts:read", "quotes:read", "orders:write", "orders:read", "records:read", "pushes:write" ], "allowed_tools": [ "count_audience", "quote_order", "create_order", "fetch_order_records", "push_to_crm" ], "allowed_connection_ids": [ "conn_01JB3Y2X6Y7Z8A1B2C3D4E5F6G" ], "monthly_budget_credits": 1000, "per_order_max_credits": 500, "expires_at": "2027-03-31T00:00:00Z", "licence_accepted_version": "1.0" } } } } } }, "responses": { "201": { "description": "The key and its secret.", "headers": { "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" }, "Location": { "$ref": "#/components/headers/Location" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiKeyCreated" }, "examples": { "illustrative": { "summary": "An agent key with a 1,000 credit monthly budget", "value": { "key": { "id": "key_01JB3Z9R6T1Y5W8ZAK8Q2V7XN3", "kind": "agent", "label": "SDR agent", "mode": "test", "prefix": "mdh_test_Exam", "scopes": [ "counts:read", "quotes:read", "orders:write", "orders:read", "records:read", "pushes:write" ], "ip_allowlist": [], "created_at": "2026-09-20T09:00:00Z", "created_by": "usr_01JA0Q3V7XN3M9R6T1Y5W8ZAK8", "last_used_at": "2026-09-26T02:00:00Z", "expires_at": "2027-03-31T00:00:00Z", "revoked_at": null, "allowed_tools": [ "count_audience", "quote_order", "create_order", "fetch_order_records", "push_to_crm" ], "allowed_connection_ids": [ "conn_01JB3Y2X6Y7Z8A1B2C3D4E5F6G" ], "monthly_budget_credits": 1000, "per_order_max_credits": 500, "budget": { "monthly_credits": 1000, "spent": 400, "remaining": 600, "resets_at": "2026-10-01T00:00:00Z" }, "webhook_url": "https://agent.example.com/mydatahub/events", "disclosure": "account" }, "secret": "mdh_test_Example0000000000000000000000000" } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "409": { "$ref": "#/components/responses/Conflict" }, "422": { "$ref": "#/components/responses/ValidationFailed" }, "429": { "$ref": "#/components/responses/RateLimited" }, "default": { "$ref": "#/components/responses/ServerError" } }, "x-cost-credits": 0, "x-free": true, "x-anonymous": false, "x-idempotency-key": "optional" } }, "/api-keys/{id}": { "patch": { "operationId": "updateApiKey", "summary": "Update an API key", "description": "Change a key's label, scopes, allowlist, expiry or, for an agent key, its tools, connections, budget and cap. Only a signed-in person, through OAuth, may: no key changes its own limits, and an agent key never takes admin.", "tags": [ "Keys" ], "security": [ { "OAuth2": [ "admin" ] } ], "parameters": [ { "$ref": "#/components/parameters/MyDataHubVersion" }, { "name": "id", "in": "path", "required": true, "description": "Format: an API key id: key_ followed by a 26 character ULID in upper case Crockford base32, such as key_01JB3Z4Q2V7XN3M9R6T1Y5W8ZA.", "schema": { "type": "string", "pattern": "^key_[0-7][0-9A-HJKMNP-TV-Z]{25}$", "examples": [ "key_01JB3Z4Q2V7XN3M9R6T1Y5W8ZA" ] }, "example": "key_01JB3Z9R6T1Y5W8ZAK8Q2V7XN3" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiKeyUpdate" }, "examples": { "illustrative": { "summary": "Raise an agent key budget", "value": { "monthly_budget_credits": 2000 } } } } } }, "responses": { "200": { "description": "The updated key.", "headers": { "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiKey" }, "examples": { "illustrative": { "summary": "Raise an agent key budget", "value": { "id": "key_01JB3Z9R6T1Y5W8ZAK8Q2V7XN3", "kind": "agent", "label": "SDR agent", "mode": "live", "prefix": "mdh_live_7Kq2", "scopes": [ "counts:read", "quotes:read", "orders:write", "orders:read", "records:read", "pushes:write" ], "ip_allowlist": [], "created_at": "2026-09-20T09:00:00Z", "created_by": "usr_01JA0Q3V7XN3M9R6T1Y5W8ZAK8", "last_used_at": "2026-09-26T02:00:00Z", "expires_at": "2027-03-31T00:00:00Z", "revoked_at": null, "allowed_tools": [ "count_audience", "quote_order", "create_order", "fetch_order_records", "push_to_crm" ], "allowed_connection_ids": [ "conn_01JB3Y2X6Y7Z8A1B2C3D4E5F6G" ], "monthly_budget_credits": 2000, "per_order_max_credits": 500, "budget": { "monthly_credits": 2000, "spent": 400, "remaining": 1600, "resets_at": "2026-10-01T00:00:00Z" }, "webhook_url": "https://agent.example.com/mydatahub/events", "disclosure": "account" } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/ValidationFailed" }, "429": { "$ref": "#/components/responses/RateLimited" }, "default": { "$ref": "#/components/responses/ServerError" } }, "x-cost-credits": 0, "x-free": true, "x-anonymous": false }, "delete": { "operationId": "revokeApiKey", "summary": "Revoke an API key", "description": "Revoke a key at once. Orders it placed stay in the audit trail. A signed-in person revokes keys through OAuth.", "tags": [ "Keys" ], "security": [ { "OAuth2": [ "admin" ] } ], "parameters": [ { "$ref": "#/components/parameters/MyDataHubVersion" }, { "name": "id", "in": "path", "required": true, "description": "Format: an API key id: key_ followed by a 26 character ULID in upper case Crockford base32, such as key_01JB3Z4Q2V7XN3M9R6T1Y5W8ZA.", "schema": { "type": "string", "pattern": "^key_[0-7][0-9A-HJKMNP-TV-Z]{25}$", "examples": [ "key_01JB3Z4Q2V7XN3M9R6T1Y5W8ZA" ] }, "example": "key_01JB3Z9R6T1Y5W8ZAK8Q2V7XN3" } ], "responses": { "204": { "description": "Revoked.", "headers": { "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/RateLimited" }, "default": { "$ref": "#/components/responses/ServerError" } }, "x-cost-credits": 0, "x-free": true, "x-anonymous": false } }, "/connections": { "get": { "operationId": "listConnections", "summary": "List CRM connections", "description": "CRM and destination connections with their status.", "tags": [ "CRM push" ], "security": [ { "OAuth2": [ "pushes:write" ] }, { "ApiKey": [ "pushes:write" ] } ], "parameters": [ { "$ref": "#/components/parameters/MyDataHubVersion" }, { "name": "limit", "in": "query", "required": false, "description": "Items per page, 1 to 100. Default 25.", "schema": { "default": 25, "type": "integer", "minimum": 1, "maximum": 100 } }, { "name": "cursor", "in": "query", "required": false, "description": "An opaque cursor from next_cursor. Pass it back unchanged.", "schema": { "type": "string", "minLength": 1, "maxLength": 512 } } ], "responses": { "200": { "description": "A page of connections.", "headers": { "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConnectionList" }, "examples": { "illustrative": { "summary": "One HubSpot connection", "value": { "data": [ { "id": "conn_01JB3Y2X6Y7Z8A1B2C3D4E5F6G", "provider": "hubspot", "name": "Sales HubSpot", "status": "connected", "authorise_url": null, "read_only_overlap": true, "created_at": "2026-09-20T09:30:00Z", "last_used_at": "2026-09-26T02:05:00Z" } ], "has_more": false, "next_cursor": null } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "422": { "$ref": "#/components/responses/ValidationFailed" }, "429": { "$ref": "#/components/responses/RateLimited" }, "default": { "$ref": "#/components/responses/ServerError" } }, "x-cost-credits": 0, "x-free": true, "x-anonymous": false }, "post": { "operationId": "createConnection", "summary": "Create a CRM connection", "description": "Start a connection to HubSpot, Salesforce, Google Sheets, Deliverite, a webhook or CSV. OAuth providers return an authorise_url for a person to approve in the app.", "tags": [ "CRM push" ], "security": [ { "OAuth2": [ "pushes:write" ] }, { "ApiKey": [ "pushes:write" ] } ], "parameters": [ { "$ref": "#/components/parameters/MyDataHubVersion" }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConnectionRequest" }, "examples": { "illustrative": { "summary": "Connect HubSpot", "value": { "provider": "hubspot", "name": "Sales HubSpot" } } } } } }, "responses": { "201": { "description": "The connection.", "headers": { "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" }, "Location": { "$ref": "#/components/headers/Location" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Connection" }, "examples": { "illustrative": { "summary": "Connect HubSpot", "value": { "id": "conn_01JB3Y2X6Y7Z8A1B2C3D4E5F6G", "provider": "hubspot", "name": "Sales HubSpot", "status": "pending_authorisation", "authorise_url": "https://mydatahub.emailmovers.com/connections/conn_01JB3Y2X6Y7Z8A1B2C3D4E5F6G/authorise", "read_only_overlap": true, "created_at": "2026-09-20T09:30:00Z", "last_used_at": null } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "409": { "$ref": "#/components/responses/Conflict" }, "422": { "$ref": "#/components/responses/ValidationFailed" }, "429": { "$ref": "#/components/responses/RateLimited" }, "default": { "$ref": "#/components/responses/ServerError" } }, "x-cost-credits": 0, "x-free": true, "x-anonymous": false, "x-idempotency-key": "optional" } }, "/connections/{id}/overlap": { "post": { "operationId": "checkConnectionOverlap", "summary": "Check CRM overlap", "description": "The New to you check before an order: read-only, email-only, salted SHA-256 matching in memory, nothing retained and nothing added to our database. Matched records are never charged.", "tags": [ "CRM push" ], "security": [ { "OAuth2": [ "pushes:write" ] }, { "ApiKey": [ "pushes:write" ] } ], "parameters": [ { "$ref": "#/components/parameters/MyDataHubVersion" }, { "name": "id", "in": "path", "required": true, "description": "Format: a CRM connection id: conn_ followed by a 26 character ULID in upper case Crockford base32, such as conn_01JB3Y2X6Y7Z8A1B2C3D4E5F6G.", "schema": { "type": "string", "pattern": "^conn_[0-7][0-9A-HJKMNP-TV-Z]{25}$", "examples": [ "conn_01JB3Y2X6Y7Z8A1B2C3D4E5F6G" ] }, "example": "conn_01JB3Y2X6Y7Z8A1B2C3D4E5F6G" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OverlapRequest" }, "examples": { "illustrative": { "summary": "Overlap with HubSpot", "value": { "count_id": "cnt_7K2PQ4MAXN3R6TBY5WDZ" } } } } } }, "responses": { "200": { "description": "The overlap.", "headers": { "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Overlap" }, "examples": { "illustrative": { "summary": "Overlap with HubSpot", "value": { "connection_id": "conn_01JB3Y2X6Y7Z8A1B2C3D4E5F6G", "count_id": "cnt_7K2PQ4MAXN3R6TBY5WDZ", "records": 4650, "already_held": 548, "new_to_you": 4102, "method": "salted_sha256_in_memory", "retained": false, "checked_at": "2026-09-26T10:12:00Z" } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/ValidationFailed" }, "429": { "$ref": "#/components/responses/RateLimited" }, "default": { "$ref": "#/components/responses/ServerError" } }, "x-cost-credits": 0, "x-free": true, "x-anonymous": false } }, "/orders/{id}/pushes": { "post": { "operationId": "createPush", "summary": "Push an order to a CRM", "description": "Push an order's records to a connection, keyed on mydatahub_record_id with the MyDataHub property group. dry_run defaults to true and reports what would change. A live push needs approval: a person's confirmation_token (or MCP elicitation), or an agent key whose allowed_tools include push_to_crm and whose allowed_connection_ids include the connection; otherwise 403 confirmation-required. Records only: nothing is ever sent to the contacts. Free.", "tags": [ "CRM push" ], "security": [ { "OAuth2": [ "pushes:write" ] }, { "ApiKey": [ "pushes:write" ] } ], "parameters": [ { "$ref": "#/components/parameters/MyDataHubVersion" }, { "$ref": "#/components/parameters/IdempotencyKey" }, { "name": "id", "in": "path", "required": true, "description": "Format: an order id: ord_ followed by a 26 character ULID in upper case Crockford base32, such as ord_01JB4N9S3W2X6Y7Z8A1B2C3D4E.", "schema": { "type": "string", "pattern": "^ord_[0-7][0-9A-HJKMNP-TV-Z]{25}$", "examples": [ "ord_01JB4N9S3W2X6Y7Z8A1B2C3D4E" ] }, "example": "ord_01JB4N9S3W2X6Y7Z8A1B2C3D4E" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PushRequest" }, "examples": { "illustrative": { "summary": "Dry run to HubSpot", "value": { "connection_id": "conn_01JB3Y2X6Y7Z8A1B2C3D4E5F6G" } } } } } }, "responses": { "202": { "description": "The push, or its dry run.", "headers": { "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" }, "Location": { "$ref": "#/components/headers/Location" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Push" }, "examples": { "illustrative": { "summary": "Dry run to HubSpot", "value": { "id": "psh_01JB4NC3W2X6Y7Z8A1B2C3D4E5", "order_id": "ord_01JB4N9S3W2X6Y7Z8A1B2C3D4E", "connection_id": "conn_01JB3Y2X6Y7Z8A1B2C3D4E5F6G", "dry_run": true, "status": "completed", "summary": { "to_create": 4102, "to_update": 0, "already_present": 0, "skipped": 0, "failed": 0 }, "property_group": [ "mydatahub_record_id", "licence_expires_at", "lawful_basis", "article14_status", "tps_ctps_screened_at", "subscriber_class", "suppression_status", "compliance_receipt_url" ], "sample": { "mydatahub_record_id": "contact_01JA9X2V7XN3M9R6T1Y5W8ZAK8", "licence_expires_at": "2027-09-26", "lawful_basis": "legitimate_interests_art6_1_f", "article14_status": "notified", "tps_ctps_screened_at": "2026-09-12", "subscriber_class": "ltd", "suppression_status": "none", "compliance_receipt_url": "https://mydatahub.emailmovers.com/receipts/rcpt_01JB4NA2Q5W8ZAK8Q2V7XN3M9R" }, "errors": [], "created_at": "2026-09-26T10:20:00Z", "completed_at": "2026-09-26T10:20:03Z" } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "422": { "$ref": "#/components/responses/ValidationFailed" }, "429": { "$ref": "#/components/responses/RateLimited" }, "default": { "$ref": "#/components/responses/ServerError" } }, "x-cost-credits": 0, "x-free": true, "x-anonymous": false, "x-idempotency-key": "optional", "x-mcp-tool": "push_to_crm" } }, "/pushes/{id}": { "get": { "operationId": "getPush", "summary": "Get a push", "description": "A push's status and summary: to create, to update, already present, skipped and failed.", "tags": [ "CRM push" ], "security": [ { "OAuth2": [ "orders:read" ] }, { "ApiKey": [ "orders:read" ] } ], "parameters": [ { "$ref": "#/components/parameters/MyDataHubVersion" }, { "name": "id", "in": "path", "required": true, "description": "Format: a CRM push id: psh_ followed by a 26 character ULID in upper case Crockford base32, such as psh_01JB4NC3W2X6Y7Z8A1B2C3D4E5.", "schema": { "type": "string", "pattern": "^psh_[0-7][0-9A-HJKMNP-TV-Z]{25}$", "examples": [ "psh_01JB4NC3W2X6Y7Z8A1B2C3D4E5" ] }, "example": "psh_01JB4NC3W2X6Y7Z8A1B2C3D4E5" } ], "responses": { "200": { "description": "The push.", "headers": { "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Push" }, "examples": { "illustrative": { "summary": "A finished dry run", "value": { "id": "psh_01JB4NC3W2X6Y7Z8A1B2C3D4E5", "order_id": "ord_01JB4N9S3W2X6Y7Z8A1B2C3D4E", "connection_id": "conn_01JB3Y2X6Y7Z8A1B2C3D4E5F6G", "dry_run": true, "status": "completed", "summary": { "to_create": 4102, "to_update": 0, "already_present": 0, "skipped": 0, "failed": 0 }, "property_group": [ "mydatahub_record_id", "licence_expires_at", "lawful_basis", "article14_status", "tps_ctps_screened_at", "subscriber_class", "suppression_status", "compliance_receipt_url" ], "sample": { "mydatahub_record_id": "contact_01JA9X2V7XN3M9R6T1Y5W8ZAK8", "licence_expires_at": "2027-09-26", "lawful_basis": "legitimate_interests_art6_1_f", "article14_status": "notified", "tps_ctps_screened_at": "2026-09-12", "subscriber_class": "ltd", "suppression_status": "none", "compliance_receipt_url": "https://mydatahub.emailmovers.com/receipts/rcpt_01JB4NA2Q5W8ZAK8Q2V7XN3M9R" }, "errors": [], "created_at": "2026-09-26T10:20:00Z", "completed_at": "2026-09-26T10:20:03Z" } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/RateLimited" }, "default": { "$ref": "#/components/responses/ServerError" } }, "x-cost-credits": 0, "x-free": true, "x-anonymous": false } }, "/pushes/{id}/retry": { "post": { "operationId": "retryPush", "summary": "Retry a push", "description": "Retry the failed records of a partial or failed push. A live retry needs the same approval as the push it retries.", "tags": [ "CRM push" ], "security": [ { "OAuth2": [ "pushes:write" ] }, { "ApiKey": [ "pushes:write" ] } ], "parameters": [ { "$ref": "#/components/parameters/MyDataHubVersion" }, { "$ref": "#/components/parameters/IdempotencyKey" }, { "name": "id", "in": "path", "required": true, "description": "Format: a CRM push id: psh_ followed by a 26 character ULID in upper case Crockford base32, such as psh_01JB4NC3W2X6Y7Z8A1B2C3D4E5.", "schema": { "type": "string", "pattern": "^psh_[0-7][0-9A-HJKMNP-TV-Z]{25}$", "examples": [ "psh_01JB4NC3W2X6Y7Z8A1B2C3D4E5" ] }, "example": "psh_01JB4NC3W2X6Y7Z8A1B2C3D4E5" } ], "responses": { "202": { "description": "The push, queued again.", "headers": { "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Push" }, "examples": { "illustrative": { "summary": "Retry a partial push", "value": { "id": "psh_01JB4NC3W2X6Y7Z8A1B2C3D4E5", "order_id": "ord_01JB4N9S3W2X6Y7Z8A1B2C3D4E", "connection_id": "conn_01JB3Y2X6Y7Z8A1B2C3D4E5F6G", "dry_run": false, "status": "queued", "summary": { "to_create": 4102, "to_update": 0, "already_present": 0, "skipped": 0, "failed": 0 }, "property_group": [ "mydatahub_record_id", "licence_expires_at", "lawful_basis", "article14_status", "tps_ctps_screened_at", "subscriber_class", "suppression_status", "compliance_receipt_url" ], "sample": { "mydatahub_record_id": "contact_01JA9X2V7XN3M9R6T1Y5W8ZAK8", "licence_expires_at": "2027-09-26", "lawful_basis": "legitimate_interests_art6_1_f", "article14_status": "notified", "tps_ctps_screened_at": "2026-09-12", "subscriber_class": "ltd", "suppression_status": "none", "compliance_receipt_url": "https://mydatahub.emailmovers.com/receipts/rcpt_01JB4NA2Q5W8ZAK8Q2V7XN3M9R" }, "errors": [], "created_at": "2026-09-26T10:20:00Z", "completed_at": null } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "429": { "$ref": "#/components/responses/RateLimited" }, "default": { "$ref": "#/components/responses/ServerError" } }, "x-cost-credits": 0, "x-free": true, "x-anonymous": false, "x-idempotency-key": "optional" } }, "/webhooks": { "get": { "operationId": "listWebhookEndpoints", "summary": "List webhook endpoints", "description": "Webhook endpoints, their events and pinned MyDataHub-Version.", "tags": [ "Webhooks" ], "security": [ { "OAuth2": [ "webhooks:write" ] }, { "ApiKey": [ "webhooks:write" ] } ], "parameters": [ { "$ref": "#/components/parameters/MyDataHubVersion" }, { "name": "limit", "in": "query", "required": false, "description": "Items per page, 1 to 100. Default 25.", "schema": { "default": 25, "type": "integer", "minimum": 1, "maximum": 100 } }, { "name": "cursor", "in": "query", "required": false, "description": "An opaque cursor from next_cursor. Pass it back unchanged.", "schema": { "type": "string", "minLength": 1, "maxLength": 512 } } ], "responses": { "200": { "description": "A page of endpoints.", "headers": { "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookEndpointList" }, "examples": { "illustrative": { "summary": "One endpoint", "value": { "data": [ { "id": "whk_01JB3Y8Q2V7XN3M9R6T1Y5W8ZA", "url": "https://agent.example.com/mydatahub/events", "events": [ "order.ready", "credits.low", "suppression.created" ], "api_version": "2027-01-15", "status": "active", "description": "SDR agent", "created_at": "2026-09-20T09:45:00Z" } ], "has_more": false, "next_cursor": null } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "422": { "$ref": "#/components/responses/ValidationFailed" }, "429": { "$ref": "#/components/responses/RateLimited" }, "default": { "$ref": "#/components/responses/ServerError" } }, "x-cost-credits": 0, "x-free": true, "x-anonymous": false }, "post": { "operationId": "createWebhookEndpoint", "summary": "Create a webhook endpoint", "description": "Register an https endpoint for events. Deliveries follow Standard Webhooks (webhook-id, webhook-timestamp, webhook-signature; HMAC-SHA256 with a whsec_ secret, shown once) and retry over 24 hours. The endpoint is pinned to the request's MyDataHub-Version.", "tags": [ "Webhooks" ], "security": [ { "OAuth2": [ "webhooks:write" ] }, { "ApiKey": [ "webhooks:write" ] } ], "parameters": [ { "$ref": "#/components/parameters/MyDataHubVersion" }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookEndpointRequest" }, "examples": { "illustrative": { "summary": "Order and credit events", "value": { "url": "https://agent.example.com/mydatahub/events", "events": [ "order.ready", "credits.low", "suppression.created" ], "description": "SDR agent" } } } } } }, "responses": { "201": { "description": "The endpoint and its secret.", "headers": { "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" }, "Location": { "$ref": "#/components/headers/Location" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookEndpointCreated" }, "examples": { "illustrative": { "summary": "Order and credit events", "value": { "endpoint": { "id": "whk_01JB3Y8Q2V7XN3M9R6T1Y5W8ZA", "url": "https://agent.example.com/mydatahub/events", "events": [ "order.ready", "credits.low", "suppression.created" ], "api_version": "2027-01-15", "status": "active", "description": "SDR agent", "created_at": "2026-09-20T09:45:00Z" }, "secret": "whsec_ExampleSecret0000000000000000000" } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "409": { "$ref": "#/components/responses/Conflict" }, "422": { "$ref": "#/components/responses/ValidationFailed" }, "429": { "$ref": "#/components/responses/RateLimited" }, "default": { "$ref": "#/components/responses/ServerError" } }, "x-cost-credits": 0, "x-free": true, "x-anonymous": false, "x-idempotency-key": "optional" } }, "/webhooks/{id}": { "delete": { "operationId": "deleteWebhookEndpoint", "summary": "Delete a webhook endpoint", "description": "Stop deliveries to an endpoint. Its events stay in the event log for 30 days.", "tags": [ "Webhooks" ], "security": [ { "OAuth2": [ "webhooks:write" ] }, { "ApiKey": [ "webhooks:write" ] } ], "parameters": [ { "$ref": "#/components/parameters/MyDataHubVersion" }, { "name": "id", "in": "path", "required": true, "description": "Format: a webhook endpoint id: whk_ followed by a 26 character ULID in upper case Crockford base32, such as whk_01JB3Y8Q2V7XN3M9R6T1Y5W8ZA.", "schema": { "type": "string", "pattern": "^whk_[0-7][0-9A-HJKMNP-TV-Z]{25}$", "examples": [ "whk_01JB3Y8Q2V7XN3M9R6T1Y5W8ZA" ] }, "example": "whk_01JB3Y8Q2V7XN3M9R6T1Y5W8ZA" } ], "responses": { "204": { "description": "Deleted.", "headers": { "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/RateLimited" }, "default": { "$ref": "#/components/responses/ServerError" } }, "x-cost-credits": 0, "x-free": true, "x-anonymous": false } }, "/webhooks/{id}/test": { "post": { "operationId": "testWebhookEndpoint", "summary": "Send a test event", "description": "Send a signed test event to an endpoint and report the response.", "tags": [ "Webhooks" ], "security": [ { "OAuth2": [ "webhooks:write" ] }, { "ApiKey": [ "webhooks:write" ] } ], "parameters": [ { "$ref": "#/components/parameters/MyDataHubVersion" }, { "name": "id", "in": "path", "required": true, "description": "Format: a webhook endpoint id: whk_ followed by a 26 character ULID in upper case Crockford base32, such as whk_01JB3Y8Q2V7XN3M9R6T1Y5W8ZA.", "schema": { "type": "string", "pattern": "^whk_[0-7][0-9A-HJKMNP-TV-Z]{25}$", "examples": [ "whk_01JB3Y8Q2V7XN3M9R6T1Y5W8ZA" ] }, "example": "whk_01JB3Y8Q2V7XN3M9R6T1Y5W8ZA" } ], "responses": { "200": { "description": "The delivery result.", "headers": { "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookTest" }, "examples": { "illustrative": { "summary": "A delivered test", "value": { "event_id": "evt_01JB4NB7T1Y5W8ZAK8Q2V7XN3M", "delivered": true, "status_code": 200, "duration_ms": 182 } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/RateLimited" }, "default": { "$ref": "#/components/responses/ServerError" } }, "x-cost-credits": 0, "x-free": true, "x-anonymous": false } }, "/events": { "get": { "operationId": "listEvents", "summary": "List events", "description": "Replay events from the last 30 days, oldest first, in the same envelope webhooks deliver. Use since to catch up after downtime.", "tags": [ "Webhooks" ], "security": [ { "OAuth2": [ "webhooks:write" ] }, { "ApiKey": [ "webhooks:write" ] } ], "parameters": [ { "$ref": "#/components/parameters/MyDataHubVersion" }, { "name": "since", "in": "query", "required": false, "description": "Events after this time, up to 30 days back.", "schema": { "type": "string", "format": "date-time" }, "example": "2026-09-26T10:00:00Z" }, { "name": "type", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "order.ready", "order.failed", "audience.refreshed", "credits.low", "credits.topped_up", "warranty.replacement_issued", "suppression.created", "push.completed", "push.partial", "push.failed", "connection.expired" ] } }, { "name": "limit", "in": "query", "required": false, "description": "Items per page, 1 to 100. Default 25.", "schema": { "default": 25, "type": "integer", "minimum": 1, "maximum": 100 } }, { "name": "cursor", "in": "query", "required": false, "description": "An opaque cursor from next_cursor. Pass it back unchanged.", "schema": { "type": "string", "minLength": 1, "maxLength": 512 } } ], "responses": { "200": { "description": "A page of events.", "headers": { "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EventList" }, "examples": { "illustrative": { "summary": "Events since the order", "value": { "data": [ { "id": "evt_01JB4NB7T1Y5W8ZAK8Q2V7XN3M", "type": "order.ready", "timestamp": "2026-09-26T10:16:04Z", "api_version": "2027-01-15", "data": { "order_id": "ord_01JB4N9S3W2X6Y7Z8A1B2C3D4E", "records": 5000, "records_url": "/v1/orders/ord_01JB4N9S3W2X6Y7Z8A1B2C3D4E/records", "receipt_url": "/v1/orders/ord_01JB4N9S3W2X6Y7Z8A1B2C3D4E/receipt" } } ], "has_more": false, "next_cursor": null } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "422": { "$ref": "#/components/responses/ValidationFailed" }, "429": { "$ref": "#/components/responses/RateLimited" }, "default": { "$ref": "#/components/responses/ServerError" } }, "x-cost-credits": 0, "x-free": true, "x-anonymous": false } }, "/openapi.json": { "get": { "operationId": "getOpenApiDocument", "summary": "Get this OpenAPI document", "description": "This document: OpenAPI 3.1 with x-cost-credits and x-free on every operation, generated from the same schemas as the MCP tools.", "tags": [ "Meta" ], "security": [], "parameters": [ { "$ref": "#/components/parameters/MyDataHubVersion" } ], "responses": { "200": { "description": "The OpenAPI document.", "headers": { "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpenApiDocument" }, "examples": { "illustrative": { "summary": "The first lines", "value": { "openapi": "3.1.1", "info": { "title": "MyDataHub API", "version": "2.0.0" } } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "429": { "$ref": "#/components/responses/RateLimited" }, "default": { "$ref": "#/components/responses/ServerError" } }, "x-cost-credits": 0, "x-free": true, "x-anonymous": true } }, "/health": { "get": { "operationId": "getHealth", "summary": "Check health", "description": "Whether the API is up, with the release, the latest MyDataHub-Version, the current dataset version and how old its TPS and CTPS screen is.", "tags": [ "Meta" ], "security": [], "parameters": [ { "$ref": "#/components/parameters/MyDataHubVersion" } ], "responses": { "200": { "description": "Health.", "headers": { "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Health" }, "examples": { "illustrative": { "summary": "Healthy", "value": { "status": "ok", "version": "2.0.0", "api_version": "2027-01-15", "dataset_version": "2026-W39", "tps_screen": { "screened_at": "2026-09-25", "age_days": 1, "status": "ok" }, "time": "2026-09-26T10:14:00Z", "status_page": "https://status.emailmovers.com" } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "429": { "$ref": "#/components/responses/RateLimited" }, "default": { "$ref": "#/components/responses/ServerError" } }, "x-cost-credits": 0, "x-free": true, "x-anonymous": true } } }, "webhooks": { "order.ready": { "post": { "operationId": "webhookOrderReady", "summary": "order.ready event", "description": "Delivered to your endpoint under Standard Webhooks: verify webhook-signature (HMAC-SHA256 over webhook-id, webhook-timestamp and the body with your whsec_ secret) and treat webhook-id as the idempotency key. Any 2xx acknowledges; anything else is retried over 24 hours with backoff.", "tags": [ "Webhooks" ], "security": [], "parameters": [ { "name": "webhook-id", "in": "header", "required": true, "schema": { "type": "string" }, "description": "The event id; your idempotency key." }, { "name": "webhook-timestamp", "in": "header", "required": true, "schema": { "type": "string" }, "description": "Unix seconds when the delivery was signed." }, { "name": "webhook-signature", "in": "header", "required": true, "schema": { "type": "string" }, "description": "One or more space separated v1,base64 signatures." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OrderReadyEvent" }, "examples": { "illustrative": { "summary": "An order is ready", "value": { "id": "evt_01JB4NB7T1Y5W8ZAK8Q2V7XN3M", "type": "order.ready", "timestamp": "2026-09-26T10:16:04Z", "api_version": "2027-01-15", "data": { "order_id": "ord_01JB4N9S3W2X6Y7Z8A1B2C3D4E", "records": 5000, "records_url": "/v1/orders/ord_01JB4N9S3W2X6Y7Z8A1B2C3D4E/records", "receipt_url": "/v1/orders/ord_01JB4N9S3W2X6Y7Z8A1B2C3D4E/receipt" } } } } } } }, "responses": { "200": { "description": "Acknowledged." }, "400": { "description": "Not acknowledged; the delivery is retried with backoff." } } } }, "order.failed": { "post": { "operationId": "webhookOrderFailed", "summary": "order.failed event", "description": "Delivered to your endpoint under Standard Webhooks: verify webhook-signature (HMAC-SHA256 over webhook-id, webhook-timestamp and the body with your whsec_ secret) and treat webhook-id as the idempotency key. Any 2xx acknowledges; anything else is retried over 24 hours with backoff.", "tags": [ "Webhooks" ], "security": [], "parameters": [ { "name": "webhook-id", "in": "header", "required": true, "schema": { "type": "string" }, "description": "The event id; your idempotency key." }, { "name": "webhook-timestamp", "in": "header", "required": true, "schema": { "type": "string" }, "description": "Unix seconds when the delivery was signed." }, { "name": "webhook-signature", "in": "header", "required": true, "schema": { "type": "string" }, "description": "One or more space separated v1,base64 signatures." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OrderFailedEvent" } } } }, "responses": { "200": { "description": "Acknowledged." }, "400": { "description": "Not acknowledged; the delivery is retried with backoff." } } } }, "audience.refreshed": { "post": { "operationId": "webhookAudienceRefreshed", "summary": "audience.refreshed event", "description": "Delivered to your endpoint under Standard Webhooks: verify webhook-signature (HMAC-SHA256 over webhook-id, webhook-timestamp and the body with your whsec_ secret) and treat webhook-id as the idempotency key. Any 2xx acknowledges; anything else is retried over 24 hours with backoff.", "tags": [ "Webhooks" ], "security": [], "parameters": [ { "name": "webhook-id", "in": "header", "required": true, "schema": { "type": "string" }, "description": "The event id; your idempotency key." }, { "name": "webhook-timestamp", "in": "header", "required": true, "schema": { "type": "string" }, "description": "Unix seconds when the delivery was signed." }, { "name": "webhook-signature", "in": "header", "required": true, "schema": { "type": "string" }, "description": "One or more space separated v1,base64 signatures." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AudienceRefreshedEvent" } } } }, "responses": { "200": { "description": "Acknowledged." }, "400": { "description": "Not acknowledged; the delivery is retried with backoff." } } } }, "credits.low": { "post": { "operationId": "webhookCreditsLow", "summary": "credits.low event", "description": "Delivered to your endpoint under Standard Webhooks: verify webhook-signature (HMAC-SHA256 over webhook-id, webhook-timestamp and the body with your whsec_ secret) and treat webhook-id as the idempotency key. Any 2xx acknowledges; anything else is retried over 24 hours with backoff.", "tags": [ "Webhooks" ], "security": [], "parameters": [ { "name": "webhook-id", "in": "header", "required": true, "schema": { "type": "string" }, "description": "The event id; your idempotency key." }, { "name": "webhook-timestamp", "in": "header", "required": true, "schema": { "type": "string" }, "description": "Unix seconds when the delivery was signed." }, { "name": "webhook-signature", "in": "header", "required": true, "schema": { "type": "string" }, "description": "One or more space separated v1,base64 signatures." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreditsLowEvent" } } } }, "responses": { "200": { "description": "Acknowledged." }, "400": { "description": "Not acknowledged; the delivery is retried with backoff." } } } }, "credits.topped_up": { "post": { "operationId": "webhookCreditsToppedUp", "summary": "credits.topped_up event", "description": "Delivered to your endpoint under Standard Webhooks: verify webhook-signature (HMAC-SHA256 over webhook-id, webhook-timestamp and the body with your whsec_ secret) and treat webhook-id as the idempotency key. Any 2xx acknowledges; anything else is retried over 24 hours with backoff.", "tags": [ "Webhooks" ], "security": [], "parameters": [ { "name": "webhook-id", "in": "header", "required": true, "schema": { "type": "string" }, "description": "The event id; your idempotency key." }, { "name": "webhook-timestamp", "in": "header", "required": true, "schema": { "type": "string" }, "description": "Unix seconds when the delivery was signed." }, { "name": "webhook-signature", "in": "header", "required": true, "schema": { "type": "string" }, "description": "One or more space separated v1,base64 signatures." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreditsToppedUpEvent" } } } }, "responses": { "200": { "description": "Acknowledged." }, "400": { "description": "Not acknowledged; the delivery is retried with backoff." } } } }, "warranty.replacement_issued": { "post": { "operationId": "webhookWarrantyReplacementIssued", "summary": "warranty.replacement_issued event", "description": "Delivered to your endpoint under Standard Webhooks: verify webhook-signature (HMAC-SHA256 over webhook-id, webhook-timestamp and the body with your whsec_ secret) and treat webhook-id as the idempotency key. Any 2xx acknowledges; anything else is retried over 24 hours with backoff.", "tags": [ "Webhooks" ], "security": [], "parameters": [ { "name": "webhook-id", "in": "header", "required": true, "schema": { "type": "string" }, "description": "The event id; your idempotency key." }, { "name": "webhook-timestamp", "in": "header", "required": true, "schema": { "type": "string" }, "description": "Unix seconds when the delivery was signed." }, { "name": "webhook-signature", "in": "header", "required": true, "schema": { "type": "string" }, "description": "One or more space separated v1,base64 signatures." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WarrantyReplacementEvent" } } } }, "responses": { "200": { "description": "Acknowledged." }, "400": { "description": "Not acknowledged; the delivery is retried with backoff." } } } }, "suppression.created": { "post": { "operationId": "webhookSuppressionCreated", "summary": "suppression.created event", "description": "Delivered to your endpoint under Standard Webhooks: verify webhook-signature (HMAC-SHA256 over webhook-id, webhook-timestamp and the body with your whsec_ secret) and treat webhook-id as the idempotency key. Any 2xx acknowledges; anything else is retried over 24 hours with backoff.", "tags": [ "Webhooks" ], "security": [], "parameters": [ { "name": "webhook-id", "in": "header", "required": true, "schema": { "type": "string" }, "description": "The event id; your idempotency key." }, { "name": "webhook-timestamp", "in": "header", "required": true, "schema": { "type": "string" }, "description": "Unix seconds when the delivery was signed." }, { "name": "webhook-signature", "in": "header", "required": true, "schema": { "type": "string" }, "description": "One or more space separated v1,base64 signatures." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SuppressionCreatedEvent" } } } }, "responses": { "200": { "description": "Acknowledged." }, "400": { "description": "Not acknowledged; the delivery is retried with backoff." } } } }, "push.completed": { "post": { "operationId": "webhookPushCompleted", "summary": "push.completed event", "description": "Delivered to your endpoint under Standard Webhooks: verify webhook-signature (HMAC-SHA256 over webhook-id, webhook-timestamp and the body with your whsec_ secret) and treat webhook-id as the idempotency key. Any 2xx acknowledges; anything else is retried over 24 hours with backoff.", "tags": [ "Webhooks" ], "security": [], "parameters": [ { "name": "webhook-id", "in": "header", "required": true, "schema": { "type": "string" }, "description": "The event id; your idempotency key." }, { "name": "webhook-timestamp", "in": "header", "required": true, "schema": { "type": "string" }, "description": "Unix seconds when the delivery was signed." }, { "name": "webhook-signature", "in": "header", "required": true, "schema": { "type": "string" }, "description": "One or more space separated v1,base64 signatures." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PushCompletedEvent" } } } }, "responses": { "200": { "description": "Acknowledged." }, "400": { "description": "Not acknowledged; the delivery is retried with backoff." } } } }, "push.partial": { "post": { "operationId": "webhookPushPartial", "summary": "push.partial event", "description": "Delivered to your endpoint under Standard Webhooks: verify webhook-signature (HMAC-SHA256 over webhook-id, webhook-timestamp and the body with your whsec_ secret) and treat webhook-id as the idempotency key. Any 2xx acknowledges; anything else is retried over 24 hours with backoff.", "tags": [ "Webhooks" ], "security": [], "parameters": [ { "name": "webhook-id", "in": "header", "required": true, "schema": { "type": "string" }, "description": "The event id; your idempotency key." }, { "name": "webhook-timestamp", "in": "header", "required": true, "schema": { "type": "string" }, "description": "Unix seconds when the delivery was signed." }, { "name": "webhook-signature", "in": "header", "required": true, "schema": { "type": "string" }, "description": "One or more space separated v1,base64 signatures." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PushPartialEvent" } } } }, "responses": { "200": { "description": "Acknowledged." }, "400": { "description": "Not acknowledged; the delivery is retried with backoff." } } } }, "push.failed": { "post": { "operationId": "webhookPushFailed", "summary": "push.failed event", "description": "Delivered to your endpoint under Standard Webhooks: verify webhook-signature (HMAC-SHA256 over webhook-id, webhook-timestamp and the body with your whsec_ secret) and treat webhook-id as the idempotency key. Any 2xx acknowledges; anything else is retried over 24 hours with backoff.", "tags": [ "Webhooks" ], "security": [], "parameters": [ { "name": "webhook-id", "in": "header", "required": true, "schema": { "type": "string" }, "description": "The event id; your idempotency key." }, { "name": "webhook-timestamp", "in": "header", "required": true, "schema": { "type": "string" }, "description": "Unix seconds when the delivery was signed." }, { "name": "webhook-signature", "in": "header", "required": true, "schema": { "type": "string" }, "description": "One or more space separated v1,base64 signatures." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PushFailedEvent" } } } }, "responses": { "200": { "description": "Acknowledged." }, "400": { "description": "Not acknowledged; the delivery is retried with backoff." } } } }, "connection.expired": { "post": { "operationId": "webhookConnectionExpired", "summary": "connection.expired event", "description": "Delivered to your endpoint under Standard Webhooks: verify webhook-signature (HMAC-SHA256 over webhook-id, webhook-timestamp and the body with your whsec_ secret) and treat webhook-id as the idempotency key. Any 2xx acknowledges; anything else is retried over 24 hours with backoff.", "tags": [ "Webhooks" ], "security": [], "parameters": [ { "name": "webhook-id", "in": "header", "required": true, "schema": { "type": "string" }, "description": "The event id; your idempotency key." }, { "name": "webhook-timestamp", "in": "header", "required": true, "schema": { "type": "string" }, "description": "Unix seconds when the delivery was signed." }, { "name": "webhook-signature", "in": "header", "required": true, "schema": { "type": "string" }, "description": "One or more space separated v1,base64 signatures." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConnectionExpiredEvent" } } } }, "responses": { "200": { "description": "Acknowledged." }, "400": { "description": "Not acknowledged; the delivery is retried with backoff." } } } } }, "components": { "schemas": { "Account": { "type": "object", "properties": { "organisation": { "type": "object", "properties": { "id": { "type": "string", "pattern": "^org_[0-7][0-9A-HJKMNP-TV-Z]{25}$", "description": "Format: an organisation id: org_ followed by a 26 character ULID in upper case Crockford base32, such as org_01JA0Q2V7XN3M9R6T1Y5W8ZAK8.", "examples": [ "org_01JA0Q2V7XN3M9R6T1Y5W8ZAK8" ] }, "name": { "type": "string" }, "business_details": { "$ref": "#/components/schemas/BusinessDetails" } }, "required": [ "id", "name", "business_details" ] }, "user": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "string", "pattern": "^usr_[0-7][0-9A-HJKMNP-TV-Z]{25}$", "description": "Format: a user id: usr_ followed by a 26 character ULID in upper case Crockford base32, such as usr_01JA0Q3V7XN3M9R6T1Y5W8ZAK8.", "examples": [ "usr_01JA0Q3V7XN3M9R6T1Y5W8ZAK8" ] }, "name": { "type": "string" } }, "required": [ "id", "name" ] }, { "type": "null" } ], "description": "The signed-in person; null when the caller is an API key." }, "mode": { "type": "string", "enum": [ "live", "test" ], "description": "live keys (mdh_live_) spend real credits; test keys (mdh_test_) return synthetic data and never charge." }, "plan": { "type": "object", "properties": { "id": { "type": "string", "pattern": "^[a-z0-9]+(_[a-z0-9]+)*$" }, "name": { "type": "string" }, "kind": { "type": "string", "enum": [ "free", "subscription", "pack" ] }, "renews_at": { "anyOf": [ { "type": "string", "format": "date" }, { "type": "null" } ] }, "cancel_at_period_end": { "type": "boolean" } }, "required": [ "id", "name", "kind", "renews_at", "cancel_at_period_end" ] }, "balance": { "type": "object", "properties": { "credits": { "type": "number", "description": "Credits available to spend now." }, "pack_credits": { "type": "number", "description": "From credit packs: never expire." }, "subscription_credits": { "type": "number", "description": "From the plan: roll over while subscribed, up to the cap." }, "rollover_cap": { "anyOf": [ { "type": "integer", "minimum": 0 }, { "type": "null" } ] }, "low_threshold": { "anyOf": [ { "type": "integer", "minimum": 0 }, { "type": "null" } ], "description": "The credits.low webhook fires when the balance crosses this." } }, "required": [ "credits", "pack_credits", "subscription_credits", "rollover_cap", "low_threshold" ], "description": "Credits by source." }, "prices": { "type": "array", "items": { "$ref": "#/components/schemas/CreditRule" }, "description": "What each action costs in credits." }, "gbp_per_credit": { "type": "number", "minimum": 0, "description": "Your plan's price per credit, excluding VAT." }, "rate_limit": { "$ref": "#/components/schemas/RateLimit" }, "key": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "string", "pattern": "^key_[0-7][0-9A-HJKMNP-TV-Z]{25}$", "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" ] }, "kind": { "type": "string", "enum": [ "standard", "agent" ] }, "budget": { "anyOf": [ { "$ref": "#/components/schemas/Budget" }, { "type": "null" } ] }, "per_order_max_credits": { "anyOf": [ { "type": "integer", "minimum": 0 }, { "type": "null" } ] }, "expires_at": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ] } }, "required": [ "id", "kind", "budget", "per_order_max_credits", "expires_at" ] }, { "type": "null" } ], "description": "The calling key and, for an agent key, its budget; null for a person." }, "account_manager": { "anyOf": [ { "type": "object", "properties": { "name": { "type": "string" }, "calendar_url": { "type": "string", "format": "uri" } }, "required": [ "name", "calendar_url" ] }, { "type": "null" } ], "description": "The named person behind Talk to us." }, "agreements": { "type": "object", "properties": { "dlsa": { "$ref": "#/components/schemas/Agreement" }, "dpa": { "$ref": "#/components/schemas/Agreement" } }, "required": [ "dlsa", "dpa" ], "description": "The Data Licence and Sharing Agreement (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)." } }, "required": [ "organisation", "user", "mode", "plan", "balance", "prices", "gbp_per_credit", "rate_limit", "key", "account_manager", "agreements" ], "description": "Balance, plan, per-action prices, rate limit and the calling key's budget." }, "AccountAgreementsRequest": { "type": "object", "properties": { "dpa_accepted_version": { "type": "string", "minLength": 1, "maxLength": 100, "description": "The version of the Article 28 data processing agreement the owner accepts: the version in force, the account's agreements.dpa.version." } }, "required": [ "dpa_accepted_version" ], "additionalProperties": false, "description": "An owner's acceptance of the Article 28 data processing agreement, which a suppression upload needs first." }, "AccountCancellation": { "type": "object", "properties": { "plan": { "type": "string", "pattern": "^[a-z0-9]+(_[a-z0-9]+)*$" }, "cancel_at_period_end": { "type": "boolean", "const": true }, "ends_at": { "type": "string", "format": "date" }, "pack_credits_kept": { "type": "number", "description": "Credit pack credits never expire and survive cancellation." }, "subscription_credits_usable_until": { "type": "string", "format": "date" }, "licences_unaffected": { "type": "boolean", "const": true, "description": "Delivered records stay licensed to the end of their term." } }, "required": [ "plan", "cancel_at_period_end", "ends_at", "pack_credits_kept", "subscription_credits_usable_until", "licences_unaffected" ], "description": "The plan ends at the end of its period; credits and licences survive to the end of their term." }, "AccountCancellationRequest": { "type": "object", "properties": { "reason": { "description": "Optional; never required.", "type": "string", "maxLength": 1000 } }, "additionalProperties": false, "description": "Cancel the rolling plan at period end." }, "AccountUpdateRequest": { "type": "object", "properties": { "business_name": { "type": "string", "minLength": 1, "maxLength": 200, "pattern": "^\\P{Cc}*$", "description": "The organisation's business name, 1 to 200 characters, with no control character such as a line break." }, "uk_business": { "type": "boolean", "const": true, "description": "true confirms that the organisation is a UK business." } }, "required": [ "business_name", "uk_business" ], "additionalProperties": false, "description": "The business name and a UK business confirmation, which a self-serve account needs before its first order. Only an organisation made by self-serve sign-up takes it." }, "AccountUsage": { "type": "object", "properties": { "from": { "type": "string", "format": "date" }, "to": { "type": "string", "format": "date" }, "credits_charged": { "type": "number", "minimum": 0, "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)." }, "credits_refunded": { "type": "number", "minimum": 0, "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)." }, "credits_added": { "type": "number", "minimum": 0, "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)." }, "by_action": { "type": "array", "items": { "type": "object", "properties": { "action": { "type": "string", "pattern": "^[a-z0-9]+(_[a-z0-9]+)*$" }, "calls": { "type": "integer", "minimum": 0 }, "credits": { "type": "number", "minimum": 0, "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)." } }, "required": [ "action", "calls", "credits" ] } }, "by_key": { "type": "array", "items": { "type": "object", "properties": { "key_id": { "type": "string", "pattern": "^key_[0-7][0-9A-HJKMNP-TV-Z]{25}$", "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" ] }, "label": { "type": "string" }, "credits": { "type": "number", "minimum": 0, "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)." } }, "required": [ "key_id", "label", "credits" ] } } }, "required": [ "from", "to", "credits_charged", "credits_refunded", "credits_added", "by_action", "by_key" ], "description": "Credits charged, refunded and added in a period, by action and by key." }, "ActionPathStep": { "type": "object", "properties": { "step": { "type": "integer", "minimum": 1 }, "action": { "type": "string", "description": "An MCP tool, a REST operation or a URL." }, "rest": { "description": "The REST operation, such as POST /v1/quotes.", "type": [ "string", "null" ] }, "description": { "type": "string" } }, "required": [ "step", "action", "rest", "description" ], "description": "One step from a price to a delivered order." }, "AgentBudgetProblem": { "type": "object", "properties": { "type": { "type": "string", "format": "uri", "description": "A URI under https://emailmovers.com/mydatahub/docs/errors/ naming the problem type." }, "title": { "type": "string", "description": "A short summary of the problem type." }, "status": { "type": "integer", "minimum": 400, "maximum": 599 }, "detail": { "type": "string", "description": "What happened on this request, in plain English." }, "instance": { "description": "The request path or a request id this problem belongs to.", "type": "string" }, "code": { "type": "string", "const": "agent-budget-exceeded" }, "next_step": { "type": "string", "description": "What to do next, in plain English." }, "did_you_mean": { "description": "The closest valid values, best first.", "type": "array", "items": { "type": "string" } }, "errors": { "description": "For validation-failed: every problem found, each with a JSON pointer.", "type": "array", "items": { "$ref": "#/components/schemas/ProblemError" } }, "required_scope": { "description": "For insufficient-scope: the scope to request, such as orders:write.", "type": "string" }, "retry_after_seconds": { "description": "For rate-limited and service-unavailable: the same value as the Retry-After header.", "type": "integer", "minimum": 0 }, "budget": { "$ref": "#/components/schemas/Budget" }, "per_order_max_credits": { "type": "integer", "minimum": 0 }, "quote_id": { "description": "The machine quote the key could not settle; absent for an enrichment.", "type": "string", "pattern": "^qte_[0-7][0-9A-HJKMNP-TV-Z]{25}$", "examples": [ "qte_01JB4M2R6T1Y5W8ZAK8Q2V7XN3" ] }, "credits_required": { "type": "number", "minimum": 0, "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)." }, "approval_url": { "type": "string", "format": "uri", "description": "Where the key owner approves this spend in the app." }, "top_up_url": { "type": "string", "format": "uri" } }, "required": [ "type", "title", "status", "detail", "code", "next_step", "budget", "approval_url", "top_up_url" ], "description": "403: the agent key's per-order cap or monthly budget does not cover the machine quote or the enrichment. No order was created. The owner gets a signed notice only when an endpoint is registered at the key's webhook_url." }, "AgentKey": { "type": "object", "properties": { "id": { "type": "string", "pattern": "^key_[0-7][0-9A-HJKMNP-TV-Z]{25}$", "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" ] }, "label": { "type": "string" }, "mode": { "type": "string", "enum": [ "live", "test" ], "description": "live keys (mdh_live_) spend real credits; test keys (mdh_test_) return synthetic data and never charge." }, "prefix": { "type": "string", "description": "The first characters of the secret, such as mdh_live_7Kq2." }, "scopes": { "type": "array", "items": { "type": "string", "enum": [ "account:read", "counts:read", "previews:read", "audiences:read", "audiences:write", "quotes:read", "orders:read", "orders:write", "records:read", "enrich:write", "suppressions:read", "suppressions:write", "pushes:write", "webhooks:write", "samples:request", "admin" ] } }, "ip_allowlist": { "type": "array", "items": { "anyOf": [ { "type": "string", "pattern": "^((25[0-5]|2[0-4][0-9]|1[0-9][0-9]|[1-9][0-9]|[0-9])\\.){3}(25[0-5]|2[0-4][0-9]|1[0-9][0-9]|[1-9][0-9]|[0-9])\\/([0-9]|[1-2][0-9]|3[0-2])$" }, { "type": "string", "pattern": "^(([0-9a-fA-F]{1,4}:){7}[0-9a-fA-F]{1,4}|([0-9a-fA-F]{1,4}:){1,7}:|([0-9a-fA-F]{1,4}:){1,6}:[0-9a-fA-F]{1,4}|([0-9a-fA-F]{1,4}:){1,5}(:[0-9a-fA-F]{1,4}){1,2}|([0-9a-fA-F]{1,4}:){1,4}(:[0-9a-fA-F]{1,4}){1,3}|([0-9a-fA-F]{1,4}:){1,3}(:[0-9a-fA-F]{1,4}){1,4}|([0-9a-fA-F]{1,4}:){1,2}(:[0-9a-fA-F]{1,4}){1,5}|[0-9a-fA-F]{1,4}:((:[0-9a-fA-F]{1,4}){1,6})|:((:[0-9a-fA-F]{1,4}){1,7}|:))\\/(12[0-8]|1[01][0-9]|[1-9]?[0-9])$" } ], "description": "An IPv4 or IPv6 range in CIDR notation, such as 203.0.113.0/24." }, "description": "CIDR ranges the key may be used from; empty allows any address." }, "created_at": { "type": "string", "format": "date-time" }, "created_by": { "type": "string", "pattern": "^usr_[0-7][0-9A-HJKMNP-TV-Z]{25}$", "description": "Format: a user id: usr_ followed by a 26 character ULID in upper case Crockford base32, such as usr_01JA0Q3V7XN3M9R6T1Y5W8ZAK8.", "examples": [ "usr_01JA0Q3V7XN3M9R6T1Y5W8ZAK8" ] }, "last_used_at": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ] }, "expires_at": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ] }, "revoked_at": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ] }, "kind": { "type": "string", "const": "agent" }, "allowed_tools": { "type": "array", "items": { "type": "string", "enum": [ "get_plans", "get_account", "list_filters", "search_filter_values", "expand_job_titles", "resolve_location", "compile_audience", "count_audience", "preview_records", "save_audience", "list_audiences", "list_field_sets", "quote_order", "create_order", "get_order", "fetch_order_records", "push_to_crm", "lookup_company", "enrich_contact", "check_suppression", "report_objection", "get_compliance_receipt" ] }, "description": "The tools the key may call; a spending tool (create_order, enrich_contact) only if listed." }, "allowed_connection_ids": { "type": "array", "items": { "type": "string", "pattern": "^conn_[0-7][0-9A-HJKMNP-TV-Z]{25}$", "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" ] }, "description": "The CRM connections push_to_crm may push to live; empty allows dry runs only." }, "monthly_budget_credits": { "type": "integer", "minimum": 0 }, "per_order_max_credits": { "type": "integer", "minimum": 0 }, "budget": { "description": "The live spend meter.", "$ref": "#/components/schemas/Budget" }, "webhook_url": { "anyOf": [ { "type": "string", "format": "uri" }, { "type": "null" } ] }, "disclosure": { "type": "string", "enum": [ "account", "anonymous" ], "description": "account: counts as the organisation's own; anonymous: every anonymous visitor's rule, for a public assistant." } }, "required": [ "id", "label", "mode", "prefix", "scopes", "ip_allowlist", "created_at", "created_by", "last_used_at", "expires_at", "revoked_at", "kind", "allowed_tools", "allowed_connection_ids", "monthly_budget_credits", "per_order_max_credits", "budget", "webhook_url", "disclosure" ], "description": "An API key with kind agent: it spends without a human step only when the tool is in allowed_tools, per_order_max_credits covers the machine quote and monthly budget remains. Only a person in the app changes these limits, never a key." }, "Agreement": { "type": "object", "properties": { "name": { "type": "string" }, "version": { "type": "string", "description": "The version in force: draft until the text is approved." }, "url": { "type": "string", "format": "uri" }, "accepted": { "anyOf": [ { "type": "object", "properties": { "version": { "type": "string" }, "accepted_at": { "type": "string", "format": "date-time" }, "accepted_by": { "type": "string", "pattern": "^usr_[0-7][0-9A-HJKMNP-TV-Z]{25}$", "description": "Format: a user id: usr_ followed by a 26 character ULID in upper case Crockford base32, such as usr_01JA0Q3V7XN3M9R6T1Y5W8ZAK8.", "examples": [ "usr_01JA0Q3V7XN3M9R6T1Y5W8ZAK8" ] } }, "required": [ "version", "accepted_at", "accepted_by" ] }, { "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." } }, "required": [ "name", "version", "url", "accepted" ] }, "AllGroup": { "type": "object", "properties": { "all": { "minItems": 1, "type": "array", "items": { "$ref": "#/components/schemas/WhereNode" } } }, "required": [ "all" ], "additionalProperties": false, "description": "AND: every node inside must match." }, "AnyGroup": { "type": "object", "properties": { "any": { "minItems": 1, "type": "array", "items": { "$ref": "#/components/schemas/WhereNode" } } }, "required": [ "any" ], "additionalProperties": false, "description": "OR: at least one node inside must match." }, "ApiKey": { "oneOf": [ { "$ref": "#/components/schemas/StandardApiKey" }, { "$ref": "#/components/schemas/AgentKey" } ], "description": "A standard API key or an agent key. The secret is never shown again.", "discriminator": { "propertyName": "kind", "mapping": { "standard": "#/components/schemas/StandardApiKey", "agent": "#/components/schemas/AgentKey" } } }, "ApiKeyCreated": { "type": "object", "properties": { "key": { "$ref": "#/components/schemas/ApiKey" }, "secret": { "type": "string", "pattern": "^mdh_(live|test)_[0-9A-Za-z]{32}$", "description": "The secret, shown once. Send it as Authorization: Bearer." } }, "required": [ "key", "secret" ], "description": "A new key and its secret, shown once." }, "ApiKeyList": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/ApiKey" } }, "has_more": { "type": "boolean", "description": "Whether another page follows." }, "next_cursor": { "anyOf": [ { "type": "string", "minLength": 1, "maxLength": 512, "description": "An opaque cursor from next_cursor. Pass it back unchanged." }, { "type": "null" } ], "description": "Pass as cursor to fetch the next page; null on the last page." } }, "required": [ "data", "has_more", "next_cursor" ], "description": "A page of API keys, newest first." }, "ApiKeyRequest": { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "standard", "agent" ] }, "label": { "type": "string", "minLength": 1, "maxLength": 100 }, "mode": { "default": "live", "type": "string", "enum": [ "live", "test" ], "description": "live keys (mdh_live_) spend real credits; test keys (mdh_test_) return synthetic data and never charge." }, "scopes": { "minItems": 1, "type": "array", "items": { "type": "string", "enum": [ "account:read", "counts:read", "previews:read", "audiences:read", "audiences:write", "quotes:read", "orders:read", "orders:write", "records:read", "enrich:write", "suppressions:read", "suppressions:write", "pushes:write", "webhooks:write", "samples:request", "admin" ] }, "description": "The key's scopes. An agent key never takes admin, and no key takes account:write, which only a signed-in owner uses." }, "ip_allowlist": { "type": "array", "items": { "anyOf": [ { "type": "string", "pattern": "^((25[0-5]|2[0-4][0-9]|1[0-9][0-9]|[1-9][0-9]|[0-9])\\.){3}(25[0-5]|2[0-4][0-9]|1[0-9][0-9]|[1-9][0-9]|[0-9])\\/([0-9]|[1-2][0-9]|3[0-2])$" }, { "type": "string", "pattern": "^(([0-9a-fA-F]{1,4}:){7}[0-9a-fA-F]{1,4}|([0-9a-fA-F]{1,4}:){1,7}:|([0-9a-fA-F]{1,4}:){1,6}:[0-9a-fA-F]{1,4}|([0-9a-fA-F]{1,4}:){1,5}(:[0-9a-fA-F]{1,4}){1,2}|([0-9a-fA-F]{1,4}:){1,4}(:[0-9a-fA-F]{1,4}){1,3}|([0-9a-fA-F]{1,4}:){1,3}(:[0-9a-fA-F]{1,4}){1,4}|([0-9a-fA-F]{1,4}:){1,2}(:[0-9a-fA-F]{1,4}){1,5}|[0-9a-fA-F]{1,4}:((:[0-9a-fA-F]{1,4}){1,6})|:((:[0-9a-fA-F]{1,4}){1,7}|:))\\/(12[0-8]|1[01][0-9]|[1-9]?[0-9])$" } ], "description": "An IPv4 or IPv6 range in CIDR notation, such as 203.0.113.0/24." }, "description": "CIDR ranges the key may be used from; empty allows any address." }, "expires_at": { "type": "string", "format": "date-time", "description": "RFC 3339 date and time, with Z or an offset such as +01:00." }, "allowed_tools": { "description": "Agent keys only, and required there: the tools the key may call.", "type": "array", "items": { "type": "string", "enum": [ "get_plans", "get_account", "list_filters", "search_filter_values", "expand_job_titles", "resolve_location", "compile_audience", "count_audience", "preview_records", "save_audience", "list_audiences", "list_field_sets", "quote_order", "create_order", "get_order", "fetch_order_records", "push_to_crm", "lookup_company", "enrich_contact", "check_suppression", "report_objection", "get_compliance_receipt" ] } }, "allowed_connection_ids": { "description": "Agent keys only: the connections push_to_crm may push to live. Default none.", "type": "array", "items": { "type": "string", "pattern": "^conn_[0-7][0-9A-HJKMNP-TV-Z]{25}$", "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" ] } }, "monthly_budget_credits": { "description": "Agent keys only. Default 1000 credits a month (to confirm).", "type": "integer", "minimum": 0 }, "per_order_max_credits": { "description": "Agent keys only, and required there: the most one order may spend, no more than monthly_budget_credits.", "type": "integer", "minimum": 0 }, "webhook_url": { "description": "Agent keys only: the https endpoint its events go to.", "type": "string", "format": "uri", "pattern": "^https://" }, "disclosure": { "description": "Agent keys only. anonymous makes every count follow an anonymous visitor's rules, for a public assistant. Default account.", "type": "string", "enum": [ "account", "anonymous" ] }, "licence_accepted_version": { "description": "Agent keys only, and required for one that spends on its own (create_order or enrich_contact, with a monthly budget and a per-order cap above 0): the version of the Data Licence and Sharing Agreement the person making the key accepts, the account's agreements.dlsa.version. Every order and enrichment the key makes on its own carries that acceptance. A key with a budget or cap of 0 needs none: a person approves, and accepts, each of its spends.", "type": "string", "minLength": 1, "maxLength": 100 } }, "required": [ "kind", "label", "scopes" ], "additionalProperties": false, "description": "A new key, made by a signed-in person (an OAuth user token with admin), never by a key. An agent key needs allowed_tools and per_order_max_credits, no more than its monthly budget, and never takes admin.", "allOf": [ { "if": { "type": "object", "properties": { "kind": { "const": "agent" } }, "required": [ "kind" ] }, "then": { "type": "object", "properties": { "allowed_tools": true, "per_order_max_credits": true, "scopes": { "type": "array", "not": { "contains": { "const": "admin" } } } }, "required": [ "allowed_tools", "per_order_max_credits" ] }, "else": { "type": "object", "properties": { "allowed_tools": false, "allowed_connection_ids": false, "monthly_budget_credits": false, "per_order_max_credits": false, "webhook_url": false, "disclosure": false } } } ] }, "ApiKeyUpdate": { "type": "object", "properties": { "label": { "type": "string", "minLength": 1, "maxLength": 100 }, "scopes": { "description": "Replacement scopes. An agent key never takes admin, and no key takes account:write, which only a signed-in owner uses.", "minItems": 1, "type": "array", "items": { "type": "string", "enum": [ "account:read", "counts:read", "previews:read", "audiences:read", "audiences:write", "quotes:read", "orders:read", "orders:write", "records:read", "enrich:write", "suppressions:read", "suppressions:write", "pushes:write", "webhooks:write", "samples:request", "admin" ] } }, "ip_allowlist": { "type": "array", "items": { "anyOf": [ { "type": "string", "pattern": "^((25[0-5]|2[0-4][0-9]|1[0-9][0-9]|[1-9][0-9]|[0-9])\\.){3}(25[0-5]|2[0-4][0-9]|1[0-9][0-9]|[1-9][0-9]|[0-9])\\/([0-9]|[1-2][0-9]|3[0-2])$" }, { "type": "string", "pattern": "^(([0-9a-fA-F]{1,4}:){7}[0-9a-fA-F]{1,4}|([0-9a-fA-F]{1,4}:){1,7}:|([0-9a-fA-F]{1,4}:){1,6}:[0-9a-fA-F]{1,4}|([0-9a-fA-F]{1,4}:){1,5}(:[0-9a-fA-F]{1,4}){1,2}|([0-9a-fA-F]{1,4}:){1,4}(:[0-9a-fA-F]{1,4}){1,3}|([0-9a-fA-F]{1,4}:){1,3}(:[0-9a-fA-F]{1,4}){1,4}|([0-9a-fA-F]{1,4}:){1,2}(:[0-9a-fA-F]{1,4}){1,5}|[0-9a-fA-F]{1,4}:((:[0-9a-fA-F]{1,4}){1,6})|:((:[0-9a-fA-F]{1,4}){1,7}|:))\\/(12[0-8]|1[01][0-9]|[1-9]?[0-9])$" } ], "description": "An IPv4 or IPv6 range in CIDR notation, such as 203.0.113.0/24." }, "description": "CIDR ranges the key may be used from; empty allows any address." }, "expires_at": { "anyOf": [ { "type": "string", "format": "date-time", "description": "RFC 3339 date and time, with Z or an offset such as +01:00." }, { "type": "null" } ] }, "allowed_tools": { "type": "array", "items": { "type": "string", "enum": [ "get_plans", "get_account", "list_filters", "search_filter_values", "expand_job_titles", "resolve_location", "compile_audience", "count_audience", "preview_records", "save_audience", "list_audiences", "list_field_sets", "quote_order", "create_order", "get_order", "fetch_order_records", "push_to_crm", "lookup_company", "enrich_contact", "check_suppression", "report_objection", "get_compliance_receipt" ] } }, "allowed_connection_ids": { "type": "array", "items": { "type": "string", "pattern": "^conn_[0-7][0-9A-HJKMNP-TV-Z]{25}$", "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" ] } }, "monthly_budget_credits": { "type": "integer", "minimum": 0 }, "per_order_max_credits": { "type": "integer", "minimum": 0 }, "webhook_url": { "anyOf": [ { "type": "string", "format": "uri", "pattern": "^https://" }, { "type": "null" } ] }, "disclosure": { "type": "string", "enum": [ "account", "anonymous" ] }, "licence_accepted_version": { "description": "The Data Licence and Sharing Agreement version the person changing the key accepts: required when the change lets an agent key spend on its own (create_order or enrich_contact, a budget and a cap above 0), or widens what it spends (a spending tool added, a larger budget or cap), and the key has not accepted the version in force. Sent alone, it renews the key's acceptance.", "type": "string", "minLength": 1, "maxLength": 100 } }, "additionalProperties": false, "description": "Members to change on a key, at least one. Only a signed-in person changes a key; a key never changes its own tools, budget or cap.", "minProperties": 1 }, "Audience": { "type": "object", "properties": { "schema": { "type": "string", "const": "mydatahub.audience/1", "description": "The definition's namespace and version. Older versions are upgraded by a pure function." }, "dataset": { "type": "string", "enum": [ "uk_contacts", "ie_contacts", "global_contacts" ], "description": "The dataset an audience draws from. uk_contacts is live; ie_contacts and global_contacts are listed but not yet served." }, "dataset_version": { "description": "The weekly build to count against, such as 2026-W39. Left out, the current version is filled in and returned.", "type": "string", "pattern": "^[0-9]{4}-W(0[1-9]|[1-4][0-9]|5[0-3])$", "examples": [ "2026-W39" ] }, "where": { "description": "The filters. Left out, the audience is the whole dataset after the defaults.", "$ref": "#/components/schemas/WhereNode" }, "email_policy": { "$ref": "#/components/schemas/EmailPolicy" }, "dedupe": { "type": "string", "enum": [ "none", "one_per_company", "one_per_site" ], "description": "none keeps every matching contact, one_per_company keeps one contact per company, one_per_site keeps one per site. Default none." } }, "required": [ "schema" ], "additionalProperties": false, "title": "MyDataHub audience definition (mydatahub.audience/1)", "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." }, "AudienceCountSummary": { "type": "object", "properties": { "count_id": { "type": "string", "pattern": "^cnt_[A-Z2-7]{20}$", "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" ] }, "dataset_version": { "type": "string", "pattern": "^[0-9]{4}-W(0[1-9]|[1-4][0-9]|5[0-3])$", "description": "The immutable weekly build a count is bound to, such as 2026-W39. The last 52 stay queryable.", "examples": [ "2026-W39" ] }, "contacts": { "type": "integer", "minimum": 0 }, "companies": { "type": "integer", "minimum": 0 }, "emailable": { "type": "integer", "minimum": 0 }, "counted_at": { "type": "string", "format": "date-time" } }, "required": [ "count_id", "dataset_version", "contacts", "companies", "emailable", "counted_at" ], "description": "The headline numbers of one count of an audience." }, "AudienceRef": { "anyOf": [ { "type": "string", "pattern": "^aud_[0-7][0-9A-HJKMNP-TV-Z]{25}$", "description": "Format: an audience id: aud_ followed by a 26 character ULID in upper case Crockford base32, such as aud_01JB4H2K9V6XN3M9R6T1Y5W8ZA.", "examples": [ "aud_01JB4H2K9V6XN3M9R6T1Y5W8ZA" ] }, { "$ref": "#/components/schemas/Audience" } ], "description": "An audience definition (mydatahub.audience/1) inline, or the aud_ id of a saved audience." }, "AudienceRefresh": { "type": "object", "properties": { "audience_id": { "type": "string", "pattern": "^aud_[0-7][0-9A-HJKMNP-TV-Z]{25}$", "description": "Format: an audience id: aud_ followed by a 26 character ULID in upper case Crockford base32, such as aud_01JB4H2K9V6XN3M9R6T1Y5W8ZA.", "examples": [ "aud_01JB4H2K9V6XN3M9R6T1Y5W8ZA" ] }, "previous": { "anyOf": [ { "$ref": "#/components/schemas/AudienceCountSummary" }, { "type": "null" } ] }, "current": { "$ref": "#/components/schemas/AudienceCountSummary" }, "diff": { "type": "object", "properties": { "contacts": { "type": "integer" }, "companies": { "type": "integer" }, "emailable": { "type": "integer" }, "new_records": { "type": "integer", "minimum": 0, "description": "Records in the audience that were not before." }, "removed_records": { "type": "integer", "minimum": 0 } }, "required": [ "contacts", "companies", "emailable", "new_records", "removed_records" ] } }, "required": [ "audience_id", "previous", "current", "diff" ], "description": "A saved audience recounted on the current dataset version, with the difference." }, "AudienceRefreshedEvent": { "type": "object", "properties": { "id": { "type": "string", "pattern": "^evt_[0-7][0-9A-HJKMNP-TV-Z]{25}$", "description": "Also sent as the webhook-id header; your idempotency key.", "examples": [ "evt_01JB4NB7T1Y5W8ZAK8Q2V7XN3M" ] }, "type": { "type": "string", "const": "audience.refreshed" }, "timestamp": { "type": "string", "format": "date-time" }, "api_version": { "type": "string", "pattern": "^[0-9]{4}-(0[1-9]|1[0-2])-(0[1-9]|[12][0-9]|3[01])$", "description": "A dated MyDataHub-Version, such as 2027-01-15." }, "data": { "$ref": "#/components/schemas/AudienceRefresh" } }, "required": [ "id", "type", "timestamp", "api_version", "data" ], "description": "A saved audience was recounted, with the diff." }, "BetweenFilter": { "type": "object", "properties": { "field": { "type": "string", "enum": [ "company.employee_band", "company.turnover_band", "company.fleet_band", "contact.job_level_rank", "email.deliverability_score" ] }, "op": { "type": "string", "const": "between" }, "from": { "anyOf": [ { "type": "string", "minLength": 1, "maxLength": 200 }, { "type": "number" } ], "description": "A band code or a number from the field's order." }, "to": { "anyOf": [ { "type": "string", "minLength": 1, "maxLength": 200 }, { "type": "number" } ], "description": "A band code or a number from the field's order." } }, "required": [ "field", "op", "from", "to" ], "additionalProperties": false, "description": "The field lies from one value to another inclusive, over the field's order.", "examples": [ { "field": "company.employee_band", "op": "between", "from": "10-19", "to": "200-349" } ], "allOf": [ { "if": { "type": "object", "properties": { "field": { "const": "company.employee_band" } }, "required": [ "field" ] }, "then": { "type": "object", "properties": { "from": { "type": "string", "enum": [ "1-5", "6-9", "10-19", "20-49", "50-99", "100-199", "200-349", "350-499", "500-999", "1000-1499", "1500-4999", "5000-9999", "10000+" ] }, "to": { "type": "string", "enum": [ "1-5", "6-9", "10-19", "20-49", "50-99", "100-199", "200-349", "350-499", "500-999", "1000-1499", "1500-4999", "5000-9999", "10000+" ] } } } }, { "if": { "type": "object", "properties": { "field": { "const": "company.turnover_band" } }, "required": [ "field" ] }, "then": { "type": "object", "properties": { "from": { "type": "string", "enum": [ "1-100k", "101k-200k", "201k-500k", "501k-750k", "751k-1M", "1.1M-2M", "2.1M-5M", "5.1M-7.5M", "7.6M-10M", "11M-20M", "21M-50M", "51M-75M", "76M-100M", "100M-250M", "251M-500M", "501M-1B", "1B+" ] }, "to": { "type": "string", "enum": [ "1-100k", "101k-200k", "201k-500k", "501k-750k", "751k-1M", "1.1M-2M", "2.1M-5M", "5.1M-7.5M", "7.6M-10M", "11M-20M", "21M-50M", "51M-75M", "76M-100M", "100M-250M", "251M-500M", "501M-1B", "1B+" ] } } } }, { "if": { "type": "object", "properties": { "field": { "const": "company.fleet_band" } }, "required": [ "field" ] }, "then": { "type": "object", "properties": { "from": { "type": "string", "enum": [ "1-2", "3-5", "6-9", "10-19", "20-49", "50-99", "100+" ] }, "to": { "type": "string", "enum": [ "1-2", "3-5", "6-9", "10-19", "20-49", "50-99", "100+" ] } } } }, { "if": { "type": "object", "properties": { "field": { "const": "contact.job_level_rank" } }, "required": [ "field" ] }, "then": { "type": "object", "properties": { "from": { "type": "integer", "enum": [ 1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12, 13 ] }, "to": { "type": "integer", "enum": [ 1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12, 13 ] } } } }, { "if": { "type": "object", "properties": { "field": { "const": "email.deliverability_score" } }, "required": [ "field" ] }, "then": { "type": "object", "properties": { "from": { "type": "integer", "minimum": 0, "maximum": 100 }, "to": { "type": "integer", "minimum": 0, "maximum": 100 } } } } ] }, "BillingAddress": { "type": "object", "properties": { "line1": { "type": [ "string", "null" ] }, "line2": { "type": [ "string", "null" ] }, "city": { "type": [ "string", "null" ] }, "postal_code": { "type": [ "string", "null" ] }, "state": { "description": "A county or region, when given.", "type": [ "string", "null" ] }, "country": { "description": "Two letters, such as GB.", "type": [ "string", "null" ] } }, "required": [ "line1", "line2", "city", "postal_code", "state", "country" ], "description": "The billing address Stripe Checkout collected." }, "Breakdown": { "type": "object", "properties": { "by": { "type": "string", "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" ], "description": "A field a count can be broken down by." }, "cells": { "maxItems": 50, "type": "array", "items": { "$ref": "#/components/schemas/BreakdownCell" } }, "other": { "anyOf": [ { "$ref": "#/components/schemas/OtherBucket" }, { "type": "null" } ] } }, "required": [ "by", "cells" ], "description": "A count split by one field: the top 50 cells plus other. Cells under 10 read \"under 10\"." }, "BreakdownCell": { "type": "object", "properties": { "value": { "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.", "anyOf": [ { "type": "string" }, { "type": "number" }, { "type": "boolean" } ] }, "filter_value": { "description": "The value a filter takes when it differs from value, such as 6 for director on contact.job_level_rank (filters take ranks).", "anyOf": [ { "type": "string" }, { "type": "number" }, { "type": "boolean" } ] }, "label": { "type": "string" }, "contacts": { "$ref": "#/components/schemas/CellCount" }, "companies": { "$ref": "#/components/schemas/CellCount" } }, "required": [ "value", "contacts" ], "description": "One cell of a breakdown." }, "BriefQuestion": { "type": "object", "properties": { "id": { "type": "string" }, "text": { "type": "string" }, "options": { "type": "array", "items": { "type": "object", "properties": { "label": { "type": "string" }, "filter": { "$ref": "#/components/schemas/Filter" } }, "required": [ "label", "filter" ] } } }, "required": [ "id", "text", "options" ], "description": "An ambiguity to answer before counting." }, "BriefRequest": { "type": "object", "properties": { "brief": { "type": "string", "minLength": 3, "maxLength": 2000, "description": "A plain English brief, such as \"300 finance directors at law firms in Manchester\"." }, "dataset": { "type": "string", "enum": [ "uk_contacts", "ie_contacts", "global_contacts" ], "description": "The dataset an audience draws from. uk_contacts is live; ie_contacts and global_contacts are listed but not yet served." } }, "required": [ "brief" ], "additionalProperties": false, "description": "A brief to compile into an audience definition." }, "Budget": { "type": "object", "properties": { "monthly_credits": { "type": "integer", "minimum": 0 }, "spent": { "type": "number", "minimum": 0, "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)." }, "remaining": { "type": "number", "minimum": 0, "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)." }, "resets_at": { "type": "string", "format": "date-time" } }, "required": [ "monthly_credits", "spent", "remaining", "resets_at" ], "description": "An agent key's monthly budget in credits." }, "BundleNode": { "type": "object", "properties": { "bundle": { "type": "string", "enum": [ "sdm", "manager_and_above", "owner_managed" ] } }, "required": [ "bundle" ], "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)." }, "BusinessDetails": { "type": "object", "properties": { "confirmed_at": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ], "description": "When a person confirmed the business name and that it is a UK business; null until then." }, "required_before_order": { "type": "boolean", "description": "true: an order or an enrichment 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 needs them, and whether it does is set when it is made." }, "name_editable": { "type": "boolean", "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." } }, "required": [ "confirmed_at", "required_before_order", "name_editable" ], "description": "Whether the business name and a UK business confirmation are on record, which a self-serve account needs before its first order." }, "BuyerKit": { "type": "object", "properties": { "draft_lia_url": { "type": "string", "format": "uri" }, "first_email_wording_url": { "type": "string", "format": "uri" }, "article30_stub_url": { "type": "string", "format": "uri" }, "due_diligence_file_url": { "type": "string", "format": "uri" } }, "required": [ "draft_lia_url", "first_email_wording_url", "article30_stub_url", "due_diligence_file_url" ], "description": "Four signed documents that help the buyer use the list lawfully." }, "CellCount": { "anyOf": [ { "type": "integer", "minimum": 0 }, { "type": "string", "const": "under 10" }, { "type": "string", "const": "suppressed" } ], "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" ] }, "Chip": { "type": "object", "properties": { "label": { "type": "string", "description": "What the chip reads, such as Within 20 miles of Leeds." }, "pointer": { "type": "string", "description": "JSON pointer to the filter inside audience." }, "from_brief": { "type": "string", "description": "The words of the brief it came from." } }, "required": [ "label", "pointer", "from_brief" ], "description": "One visible, editable filter compiled from the brief." }, "CompanyCompliance": { "type": "object", "properties": { "lawful_basis": { "type": "string", "enum": [ "legitimate_interests_art6_1_f" ] }, "subscriber_class": { "type": "string", "enum": [ "ltd", "plc", "llp", "scottish_partnership", "public_body", "charity_incorporated", "sole_trader", "ordinary_partnership", "unknown" ] }, "corporate_subscriber": { "type": "boolean" }, "email_marketing_basis": { "type": "string", "enum": [ "pecr_corporate_subscriber", "consent_required" ] }, "subscriber_evidence": { "type": "object", "properties": { "companies_house_number": { "type": [ "string", "null" ] }, "company_type": { "type": "string" } }, "required": [ "companies_house_number", "company_type" ] }, "provenance": { "type": "object", "properties": { "company": { "type": "object", "properties": { "source": { "type": "string", "enum": [ "emailmovers_research", "companies_house", "onspd", "ukbizdirectory", "partner_rampedup" ] }, "as_of": { "type": "string", "format": "date" } }, "required": [ "source", "as_of" ] } }, "required": [ "company" ] }, "attribution": { "type": [ "string", "null" ] } }, "required": [ "lawful_basis", "subscriber_class", "corporate_subscriber", "email_marketing_basis", "subscriber_evidence", "provenance", "attribution" ], "description": "The company facts of the compliance object, for results with no contact." }, "CompanyLookup": { "type": "object", "properties": { "match_confidence": { "type": "number", "minimum": 0, "maximum": 1 }, "dataset_version": { "type": "string", "pattern": "^[0-9]{4}-W(0[1-9]|[1-4][0-9]|5[0-3])$", "description": "The immutable weekly build a count is bound to, such as 2026-W39. The last 52 stay queryable.", "examples": [ "2026-W39" ] }, "company": { "type": "object", "properties": { "companies_house_number": { "type": [ "string", "null" ] }, "name": { "type": "string" }, "status": { "type": "string" }, "type": { "type": "string" }, "subscriber_class": { "type": "string", "enum": [ "ltd", "plc", "llp", "scottish_partnership", "public_body", "charity_incorporated", "sole_trader", "ordinary_partnership", "unknown" ] }, "incorporation_date": { "anyOf": [ { "type": "string", "format": "date" }, { "type": "null" } ] }, "sic_2007": { "type": "array", "items": { "$ref": "#/components/schemas/SicCode" } }, "employee_band": { "type": [ "string", "null" ] }, "turnover_band": { "type": [ "string", "null" ] }, "website_domain": { "type": [ "string", "null" ] }, "registered_office": { "type": "object", "properties": { "town": { "type": [ "string", "null" ] }, "postcode": { "type": [ "string", "null" ] } }, "required": [ "town", "postcode" ] } }, "required": [ "companies_house_number", "name", "status", "type", "subscriber_class", "incorporation_date", "sic_2007", "employee_band", "turnover_band", "website_domain", "registered_office" ] }, "contacts_held": { "anyOf": [ { "$ref": "#/components/schemas/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." }, "contacts_by_level": { "anyOf": [ { "type": "array", "items": { "$ref": "#/components/schemas/LevelCount" } }, { "type": "null" } ], "description": "The same count by job level, most senior first, with Level not known last; null when signed out." }, "disclosure": { "$ref": "#/components/schemas/Disclosure" }, "compliance": { "$ref": "#/components/schemas/CompanyCompliance" }, "credits_charged": { "type": "number", "const": 0 } }, "required": [ "match_confidence", "dataset_version", "company", "contacts_held", "contacts_by_level", "disclosure", "compliance", "credits_charged" ], "description": "Companies House fields for one company and, for signed-in callers, the contacts held there. No contact details." }, "CompanyLookupRequest": { "type": "object", "properties": { "company_number": { "type": "string", "pattern": "^[A-Z0-9]{8}$", "description": "Eight characters in upper case, such as 05046417 or SC123456." }, "domain": { "type": "string", "minLength": 3, "maxLength": 253 }, "name": { "type": "string", "minLength": 2, "maxLength": 200 }, "town": { "description": "Narrows a name search.", "type": "string", "maxLength": 100 } }, "additionalProperties": false, "description": "A company by exactly one of number, domain or name.", "oneOf": [ { "type": "object", "properties": { "company_number": true }, "required": [ "company_number" ] }, { "type": "object", "properties": { "domain": true }, "required": [ "domain" ] }, { "type": "object", "properties": { "name": true }, "required": [ "name" ] } ] }, "CompiledBrief": { "type": "object", "properties": { "audience": { "$ref": "#/components/schemas/Audience" }, "readback": { "type": "string", "description": "The audience in one sentence, to confirm with the person." }, "chips": { "type": "array", "items": { "$ref": "#/components/schemas/Chip" } }, "questions": { "type": "array", "items": { "$ref": "#/components/schemas/BriefQuestion" } }, "unrecognised": { "type": "array", "items": { "type": "string" }, "description": "Words of the brief that matched no filter, shown rather than guessed." }, "quantity": { "anyOf": [ { "type": "integer", "minimum": 0 }, { "type": "null" } ], "description": "A quantity named in the brief, such as 300, for quote_order limit." } }, "required": [ "audience", "readback", "chips", "questions", "unrecognised", "quantity" ], "description": "An audience definition from a brief, with its chips and any questions." }, "CompiledPlan": { "type": "object", "properties": { "engine_rules_version": { "type": "string" }, "defaults_applied": { "type": "array", "items": { "type": "string", "pattern": "^[a-z0-9]+(_[a-z0-9]+)*$" }, "description": "Defaults the server filled, such as active_companies and named_emails." }, "expanded_terms": { "type": "array", "items": { "$ref": "#/components/schemas/ExpandedTerm" } }, "centres": { "type": "array", "items": { "$ref": "#/components/schemas/ResolvedCentre" } }, "sic_codes": { "type": "array", "items": { "type": "string" }, "description": "SIC codes behind any business class filter." }, "geography_sets": { "type": "array", "items": { "type": "string" } }, "suppressions": { "type": "array", "items": { "$ref": "#/components/schemas/SuppressionChecksum" } } }, "required": [ "engine_rules_version", "defaults_applied", "expanded_terms", "centres", "sic_codes", "geography_sets", "suppressions" ], "description": "How the definition was run: expanded terms, resolved centres, SIC codes behind a business class and suppression checksums." }, "ComplianceObject": { "type": "object", "properties": { "lawful_basis": { "type": "string", "enum": [ "legitimate_interests_art6_1_f" ], "description": "UK GDPR Article 6(1)(f) legitimate interests, with the LIA in lia_ref." }, "lia_ref": { "type": "string", "description": "The published legitimate interests assessment." }, "subscriber_class": { "type": "string", "enum": [ "ltd", "plc", "llp", "scottish_partnership", "public_body", "charity_incorporated", "sole_trader", "ordinary_partnership", "unknown" ], "description": "PECR subscriber class: ltd, plc, llp, scottish_partnership, public_body, charity_incorporated, sole_trader, ordinary_partnership, unknown." }, "corporate_subscriber": { "type": "boolean", "description": "True for companies, LLPs, Scottish partnerships and public bodies, where the PECR regulation 22 consent rule does not apply." }, "email_marketing_basis": { "type": "string", "enum": [ "pecr_corporate_subscriber", "consent_required" ] }, "subscriber_evidence": { "type": "object", "properties": { "companies_house_number": { "type": [ "string", "null" ] }, "company_type": { "type": "string" } }, "required": [ "companies_house_number", "company_type" ], "description": "The register entry behind subscriber_class." }, "article14_status": { "type": "string", "enum": [ "notified", "publicly_notified_disproportionate_effort", "pending_within_window" ], "description": "Article 14 notice status: notified, publicly_notified_disproportionate_effort, pending_within_window." }, "article14_notified_at": { "anyOf": [ { "type": "string", "format": "date" }, { "type": "null" } ] }, "notice_version": { "type": "string", "description": "The privacy notice version sent." }, "provenance": { "$ref": "#/components/schemas/Provenance" }, "tps_ctps_status": { "type": "string", "enum": [ "clear", "tps_registered", "ctps_registered", "tps_or_ctps_registered", "not_screened" ], "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." }, "tps_ctps_screened_at": { "anyOf": [ { "type": "string", "format": "date" }, { "type": "null" } ], "description": "The date of the screen the status is as of; null when not screened." }, "tps_ctps_valid_until": { "anyOf": [ { "type": "string", "format": "date" }, { "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." }, "suppression_status": { "type": "string", "enum": [ "none", "objected_to_emailmovers", "objected_to_licensee", "deceased", "left_company" ] }, "record_age_days": { "type": "integer", "minimum": 0, "description": "Days since the record was compiled." }, "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" ] } }, "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" ], "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": [ { "lawful_basis": "legitimate_interests_art6_1_f", "lia_ref": "EM-LIA-2026-03", "subscriber_class": "ltd", "corporate_subscriber": true, "email_marketing_basis": "pecr_corporate_subscriber", "subscriber_evidence": { "companies_house_number": "05046417", "company_type": "ltd" }, "article14_status": "notified", "article14_notified_at": "2026-06-14", "notice_version": "2026-02", "provenance": { "company": { "source": "companies_house", "as_of": "2026-09-21" }, "contact": { "source": "emailmovers_research", "compiled_at": "2026-05-02", "last_verified_at": "2026-08-30", "method": "telephone" }, "email": { "verified_at": "2026-09-10", "result": "ok", "provider_location": "EU" } }, "tps_ctps_status": "clear", "tps_ctps_screened_at": "2026-09-12", "tps_ctps_valid_until": "2026-10-10", "suppression_status": "none", "record_age_days": 147, "attribution": "Contains public sector information licensed under the Open Government Licence v3.0" } ] }, "ComplianceReceipt": { "type": "object", "properties": { "id": { "type": "string", "pattern": "^rcpt_[0-7][0-9A-HJKMNP-TV-Z]{25}$", "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" ] }, "order_id": { "type": "string", "pattern": "^ord_[0-7][0-9A-HJKMNP-TV-Z]{25}$", "description": "Format: an order id: ord_ followed by a 26 character ULID in upper case Crockford base32, such as ord_01JB4N9S3W2X6Y7Z8A1B2C3D4E.", "examples": [ "ord_01JB4N9S3W2X6Y7Z8A1B2C3D4E" ] }, "jws": { "type": "string", "pattern": "^[A-Za-z0-9_-]+\\.[A-Za-z0-9_-]+\\.[A-Za-z0-9_-]+$", "description": "The receipt as a compact JWS signed with ES256." }, "alg": { "type": "string", "const": "ES256" }, "kid": { "type": "string", "description": "The signing key id in jwks_url." }, "jwks_url": { "type": "string", "format": "uri" }, "pdf_url": { "type": "string", "format": "uri", "description": "The PDF twin at mydatahub.emailmovers.com/receipts/{id}." }, "claims": { "$ref": "#/components/schemas/ReceiptClaims" } }, "required": [ "id", "order_id", "jws", "alg", "kid", "jwks_url", "pdf_url", "claims" ], "description": "A signed compliance receipt for an order, verifiable by anyone with POST /v1/compliance/receipts/verify." }, "ComplianceSummary": { "type": "object", "properties": { "lawful_basis": { "type": "string", "enum": [ "legitimate_interests_art6_1_f" ] }, "corporate_subscriber": { "type": "integer", "minimum": 0, "description": "Records at corporate subscribers." }, "individual_subscriber_excluded": { "type": "integer", "minimum": 0, "description": "Sole traders and ordinary partnerships left out of an email audience." }, "tps_ctps_excluded": { "type": "integer", "minimum": 0, "description": "TPS or CTPS registered numbers left out when phone is requested." }, "article14_notified": { "type": "integer", "minimum": 0 }, "article14_pending_within_window": { "type": "integer", "minimum": 0, "description": "Records inside the one month Article 14 window, not yet notified." }, "suppressed_removed": { "type": "array", "items": { "$ref": "#/components/schemas/SuppressionRemoval" } }, "jurisdiction_excluded": { "description": "Partner datasets only: records the jurisdiction policy table left out (Germany, Canada and California by policy), reported like suppression removals.", "type": "array", "items": { "$ref": "#/components/schemas/JurisdictionExclusion" } } }, "required": [ "lawful_basis", "corporate_subscriber", "individual_subscriber_excluded", "tps_ctps_excluded", "article14_notified", "article14_pending_within_window", "suppressed_removed" ], "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." }, "ConfirmationRequiredProblem": { "type": "object", "properties": { "type": { "type": "string", "format": "uri", "description": "A URI under https://emailmovers.com/mydatahub/docs/errors/ naming the problem type." }, "title": { "type": "string", "description": "A short summary of the problem type." }, "status": { "type": "integer", "minimum": 400, "maximum": 599 }, "detail": { "type": "string", "description": "What happened on this request, in plain English." }, "instance": { "description": "The request path or a request id this problem belongs to.", "type": "string" }, "code": { "type": "string", "const": "confirmation-required" }, "next_step": { "type": "string", "description": "What to do next, in plain English." }, "did_you_mean": { "description": "The closest valid values, best first.", "type": "array", "items": { "type": "string" } }, "errors": { "description": "For validation-failed: every problem found, each with a JSON pointer.", "type": "array", "items": { "$ref": "#/components/schemas/ProblemError" } }, "required_scope": { "description": "For insufficient-scope: the scope to request, such as orders:write.", "type": "string" }, "retry_after_seconds": { "description": "For rate-limited and service-unavailable: the same value as the Retry-After header.", "type": "integer", "minimum": 0 }, "action": { "type": "string", "enum": [ "order", "enrichment", "live_push" ], "description": "What needs confirming: an order, an enrichment or a live CRM push." }, "quote_id": { "description": "For an order: the machine quote to keep. A person can approve it later.", "type": "string", "pattern": "^qte_[0-7][0-9A-HJKMNP-TV-Z]{25}$", "examples": [ "qte_01JB4M2R6T1Y5W8ZAK8Q2V7XN3" ] }, "approval_url": { "type": "string", "format": "uri", "description": "A page on mydatahub.emailmovers.com where the signed-in person approves, such as mydatahub.emailmovers.com/quotes/{id}/approve. It returns a confirmation_token bound to that person (their sub), this spend and an expiry." }, "expires_at": { "description": "When the approval page stops accepting: the machine quote's expiry.", "type": "string", "format": "date-time" } }, "required": [ "type", "title", "status", "detail", "code", "next_step", "action", "approval_url" ], "description": "403: no human confirmation came with a spend, and no agent key covers it. A standard API key or an OAuth token alone never spends. Nothing was charged and no order was created." }, "ConfirmedBy": { "type": "object", "properties": { "method": { "type": "string", "enum": [ "elicitation_form", "approval_url", "agent_key", "app" ], "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)." }, "key_id": { "description": "The agent key, for agent_key.", "type": "string", "pattern": "^key_[0-7][0-9A-HJKMNP-TV-Z]{25}$", "examples": [ "key_01JB3Z4Q2V7XN3M9R6T1Y5W8ZA" ] }, "user_id": { "description": "The person who confirmed.", "type": "string", "pattern": "^usr_[0-7][0-9A-HJKMNP-TV-Z]{25}$", "examples": [ "usr_01JA0Q3V7XN3M9R6T1Y5W8ZAK8" ] }, "client_id": { "description": "The OAuth client, such as a Client ID Metadata Document URL.", "type": "string" }, "user_agent": { "description": "The calling client's User-Agent.", "type": [ "string", "null" ] }, "mtls_certificate_fingerprint": { "description": "SHA-256 of the client certificate when one was presented (ChatGPT's mTLS).", "type": [ "string", "null" ] }, "web_bot_auth_signature_agent": { "description": "The Signature-Agent of a verified Web Bot Auth signature, when present.", "type": [ "string", "null" ] }, "confirmed_at": { "type": "string", "format": "date-time" } }, "required": [ "method" ], "description": "Who approved the spend and from which client, recorded in the audit trail and on invoices." }, "Connection": { "type": "object", "properties": { "id": { "type": "string", "pattern": "^conn_[0-7][0-9A-HJKMNP-TV-Z]{25}$", "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" ] }, "provider": { "type": "string", "enum": [ "hubspot", "salesforce", "google_sheets", "deliverite", "webhook", "csv" ] }, "name": { "type": "string" }, "status": { "type": "string", "enum": [ "pending_authorisation", "connected", "expired", "revoked" ] }, "authorise_url": { "anyOf": [ { "type": "string", "format": "uri" }, { "type": "null" } ], "description": "Where a person authorises the connection in the app, while pending_authorisation." }, "read_only_overlap": { "type": "boolean", "description": "Whether the connection may read email hashes for the New to you overlap check." }, "created_at": { "type": "string", "format": "date-time" }, "last_used_at": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ] } }, "required": [ "id", "provider", "name", "status", "authorise_url", "read_only_overlap", "created_at", "last_used_at" ], "description": "A CRM or destination connection." }, "ConnectionExpiredEvent": { "type": "object", "properties": { "id": { "type": "string", "pattern": "^evt_[0-7][0-9A-HJKMNP-TV-Z]{25}$", "description": "Also sent as the webhook-id header; your idempotency key.", "examples": [ "evt_01JB4NB7T1Y5W8ZAK8Q2V7XN3M" ] }, "type": { "type": "string", "const": "connection.expired" }, "timestamp": { "type": "string", "format": "date-time" }, "api_version": { "type": "string", "pattern": "^[0-9]{4}-(0[1-9]|1[0-2])-(0[1-9]|[12][0-9]|3[01])$", "description": "A dated MyDataHub-Version, such as 2027-01-15." }, "data": { "type": "object", "properties": { "connection_id": { "type": "string", "pattern": "^conn_[0-7][0-9A-HJKMNP-TV-Z]{25}$", "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" ] }, "provider": { "type": "string" }, "reconnect_url": { "type": "string", "format": "uri" } }, "required": [ "connection_id", "provider", "reconnect_url" ] } }, "required": [ "id", "type", "timestamp", "api_version", "data" ], "description": "A CRM token failed; reconnect in the app." }, "ConnectionList": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Connection" } }, "has_more": { "type": "boolean", "description": "Whether another page follows." }, "next_cursor": { "anyOf": [ { "type": "string", "minLength": 1, "maxLength": 512, "description": "An opaque cursor from next_cursor. Pass it back unchanged." }, { "type": "null" } ], "description": "Pass as cursor to fetch the next page; null on the last page." } }, "required": [ "data", "has_more", "next_cursor" ], "description": "A page of CRM connections, newest first." }, "ConnectionRequest": { "type": "object", "properties": { "provider": { "type": "string", "enum": [ "hubspot", "salesforce", "google_sheets", "deliverite", "webhook", "csv" ] }, "name": { "type": "string", "minLength": 1, "maxLength": 100 }, "webhook_url": { "description": "Provider webhook only, and required there: the https endpoint to post to.", "type": "string", "format": "uri", "pattern": "^https://" } }, "required": [ "provider", "name" ], "additionalProperties": false, "description": "A new connection. OAuth providers return an authorise_url for a person to approve; provider webhook takes webhook_url.", "allOf": [ { "if": { "type": "object", "properties": { "provider": { "const": "webhook" } }, "required": [ "provider" ] }, "then": { "type": "object", "properties": { "webhook_url": true }, "required": [ "webhook_url" ] }, "else": { "type": "object", "not": { "type": "object", "properties": { "webhook_url": true }, "required": [ "webhook_url" ] } } } ] }, "ContactRecord": { "type": "object", "properties": { "id": { "type": "string", "pattern": "^contact_[0-7][0-9A-HJKMNP-TV-Z]{25}$", "description": "The record id, pushed to CRMs as mydatahub_record_id.", "examples": [ "contact_01JA9X2V7XN3M9R6T1Y5W8ZAK8" ] }, "dataset_version": { "type": "string", "pattern": "^[0-9]{4}-W(0[1-9]|[1-4][0-9]|5[0-3])$", "description": "The immutable weekly build a count is bound to, such as 2026-W39. The last 52 stay queryable.", "examples": [ "2026-W39" ] }, "contact": { "type": "object", "properties": { "first_name": { "type": "string" }, "last_name": { "type": "string" }, "title": { "type": "string" }, "title_family": { "type": [ "string", "null" ] }, "job_function": { "type": [ "string", "null" ] }, "job_level_rank": { "anyOf": [ { "type": "integer", "minimum": 1, "maximum": 13 }, { "type": "null" } ], "description": "Rank on the 13-rank ladder, 1 (Owner) the most senior to 13 (Volunteer); null when the level is not known." }, "job_level": { "description": "The level, such as Director; null when the level is not known.", "type": [ "string", "null" ] } }, "required": [ "first_name", "last_name", "title", "title_family", "job_function", "job_level_rank", "job_level" ] }, "email": { "anyOf": [ { "type": "object", "properties": { "address": { "type": "string", "format": "email" }, "type": { "type": "string", "enum": [ "named", "generic_local_part", "generic_domain" ] }, "deliverability_score": { "type": "integer", "minimum": 0, "maximum": 100 }, "verified_at": { "anyOf": [ { "type": "string", "format": "date" }, { "type": "null" } ] }, "result": { "type": "string", "enum": [ "ok", "catch_all", "unknown", "invalid", "disposable" ] } }, "required": [ "address", "type", "deliverability_score", "verified_at", "result" ] }, { "type": "null" } ] }, "phone": { "anyOf": [ { "type": "object", "properties": { "e164": { "type": "string", "pattern": "^\\+[1-9][0-9]{7,14}$" }, "line_type": { "type": "string", "enum": [ "landline", "mobile", "voip", "unknown" ] }, "tps_ctps_status": { "type": "string", "enum": [ "clear", "tps_registered", "ctps_registered", "tps_or_ctps_registered", "not_screened" ] }, "screened_at": { "anyOf": [ { "type": "string", "format": "date" }, { "type": "null" } ] } }, "required": [ "e164", "line_type", "tps_ctps_status", "screened_at" ] }, { "type": "null" } ], "description": "Present when the field set includes telephone and a number is held." }, "company": { "type": "object", "properties": { "name": { "type": "string" }, "companies_house_number": { "type": [ "string", "null" ] }, "status": { "type": "string" }, "type": { "type": "string" }, "subscriber_class": { "type": "string", "enum": [ "ltd", "plc", "llp", "scottish_partnership", "public_body", "charity_incorporated", "sole_trader", "ordinary_partnership", "unknown" ] }, "sic_2007": { "type": "array", "items": { "$ref": "#/components/schemas/SicCode" } }, "employee_band": { "type": [ "string", "null" ] }, "turnover_band": { "type": [ "string", "null" ] }, "website_domain": { "type": [ "string", "null" ] } }, "required": [ "name", "companies_house_number", "status", "type", "subscriber_class", "sic_2007", "employee_band", "turnover_band", "website_domain" ] }, "site": { "type": "object", "properties": { "address_lines": { "type": "array", "items": { "type": "string" } }, "town": { "type": [ "string", "null" ] }, "county": { "type": [ "string", "null" ] }, "postcode": { "type": "string" }, "region": { "type": "string" } }, "required": [ "address_lines", "town", "county", "postcode", "region" ] }, "compliance": { "$ref": "#/components/schemas/ComplianceObject" }, "licence_expires_at": { "anyOf": [ { "type": "string", "format": "date" }, { "type": "null" } ] } }, "required": [ "id", "dataset_version", "contact", "email", "phone", "company", "site", "compliance", "licence_expires_at" ], "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." }, "Count": { "type": "object", "properties": { "id": { "type": "string", "pattern": "^cnt_[A-Z2-7]{20}$", "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" ] }, "dataset": { "type": "string", "enum": [ "uk_contacts", "ie_contacts", "global_contacts" ], "description": "The dataset an audience draws from. uk_contacts is live; ie_contacts and global_contacts are listed but not yet served." }, "dataset_version": { "type": "string", "pattern": "^[0-9]{4}-W(0[1-9]|[1-4][0-9]|5[0-3])$", "description": "The immutable weekly build a count is bound to, such as 2026-W39. The last 52 stay queryable.", "examples": [ "2026-W39" ] }, "engine_rules_version": { "type": "string", "minLength": 1, "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." }, "as_of": { "description": "The date the dataset version was built, for as-of statements.", "type": "string", "format": "date" }, "level": { "type": "string", "enum": [ "contact", "company" ], "description": "contact (the default) or company. Contacts and companies come back together either way." }, "credits_per_record": { "type": "number", "minimum": 0, "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)." }, "contacts": { "type": "integer", "minimum": 0, "description": "Total: every matching contact." }, "companies": { "type": "integer", "minimum": 0 }, "emailable": { "type": "integer", "minimum": 0, "description": "A named email scoring 70 or more at a corporate subscriber." }, "new_to_you": { "anyOf": [ { "type": "integer", "minimum": 0 }, { "type": "null" } ], "description": "Excludes your earlier orders and CRM overlap; null when signed out." }, "premium": { "anyOf": [ { "type": "integer", "minimum": 0 }, { "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." }, "all_records": { "type": "integer", "minimum": 0, "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." }, "premium_note": { "type": "string", "minLength": 1, "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." }, "views": { "$ref": "#/components/schemas/CountViews" }, "quality": { "$ref": "#/components/schemas/Quality" }, "breakdowns": { "type": "array", "items": { "$ref": "#/components/schemas/Breakdown" } }, "crosstab": { "anyOf": [ { "$ref": "#/components/schemas/Crosstab" }, { "type": "null" } ] }, "compliance_summary": { "$ref": "#/components/schemas/ComplianceSummary" }, "defaults": { "type": "array", "items": { "$ref": "#/components/schemas/CountDefault" }, "description": "Every default with the number behind its toggle: dissolved and insolvent, generic emails, individual subscribers, TPS and CTPS registered." }, "estimate": { "$ref": "#/components/schemas/PriceEstimate" }, "expanded_terms": { "description": "Every title a matches filter covered, with a count per term.", "type": "array", "items": { "$ref": "#/components/schemas/ExpandedTerm" } }, "disclosure": { "$ref": "#/components/schemas/Disclosure" }, "effective_audience": { "description": "The definition after defaults and bundles, as hashed into the id.", "$ref": "#/components/schemas/Audience" }, "plan": { "$ref": "#/components/schemas/CompiledPlan" }, "current": { "description": "On a replay: the same audience on the current dataset version.", "anyOf": [ { "$ref": "#/components/schemas/CurrentCount" }, { "type": "null" } ] }, "removed_since": { "description": "On a replay: records since removed by objections and erasure.", "type": "integer", "minimum": 0 }, "warnings": { "type": "array", "items": { "type": "string" } }, "created_at": { "type": "string", "format": "date-time" }, "expires_at": { "type": "string", "format": "date-time", "description": "The id replays until then (12 months)." } }, "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" ], "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." }, "CountDefault": { "type": "object", "properties": { "id": { "type": "string", "enum": [ "active_companies", "named_emails", "corporate_subscribers", "no_registered_phones" ], "description": "active_companies, named_emails, corporate_subscribers or no_registered_phones." }, "applied": { "type": "boolean", "description": "False when the audience filters the same field itself, or turned it off." }, "views": { "type": "array", "items": { "type": "string", "enum": [ "total", "new_to_you", "emailable" ] }, "description": "The headline views the default shapes; named emails and corporate subscribers shape Emailable only." }, "removed": { "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.", "$ref": "#/components/schemas/CellCount" }, "screened_at": { "description": "no_registered_phones only: the version's TPS and CTPS screen date.", "anyOf": [ { "type": "string", "format": "date" }, { "type": "null" } ] } }, "required": [ "id", "applied", "views", "removed" ], "description": "A default the count applied, and the records it removed, for its toggle." }, "CountReplay": { "type": "object", "properties": { "id": { "type": "string", "pattern": "^cnt_[A-Z2-7]{20}$", "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" ] }, "dataset": { "type": "string", "enum": [ "uk_contacts", "ie_contacts", "global_contacts" ], "description": "The dataset an audience draws from. uk_contacts is live; ie_contacts and global_contacts are listed but not yet served." }, "dataset_version": { "type": "string", "pattern": "^[0-9]{4}-W(0[1-9]|[1-4][0-9]|5[0-3])$", "description": "The immutable weekly build a count is bound to, such as 2026-W39. The last 52 stay queryable.", "examples": [ "2026-W39" ] }, "engine_rules_version": { "type": "string", "minLength": 1, "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." }, "as_of": { "description": "The date the dataset version was built, for as-of statements.", "type": "string", "format": "date" }, "level": { "type": "string", "enum": [ "contact", "company" ], "description": "contact (the default) or company. Contacts and companies come back together either way." }, "credits_per_record": { "type": "number", "minimum": 0, "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)." }, "contacts": { "type": "integer", "minimum": 0, "description": "Total: every matching contact." }, "companies": { "type": "integer", "minimum": 0 }, "emailable": { "type": "integer", "minimum": 0, "description": "A named email scoring 70 or more at a corporate subscriber." }, "new_to_you": { "anyOf": [ { "type": "integer", "minimum": 0 }, { "type": "null" } ], "description": "Excludes your earlier orders and CRM overlap; null when signed out." }, "premium": { "anyOf": [ { "type": "integer", "minimum": 0 }, { "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." }, "all_records": { "type": "integer", "minimum": 0, "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." }, "premium_note": { "type": "string", "minLength": 1, "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." }, "views": { "$ref": "#/components/schemas/CountViews" }, "quality": { "$ref": "#/components/schemas/Quality" }, "breakdowns": { "type": "array", "items": { "$ref": "#/components/schemas/Breakdown" } }, "crosstab": { "anyOf": [ { "$ref": "#/components/schemas/Crosstab" }, { "type": "null" } ] }, "compliance_summary": { "$ref": "#/components/schemas/ComplianceSummary" }, "defaults": { "type": "array", "items": { "$ref": "#/components/schemas/CountDefault" }, "description": "Every default with the number behind its toggle: dissolved and insolvent, generic emails, individual subscribers, TPS and CTPS registered." }, "estimate": { "$ref": "#/components/schemas/PriceEstimate" }, "expanded_terms": { "description": "Every title a matches filter covered, with a count per term.", "type": "array", "items": { "$ref": "#/components/schemas/ExpandedTerm" } }, "disclosure": { "$ref": "#/components/schemas/Disclosure" }, "effective_audience": { "description": "The definition after defaults and bundles, as hashed into the id.", "$ref": "#/components/schemas/Audience" }, "plan": { "$ref": "#/components/schemas/CompiledPlan" }, "current": { "anyOf": [ { "$ref": "#/components/schemas/CurrentCount" }, { "type": "null" } ], "description": "The same audience on the current dataset version; null when the pinned version is current." }, "removed_since": { "type": "integer", "minimum": 0, "description": "Records since removed by objections and erasure." }, "warnings": { "type": "array", "items": { "type": "string" } }, "created_at": { "type": "string", "format": "date-time" }, "expires_at": { "type": "string", "format": "date-time", "description": "The id replays until then (12 months)." } }, "required": [ "id", "dataset", "dataset_version", "engine_rules_version", "credits_per_record", "contacts", "companies", "emailable", "new_to_you", "premium", "all_records", "premium_note", "views", "quality", "breakdowns", "compliance_summary", "defaults", "estimate", "disclosure", "effective_audience", "plan", "current", "removed_since", "created_at", "expires_at" ], "description": "A count replayed by id for 12 months: the effective definition, the compiled plan, the pinned dataset and engine rules versions, all three views with premium and all records, the breakdowns, the compliance summary, quality, the estimate, created_at and the number on the current dataset." }, "CountRequest": { "type": "object", "properties": { "audience": { "$ref": "#/components/schemas/AudienceRef" }, "level": { "default": "contact", "type": "string", "enum": [ "contact", "company" ], "description": "contact (the default) or company. Contacts and companies come back together either way." }, "breakdown_by": { "maxItems": 3, "type": "array", "items": { "type": "string", "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" ], "description": "A field a count can be broken down 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.", "uniqueItems": true } }, "required": [ "audience" ], "additionalProperties": false, "description": "An audience, a level and up to three breakdown fields. Free, and needs no account." }, "CountView": { "type": "object", "properties": { "contacts": { "type": "integer", "minimum": 0 }, "companies": { "type": "integer", "minimum": 0 } }, "required": [ "contacts", "companies" ], "description": "Contacts and companies in one headline view." }, "CountViews": { "type": "object", "properties": { "total": { "$ref": "#/components/schemas/CountView" }, "new_to_you": { "anyOf": [ { "$ref": "#/components/schemas/CountView" }, { "type": "null" } ], "description": "Removes records from earlier orders and a connected CRM; null when signed out." }, "emailable": { "description": "A named email scoring 70 or more at a corporate subscriber.", "$ref": "#/components/schemas/CountView" }, "premium": { "anyOf": [ { "$ref": "#/components/schemas/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." }, "all_records": { "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.", "$ref": "#/components/schemas/CountView" } }, "required": [ "total", "new_to_you", "emailable", "premium", "all_records" ], "description": "Contacts and companies for the three headline views, and the premium figure beside all records." }, "CreditPack": { "type": "object", "properties": { "id": { "type": "string", "pattern": "^[a-z0-9]+(_[a-z0-9]+)*$", "description": "Such as free, pay_as_you_go or plan_12_month." }, "name": { "type": "string" }, "kind": { "type": "string", "const": "pack" }, "status": { "type": "string", "enum": [ "confirmed", "proposed", "to_confirm" ], "description": "confirmed is in force; proposed awaits a decision; to_confirm is a figure still being checked." }, "available_to": { "type": "string", "enum": [ "everyone", "new_customers", "existing_customers" ], "description": "everyone; new_customers only (the subscription); existing_customers only, who keep their prices (pay as you go and the 12-month plan)." }, "price_gbp_ex_vat": { "type": "number", "minimum": 0, "description": "Pounds sterling excluding VAT, to two decimal places." }, "billing_period": { "type": "string", "const": "once" }, "contract_months": { "description": "The contract's length in months, such as 12; absent when there is none.", "anyOf": [ { "type": "integer", "minimum": 0 }, { "type": "null" } ] }, "annual_price_gbp_ex_vat": { "anyOf": [ { "type": "number", "minimum": 0, "description": "Pounds sterling excluding VAT, to two decimal places." }, { "type": "null" } ] }, "credits": { "type": "integer", "minimum": 0, "description": "Credits per billing period, or once." }, "per_record_gbp": { "anyOf": [ { "type": "number", "minimum": 0, "description": "Pounds sterling excluding VAT, to two decimal places." }, { "type": "null" } ], "description": "Price per record at full use of the allowance; null for the free plan." }, "rollover_cap_credits": { "description": "Subscription credits roll over while subscribed, up to this many; 0 when each period's credits are used or lost.", "anyOf": [ { "type": "integer", "minimum": 0 }, { "type": "null" } ] }, "credits_expire": { "type": "boolean" }, "for_whom": { "type": "string" }, "notes": { "type": "string" } }, "required": [ "id", "name", "kind", "status", "available_to", "price_gbp_ex_vat", "billing_period", "credits", "per_record_gbp", "credits_expire", "for_whom" ], "description": "A one-off prepaid bundle of credits, usable on any plan. Credit pack credits never expire and survive cancellation." }, "CreditPurchase": { "type": "object", "properties": { "id": { "type": "string", "pattern": "^pur_[0-7][0-9A-HJKMNP-TV-Z]{25}$", "description": "Format: a credit purchase id: pur_ followed by a 26 character ULID in upper case Crockford base32, such as pur_01JB4R7K2V7XN3M9R6T1Y5W8ZA.", "examples": [ "pur_01JB4R7K2V7XN3M9R6T1Y5W8ZA" ] }, "status": { "type": "string", "enum": [ "pending", "paid", "expired" ], "description": "pending until Stripe says the payment is paid; paid once the credits are in the balance; expired when the checkout closed unpaid (nothing was taken)." }, "label": { "type": "string", "description": "What is bought, in words, numbers first." }, "lines": { "type": "array", "items": { "$ref": "#/components/schemas/CreditPurchaseLine" } }, "credits": { "type": "integer", "minimum": 0, "description": "Credits the purchase adds when paid." }, "gbp_ex_vat": { "type": "number", "minimum": 0, "description": "Pounds sterling excluding VAT, to two decimal places." }, "vat_rate_percent": { "type": "number", "minimum": 0, "maximum": 100 }, "vat_gbp": { "type": "number", "minimum": 0, "description": "Pounds sterling, to two decimal places." }, "total_gbp": { "type": "number", "minimum": 0, "description": "What the card is charged, VAT included." }, "currency": { "type": "string", "const": "GBP" }, "gbp_per_credit": { "type": "number", "minimum": 0, "description": "What one credit of this purchase cost, excluding VAT, to six decimal places. Orders value the credits they spend at it." }, "credits_added": { "type": "integer", "minimum": 0, "description": "0 until the payment is paid." }, "checkout_url": { "anyOf": [ { "type": "string", "format": "uri" }, { "type": "null" } ], "description": "Stripe Checkout, while the purchase is pending; null once paid or expired." }, "test_mode": { "type": "boolean", "description": "Made with a Stripe test key: test cards only, and no money moves." }, "created_at": { "type": "string", "format": "date-time" }, "expires_at": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ], "description": "When the checkout closes if it is not paid." }, "paid_at": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ] }, "attention": { "anyOf": [ { "$ref": "#/components/schemas/PurchaseAttention" }, { "type": "null" } ] }, "receipt": { "anyOf": [ { "$ref": "#/components/schemas/PaymentReceipt" }, { "type": "null" } ], "description": "Once paid. The buyer's name, billing address and VAT number are shown only to a signed-in person with admin; anyone else sees them as null." } }, "required": [ "id", "status", "label", "lines", "credits", "gbp_ex_vat", "vat_rate_percent", "vat_gbp", "total_gbp", "currency", "gbp_per_credit", "credits_added", "checkout_url", "test_mode", "created_at", "expires_at", "paid_at", "attention", "receipt" ], "description": "A purchase of credits by card through Stripe Checkout. Reading a pending purchase asks Stripe for its payment (at most once every 10 seconds), and adds the credits once, when it is paid." }, "CreditPurchaseLine": { "type": "object", "properties": { "id": { "type": "string", "description": "per_contact_scale or a credit pack id." }, "quantity": { "type": "integer", "minimum": 0, "description": "Credits at the scale, or credit packs." }, "credits": { "type": "integer", "minimum": 0 }, "gbp_ex_vat": { "type": "number", "minimum": 0, "description": "Pounds sterling excluding VAT, to two decimal places." } }, "required": [ "id", "quantity", "credits", "gbp_ex_vat" ], "description": "One line of a purchase, priced." }, "CreditPurchaseLineRequest": { "type": "object", "properties": { "id": { "type": "string", "maxLength": 64, "pattern": "^[a-z0-9]+(_[a-z0-9]+)*$", "description": "per_contact_scale for credits at the scale, or the id of a credit pack on sale, such as credit_pack_40000 (GET /v1/plans)." }, "quantity": { "type": "integer", "minimum": 1, "maximum": 1000000, "description": "Credits at the scale (1 to 1,000,000), or credit packs (1 to 25)." } }, "required": [ "id", "quantity" ], "additionalProperties": false, "description": "One thing to buy." }, "CreditPurchaseList": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/CreditPurchase" } }, "has_more": { "type": "boolean", "description": "Whether another page follows." }, "next_cursor": { "anyOf": [ { "type": "string", "minLength": 1, "maxLength": 512, "description": "An opaque cursor from next_cursor. Pass it back unchanged." }, { "type": "null" } ], "description": "Pass as cursor to fetch the next page; null on the last page." }, "payments": { "type": "object", "properties": { "available": { "type": "boolean", "description": "Whether card payments are switched on for this server." }, "test_mode": { "type": "boolean", "description": "Stripe test mode: test cards only." }, "vat_rate_percent": { "type": "number", "minimum": 0, "maximum": 100 } }, "required": [ "available", "test_mode", "vat_rate_percent" ], "description": "How credits are bought here." } }, "required": [ "data", "has_more", "next_cursor", "payments" ], "description": "A page of credit purchases, newest first, and whether card payments are on." }, "CreditPurchaseRequest": { "type": "object", "properties": { "lines": { "minItems": 1, "maxItems": 5, "type": "array", "items": { "$ref": "#/components/schemas/CreditPurchaseLineRequest" }, "description": "What to buy: credits at the scale, credit packs, or both, as a quote's purchase option lists them. Each id at most once." } }, "required": [ "lines" ], "additionalProperties": false, "description": "A top-up of credits at the per-contact scale (the size of the line picks its band), the 40,000 credit pack, or a quote's purchase option line by line." }, "CreditRule": { "type": "object", "properties": { "action": { "type": "string", "pattern": "^[a-z0-9]+(_[a-z0-9]+)*$" }, "label": { "type": "string" }, "credits": { "type": "number", "minimum": 0, "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)." }, "unit": { "type": "string", "enum": [ "call", "record", "match" ] }, "status": { "type": "string", "enum": [ "confirmed", "proposed", "to_confirm" ], "description": "confirmed is in force; proposed awaits a decision; to_confirm is a figure still being checked." }, "note": { "type": "string" } }, "required": [ "action", "label", "credits", "unit", "status" ], "description": "What one action costs in credits." }, "CreditsLowEvent": { "type": "object", "properties": { "id": { "type": "string", "pattern": "^evt_[0-7][0-9A-HJKMNP-TV-Z]{25}$", "description": "Also sent as the webhook-id header; your idempotency key.", "examples": [ "evt_01JB4NB7T1Y5W8ZAK8Q2V7XN3M" ] }, "type": { "type": "string", "const": "credits.low" }, "timestamp": { "type": "string", "format": "date-time" }, "api_version": { "type": "string", "pattern": "^[0-9]{4}-(0[1-9]|1[0-2])-(0[1-9]|[12][0-9]|3[01])$", "description": "A dated MyDataHub-Version, such as 2027-01-15." }, "data": { "type": "object", "properties": { "balance": { "type": "number" }, "threshold": { "type": "integer", "minimum": 0 }, "top_up_url": { "type": "string", "format": "uri" } }, "required": [ "balance", "threshold", "top_up_url" ] } }, "required": [ "id", "type", "timestamp", "api_version", "data" ], "description": "The balance crossed the configured threshold." }, "CreditsToppedUpEvent": { "type": "object", "properties": { "id": { "type": "string", "pattern": "^evt_[0-7][0-9A-HJKMNP-TV-Z]{25}$", "description": "Also sent as the webhook-id header; your idempotency key.", "examples": [ "evt_01JB4NB7T1Y5W8ZAK8Q2V7XN3M" ] }, "type": { "type": "string", "const": "credits.topped_up" }, "timestamp": { "type": "string", "format": "date-time" }, "api_version": { "type": "string", "pattern": "^[0-9]{4}-(0[1-9]|1[0-2])-(0[1-9]|[12][0-9]|3[01])$", "description": "A dated MyDataHub-Version, such as 2027-01-15." }, "data": { "type": "object", "properties": { "credits_added": { "type": "integer", "minimum": 0 }, "balance": { "type": "number" }, "source": { "type": "string", "enum": [ "credit_pack", "top_up", "plan", "refund", "adjustment" ], "description": "credit_pack for credit packs bought by card, top_up for credits bought at the per-contact scale (with or without credit packs), plan for a plan's credits, refund or adjustment." }, "amount_gbp_ex_vat": { "anyOf": [ { "type": "number", "minimum": 0, "description": "Pounds sterling excluding VAT, to two decimal places." }, { "type": "null" } ] } }, "required": [ "credits_added", "balance", "source", "amount_gbp_ex_vat" ] } }, "required": [ "id", "type", "timestamp", "api_version", "data" ], "description": "A top-up settled." }, "CrmPropertyGroup": { "type": "object", "properties": { "mydatahub_record_id": { "type": "string", "pattern": "^contact_[0-7][0-9A-HJKMNP-TV-Z]{25}$", "description": "The record id: a Salesforce External ID, a HubSpot unique property, a Pipedrive custom field.", "examples": [ "contact_01JA9X2V7XN3M9R6T1Y5W8ZAK8" ] }, "licence_expires_at": { "anyOf": [ { "type": "string", "format": "date" }, { "type": "null" } ] }, "lawful_basis": { "type": "string", "enum": [ "legitimate_interests_art6_1_f" ] }, "article14_status": { "type": "string", "enum": [ "notified", "publicly_notified_disproportionate_effort", "pending_within_window" ] }, "tps_ctps_screened_at": { "anyOf": [ { "type": "string", "format": "date" }, { "type": "null" } ] }, "subscriber_class": { "type": "string", "enum": [ "ltd", "plc", "llp", "scottish_partnership", "public_body", "charity_incorporated", "sole_trader", "ordinary_partnership", "unknown" ] }, "suppression_status": { "type": "string", "enum": [ "none", "objected_to_emailmovers", "objected_to_licensee", "deceased", "left_company" ], "description": "Kept current: an objection reaching the record updates it in the CRM." }, "compliance_receipt_url": { "type": "string", "format": "uri" } }, "required": [ "mydatahub_record_id", "licence_expires_at", "lawful_basis", "article14_status", "tps_ctps_screened_at", "subscriber_class", "suppression_status", "compliance_receipt_url" ], "description": "The MyDataHub property group written on every pushed record, so licence expiry and suppression are enforced in the CRM by field flags." }, "Crosstab": { "type": "object", "properties": { "by": { "minItems": 2, "maxItems": 3, "type": "array", "items": { "type": "string", "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" ], "description": "A field a count can be broken down by." } }, "cells": { "maxItems": 5000, "type": "array", "items": { "$ref": "#/components/schemas/CrosstabCell" } }, "other": { "anyOf": [ { "$ref": "#/components/schemas/OtherBucket" }, { "type": "null" } ] }, "truncated": { "type": "boolean", "description": "True when a cap cut the table: 5,000 cells, or fewer over MCP to keep a result under about 8,000 tokens." } }, "required": [ "by", "cells", "other", "truncated" ], "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." }, "CrosstabCell": { "type": "object", "properties": { "values": { "minItems": 2, "maxItems": 3, "type": "array", "items": { "anyOf": [ { "type": "string" }, { "type": "number" }, { "type": "boolean" } ] } }, "filter_values": { "description": "The values filters take, when any differs from values (ranks for seniority).", "minItems": 2, "maxItems": 3, "type": "array", "items": { "anyOf": [ { "type": "string" }, { "type": "number" }, { "type": "boolean" } ] } }, "contacts": { "$ref": "#/components/schemas/CellCount" } }, "required": [ "values", "contacts" ], "description": "One cell of a cross-tab, one value per field." }, "CurrentCount": { "type": "object", "properties": { "dataset_version": { "type": "string", "pattern": "^[0-9]{4}-W(0[1-9]|[1-4][0-9]|5[0-3])$", "description": "The immutable weekly build a count is bound to, such as 2026-W39. The last 52 stay queryable.", "examples": [ "2026-W39" ] }, "contacts": { "type": "integer", "minimum": 0 }, "companies": { "type": "integer", "minimum": 0 } }, "required": [ "dataset_version", "contacts", "companies" ], "description": "The same audience on the current dataset version." }, "Dataset": { "type": "object", "properties": { "id": { "type": "string", "enum": [ "uk_contacts", "ie_contacts", "global_contacts" ], "description": "The dataset an audience draws from. uk_contacts is live; ie_contacts and global_contacts are listed but not yet served." }, "name": { "type": "string" }, "status": { "type": "string", "enum": [ "live", "planned", "through_our_team" ], "description": "live is served; planned is not yet served; through_our_team is sold through the bespoke service only." }, "owner": { "type": "string" }, "source": { "type": "string" }, "licence": { "type": "string" }, "refresh": { "type": "string" }, "residency": { "type": "string" }, "regulator": { "type": "string" }, "warranty": { "type": "string" }, "credits_per_record": { "type": "number", "minimum": 0, "description": "1 for owned UK and Irish data." }, "credits_status": { "type": "string", "enum": [ "confirmed", "proposed" ] }, "current_version": { "anyOf": [ { "type": "string", "pattern": "^[0-9]{4}-W(0[1-9]|[1-4][0-9]|5[0-3])$", "description": "The immutable weekly build a count is bound to, such as 2026-W39. The last 52 stay queryable.", "examples": [ "2026-W39" ] }, { "type": "null" } ] }, "versions_available": { "type": "integer", "minimum": 0, "description": "Immutable weekly versions still queryable (the last 52)." } }, "required": [ "id", "name", "status", "owner", "source", "licence", "refresh", "residency", "regulator", "warranty", "credits_per_record", "credits_status", "current_version", "versions_available" ], "description": "A dataset with owner, source, licence, refresh, residency, regulator, warranty and credits per record." }, "DatasetList": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Dataset" } }, "has_more": { "type": "boolean", "description": "Whether another page follows." }, "next_cursor": { "anyOf": [ { "type": "string", "minLength": 1, "maxLength": 512, "description": "An opaque cursor from next_cursor. Pass it back unchanged." }, { "type": "null" } ], "description": "Pass as cursor to fetch the next page; null on the last page." } }, "required": [ "data", "has_more", "next_cursor" ], "description": "A page of datasets, newest first." }, "DatasetVersionChangelog": { "type": "object", "properties": { "dataset": { "type": "string", "enum": [ "uk_contacts", "ie_contacts", "global_contacts" ], "description": "The dataset an audience draws from. uk_contacts is live; ie_contacts and global_contacts are listed but not yet served." }, "version": { "type": "string", "pattern": "^[0-9]{4}-W(0[1-9]|[1-4][0-9]|5[0-3])$", "description": "The immutable weekly build a count is bound to, such as 2026-W39. The last 52 stay queryable.", "examples": [ "2026-W39" ] }, "built_at": { "type": "string", "format": "date-time" }, "checksum": { "type": "string", "description": "SHA-256 over the version's files." }, "row_counts": { "type": "object", "properties": { "companies": { "type": "integer", "minimum": 0 }, "sites": { "type": "integer", "minimum": 0 }, "contacts": { "type": "integer", "minimum": 0 }, "emails": { "type": "integer", "minimum": 0 }, "phones": { "type": "integer", "minimum": 0 } }, "required": [ "companies", "sites", "contacts", "emails", "phones" ] }, "changes": { "type": "object", "properties": { "records_added": { "type": "integer", "minimum": 0 }, "records_retired": { "type": "integer", "minimum": 0 }, "records_reverified": { "type": "integer", "minimum": 0 }, "companies_dissolved": { "type": "integer", "minimum": 0 }, "job_changes_confirmed": { "type": "integer", "minimum": 0 }, "suppressions_applied": { "type": "integer", "minimum": 0 } }, "required": [ "records_added", "records_retired", "records_reverified", "companies_dissolved", "job_changes_confirmed", "suppressions_applied" ] }, "coverage_pct": { "type": "object", "propertyNames": { "type": "string", "pattern": "^[a-z0-9]+(_[a-z0-9]+)*$" }, "additionalProperties": { "type": "number", "minimum": 0, "maximum": 100 }, "description": "Share of contacts holding each field, such as named_email." }, "input_snapshots": { "type": "array", "items": { "type": "object", "properties": { "source": { "type": "string" }, "as_of": { "type": "string", "format": "date" } }, "required": [ "source", "as_of" ] } } }, "required": [ "dataset", "version", "built_at", "checksum", "row_counts", "changes", "coverage_pct", "input_snapshots" ], "description": "What changed in one immutable weekly build, and the inputs it was built from." }, "Disclosure": { "type": "object", "properties": { "level": { "type": "string", "enum": [ "exact", "rounded" ], "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." }, "rounded_to": { "anyOf": [ { "type": "integer", "exclusiveMinimum": 0 }, { "type": "null" } ], "description": "5 when numbers are rounded; null when they are exact." }, "secondary_suppression": { "type": "boolean", "description": "True when cross-tab or breakdown cells of 10 or more were hidden as \"suppressed\" so totals cannot be differenced." }, "notes": { "type": "array", "items": { "type": "string" } } }, "required": [ "level", "rounded_to", "secondary_suppression", "notes" ], "description": "Whether these numbers are exact or protected: \"under 10\" cells, rounding to 5 and secondary suppression for anonymous and trial callers." }, "EmailPolicy": { "type": "object", "properties": { "min_deliverability_score": { "description": "Lowest deliverability score counted, 0 to 100. Default 70.", "type": "integer", "minimum": 0, "maximum": 100 }, "allow_catch_all": { "description": "Whether catch-all addresses count. Default false.", "type": "boolean" } }, "additionalProperties": false, "description": "Email quality floor. Defaults: min_deliverability_score 70, allow_catch_all false." }, "EnrichRequest": { "type": "object", "properties": { "email": { "type": "string", "format": "email" }, "first_name": { "type": "string", "minLength": 1, "maxLength": 100 }, "last_name": { "type": "string", "minLength": 1, "maxLength": 100 }, "company_name": { "type": "string", "minLength": 1, "maxLength": 200 }, "company_number": { "type": "string", "pattern": "^[A-Z0-9]{8}$", "description": "Eight characters in upper case, such as 05046417 or SC123456." }, "domain": { "type": "string", "minLength": 3, "maxLength": 253 }, "confirmation_token": { "type": "string", "minLength": 16, "maxLength": 2000, "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." }, "licence_accepted_version": { "description": "The version of the Data Licence and Sharing Agreement the person accepted for this record: the account's agreements.dlsa.version. Required when a person enriches in the app; an agent key carries the acceptance made with it, and a confirmation_token the one made on the approval page.", "type": "string", "minLength": 1, "maxLength": 100 } }, "additionalProperties": false, "description": "One known person to match. Send email, or first_name and last_name with company_name, company_number or domain.", "anyOf": [ { "type": "object", "properties": { "email": true }, "required": [ "email" ] }, { "type": "object", "properties": { "first_name": true, "last_name": true }, "required": [ "first_name", "last_name" ], "anyOf": [ { "type": "object", "properties": { "company_name": true }, "required": [ "company_name" ] }, { "type": "object", "properties": { "company_number": true }, "required": [ "company_number" ] }, { "type": "object", "properties": { "domain": true }, "required": [ "domain" ] } ] } ] }, "Enrichment": { "type": "object", "properties": { "matched": { "type": "boolean" }, "match_confidence": { "anyOf": [ { "type": "number", "minimum": 0, "maximum": 1 }, { "type": "null" } ] }, "already_licensed": { "type": "boolean", "description": "True when you already hold the record, so it costs 0." }, "record": { "anyOf": [ { "$ref": "#/components/schemas/ContactRecord" }, { "type": "null" } ] }, "credits_charged": { "type": "number", "minimum": 0, "description": "1 on a confident match, otherwise 0." }, "credits_remaining": { "type": "number", "minimum": 0, "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)." }, "cost_gbp": { "type": "number", "minimum": 0, "description": "Pounds sterling excluding VAT, to two decimal places." }, "licence_expires_at": { "anyOf": [ { "type": "string", "format": "date" }, { "type": "null" } ] } }, "required": [ "matched", "match_confidence", "already_licensed", "record", "credits_charged", "credits_remaining", "cost_gbp", "licence_expires_at" ], "description": "The full record for a confident match, or no match at no charge." }, "EventList": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/WebhookEvent" } }, "has_more": { "type": "boolean", "description": "Whether another page follows." }, "next_cursor": { "anyOf": [ { "type": "string", "minLength": 1, "maxLength": 512, "description": "An opaque cursor from next_cursor. Pass it back unchanged." }, { "type": "null" } ], "description": "Pass as cursor to fetch the next page; null on the last page." } }, "required": [ "data", "has_more", "next_cursor" ], "description": "A page of events, oldest first." }, "ExpandedTerm": { "type": "object", "properties": { "term": { "type": "string", "description": "A matched title." }, "from_term": { "type": "string", "description": "The input term it came from." }, "expansion_set": { "anyOf": [ { "type": "string", "enum": [ "plural_singular", "department_synonyms", "ampersand_and", "abbreviations", "permutations" ] }, { "type": "string", "const": "input" } ], "description": "The expansion set that produced it, or input for the term itself." }, "contacts": { "$ref": "#/components/schemas/CellCount" }, "excluded": { "description": "True when exclude_terms removed it from the audience.", "type": "boolean" } }, "required": [ "term", "from_term", "expansion_set", "contacts" ], "description": "One title a matches filter covers, with its count." }, "FieldSet": { "type": "object", "properties": { "id": { "type": "string", "pattern": "^[a-z0-9]+(_[a-z0-9]+)*$", "description": "Such as standard, standard_telephone or full." }, "name": { "type": "string" }, "description": { "type": "string" }, "credits_per_record": { "type": "number", "minimum": 0, "description": "Every field set costs 1 credit a record." }, "columns": { "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string" }, "description": { "type": "string" } }, "required": [ "name", "description" ] } } }, "required": [ "id", "name", "description", "credits_per_record", "columns" ], "description": "The named bundle of fields delivered with an order, with its exact columns." }, "FieldSetList": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/FieldSet" } }, "has_more": { "type": "boolean", "description": "Whether another page follows." }, "next_cursor": { "anyOf": [ { "type": "string", "minLength": 1, "maxLength": 512, "description": "An opaque cursor from next_cursor. Pass it back unchanged." }, { "type": "null" } ], "description": "Pass as cursor to fetch the next page; null on the last page." } }, "required": [ "data", "has_more", "next_cursor" ], "description": "A page of field sets, newest first." }, "Filter": { "oneOf": [ { "$ref": "#/components/schemas/InFilter" }, { "$ref": "#/components/schemas/BetweenFilter" }, { "$ref": "#/components/schemas/GteFilter" }, { "$ref": "#/components/schemas/LteFilter" }, { "$ref": "#/components/schemas/MatchesFilter" }, { "$ref": "#/components/schemas/WithinRadiusFilter" }, { "$ref": "#/components/schemas/InListFilter" }, { "$ref": "#/components/schemas/SinceFilter" } ], "description": "One criterion: a field from GET /v1/catalogue/filters, an operator and its operands. Exclusions nest under not.", "discriminator": { "propertyName": "op", "mapping": { "in": "#/components/schemas/InFilter", "between": "#/components/schemas/BetweenFilter", "gte": "#/components/schemas/GteFilter", "lte": "#/components/schemas/LteFilter", "matches": "#/components/schemas/MatchesFilter", "within_radius": "#/components/schemas/WithinRadiusFilter", "in_list": "#/components/schemas/InListFilter", "since": "#/components/schemas/SinceFilter" } } }, "FilterCatalogue": { "type": "object", "properties": { "dataset": { "type": "string", "enum": [ "uk_contacts", "ie_contacts", "global_contacts" ], "description": "The dataset an audience draws from. uk_contacts is live; ie_contacts and global_contacts are listed but not yet served." }, "dataset_version": { "type": "string", "pattern": "^[0-9]{4}-W(0[1-9]|[1-4][0-9]|5[0-3])$", "description": "The immutable weekly build a count is bound to, such as 2026-W39. The last 52 stay queryable.", "examples": [ "2026-W39" ] }, "fields": { "type": "array", "items": { "$ref": "#/components/schemas/FilterDimension" } }, "operators": { "type": "array", "items": { "$ref": "#/components/schemas/OperatorInfo" } }, "datasets": { "type": "array", "items": { "$ref": "#/components/schemas/Dataset" } } }, "required": [ "dataset", "dataset_version", "fields", "operators", "datasets" ], "description": "Every filterable field with its type, operators and value count, plus the datasets." }, "FilterDimension": { "type": "object", "properties": { "field": { "type": "string", "description": "The field name, also the dimension slug." }, "group": { "type": "string", "enum": [ "company", "site", "contact", "email", "phone", "signal" ] }, "type": { "type": "string", "enum": [ "enum", "text", "number", "date", "geo", "hashed_list", "boolean", "band" ] }, "label": { "type": "string" }, "description": { "type": "string" }, "operators": { "type": "array", "items": { "type": "string", "enum": [ "in", "between", "gte", "lte", "matches", "within_radius", "in_list", "since" ] } }, "facet": { "type": "boolean", "description": "Usable in breakdown_by." }, "value_count": { "anyOf": [ { "type": "integer", "minimum": 0 }, { "type": "null" } ], "description": "Distinct values in this dataset version; null for free text and numbers." }, "default": { "type": [ "string", "null" ] }, "examples": { "type": "array", "items": { "anyOf": [ { "type": "string" }, { "type": "number" }, { "type": "boolean" } ] } }, "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" ], "description": "One filterable field." }, "FilterValue": { "type": "object", "properties": { "code": { "description": "The value to use in a filter.", "anyOf": [ { "type": "string" }, { "type": "number" }, { "type": "boolean" } ] }, "label": { "type": "string" }, "contacts": { "$ref": "#/components/schemas/CellCount" }, "companies": { "$ref": "#/components/schemas/CellCount" }, "parent": { "description": "The parent code for hierarchical fields, such as SIC division 62 under J.", "type": [ "string", "null" ] } }, "required": [ "code", "label", "contacts", "companies" ], "description": "One value of a field, with its counts." }, "FilterValueList": { "type": "object", "properties": { "field": { "type": "string" }, "dataset_version": { "type": "string", "pattern": "^[0-9]{4}-W(0[1-9]|[1-4][0-9]|5[0-3])$", "description": "The immutable weekly build a count is bound to, such as 2026-W39. The last 52 stay queryable.", "examples": [ "2026-W39" ] }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/FilterValue" } }, "has_more": { "type": "boolean" }, "next_cursor": { "anyOf": [ { "type": "string", "minLength": 1, "maxLength": 512, "description": "An opaque cursor from next_cursor. Pass it back unchanged." }, { "type": "null" } ] }, "did_you_mean": { "type": "array", "items": { "type": "string" } }, "disclosure": { "$ref": "#/components/schemas/Disclosure" } }, "required": [ "field", "dataset_version", "data", "has_more", "next_cursor", "disclosure" ], "description": "A page of values in one field, best match first when q is given." }, "GteFilter": { "type": "object", "properties": { "field": { "type": "string", "enum": [ "company.employee_band", "company.turnover_band", "company.fleet_band", "contact.job_level_rank", "email.deliverability_score" ] }, "op": { "type": "string", "const": "gte" }, "value": { "anyOf": [ { "type": "string", "minLength": 1, "maxLength": 200 }, { "type": "number" } ], "description": "A band code or a number from the field's order." } }, "required": [ "field", "op", "value" ], "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" } ], "allOf": [ { "if": { "type": "object", "properties": { "field": { "const": "company.employee_band" } }, "required": [ "field" ] }, "then": { "type": "object", "properties": { "value": { "type": "string", "enum": [ "1-5", "6-9", "10-19", "20-49", "50-99", "100-199", "200-349", "350-499", "500-999", "1000-1499", "1500-4999", "5000-9999", "10000+" ] } } } }, { "if": { "type": "object", "properties": { "field": { "const": "company.turnover_band" } }, "required": [ "field" ] }, "then": { "type": "object", "properties": { "value": { "type": "string", "enum": [ "1-100k", "101k-200k", "201k-500k", "501k-750k", "751k-1M", "1.1M-2M", "2.1M-5M", "5.1M-7.5M", "7.6M-10M", "11M-20M", "21M-50M", "51M-75M", "76M-100M", "100M-250M", "251M-500M", "501M-1B", "1B+" ] } } } }, { "if": { "type": "object", "properties": { "field": { "const": "company.fleet_band" } }, "required": [ "field" ] }, "then": { "type": "object", "properties": { "value": { "type": "string", "enum": [ "1-2", "3-5", "6-9", "10-19", "20-49", "50-99", "100+" ] } } } }, { "if": { "type": "object", "properties": { "field": { "const": "contact.job_level_rank" } }, "required": [ "field" ] }, "then": { "type": "object", "properties": { "value": { "type": "integer", "enum": [ 1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12, 13 ] } } } }, { "if": { "type": "object", "properties": { "field": { "const": "email.deliverability_score" } }, "required": [ "field" ] }, "then": { "type": "object", "properties": { "value": { "type": "integer", "minimum": 0, "maximum": 100 } } } } ] }, "Health": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "ok", "degraded", "down" ] }, "version": { "type": "string", "description": "The API release, such as 2.0.0." }, "api_version": { "type": "string", "description": "The latest MyDataHub-Version, such as 2027-01-15." }, "dataset_version": { "type": "string", "pattern": "^[0-9]{4}-W(0[1-9]|[1-4][0-9]|5[0-3])$", "description": "The immutable weekly build a count is bound to, such as 2026-W39. The last 52 stay queryable.", "examples": [ "2026-W39" ] }, "tps_screen": { "$ref": "#/components/schemas/TpsScreen" }, "time": { "type": "string", "format": "date-time" }, "status_page": { "type": "string", "format": "uri" } }, "required": [ "status", "version", "api_version", "dataset_version", "tps_screen", "time", "status_page" ], "description": "Whether the API is up, and which versions it serves." }, "InFilter": { "type": "object", "properties": { "field": { "type": "string", "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" ] }, "op": { "type": "string", "const": "in" }, "values": { "minItems": 1, "maxItems": 10000, "type": "array", "items": { "anyOf": [ { "type": "string", "minLength": 1, "maxLength": 200 }, { "type": "number" }, { "type": "boolean" } ], "description": "A code, a rank or a boolean, as the field's catalogue lists it." } } }, "required": [ "field", "op", "values" ], "additionalProperties": false, "description": "The field holds one of the listed codes.", "examples": [ { "field": "company.sic_2007", "op": "in", "values": [ "C" ] } ], "allOf": [ { "if": { "type": "object", "properties": { "field": { "const": "company.sic_2007" } }, "required": [ "field" ] }, "then": { "type": "object", "properties": { "values": { "type": "array", "items": { "type": "string", "pattern": "^([A-U]|[0-9]{2,5})$" } } } } }, { "if": { "type": "object", "properties": { "field": { "const": "company.business_class" } }, "required": [ "field" ] }, "then": { "type": "object", "properties": { "values": { "type": "array", "items": { "type": "string", "minLength": 1 } } } } }, { "if": { "type": "object", "properties": { "field": { "const": "company.employee_band" } }, "required": [ "field" ] }, "then": { "type": "object", "properties": { "values": { "type": "array", "items": { "type": "string", "enum": [ "1-5", "6-9", "10-19", "20-49", "50-99", "100-199", "200-349", "350-499", "500-999", "1000-1499", "1500-4999", "5000-9999", "10000+", "unclassified" ] } } } } }, { "if": { "type": "object", "properties": { "field": { "const": "company.turnover_band" } }, "required": [ "field" ] }, "then": { "type": "object", "properties": { "values": { "type": "array", "items": { "type": "string", "enum": [ "1-100k", "101k-200k", "201k-500k", "501k-750k", "751k-1M", "1.1M-2M", "2.1M-5M", "5.1M-7.5M", "7.6M-10M", "11M-20M", "21M-50M", "51M-75M", "76M-100M", "100M-250M", "251M-500M", "501M-1B", "1B+", "unclassified" ] } } } } }, { "if": { "type": "object", "properties": { "field": { "const": "company.fleet_band" } }, "required": [ "field" ] }, "then": { "type": "object", "properties": { "values": { "type": "array", "items": { "type": "string", "enum": [ "1-2", "3-5", "6-9", "10-19", "20-49", "50-99", "100+", "unclassified" ] } } } } }, { "if": { "type": "object", "properties": { "field": { "const": "company.type" } }, "required": [ "field" ] }, "then": { "type": "object", "properties": { "values": { "type": "array", "items": { "type": "string", "pattern": "^[a-z0-9]+(_[a-z0-9]+)*$" } } } } }, { "if": { "type": "object", "properties": { "field": { "const": "company.status" } }, "required": [ "field" ] }, "then": { "type": "object", "properties": { "values": { "type": "array", "items": { "type": "string", "pattern": "^[a-z0-9]+(_[a-z0-9]+)*$" } } } } }, { "if": { "type": "object", "properties": { "field": { "const": "company.subscriber_class" } }, "required": [ "field" ] }, "then": { "type": "object", "properties": { "values": { "type": "array", "items": { "type": "string", "enum": [ "ltd", "plc", "llp", "scottish_partnership", "public_body", "charity_incorporated", "sole_trader", "ordinary_partnership", "unknown" ] } } } } }, { "if": { "type": "object", "properties": { "field": { "const": "company.companies_house_number" } }, "required": [ "field" ] }, "then": { "type": "object", "properties": { "values": { "type": "array", "items": { "type": "string", "pattern": "^[A-Z0-9]{8}$" } } } } }, { "if": { "type": "object", "properties": { "field": { "const": "site.region" } }, "required": [ "field" ] }, "then": { "type": "object", "properties": { "values": { "type": "array", "items": { "type": "string", "enum": [ "north_east", "north_west", "yorkshire_and_the_humber", "east_midlands", "west_midlands", "east_of_england", "london", "south_east", "south_west", "scotland", "wales", "northern_ireland", "crown_dependencies" ] } } } } }, { "if": { "type": "object", "properties": { "field": { "const": "site.county" } }, "required": [ "field" ] }, "then": { "type": "object", "properties": { "values": { "type": "array", "items": { "type": "string", "minLength": 1 } } } } }, { "if": { "type": "object", "properties": { "field": { "const": "site.town" } }, "required": [ "field" ] }, "then": { "type": "object", "properties": { "values": { "type": "array", "items": { "type": "string", "minLength": 1 } } } } }, { "if": { "type": "object", "properties": { "field": { "const": "site.postcode" } }, "required": [ "field" ] }, "then": { "type": "object", "properties": { "values": { "type": "array", "items": { "type": "string", "pattern": "^[A-Za-z]{1,2}([0-9][0-9A-Za-z]?( [0-9]([A-Za-z]{2})?| ?[0-9][A-Za-z]{2})?)?$" } } } } }, { "if": { "type": "object", "properties": { "field": { "const": "contact.title_family" } }, "required": [ "field" ] }, "then": { "type": "object", "properties": { "values": { "type": "array", "items": { "type": "string", "minLength": 1 } } } } }, { "if": { "type": "object", "properties": { "field": { "const": "contact.job_function" } }, "required": [ "field" ] }, "then": { "type": "object", "properties": { "values": { "type": "array", "items": { "type": "string", "minLength": 1 } } } } }, { "if": { "type": "object", "properties": { "field": { "const": "contact.job_level_rank" } }, "required": [ "field" ] }, "then": { "type": "object", "properties": { "values": { "type": "array", "items": { "type": "integer", "enum": [ 1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12, 13, 0 ] } } } } }, { "if": { "type": "object", "properties": { "field": { "const": "contact.premium" } }, "required": [ "field" ] }, "then": { "type": "object", "properties": { "values": { "type": "array", "items": { "type": "boolean" } } } } }, { "if": { "type": "object", "properties": { "field": { "const": "email.exists" } }, "required": [ "field" ] }, "then": { "type": "object", "properties": { "values": { "type": "array", "items": { "type": "boolean" } } } } }, { "if": { "type": "object", "properties": { "field": { "const": "email.type" } }, "required": [ "field" ] }, "then": { "type": "object", "properties": { "values": { "type": "array", "items": { "type": "string", "enum": [ "named", "generic_local_part", "generic_domain" ] } } } } }, { "if": { "type": "object", "properties": { "field": { "const": "phone.exists" } }, "required": [ "field" ] }, "then": { "type": "object", "properties": { "values": { "type": "array", "items": { "type": "boolean" } } } } }, { "if": { "type": "object", "properties": { "field": { "const": "phone.tps_ctps_status" } }, "required": [ "field" ] }, "then": { "type": "object", "properties": { "values": { "type": "array", "items": { "type": "string", "enum": [ "clear", "tps_registered", "ctps_registered", "tps_or_ctps_registered", "not_screened" ] } } } } } ] }, "InListFilter": { "type": "object", "properties": { "field": { "type": "string", "enum": [ "company.companies_house_number", "contact.title", "email.address_sha256", "email.domain_sha256", "phone.e164_sha256" ] }, "op": { "type": "string", "const": "in_list" }, "list_id": { "type": "string", "pattern": "^sup_[0-7][0-9A-HJKMNP-TV-Z]{25}$", "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" ] } }, "required": [ "field", "op", "list_id" ], "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", "op": "in_list", "list_id": "sup_01JB4H7Q2V7XN3M9R6T1Y5W8ZA" } ] }, "InsufficientCreditsProblem": { "type": "object", "properties": { "type": { "type": "string", "format": "uri", "description": "A URI under https://emailmovers.com/mydatahub/docs/errors/ naming the problem type." }, "title": { "type": "string", "description": "A short summary of the problem type." }, "status": { "type": "integer", "minimum": 400, "maximum": 599 }, "detail": { "type": "string", "description": "What happened on this request, in plain English." }, "instance": { "description": "The request path or a request id this problem belongs to.", "type": "string" }, "code": { "type": "string", "const": "insufficient-credits" }, "next_step": { "type": "string", "description": "What to do next, in plain English." }, "did_you_mean": { "description": "The closest valid values, best first.", "type": "array", "items": { "type": "string" } }, "errors": { "description": "For validation-failed: every problem found, each with a JSON pointer.", "type": "array", "items": { "$ref": "#/components/schemas/ProblemError" } }, "required_scope": { "description": "For insufficient-scope: the scope to request, such as orders:write.", "type": "string" }, "retry_after_seconds": { "description": "For rate-limited and service-unavailable: the same value as the Retry-After header.", "type": "integer", "minimum": 0 }, "quote_id": { "description": "The machine quote to retry after topping up; absent for an enrichment.", "type": "string", "pattern": "^qte_[0-7][0-9A-HJKMNP-TV-Z]{25}$", "examples": [ "qte_01JB4M2R6T1Y5W8ZAK8Q2V7XN3" ] }, "quote": { "description": "The machine quote the balance does not cover; absent for an enrichment.", "$ref": "#/components/schemas/MachineQuote" }, "credits_required": { "type": "number", "minimum": 0, "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)." }, "credits_available": { "type": "number", "minimum": 0, "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)." }, "top_up_url": { "type": "string", "format": "uri", "description": "Stripe Checkout on mydatahub.emailmovers.com. Money never moves inside an agent host." } }, "required": [ "type", "title", "status", "detail", "code", "next_step", "credits_required", "credits_available", "top_up_url" ], "description": "402: the balance does not cover the machine quote (or the enrichment), which is carried here with a Stripe Checkout top_up_url. Nothing was charged." }, "JurisdictionExclusion": { "type": "object", "properties": { "jurisdiction": { "type": "string", "description": "An ISO 3166 code, such as DE, CA or US-CA." }, "removed": { "type": "integer", "minimum": 0 } }, "required": [ "jurisdiction", "removed" ], "description": "Records one policy removed." }, "LevelCount": { "type": "object", "properties": { "level": { "type": "string" }, "contacts": { "$ref": "#/components/schemas/CellCount" } }, "required": [ "level", "contacts" ], "description": "Contacts at one job level." }, "LiaDocument": { "type": "object", "properties": { "ref": { "type": "string" }, "version": { "type": "string" }, "published_at": { "type": "string", "format": "date" }, "url": { "type": "string", "format": "uri" }, "lawful_basis": { "type": "string", "enum": [ "legitimate_interests_art6_1_f" ] }, "summary": { "type": "string" }, "versions": { "type": "array", "items": { "type": "object", "properties": { "ref": { "type": "string" }, "published_at": { "type": "string", "format": "date" }, "url": { "type": "string", "format": "uri" } }, "required": [ "ref", "published_at", "url" ] } } }, "required": [ "ref", "version", "published_at", "url", "lawful_basis", "summary", "versions" ], "description": "The published legitimate interests assessment with its version history." }, "Licence": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "multi_use_12m", "outright" ], "description": "multi_use_12m (12 month multi-use, every plan) or outright (1.8 credits a record, proposed)." }, "reuse_until": { "anyOf": [ { "type": "string", "format": "date" }, { "type": "null" } ], "description": "Order date plus 12 months; null for outright." }, "resale_prohibited": { "type": "boolean" }, "permitted_channels": { "type": "array", "items": { "type": "string", "enum": [ "email", "telephone", "post" ] }, "description": "email, telephone and post on standard terms." }, "warranty_url": { "type": "string", "format": "uri" }, "terms_version": { "type": "string", "description": "The version of the Data Licence and Sharing Agreement the licence is under, such as 1.0." }, "terms_url": { "description": "Where that version of the Data Licence and Sharing Agreement is published.", "type": "string", "format": "uri" } }, "required": [ "type", "reuse_until", "resale_prohibited", "permitted_channels", "warranty_url", "terms_version" ], "description": "Licence terms as data, on every quote, order, records page and receipt. Records stay usable, pushable and re-downloadable free until reuse_until." }, "LicenceTerms": { "type": "object", "properties": { "licence_type": { "type": "string", "enum": [ "multi_use_12m", "outright" ], "description": "multi_use_12m (12 month multi-use, every plan) or outright (1.8 credits a record, proposed)." }, "status": { "type": "string", "enum": [ "confirmed", "proposed" ] }, "credits_per_record": { "type": "number", "exclusiveMinimum": 0 }, "permitted_channels": { "type": "array", "items": { "type": "string", "enum": [ "email", "telephone", "post" ] } }, "reuse_months": { "anyOf": [ { "type": "integer", "exclusiveMinimum": 0 }, { "type": "null" } ], "description": "12 for multi_use_12m; null for outright." }, "resale_prohibited": { "type": "boolean" }, "warranty_url": { "type": "string", "format": "uri" }, "terms_version": { "type": "string" } }, "required": [ "licence_type", "status", "credits_per_record", "permitted_channels", "reuse_months", "resale_prohibited", "warranty_url", "terms_version" ], "description": "Licence terms for a plan, as in licence.json." }, "LocationCandidate": { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "region", "county", "town", "local_authority", "postcode_area", "postcode_district", "postcode_sector", "postcode_unit", "geography_set", "radius" ] }, "code": { "type": "string", "description": "The filter code, or the ONS code for a centre." }, "label": { "type": "string" }, "contacts": { "$ref": "#/components/schemas/CellCount" }, "centre": { "anyOf": [ { "type": "object", "properties": { "lat": { "type": "number" }, "lon": { "type": "number" } }, "required": [ "lat", "lon" ] }, { "type": "null" } ] }, "filter": { "description": "A ready filter for this candidate.", "$ref": "#/components/schemas/Filter", "discriminator": { "propertyName": "op", "mapping": { "in": "#/components/schemas/InFilter", "between": "#/components/schemas/BetweenFilter", "gte": "#/components/schemas/GteFilter", "lte": "#/components/schemas/LteFilter", "matches": "#/components/schemas/MatchesFilter", "within_radius": "#/components/schemas/WithinRadiusFilter", "in_list": "#/components/schemas/InListFilter", "since": "#/components/schemas/SinceFilter" } } } }, "required": [ "kind", "code", "label", "contacts", "centre", "filter" ], "description": "One reading of the text." }, "LocationRequest": { "type": "object", "properties": { "text": { "type": "string", "minLength": 1, "maxLength": 200, "description": "Free text such as \"20 miles of Leeds\", \"Yorkshire\" or \"SW1\"." }, "radius_miles": { "type": "number", "minimum": 1, "maximum": 100 }, "dataset": { "type": "string", "enum": [ "uk_contacts", "ie_contacts", "global_contacts" ], "description": "The dataset an audience draws from. uk_contacts is live; ie_contacts and global_contacts are listed but not yet served." } }, "required": [ "text" ], "additionalProperties": false, "description": "A place to resolve into geography filters." }, "LocationResolution": { "type": "object", "properties": { "text": { "type": "string" }, "ambiguous": { "type": "boolean", "description": "True when more than one candidate fits; ask the person which they meant." }, "question": { "type": [ "string", "null" ] }, "candidates": { "type": "array", "items": { "$ref": "#/components/schemas/LocationCandidate" } }, "disclosure": { "$ref": "#/components/schemas/Disclosure" } }, "required": [ "text", "ambiguous", "question", "candidates", "disclosure" ], "description": "Candidates for a place. Ambiguous names come back as candidates, never a silent choice." }, "LteFilter": { "type": "object", "properties": { "field": { "type": "string", "enum": [ "company.employee_band", "company.turnover_band", "company.fleet_band", "contact.job_level_rank", "contact.company_contact_rank", "email.deliverability_score" ] }, "op": { "type": "string", "const": "lte" }, "value": { "anyOf": [ { "type": "string", "minLength": 1, "maxLength": 200 }, { "type": "number" } ], "description": "A band code or a number from the field's order." } }, "required": [ "field", "op", "value" ], "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 } ], "allOf": [ { "if": { "type": "object", "properties": { "field": { "const": "company.employee_band" } }, "required": [ "field" ] }, "then": { "type": "object", "properties": { "value": { "type": "string", "enum": [ "1-5", "6-9", "10-19", "20-49", "50-99", "100-199", "200-349", "350-499", "500-999", "1000-1499", "1500-4999", "5000-9999", "10000+" ] } } } }, { "if": { "type": "object", "properties": { "field": { "const": "company.turnover_band" } }, "required": [ "field" ] }, "then": { "type": "object", "properties": { "value": { "type": "string", "enum": [ "1-100k", "101k-200k", "201k-500k", "501k-750k", "751k-1M", "1.1M-2M", "2.1M-5M", "5.1M-7.5M", "7.6M-10M", "11M-20M", "21M-50M", "51M-75M", "76M-100M", "100M-250M", "251M-500M", "501M-1B", "1B+" ] } } } }, { "if": { "type": "object", "properties": { "field": { "const": "company.fleet_band" } }, "required": [ "field" ] }, "then": { "type": "object", "properties": { "value": { "type": "string", "enum": [ "1-2", "3-5", "6-9", "10-19", "20-49", "50-99", "100+" ] } } } }, { "if": { "type": "object", "properties": { "field": { "const": "contact.job_level_rank" } }, "required": [ "field" ] }, "then": { "type": "object", "properties": { "value": { "type": "integer", "enum": [ 1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12, 13 ] } } } }, { "if": { "type": "object", "properties": { "field": { "const": "contact.company_contact_rank" } }, "required": [ "field" ] }, "then": { "type": "object", "properties": { "value": { "type": "integer", "minimum": 1, "maximum": 1000 } } } }, { "if": { "type": "object", "properties": { "field": { "const": "email.deliverability_score" } }, "required": [ "field" ] }, "then": { "type": "object", "properties": { "value": { "type": "integer", "minimum": 0, "maximum": 100 } } } } ] }, "MachineQuote": { "type": "object", "properties": { "id": { "type": "string", "pattern": "^qte_[0-7][0-9A-HJKMNP-TV-Z]{25}$", "description": "Format: a quote id: qte_ followed by a 26 character ULID in upper case Crockford base32, such as qte_01JB4M2R6T1Y5W8ZAK8Q2V7XN3.", "examples": [ "qte_01JB4M2R6T1Y5W8ZAK8Q2V7XN3" ] }, "kind": { "type": "string", "const": "machine" }, "organisation_id": { "anyOf": [ { "type": "string", "pattern": "^org_[0-7][0-9A-HJKMNP-TV-Z]{25}$", "description": "Format: an organisation id: org_ followed by a 26 character ULID in upper case Crockford base32, such as org_01JA0Q2V7XN3M9R6T1Y5W8ZAK8.", "examples": [ "org_01JA0Q2V7XN3M9R6T1Y5W8ZAK8" ] }, { "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." }, "count_id": { "type": "string", "pattern": "^cnt_[A-Z2-7]{20}$", "description": "The count the quote was priced from.", "examples": [ "cnt_7K2PQ4MAXN3R6TBY5WDZ" ] }, "dataset": { "type": "string", "enum": [ "uk_contacts", "ie_contacts", "global_contacts" ], "description": "The dataset an audience draws from. uk_contacts is live; ie_contacts and global_contacts are listed but not yet served." }, "dataset_version": { "type": "string", "pattern": "^[0-9]{4}-W(0[1-9]|[1-4][0-9]|5[0-3])$", "description": "The immutable weekly build a count is bound to, such as 2026-W39. The last 52 stay queryable.", "examples": [ "2026-W39" ] }, "field_set": { "type": "string", "pattern": "^[a-z0-9]+(_[a-z0-9]+)*$" }, "records": { "type": "integer", "minimum": 0, "description": "Records after overlap and suppression; what you would receive." }, "removed": { "type": "object", "properties": { "already_held": { "type": "integer", "minimum": 0 }, "suppressed": { "type": "integer", "minimum": 0 } }, "required": [ "already_held", "suppressed" ], "description": "Records left out and never charged." }, "credits_per_record": { "type": "number", "minimum": 0, "description": "1 for a complete UK record; 1.8 outright (proposed)." }, "credits_required": { "type": "number", "minimum": 0, "description": "records times credits_per_record (creditsFor)." }, "credits_available": { "anyOf": [ { "type": "number", "minimum": 0, "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)." }, { "type": "null" } ], "description": "Your balance; null when signed out." }, "balance_after": { "description": "credits_available less credits_required; negative means a top-up is needed; null when signed out.", "type": [ "number", "null" ] }, "gbp_ex_vat": { "type": "number", "minimum": 0, "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." }, "purchase": { "$ref": "#/components/schemas/Purchase" }, "licence": { "$ref": "#/components/schemas/Licence" }, "warranty": { "$ref": "#/components/schemas/Warranty" }, "created_at": { "type": "string", "format": "date-time" }, "expires_at": { "type": "string", "format": "date-time", "description": "24 hours after creation." }, "blockers": { "type": "array", "items": { "$ref": "#/components/schemas/QuoteBlocker" } }, "signature": { "$ref": "#/components/schemas/QuoteSignature" } }, "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" ], "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." }, "MatchesFilter": { "type": "object", "properties": { "field": { "type": "string", "enum": [ "contact.title" ] }, "op": { "type": "string", "const": "matches" }, "terms": { "minItems": 1, "maxItems": 500, "type": "array", "items": { "type": "string", "minLength": 1, "maxLength": 200 } }, "mode": { "type": "string", "enum": [ "contains", "starts_with", "exact" ], "description": "contains (the default) matches titles containing a term, starts_with matches titles beginning with it, exact takes verbatim titles with no expansion." }, "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.", "uniqueItems": true, "maxItems": 5, "type": "array", "items": { "type": "string", "enum": [ "plural_singular", "department_synonyms", "ampersand_and", "abbreviations", "permutations" ] } }, "exclude_terms": { "description": "Expanded terms removed by hand. Kept in the definition so the count stays reproducible when the title dictionary changes.", "maxItems": 500, "type": "array", "items": { "type": "string", "minLength": 1, "maxLength": 200 } } }, "required": [ "field", "op", "terms" ], "additionalProperties": false, "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": [ { "field": "contact.title", "op": "matches", "terms": [ "marketing manager" ], "mode": "contains", "expand": [ "plural_singular", "department_synonyms", "ampersand_and", "abbreviations" ] } ], "allOf": [ { "if": { "type": "object", "properties": { "mode": { "const": "exact" } }, "required": [ "mode" ] }, "then": { "type": "object", "properties": { "expand": { "type": "array", "maxItems": 0 }, "exclude_terms": { "type": "array", "maxItems": 0 } } } } ] }, "Meter": { "type": "object", "properties": { "action": { "type": "string", "pattern": "^[a-z0-9]+(_[a-z0-9]+)*$", "description": "What is metered, such as record or enrich_contact." }, "unit": { "type": "string", "enum": [ "record", "match", "call" ] }, "credits": { "type": "number", "minimum": 0, "description": "Credits per unit." }, "status": { "type": "string", "enum": [ "confirmed", "proposed", "to_confirm" ], "description": "confirmed is in force; proposed awaits a decision; to_confirm is a figure still being checked." } }, "required": [ "action", "unit", "credits", "status" ], "description": "One metered action and its price in credits." }, "NotGroup": { "type": "object", "properties": { "not": { "$ref": "#/components/schemas/WhereNode" } }, "required": [ "not" ], "additionalProperties": false, "description": "Negation: the single node inside must not match." }, "NoticeVersion": { "type": "object", "properties": { "version": { "type": "string" }, "published_at": { "type": "string", "format": "date" }, "url": { "type": "string", "format": "uri" } }, "required": [ "version", "published_at", "url" ], "description": "One dated version of the notice." }, "Objection": { "type": "object", "properties": { "suppression_id": { "type": "string", "pattern": "^sup_[0-7][0-9A-HJKMNP-TV-Z]{25}$", "description": "The list the record now sits on.", "examples": [ "sup_01JB4H7Q2V7XN3M9R6T1Y5W8ZA" ] }, "record_id": { "anyOf": [ { "type": "string", "pattern": "^contact_[0-7][0-9A-HJKMNP-TV-Z]{25}$", "description": "Format: a contact id: contact_ followed by a 26 character ULID in upper case Crockford base32, such as contact_01JA9X2V7XN3M9R6T1Y5W8ZAK8.", "examples": [ "contact_01JA9X2V7XN3M9R6T1Y5W8ZAK8" ] }, { "type": "null" } ] }, "scope": { "type": "string", "enum": [ "licensee", "emailmovers" ] }, "status": { "type": "string", "enum": [ "suppressed", "pending" ], "description": "suppressed now, or pending until the database-wide overlay applies." }, "suppressed_at": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ] }, "effective_by": { "type": "string", "format": "date-time" } }, "required": [ "suppression_id", "record_id", "scope", "status", "suppressed_at", "effective_by" ], "description": "The suppression an objection created. Database-wide objections reach every licensee holding the record through the suppression.created webhook." }, "ObjectionRequest": { "type": "object", "properties": { "record_id": { "type": "string", "pattern": "^contact_[0-7][0-9A-HJKMNP-TV-Z]{25}$", "description": "Format: a contact id: contact_ followed by a 26 character ULID in upper case Crockford base32, such as contact_01JA9X2V7XN3M9R6T1Y5W8ZAK8.", "examples": [ "contact_01JA9X2V7XN3M9R6T1Y5W8ZAK8" ] }, "email_sha256": { "description": "SHA-256 of the trimmed, lower cased address, when the record id is not known.", "type": "string", "pattern": "^[0-9a-f]{64}$" }, "channel": { "type": "string", "enum": [ "email", "telephone", "post", "web_form", "other" ] }, "received_at": { "type": "string", "format": "date-time", "description": "RFC 3339 date and time, with Z or an offset such as +01:00." }, "scope": { "type": "string", "enum": [ "licensee", "emailmovers" ], "description": "licensee suppresses the record for your organisation at once; emailmovers suppresses it database-wide within one working day." }, "note": { "type": "string", "maxLength": 2000 } }, "required": [ "channel", "received_at", "scope" ], "additionalProperties": false, "description": "An objection to direct marketing, to record and propagate: exactly one of record_id or email_sha256.", "oneOf": [ { "type": "object", "properties": { "record_id": true }, "required": [ "record_id" ] }, { "type": "object", "properties": { "email_sha256": true }, "required": [ "email_sha256" ] } ] }, "OpenApiDocument": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": {}, "description": "This OpenAPI 3.1 document, with x-cost-credits on every operation." }, "OperatorInfo": { "type": "object", "properties": { "op": { "type": "string", "enum": [ "in", "between", "gte", "lte", "matches", "within_radius", "in_list", "since", "all", "any", "not" ] }, "applies_to": { "type": "string" }, "description": { "type": "string" } }, "required": [ "op", "applies_to", "description" ], "description": "An operator of the audience definition." }, "Order": { "type": "object", "properties": { "id": { "type": "string", "pattern": "^ord_[0-7][0-9A-HJKMNP-TV-Z]{25}$", "description": "Format: an order id: ord_ followed by a 26 character ULID in upper case Crockford base32, such as ord_01JB4N9S3W2X6Y7Z8A1B2C3D4E.", "examples": [ "ord_01JB4N9S3W2X6Y7Z8A1B2C3D4E" ] }, "status": { "type": "string", "enum": [ "queued", "building", "verifying", "ready", "failed", "cancelled" ], "description": "queued, building, verifying, ready; failed if processing failed; cancelled (only while queued)." }, "name": { "type": "string" }, "quote_id": { "type": "string", "pattern": "^qte_[0-7][0-9A-HJKMNP-TV-Z]{25}$", "description": "The machine quote the order settled.", "examples": [ "qte_01JB4M2R6T1Y5W8ZAK8Q2V7XN3" ] }, "count_id": { "type": "string", "pattern": "^cnt_[A-Z2-7]{20}$", "description": "The count the machine quote was priced from.", "examples": [ "cnt_7K2PQ4MAXN3R6TBY5WDZ" ] }, "dataset_version": { "type": "string", "pattern": "^[0-9]{4}-W(0[1-9]|[1-4][0-9]|5[0-3])$", "description": "The immutable weekly build a count is bound to, such as 2026-W39. The last 52 stay queryable.", "examples": [ "2026-W39" ] }, "field_set": { "type": "string", "pattern": "^[a-z0-9]+(_[a-z0-9]+)*$" }, "delivery": { "type": "array", "items": { "type": "string", "enum": [ "api", "csv", "google_sheets" ] } }, "records": { "type": "integer", "minimum": 0 }, "credits_charged": { "type": "number", "minimum": 0, "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)." }, "credits_remaining": { "type": "number", "minimum": 0, "description": "The balance right after this order was charged." }, "cost_gbp": { "type": "number", "minimum": 0, "description": "The charge in GBP excluding VAT at your plan's rate." }, "licence_expires_at": { "anyOf": [ { "type": "string", "format": "date" }, { "type": "null" } ], "description": "When the licence ends; null for outright ownership." }, "licence": { "$ref": "#/components/schemas/Licence" }, "confirmed_by": { "$ref": "#/components/schemas/ConfirmedBy" }, "verification": { "description": "The real-time check at delivery, such as 4,102 checked, 4,071 passed.", "type": "object", "properties": { "checked": { "type": "integer", "minimum": 0 }, "passed": { "type": "integer", "minimum": 0 }, "replaced": { "type": "integer", "minimum": 0 } }, "required": [ "checked", "passed", "replaced" ] }, "records_url": { "type": "string", "pattern": "^\\/v1\\/[A-Za-z0-9_\\-./]+$", "format": "uri-reference", "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." }, "download_url": { "description": "302 to a single-use signed URL that lives 5 minutes.", "type": "string", "pattern": "^\\/v1\\/[A-Za-z0-9_\\-./]+$", "format": "uri-reference" }, "receipt_url": { "type": "string", "pattern": "^\\/v1\\/[A-Za-z0-9_\\-./]+$", "format": "uri-reference", "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." }, "validation_report": { "description": "Present once the order is ready.", "$ref": "#/components/schemas/ValidationReportLinks" }, "buyer_kit": { "$ref": "#/components/schemas/BuyerKit" }, "created_at": { "type": "string", "format": "date-time" }, "ready_at": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ] }, "failure": { "type": [ "string", "null" ] } }, "required": [ "id", "status", "quote_id", "count_id", "records", "credits_charged", "credits_remaining", "cost_gbp", "licence_expires_at", "licence", "confirmed_by", "records_url" ], "description": "The purchase and its delivery: status, records, charges, the licence, links to records, download, the validation report and the signed compliance receipt." }, "OrderFailedEvent": { "type": "object", "properties": { "id": { "type": "string", "pattern": "^evt_[0-7][0-9A-HJKMNP-TV-Z]{25}$", "description": "Also sent as the webhook-id header; your idempotency key.", "examples": [ "evt_01JB4NB7T1Y5W8ZAK8Q2V7XN3M" ] }, "type": { "type": "string", "const": "order.failed" }, "timestamp": { "type": "string", "format": "date-time" }, "api_version": { "type": "string", "pattern": "^[0-9]{4}-(0[1-9]|1[0-2])-(0[1-9]|[12][0-9]|3[01])$", "description": "A dated MyDataHub-Version, such as 2027-01-15." }, "data": { "type": "object", "properties": { "order_id": { "type": "string", "pattern": "^ord_[0-7][0-9A-HJKMNP-TV-Z]{25}$", "description": "Format: an order id: ord_ followed by a 26 character ULID in upper case Crockford base32, such as ord_01JB4N9S3W2X6Y7Z8A1B2C3D4E.", "examples": [ "ord_01JB4N9S3W2X6Y7Z8A1B2C3D4E" ] }, "reason": { "type": "string" }, "credits_refunded": { "type": "number", "minimum": 0, "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)." } }, "required": [ "order_id", "reason", "credits_refunded" ] } }, "required": [ "id", "type", "timestamp", "api_version", "data" ], "description": "Processing failed; credits are refunded." }, "OrderList": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Order" } }, "has_more": { "type": "boolean", "description": "Whether another page follows." }, "next_cursor": { "anyOf": [ { "type": "string", "minLength": 1, "maxLength": 512, "description": "An opaque cursor from next_cursor. Pass it back unchanged." }, { "type": "null" } ], "description": "Pass as cursor to fetch the next page; null on the last page." } }, "required": [ "data", "has_more", "next_cursor" ], "description": "A page of orders, newest first." }, "OrderReadyEvent": { "type": "object", "properties": { "id": { "type": "string", "pattern": "^evt_[0-7][0-9A-HJKMNP-TV-Z]{25}$", "description": "Also sent as the webhook-id header; your idempotency key.", "examples": [ "evt_01JB4NB7T1Y5W8ZAK8Q2V7XN3M" ] }, "type": { "type": "string", "const": "order.ready" }, "timestamp": { "type": "string", "format": "date-time" }, "api_version": { "type": "string", "pattern": "^[0-9]{4}-(0[1-9]|1[0-2])-(0[1-9]|[12][0-9]|3[01])$", "description": "A dated MyDataHub-Version, such as 2027-01-15." }, "data": { "type": "object", "properties": { "order_id": { "type": "string", "pattern": "^ord_[0-7][0-9A-HJKMNP-TV-Z]{25}$", "description": "Format: an order id: ord_ followed by a 26 character ULID in upper case Crockford base32, such as ord_01JB4N9S3W2X6Y7Z8A1B2C3D4E.", "examples": [ "ord_01JB4N9S3W2X6Y7Z8A1B2C3D4E" ] }, "records": { "type": "integer", "minimum": 0 }, "records_url": { "type": "string", "pattern": "^\\/v1\\/[A-Za-z0-9_\\-./]+$", "format": "uri-reference", "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." }, "receipt_url": { "type": "string", "pattern": "^\\/v1\\/[A-Za-z0-9_\\-./]+$", "format": "uri-reference", "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." } }, "required": [ "order_id", "records", "records_url", "receipt_url" ] } }, "required": [ "id", "type", "timestamp", "api_version", "data" ], "description": "Records are available." }, "OrderRequest": { "type": "object", "properties": { "quote_id": { "type": "string", "pattern": "^qte_[0-7][0-9A-HJKMNP-TV-Z]{25}$", "description": "A live machine quote from quote_order. Without one nothing is charged.", "examples": [ "qte_01JB4M2R6T1Y5W8ZAK8Q2V7XN3" ] }, "name": { "type": "string", "minLength": 1, "maxLength": 200 }, "delivery": { "description": "api (fetch records), csv (signed download) and google_sheets. Default api.", "minItems": 1, "type": "array", "items": { "type": "string", "enum": [ "api", "csv", "google_sheets" ] } }, "confirmation_token": { "type": "string", "minLength": 16, "maxLength": 2000, "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." }, "licence_accepted_version": { "description": "The version of the Data Licence and Sharing Agreement the person accepted for this order: the version in force, the account's agreements.dlsa.version. Required when a person orders in the app; an agent key carries the acceptance made with it, and a confirmation_token the one made on the approval page.", "type": "string", "minLength": 1, "maxLength": 100 } }, "required": [ "quote_id" ], "additionalProperties": false, "description": "Spend credits against a machine quote. A model-set confirmed flag is never consent: the order needs a human confirmation (MCP elicitation or confirmation_token) or a pre-authorised agent key within its limits." }, "OtherBadge": { "type": "object", "properties": { "badge": { "type": "string", "enum": [ "re_checking", "unverified", "suppressed" ] }, "date": { "anyOf": [ { "type": "string", "format": "date" }, { "type": "null" } ], "description": "The date behind the badge, if any." }, "label": { "type": "string", "description": "Such as Verified 12 September 2026." } }, "required": [ "badge", "date", "label" ], "description": "Re-checking, unverified or suppressed." }, "OtherBucket": { "type": "object", "properties": { "cells": { "type": "integer", "minimum": 0, "description": "How many cells were folded into other." }, "contacts": { "$ref": "#/components/schemas/CellCount" }, "companies": { "$ref": "#/components/schemas/CellCount" } }, "required": [ "cells", "contacts" ], "description": "Every cell beyond the top 50, summed." }, "Overlap": { "type": "object", "properties": { "connection_id": { "type": "string", "pattern": "^conn_[0-7][0-9A-HJKMNP-TV-Z]{25}$", "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" ] }, "count_id": { "type": "string", "pattern": "^cnt_[A-Z2-7]{20}$", "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" ] }, "records": { "type": "integer", "minimum": 0 }, "already_held": { "type": "integer", "minimum": 0, "description": "Records already in the CRM; never charged." }, "new_to_you": { "type": "integer", "minimum": 0 }, "method": { "type": "string", "const": "salted_sha256_in_memory" }, "retained": { "type": "boolean", "const": false, "description": "Nothing from the CRM is kept after the check." }, "checked_at": { "type": "string", "format": "date-time" } }, "required": [ "connection_id", "count_id", "records", "already_held", "new_to_you", "method", "retained", "checked_at" ], "description": "The New to you overlap check: salted SHA-256 email matching in memory, nothing retained." }, "OverlapRequest": { "type": "object", "properties": { "count_id": { "type": "string", "pattern": "^cnt_[A-Za-z2-7]{20}$", "description": "A count id from POST /v1/counts or count_audience. Either case is accepted; responses use upper case.", "examples": [ "cnt_7K2PQ4MAXN3R6TBY5WDZ" ] }, "quote_id": { "type": "string", "pattern": "^qte_[0-7][0-9A-HJKMNP-TV-Z]{25}$", "description": "Format: a quote id: qte_ followed by a 26 character ULID in upper case Crockford base32, such as qte_01JB4M2R6T1Y5W8ZAK8Q2V7XN3.", "examples": [ "qte_01JB4M2R6T1Y5W8ZAK8Q2V7XN3" ] } }, "additionalProperties": false, "description": "The count or the machine quote to compare with the CRM: exactly one of count_id or quote_id.", "oneOf": [ { "type": "object", "properties": { "count_id": true }, "required": [ "count_id" ] }, { "type": "object", "properties": { "quote_id": true }, "required": [ "quote_id" ] } ] }, "PaymentReceipt": { "type": "object", "properties": { "number": { "type": "string", "description": "The receipt number, such as MDH-000042: one sequence for every receipt, with no number skipped." }, "issued_at": { "type": "string", "format": "date-time" }, "supplier": { "type": "object", "properties": { "name": { "description": "The company, such as Emailmovers Limited.", "type": [ "string", "null" ] }, "company_number": { "type": [ "string", "null" ] }, "registered_office": { "type": [ "string", "null" ] }, "vat_number": { "type": [ "string", "null" ] } }, "required": [ "name", "company_number", "registered_office", "vat_number" ], "description": "Who sold the credits, as the server's settings name them when the receipt is written. In production a receipt is never written without them; a development server may leave them null." }, "customer": { "type": "object", "properties": { "organisation_id": { "type": "string", "pattern": "^org_[0-7][0-9A-HJKMNP-TV-Z]{25}$", "description": "Format: an organisation id: org_ followed by a 26 character ULID in upper case Crockford base32, such as org_01JA0Q2V7XN3M9R6T1Y5W8ZAK8.", "examples": [ "org_01JA0Q2V7XN3M9R6T1Y5W8ZAK8" ] }, "organisation_name": { "type": "string" }, "business_name": { "description": "The organisation's business name when the receipt was written, which the receipt leads with: confirmed by an owner for an account made by self-serve sign-up, or the name Emailmovers set the account up under. Null while a self-serve account has not confirmed it, and on receipts written before 21 October 2026.", "type": [ "string", "null" ] }, "name": { "description": "The name on the billing details Checkout collected: the business name when the buyer gave one.", "type": [ "string", "null" ] }, "address": { "anyOf": [ { "$ref": "#/components/schemas/BillingAddress" }, { "type": "null" } ] }, "vat_number": { "description": "The buyer's own VAT number, when they gave one at checkout.", "type": [ "string", "null" ] } }, "required": [ "organisation_id", "organisation_name", "business_name", "name", "address", "vat_number" ], "description": "Who bought the credits, as Stripe Checkout collected it." }, "description": { "type": "string", "description": "What was bought, such as 1 credit pack of 40,000." }, "credits": { "type": "integer", "minimum": 0 }, "gbp_per_credit": { "type": "number", "minimum": 0, "description": "The unit price: one credit, excluding VAT, to six decimal places." }, "gbp_ex_vat": { "type": "number", "minimum": 0, "description": "Pounds sterling excluding VAT, to two decimal places." }, "vat_rate_percent": { "type": "number", "minimum": 0, "maximum": 100 }, "vat_gbp": { "type": "number", "minimum": 0, "description": "Pounds sterling, to two decimal places." }, "total_gbp": { "type": "number", "minimum": 0, "description": "What the card was charged, VAT included." }, "paid_by": { "type": "string", "const": "card", "description": "Card, through Stripe Checkout." }, "payment_reference": { "type": "string", "description": "Stripe's reference for the payment." }, "refunds": { "type": "string", "description": "The refund terms the purchase was made under." }, "test_mode": { "type": "boolean", "description": "A Stripe test mode payment: no money moved." } }, "required": [ "number", "issued_at", "supplier", "customer", "description", "credits", "gbp_per_credit", "gbp_ex_vat", "vat_rate_percent", "vat_gbp", "total_gbp", "paid_by", "payment_reference", "refunds", "test_mode" ], "description": "The receipt for a paid credit purchase, which serves as the VAT invoice: the supplier and its VAT number, the buyer's name, billing address and VAT number when given, what was bought, the price per credit and in total excluding VAT, the VAT rate and amount, and the total. Written once, when the credits are added." }, "PlaceCentre": { "type": "object", "properties": { "place": { "type": "string", "minLength": 1, "maxLength": 100, "description": "A place name, resolved with resolve_location, such as Leeds." }, "code": { "description": "The ONS geography code of the chosen candidate when resolve_location found more than one, such as E08000035 for the Leeds district.", "type": "string", "minLength": 1, "maxLength": 20 } }, "required": [ "place" ], "additionalProperties": false, "description": "A named place. Ambiguous names come back from resolve_location as candidates, never a silent choice." }, "Plan": { "type": "object", "properties": { "id": { "type": "string", "pattern": "^[a-z0-9]+(_[a-z0-9]+)*$", "description": "Such as free, pay_as_you_go or plan_12_month." }, "name": { "type": "string" }, "kind": { "type": "string", "enum": [ "free", "subscription", "pack" ] }, "status": { "type": "string", "enum": [ "confirmed", "proposed", "to_confirm" ], "description": "confirmed is in force; proposed awaits a decision; to_confirm is a figure still being checked." }, "available_to": { "type": "string", "enum": [ "everyone", "new_customers", "existing_customers" ], "description": "everyone; new_customers only (the subscription); existing_customers only, who keep their prices (pay as you go and the 12-month plan)." }, "price_gbp_ex_vat": { "type": "number", "minimum": 0, "description": "Pounds sterling excluding VAT, to two decimal places." }, "billing_period": { "type": "string", "enum": [ "once", "month", "year" ] }, "contract_months": { "description": "The contract's length in months, such as 12; absent when there is none.", "anyOf": [ { "type": "integer", "minimum": 0 }, { "type": "null" } ] }, "annual_price_gbp_ex_vat": { "anyOf": [ { "type": "number", "minimum": 0, "description": "Pounds sterling excluding VAT, to two decimal places." }, { "type": "null" } ] }, "credits": { "type": "integer", "minimum": 0, "description": "Credits per billing period, or once." }, "per_record_gbp": { "anyOf": [ { "type": "number", "minimum": 0, "description": "Pounds sterling excluding VAT, to two decimal places." }, { "type": "null" } ], "description": "Price per record at full use of the allowance; null for the free plan." }, "rollover_cap_credits": { "description": "Subscription credits roll over while subscribed, up to this many; 0 when each period's credits are used or lost.", "anyOf": [ { "type": "integer", "minimum": 0 }, { "type": "null" } ] }, "credits_expire": { "type": "boolean" }, "for_whom": { "type": "string" }, "notes": { "type": "string" } }, "required": [ "id", "name", "kind", "status", "available_to", "price_gbp_ex_vat", "billing_period", "credits", "per_record_gbp", "credits_expire", "for_whom" ], "description": "A plan: free, a rolling subscription or a credit pack. No seats on any plan." }, "PointCentre": { "type": "object", "properties": { "lat": { "type": "number", "minimum": 49, "maximum": 61 }, "lon": { "type": "number", "minimum": -9, "maximum": 2 } }, "required": [ "lat", "lon" ], "additionalProperties": false, "description": "A latitude and longitude in WGS84 degrees." }, "PostcodeCentre": { "type": "object", "properties": { "postcode": { "type": "string", "pattern": "^[A-Za-z]{1,2}([0-9][0-9A-Za-z]?( [0-9]([A-Za-z]{2})?| ?[0-9][A-Za-z]{2})?)?$", "description": "The centroid of a postcode unit, sector, district or area, such as LS1 4AP." } }, "required": [ "postcode" ], "additionalProperties": false, "description": "A postcode centroid from ONSPD." }, "Preview": { "type": "object", "properties": { "id": { "type": "string", "pattern": "^prv_[0-7][0-9A-HJKMNP-TV-Z]{25}$", "description": "Format: a preview id: prv_ followed by a 26 character ULID in upper case Crockford base32, such as prv_01JB4H3M7Q2V7XN3M9R6T1Y5W8.", "examples": [ "prv_01JB4H3M7Q2V7XN3M9R6T1Y5W8" ] }, "count_id": { "type": "string", "pattern": "^cnt_[A-Z2-7]{20}$", "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" ] }, "dataset_version": { "type": "string", "pattern": "^[0-9]{4}-W(0[1-9]|[1-4][0-9]|5[0-3])$", "description": "The immutable weekly build a count is bound to, such as 2026-W39. The last 52 stay queryable.", "examples": [ "2026-W39" ] }, "seed": { "type": "string", "description": "The seed the rows came from; the same audience gives the same seed." }, "count": { "type": "integer", "minimum": 0, "description": "The count the rows were drawn from, rounded as disclosure says." }, "disclosure": { "$ref": "#/components/schemas/Disclosure" }, "rows": { "maxItems": 25, "type": "array", "items": { "$ref": "#/components/schemas/PreviewRow" } }, "withheld": { "anyOf": [ { "type": "object", "properties": { "rows": { "type": "integer", "minimum": 0 }, "reason": { "type": "string" } }, "required": [ "rows", "reason" ] }, { "type": "null" } ], "description": "Rows held back: all of them when the count is under 25, or rows whose title fewer than 10 people hold." }, "masked": { "type": "boolean", "const": true }, "watermark": { "description": "The account id watermarked into sample CSVs; null when signed out.", "type": [ "string", "null" ] }, "created_at": { "type": "string", "format": "date-time" } }, "required": [ "id", "count_id", "dataset_version", "seed", "count", "disclosure", "rows", "withheld", "masked", "watermark", "created_at" ], "description": "A free, masked sample of up to 25 rows. Repeating a sample returns the same rows." }, "PreviewRequest": { "type": "object", "properties": { "audience": { "$ref": "#/components/schemas/AudienceRef" }, "count_id": { "description": "A count id instead of an audience.", "type": "string", "pattern": "^cnt_[A-Za-z2-7]{20}$", "examples": [ "cnt_7K2PQ4MAXN3R6TBY5WDZ" ] }, "limit": { "description": "Rows to return, 1 to 25. Default 10.", "default": 10, "type": "integer", "minimum": 1, "maximum": 25 }, "shuffle": { "description": "Draw a new seed. Counts against your rate budget and is logged. Default false, so a repeat returns the same rows.", "default": false, "type": "boolean" } }, "additionalProperties": false, "description": "The audience or count to sample: exactly one of audience or count_id.", "oneOf": [ { "type": "object", "properties": { "audience": true }, "required": [ "audience" ] }, { "type": "object", "properties": { "count_id": true }, "required": [ "count_id" ] } ] }, "PreviewRow": { "type": "object", "properties": { "id": { "type": "string", "pattern": "^prv_[0-7][0-9A-HJKMNP-TV-Z]{25}$", "description": "A session-scoped id standing in for the record. It never reveals contact_ ids.", "examples": [ "prv_01JB4H3M7Q2V7XN3M9R6T1Y5W8" ] }, "title": { "type": "string" }, "job_level": { "description": "The level, such as Director; null when the level is not known.", "type": [ "string", "null" ] }, "job_function": { "type": [ "string", "null" ] }, "company": { "type": "object", "properties": { "name": { "type": "string" }, "companies_house_number": { "type": [ "string", "null" ] }, "status": { "type": "string" }, "employee_band": { "type": [ "string", "null" ] }, "sic_2007": { "type": "array", "items": { "type": "string" } } }, "required": [ "name", "companies_house_number", "status", "employee_band", "sic_2007" ] }, "site": { "type": "object", "properties": { "town": { "type": [ "string", "null" ] }, "postcode_district": { "type": [ "string", "null" ] }, "region": { "type": "string" } }, "required": [ "town", "postcode_district", "region" ] }, "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": [ { "type": "string", "enum": [ "named", "generic_local_part", "generic_domain" ] }, { "type": "null" } ] }, "phone_masked": { "description": "To the area code, such as 0113 ••• •••1.", "type": [ "string", "null" ] }, "tps_ctps_status": { "anyOf": [ { "type": "string", "enum": [ "clear", "tps_registered", "ctps_registered", "tps_or_ctps_registered", "not_screened" ] }, { "type": "null" } ] }, "badges": { "type": "array", "items": { "$ref": "#/components/schemas/VerificationBadge" } }, "why_it_matches": { "type": "array", "items": { "$ref": "#/components/schemas/WhyItMatches" } }, "provenance": { "$ref": "#/components/schemas/ProvenanceCard" }, "compliance": { "$ref": "#/components/schemas/ComplianceObject" } }, "required": [ "id", "title", "job_level", "job_function", "company", "site", "email_masked", "email_type", "phone_masked", "tps_ctps_status", "badges", "why_it_matches", "provenance", "compliance" ], "description": "One masked sample record." }, "PriceBand": { "type": "object", "properties": { "from_records": { "type": "integer", "minimum": 0 }, "to_records": { "anyOf": [ { "type": "integer", "minimum": 0 }, { "type": "null" } ], "description": "null for the last band." }, "gbp_per_record": { "type": "number", "minimum": 0, "description": "Pounds sterling excluding VAT, to two decimal places." } }, "required": [ "from_records", "to_records", "gbp_per_record" ], "description": "One band of the per-contact scale." }, "PriceEstimate": { "type": "object", "properties": { "credits": { "type": "number", "minimum": 0, "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)." }, "gbp_ex_vat": { "type": "object", "propertyNames": { "type": "string", "pattern": "^[a-z0-9]+(_[a-z0-9]+)*$" }, "additionalProperties": { "type": "number", "minimum": 0, "description": "Pounds sterling excluding VAT, to two decimal places." }, "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)." } }, "required": [ "credits", "gbp_ex_vat" ], "description": "What ordering the whole count would cost. An estimate; quote_order gives the machine quote." }, "PriceScale": { "type": "object", "properties": { "id": { "type": "string", "const": "per_contact_scale" }, "name": { "type": "string" }, "status": { "type": "string", "enum": [ "confirmed", "proposed", "to_confirm" ], "description": "confirmed is in force; proposed awaits a decision; to_confirm is a figure still being checked." }, "available_to": { "type": "string", "enum": [ "everyone", "new_customers", "existing_customers" ], "description": "everyone; new_customers only (the subscription); existing_customers only, who keep their prices (pay as you go and the 12-month plan)." }, "minimum_order_records": { "type": "integer", "minimum": 0 }, "rule": { "type": "string", "description": "How a purchase is priced, in words." }, "bands": { "minItems": 1, "type": "array", "items": { "$ref": "#/components/schemas/PriceBand" } } }, "required": [ "id", "name", "status", "available_to", "minimum_order_records", "rule", "bands" ], "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." }, "Pricing": { "type": "object", "properties": { "version": { "type": "string" }, "valid_from": { "type": "string", "format": "date" }, "currency": { "type": "string", "const": "GBP" }, "vat_treatment": { "type": "string" }, "credit_definition": { "type": "string" }, "price_scale": { "$ref": "#/components/schemas/PriceScale" }, "plans": { "type": "array", "items": { "$ref": "#/components/schemas/Plan" } }, "credit_packs": { "type": "array", "items": { "$ref": "#/components/schemas/CreditPack" } }, "credit_rules": { "type": "array", "items": { "$ref": "#/components/schemas/CreditRule" } }, "licence": { "type": "array", "items": { "$ref": "#/components/schemas/LicenceTerms" } }, "guarantee": { "type": "object", "properties": { "current": { "$ref": "#/components/schemas/Warranty" }, "proposed": { "anyOf": [ { "$ref": "#/components/schemas/Warranty" }, { "type": "null" } ] }, "refunds": { "type": "array", "items": { "type": "string" } } }, "required": [ "current", "proposed", "refunds" ] }, "trial": { "type": "object", "properties": { "credits": { "type": "integer", "minimum": 0 }, "card_required": { "type": "boolean" }, "expires": { "type": "boolean" } }, "required": [ "credits", "card_required", "expires" ] }, "promises": { "type": "array", "items": { "$ref": "#/components/schemas/PricingPromise" } }, "meters": { "type": "array", "items": { "$ref": "#/components/schemas/Meter" }, "description": "What agents and code are metered on, in credits, the same on every surface." }, "action_path": { "type": "array", "items": { "$ref": "#/components/schemas/ActionPathStep" }, "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." } }, "required": [ "version", "valid_from", "currency", "vat_treatment", "credit_definition", "price_scale", "plans", "credit_packs", "credit_rules", "licence", "guarantee", "trial", "promises", "meters", "action_path" ], "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." }, "PricingPromise": { "type": "object", "properties": { "key": { "type": "string", "pattern": "^[a-z0-9]+(_[a-z0-9]+)*$" }, "statement": { "type": "string" }, "in_practice": { "type": "string" } }, "required": [ "key", "statement", "in_practice" ], "description": "One of the seven promises on the pricing page." }, "Problem": { "type": "object", "properties": { "type": { "type": "string", "format": "uri", "description": "A URI under https://emailmovers.com/mydatahub/docs/errors/ naming the problem type." }, "title": { "type": "string", "description": "A short summary of the problem type." }, "status": { "type": "integer", "minimum": 400, "maximum": 599 }, "detail": { "type": "string", "description": "What happened on this request, in plain English." }, "instance": { "description": "The request path or a request id this problem belongs to.", "type": "string" }, "code": { "type": "string", "enum": [ "invalid-request", "idempotency-key-required", "unsupported-version", "authentication-required", "account-required", "insufficient-credits", "insufficient-scope", "confirmation-required", "business-details-required", "licence-acceptance-required", "dpa-acceptance-required", "agent-budget-exceeded", "not-found", "method-not-allowed", "idempotency-key-reused", "quote-expired", "order-not-ready", "order-not-cancellable", "validation-failed", "quote-required", "dataset-unavailable", "rate-limited", "internal-error", "not-implemented", "service-unavailable", "tps-screen-expired" ], "description": "The problem type as a stable code." }, "next_step": { "type": "string", "description": "What to do next, in plain English." }, "did_you_mean": { "description": "The closest valid values, best first.", "type": "array", "items": { "type": "string" } }, "errors": { "description": "For validation-failed: every problem found, each with a JSON pointer.", "type": "array", "items": { "$ref": "#/components/schemas/ProblemError" } }, "required_scope": { "description": "For insufficient-scope: the scope to request, such as orders:write.", "type": "string" }, "retry_after_seconds": { "description": "For rate-limited and service-unavailable: the same value as the Retry-After header.", "type": "integer", "minimum": 0 } }, "required": [ "type", "title", "status", "detail", "code", "next_step" ], "description": "An RFC 9457 problem. MCP tool errors carry the same object with isError true.", "examples": [ { "type": "https://emailmovers.com/mydatahub/docs/errors/validation-failed", "title": "The request is not valid", "status": 422, "detail": "Unknown field company.employees.", "instance": "/v1/counts", "code": "validation-failed", "next_step": "Fix each entry in errors, using did_you_mean where given, and send it again.", "errors": [ { "pointer": "/audience/where/all/0/field", "code": "invalid_value", "message": "Unknown field company.employees.", "did_you_mean": [ "company.employee_band" ] } ] } ] }, "ProblemError": { "type": "object", "properties": { "pointer": { "type": "string", "description": "RFC 6901 JSON pointer to the member at fault, such as /audience/where/all/0/field." }, "code": { "type": "string", "description": "What went wrong, such as invalid_value or custom." }, "message": { "type": "string" }, "did_you_mean": { "type": "array", "items": { "type": "string" } } }, "required": [ "pointer", "code", "message" ], "description": "One validation failure." }, "Provenance": { "type": "object", "properties": { "company": { "type": "object", "properties": { "source": { "type": "string", "enum": [ "emailmovers_research", "companies_house", "onspd", "ukbizdirectory", "partner_rampedup" ] }, "as_of": { "type": "string", "format": "date" } }, "required": [ "source", "as_of" ], "description": "Where the company facts came from and the snapshot date." }, "contact": { "anyOf": [ { "type": "object", "properties": { "source": { "type": "string", "enum": [ "emailmovers_research", "companies_house", "onspd", "ukbizdirectory", "partner_rampedup" ] }, "compiled_at": { "type": "string", "format": "date" }, "last_verified_at": { "anyOf": [ { "type": "string", "format": "date" }, { "type": "null" } ] }, "method": { "type": "string", "enum": [ "telephone", "web", "register" ] } }, "required": [ "source", "compiled_at", "last_verified_at", "method" ] }, { "type": "null" } ], "description": "Who compiled the contact, when, and how it was last confirmed." }, "email": { "description": "The latest email verification: date, provider result and location.", "anyOf": [ { "type": "object", "properties": { "verified_at": { "type": "string", "format": "date" }, "result": { "type": "string", "enum": [ "ok", "catch_all", "unknown", "invalid", "disposable" ] }, "provider_location": { "type": "string", "enum": [ "UK", "EU", "US" ] } }, "required": [ "verified_at", "result", "provider_location" ] }, { "type": "null" } ] } }, "required": [ "company", "contact" ], "description": "Source per entity, answering the ICO questions who compiled it and where from." }, "ProvenanceCard": { "type": "object", "properties": { "sources": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": { "type": "string", "enum": [ "emailmovers_research", "companies_house", "onspd", "ukbizdirectory", "partner_rampedup" ] }, "description": "The source of each field shown, such as title: emailmovers_research." }, "first_seen_at": { "type": "string", "format": "date" }, "last_verified_at": { "anyOf": [ { "type": "string", "format": "date" }, { "type": "null" } ] }, "method": { "type": "string", "enum": [ "telephone", "web", "register" ] }, "companies_house_number": { "type": [ "string", "null" ] }, "company_status": { "type": "string" }, "article14_status": { "type": "string", "enum": [ "notified", "publicly_notified_disproportionate_effort", "pending_within_window" ] }, "tps_ctps_screened_at": { "anyOf": [ { "type": "string", "format": "date" }, { "type": "null" } ] }, "lawful_basis": { "type": "string", "enum": [ "legitimate_interests_art6_1_f" ] } }, "required": [ "sources", "first_seen_at", "last_verified_at", "method", "companies_house_number", "company_status", "article14_status", "tps_ctps_screened_at", "lawful_basis" ], "description": "The ICO due diligence answers for one record, as shown on the sample row." }, "Purchase": { "type": "object", "properties": { "credits_to_buy": { "type": "integer", "minimum": 0, "description": "credits_required less the balance: all of it when signed out, 0 when the balance covers the order." }, "cheapest": { "anyOf": [ { "type": "string", "pattern": "^[a-z0-9]+(_[a-z0-9]+)*$" }, { "type": "null" } ], "description": "The id of the cheapest option; null when nothing needs buying." }, "gbp_ex_vat": { "type": "number", "minimum": 0, "description": "What the cheapest option costs, excluding VAT; 0 when nothing needs buying." }, "options": { "type": "array", "items": { "$ref": "#/components/schemas/PurchaseOption" }, "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." } }, "required": [ "credits_to_buy", "cheapest", "gbp_ex_vat", "options" ], "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." }, "PurchaseAttention": { "type": "object", "properties": { "reason": { "type": "string", "enum": [ "checkout_mismatch", "billed_outside_uk" ], "description": "checkout_mismatch: Stripe says it is paid but the checkout does not match this purchase, so no credits were added; billed_outside_uk: credited, but the billing address is not in the UK." }, "detail": { "type": "string", "description": "What a person should look at, in plain English." }, "since": { "type": "string", "format": "date-time" } }, "required": [ "reason", "detail", "since" ], "description": "A purchase a person at Emailmovers looks at. It is flagged on the purchase, and emailed to the payment alerts address when one is set." }, "PurchaseLine": { "type": "object", "properties": { "id": { "type": "string", "pattern": "^[a-z0-9]+(_[a-z0-9]+)*$", "description": "A credit pack id, or per_contact_scale." }, "quantity": { "type": "integer", "minimum": 0, "description": "Credit packs bought, or credits bought at the scale." }, "credits": { "type": "integer", "minimum": 0 }, "gbp_ex_vat": { "type": "number", "minimum": 0, "description": "Pounds sterling excluding VAT, to two decimal places." } }, "required": [ "id", "quantity", "credits", "gbp_ex_vat" ], "description": "One thing bought: credit packs, or credits at the scale." }, "PurchaseOption": { "type": "object", "properties": { "id": { "type": "string", "pattern": "^[a-z0-9]+(_[a-z0-9]+)*$", "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." }, "label": { "type": "string", "description": "Such as 12,000 records at 22p." }, "credits": { "type": "integer", "minimum": 0, "description": "Credits the option buys." }, "gbp_ex_vat": { "type": "number", "minimum": 0, "description": "Pounds sterling excluding VAT, to two decimal places." }, "credits_left_over": { "type": "integer", "minimum": 0, "description": "Credits that stay in the balance after the order." }, "lines": { "type": "array", "items": { "$ref": "#/components/schemas/PurchaseLine" } } }, "required": [ "id", "label", "credits", "gbp_ex_vat", "credits_left_over", "lines" ], "description": "One way to buy the credits the order needs." }, "Push": { "type": "object", "properties": { "id": { "type": "string", "pattern": "^psh_[0-7][0-9A-HJKMNP-TV-Z]{25}$", "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" ] }, "order_id": { "type": "string", "pattern": "^ord_[0-7][0-9A-HJKMNP-TV-Z]{25}$", "description": "Format: an order id: ord_ followed by a 26 character ULID in upper case Crockford base32, such as ord_01JB4N9S3W2X6Y7Z8A1B2C3D4E.", "examples": [ "ord_01JB4N9S3W2X6Y7Z8A1B2C3D4E" ] }, "connection_id": { "type": "string", "pattern": "^conn_[0-7][0-9A-HJKMNP-TV-Z]{25}$", "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" ] }, "dry_run": { "type": "boolean" }, "status": { "type": "string", "enum": [ "queued", "running", "completed", "partial", "failed" ] }, "summary": { "type": "object", "properties": { "to_create": { "type": "integer", "minimum": 0 }, "to_update": { "type": "integer", "minimum": 0 }, "already_present": { "type": "integer", "minimum": 0 }, "skipped": { "type": "integer", "minimum": 0 }, "failed": { "type": "integer", "minimum": 0 } }, "required": [ "to_create", "to_update", "already_present", "skipped", "failed" ] }, "property_group": { "type": "array", "items": { "type": "string", "enum": [ "mydatahub_record_id", "licence_expires_at", "lawful_basis", "article14_status", "tps_ctps_screened_at", "subscriber_class", "suppression_status", "compliance_receipt_url" ] }, "description": "The MyDataHub property group written on every record (CrmPropertyGroup)." }, "sample": { "anyOf": [ { "$ref": "#/components/schemas/CrmPropertyGroup" }, { "type": "null" } ], "description": "On a dry run: the property group the first record would carry." }, "errors": { "type": "array", "items": { "type": "object", "properties": { "record_id": { "type": "string" }, "message": { "type": "string" } }, "required": [ "record_id", "message" ] } }, "created_at": { "type": "string", "format": "date-time" }, "completed_at": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ] } }, "required": [ "id", "order_id", "connection_id", "dry_run", "status", "summary", "property_group", "sample", "errors", "created_at", "completed_at" ], "description": "A CRM push or its dry run, such as 4,102 to create and 0 already in your HubSpot." }, "PushCompletedEvent": { "type": "object", "properties": { "id": { "type": "string", "pattern": "^evt_[0-7][0-9A-HJKMNP-TV-Z]{25}$", "description": "Also sent as the webhook-id header; your idempotency key.", "examples": [ "evt_01JB4NB7T1Y5W8ZAK8Q2V7XN3M" ] }, "type": { "type": "string", "const": "push.completed" }, "timestamp": { "type": "string", "format": "date-time" }, "api_version": { "type": "string", "pattern": "^[0-9]{4}-(0[1-9]|1[0-2])-(0[1-9]|[12][0-9]|3[01])$", "description": "A dated MyDataHub-Version, such as 2027-01-15." }, "data": { "$ref": "#/components/schemas/Push" } }, "required": [ "id", "type", "timestamp", "api_version", "data" ], "description": "A CRM push finished." }, "PushFailedEvent": { "type": "object", "properties": { "id": { "type": "string", "pattern": "^evt_[0-7][0-9A-HJKMNP-TV-Z]{25}$", "description": "Also sent as the webhook-id header; your idempotency key.", "examples": [ "evt_01JB4NB7T1Y5W8ZAK8Q2V7XN3M" ] }, "type": { "type": "string", "const": "push.failed" }, "timestamp": { "type": "string", "format": "date-time" }, "api_version": { "type": "string", "pattern": "^[0-9]{4}-(0[1-9]|1[0-2])-(0[1-9]|[12][0-9]|3[01])$", "description": "A dated MyDataHub-Version, such as 2027-01-15." }, "data": { "$ref": "#/components/schemas/Push" } }, "required": [ "id", "type", "timestamp", "api_version", "data" ], "description": "A CRM push failed." }, "PushPartialEvent": { "type": "object", "properties": { "id": { "type": "string", "pattern": "^evt_[0-7][0-9A-HJKMNP-TV-Z]{25}$", "description": "Also sent as the webhook-id header; your idempotency key.", "examples": [ "evt_01JB4NB7T1Y5W8ZAK8Q2V7XN3M" ] }, "type": { "type": "string", "const": "push.partial" }, "timestamp": { "type": "string", "format": "date-time" }, "api_version": { "type": "string", "pattern": "^[0-9]{4}-(0[1-9]|1[0-2])-(0[1-9]|[12][0-9]|3[01])$", "description": "A dated MyDataHub-Version, such as 2027-01-15." }, "data": { "$ref": "#/components/schemas/Push" } }, "required": [ "id", "type", "timestamp", "api_version", "data" ], "description": "A CRM push partly finished; retry the failed records." }, "PushRequest": { "type": "object", "properties": { "connection_id": { "type": "string", "pattern": "^conn_[0-7][0-9A-HJKMNP-TV-Z]{25}$", "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" ] }, "dry_run": { "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.", "default": true, "type": "boolean" }, "update_existing": { "description": "Update records already in the CRM, matched on mydatahub_record_id. Default true.", "default": true, "type": "boolean" }, "confirmation_token": { "type": "string", "minLength": 16, "maxLength": 2000, "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." } }, "required": [ "connection_id" ], "additionalProperties": false, "description": "Push an order's records to a connection. Records only; nothing is ever sent to the contacts. A live push without approval returns 403 confirmation-required." }, "Quality": { "type": "object", "properties": { "email_coverage_pct": { "type": "number", "minimum": 0, "maximum": 100, "description": "Records with a named email as a share of the count." }, "verified_90d_pct": { "type": "number", "minimum": 0, "maximum": 100, "description": "Share of emails with a provider result of ok in the last 90 days." }, "verified_measured_at": { "type": "string", "format": "date" }, "deliverability": { "description": "Score distribution: good 70 to 100, risky 40 to 69, poor under 40.", "type": "object", "properties": { "good": { "type": "number", "minimum": 0, "maximum": 100 }, "risky": { "type": "number", "minimum": 0, "maximum": 100 }, "poor": { "type": "number", "minimum": 0, "maximum": 100 } }, "required": [ "good", "risky", "poor" ] }, "avg_days_since_verification": { "type": "number", "minimum": 0 }, "phone_coverage_pct": { "description": "Share with a validated number, when phone is requested.", "type": "number", "minimum": 0, "maximum": 100 }, "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.", "type": "string", "format": "date" } }, "required": [ "email_coverage_pct", "verified_90d_pct" ], "description": "Quality signals shown with every count." }, "Quote": { "oneOf": [ { "$ref": "#/components/schemas/MachineQuote" }, { "$ref": "#/components/schemas/SalesQuote" } ], "description": "A machine quote (kind machine, 24 hours) or a human sales quote (kind sales, 14 days).", "discriminator": { "propertyName": "kind", "mapping": { "machine": "#/components/schemas/MachineQuote", "sales": "#/components/schemas/SalesQuote" } } }, "QuoteBlocker": { "type": "object", "properties": { "code": { "type": "string", "enum": [ "insufficient_credits", "account_required", "agent_budget_exceeded", "dataset_unavailable", "count_expired" ] }, "detail": { "type": "string" }, "top_up_url": { "type": "string", "format": "uri" } }, "required": [ "code", "detail" ], "description": "Something that stops create_order until it is fixed." }, "QuoteRequest": { "type": "object", "properties": { "count_id": { "type": "string", "pattern": "^cnt_[A-Za-z2-7]{20}$", "description": "A count id from POST /v1/counts or count_audience. Either case is accepted; responses use upper case.", "examples": [ "cnt_7K2PQ4MAXN3R6TBY5WDZ" ] }, "field_set": { "type": "string", "pattern": "^[a-z0-9]+(_[a-z0-9]+)*$", "description": "A field set id from GET /v1/field-sets, such as standard." }, "limit": { "description": "Records to buy; left out, the whole count.", "type": "integer", "minimum": 1, "maximum": 1000000 }, "dedupe_against": { "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.", "default": "previous_orders", "type": "string", "enum": [ "none", "previous_orders", "crm", "previous_orders_and_crm" ] }, "connection_id": { "description": "The CRM connection to check, only with dedupe_against crm or previous_orders_and_crm.", "type": "string", "pattern": "^conn_[0-7][0-9A-HJKMNP-TV-Z]{25}$", "examples": [ "conn_01JB3Y2X6Y7Z8A1B2C3D4E5F6G" ] }, "licence": { "default": "multi_use_12m", "type": "string", "enum": [ "multi_use_12m", "outright" ], "description": "multi_use_12m (12 month multi-use, every plan) or outright (1.8 credits a record, proposed)." } }, "required": [ "count_id", "field_set" ], "additionalProperties": false, "description": "What to price: a count, a field set, how many records and the licence. Free, and needs no account.", "allOf": [ { "if": { "type": "object", "properties": { "dedupe_against": { "enum": [ "crm", "previous_orders_and_crm" ] } }, "required": [ "dedupe_against" ] }, "then": { "type": "object", "properties": { "connection_id": true }, "required": [ "connection_id" ] } }, { "if": { "type": "object", "properties": { "connection_id": true }, "required": [ "connection_id" ] }, "then": { "type": "object", "properties": { "dedupe_against": { "enum": [ "crm", "previous_orders_and_crm" ] } }, "required": [ "dedupe_against" ] } } ] }, "QuoteSignature": { "type": "object", "properties": { "alg": { "type": "string", "const": "ES256" }, "kid": { "type": "string", "description": "The signing key id in jwks_url." }, "jwks_url": { "type": "string", "format": "uri" }, "jws": { "type": "string", "pattern": "^[A-Za-z0-9_-]+\\.[A-Za-z0-9_-]+\\.[A-Za-z0-9_-]+$", "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." } }, "required": [ "alg", "kid", "jwks_url", "jws" ], "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." }, "RadiusCentre": { "anyOf": [ { "$ref": "#/components/schemas/PlaceCentre" }, { "$ref": "#/components/schemas/PostcodeCentre" }, { "$ref": "#/components/schemas/PointCentre" } ], "description": "The centre of a radius: a place, a postcode or a latitude and longitude." }, "RateLimit": { "type": "object", "properties": { "tier": { "type": "string", "enum": [ "anonymous", "free", "paid" ] }, "counts_per_minute": { "anyOf": [ { "type": "integer", "minimum": 0 }, { "type": "null" } ] }, "counts_per_hour": { "anyOf": [ { "type": "integer", "minimum": 0 }, { "type": "null" } ] }, "counts_per_day": { "anyOf": [ { "type": "integer", "minimum": 0 }, { "type": "null" } ] }, "remaining": { "type": "integer", "minimum": 0 }, "resets_at": { "type": "string", "format": "date-time" }, "status": { "type": "string", "enum": [ "confirmed", "to_confirm" ] } }, "required": [ "tier", "counts_per_minute", "counts_per_hour", "counts_per_day", "remaining", "resets_at", "status" ], "description": "The caller's count limits and what remains in the window." }, "ReceiptClaims": { "type": "object", "properties": { "receipt_id": { "type": "string", "pattern": "^rcpt_[0-7][0-9A-HJKMNP-TV-Z]{25}$", "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" ] }, "order_id": { "type": "string", "pattern": "^ord_[0-7][0-9A-HJKMNP-TV-Z]{25}$", "description": "Format: an order id: ord_ followed by a 26 character ULID in upper case Crockford base32, such as ord_01JB4N9S3W2X6Y7Z8A1B2C3D4E.", "examples": [ "ord_01JB4N9S3W2X6Y7Z8A1B2C3D4E" ] }, "issued_at": { "type": "string", "format": "date-time" }, "dataset_version": { "type": "string", "pattern": "^[0-9]{4}-W(0[1-9]|[1-4][0-9]|5[0-3])$", "description": "The immutable weekly build a count is bound to, such as 2026-W39. The last 52 stay queryable.", "examples": [ "2026-W39" ] }, "records_delivered": { "type": "integer", "minimum": 0 }, "removed_by_suppression": { "type": "integer", "minimum": 0 }, "counts": { "type": "object", "properties": { "subscriber_class": { "type": "object", "properties": { "ltd": { "type": "integer", "minimum": 0 }, "plc": { "type": "integer", "minimum": 0 }, "llp": { "type": "integer", "minimum": 0 }, "scottish_partnership": { "type": "integer", "minimum": 0 }, "public_body": { "type": "integer", "minimum": 0 }, "charity_incorporated": { "type": "integer", "minimum": 0 }, "sole_trader": { "type": "integer", "minimum": 0 }, "ordinary_partnership": { "type": "integer", "minimum": 0 }, "unknown": { "type": "integer", "minimum": 0 } }, "required": [ "ltd", "plc", "llp", "scottish_partnership", "public_body", "charity_incorporated", "sole_trader", "ordinary_partnership", "unknown" ] }, "tps_ctps_status": { "type": "object", "properties": { "clear": { "type": "integer", "minimum": 0 }, "tps_registered": { "type": "integer", "minimum": 0 }, "ctps_registered": { "type": "integer", "minimum": 0 }, "tps_or_ctps_registered": { "type": "integer", "minimum": 0 }, "not_screened": { "type": "integer", "minimum": 0 } }, "required": [ "clear", "tps_registered", "ctps_registered", "tps_or_ctps_registered", "not_screened" ] }, "article14_status": { "type": "object", "properties": { "notified": { "type": "integer", "minimum": 0 }, "publicly_notified_disproportionate_effort": { "type": "integer", "minimum": 0 }, "pending_within_window": { "type": "integer", "minimum": 0 } }, "required": [ "notified", "publicly_notified_disproportionate_effort", "pending_within_window" ] } }, "required": [ "subscriber_class", "tps_ctps_status", "article14_status" ] }, "lawful_basis": { "type": "string", "enum": [ "legitimate_interests_art6_1_f" ] }, "lia_ref": { "type": "string" }, "licence": { "$ref": "#/components/schemas/Licence" }, "residency_statement_version": { "type": "string" }, "sub_processor_list_version": { "type": "string" }, "verified_within_days": { "type": "object", "properties": { "within_30_days": { "type": "number", "minimum": 0, "maximum": 100 }, "within_60_days": { "type": "number", "minimum": 0, "maximum": 100 }, "within_90_days": { "type": "number", "minimum": 0, "maximum": 100 } }, "required": [ "within_30_days", "within_60_days", "within_90_days" ], "description": "Share of delivered emails verified within 30, 60 and 90 days." }, "content_sha256": { "type": "string", "pattern": "^[0-9a-f]{64}$", "description": "SHA-256 of the delivered file, lower case hex." } }, "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" ], "description": "The decoded payload of a compliance receipt." }, "ReceiptVerification": { "type": "object", "properties": { "valid": { "type": "boolean", "description": "The signature checks out against the published key." }, "order_exists": { "type": "boolean" }, "licence_in_force_until": { "anyOf": [ { "type": "string", "format": "date" }, { "type": "null" } ] }, "revoked": { "type": "boolean" }, "receipt_id": { "anyOf": [ { "type": "string", "pattern": "^rcpt_[0-7][0-9A-HJKMNP-TV-Z]{25}$", "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" ] }, { "type": "null" } ] }, "checked_at": { "type": "string", "format": "date-time" } }, "required": [ "valid", "order_exists", "licence_in_force_until", "revoked", "receipt_id", "checked_at" ], "description": "The verdict on a receipt, so one agent can prove to another a list is licensed." }, "ReceiptVerifyRequest": { "type": "object", "properties": { "jws": { "type": "string", "minLength": 10, "maxLength": 20000, "description": "The compact JWS to check." } }, "required": [ "jws" ], "additionalProperties": false, "description": "A compliance receipt to verify." }, "RecordsPage": { "type": "object", "properties": { "order_id": { "type": "string", "pattern": "^ord_[0-7][0-9A-HJKMNP-TV-Z]{25}$", "description": "Format: an order id: ord_ followed by a 26 character ULID in upper case Crockford base32, such as ord_01JB4N9S3W2X6Y7Z8A1B2C3D4E.", "examples": [ "ord_01JB4N9S3W2X6Y7Z8A1B2C3D4E" ] }, "format": { "type": "string", "const": "json" }, "fields": { "type": "array", "items": { "type": "string", "pattern": "^[a-z0-9]+(_[a-z0-9]+)*$" }, "description": "The field set's columns in this page." }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/ContactRecord" } }, "has_more": { "type": "boolean" }, "next_cursor": { "anyOf": [ { "type": "string", "minLength": 1, "maxLength": 512, "description": "An opaque cursor from next_cursor. Pass it back unchanged." }, { "type": "null" } ] }, "remaining": { "type": "integer", "minimum": 0, "description": "Records after this page." }, "approx_tokens": { "description": "A rough token size of this page; pages stay under about 8,000 tokens.", "type": "integer", "minimum": 0 }, "licence": { "$ref": "#/components/schemas/Licence" } }, "required": [ "order_id", "format", "fields", "data", "has_more", "next_cursor", "remaining", "licence" ], "description": "A page of delivered records with the licence block. Re-fetching records under licence costs 0 credits." }, "ResolvedCentre": { "type": "object", "properties": { "label": { "type": "string" }, "code": { "type": [ "string", "null" ] }, "lat": { "type": "number" }, "lon": { "type": "number" }, "radius_miles": { "type": "number" }, "postcode_districts_matched": { "type": "integer", "minimum": 0 } }, "required": [ "label", "code", "lat", "lon", "radius_miles", "postcode_districts_matched" ], "description": "A radius centre as the engine resolved it." }, "SalesQuote": { "type": "object", "properties": { "id": { "type": "string", "pattern": "^qte_[0-7][0-9A-HJKMNP-TV-Z]{25}$", "description": "Format: a quote id: qte_ followed by a 26 character ULID in upper case Crockford base32, such as qte_01JB4M2R6T1Y5W8ZAK8Q2V7XN3.", "examples": [ "qte_01JB4M2R6T1Y5W8ZAK8Q2V7XN3" ] }, "kind": { "type": "string", "const": "sales" }, "status": { "type": "string", "enum": [ "draft", "sent", "accepted", "paid", "expired", "withdrawn" ] }, "created_at": { "type": "string", "format": "date-time" }, "valid_until": { "type": "string", "format": "date", "description": "14 days after creation." }, "created_by": { "type": "object", "properties": { "role": { "type": "string", "enum": [ "user", "account_manager" ] }, "name": { "type": "string" } }, "required": [ "role", "name" ] }, "customer": { "type": "string", "description": "The organisation the quote is for." }, "count_id": { "anyOf": [ { "type": "string", "pattern": "^cnt_[A-Z2-7]{20}$", "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" ] }, { "type": "null" } ] }, "field_set": { "type": "string", "pattern": "^[a-z0-9]+(_[a-z0-9]+)*$" }, "records": { "type": "integer", "minimum": 0, "description": "Records the quote covers." }, "credits_per_record": { "type": "number", "minimum": 0, "description": "Credits a record under the licence: 1, or 1.8 outright (proposed)." }, "lines": { "type": "array", "items": { "$ref": "#/components/schemas/SalesQuoteLine" } }, "subtotal_gbp_ex_vat": { "type": "number", "minimum": 0, "description": "Pounds sterling excluding VAT, to two decimal places." }, "vat_gbp": { "type": "number", "minimum": 0, "description": "Pounds sterling excluding VAT, to two decimal places." }, "total_gbp_inc_vat": { "type": "number", "minimum": 0, "description": "Pounds sterling excluding VAT, to two decimal places." }, "balance_after": { "description": "The customer's credits after the order. Paying by card or invoice leaves the balance as it is; null when the customer has no account yet.", "type": [ "number", "null" ] }, "licence": { "$ref": "#/components/schemas/Licence" }, "warranty": { "$ref": "#/components/schemas/Warranty" }, "payment_methods": { "type": "array", "items": { "type": "string", "enum": [ "card", "invoice" ] } }, "pay_url": { "type": "string", "format": "uri", "description": "Pay by card or request an invoice link, no account needed." }, "pdf_url": { "type": "string", "format": "uri" } }, "required": [ "id", "kind", "status", "created_at", "valid_until", "created_by", "customer", "count_id", "field_set", "records", "credits_per_record", "lines", "subtotal_gbp_ex_vat", "vat_gbp", "total_gbp_inc_vat", "balance_after", "licence", "warranty", "payment_methods", "pay_url", "pdf_url" ], "description": "A human sales quote: 14 days, a PDF, payable by card or invoice link, created in the app or by an account manager. Not a machine quote; create_order does not take it." }, "SalesQuoteLine": { "type": "object", "properties": { "description": { "type": "string" }, "quantity": { "type": "integer", "minimum": 0 }, "unit_price_gbp": { "type": "number", "minimum": 0, "description": "Pounds sterling excluding VAT, to two decimal places." }, "amount_gbp": { "type": "number", "minimum": 0, "description": "Pounds sterling excluding VAT, to two decimal places." } }, "required": [ "description", "quantity", "unit_price_gbp", "amount_gbp" ], "description": "One line of a sales quote, excluding VAT." }, "SampleDownload": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "ready", "empty", "downloaded" ], "description": "ready: download_url serves the sample once; empty: no record of the audience can be sent as a sample now, and nothing is supplied; downloaded: the sample was already served, and is never served twice." }, "records": { "type": "integer", "minimum": 0, "maximum": 10, "description": "Records in the sample: up to 10, fewer when fewer are left." }, "download_url": { "description": "A relative link on this host to the CSV, whose first lines are the licence. It works once, for 5 minutes, from the address that asked for it. Null unless ready.", "type": [ "string", "null" ] }, "expires_at": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ], "description": "When download_url stops working. Null unless ready." } }, "required": [ "status", "records", "download_url", "expires_at" ], "description": "The confirmed sample: a single-use link to it, or why there is none. Confirming chooses the records, read afresh against every suppression." }, "SampleDownloadCreate": { "type": "object", "properties": { "token": { "type": "string", "pattern": "^[A-Za-z0-9_-]{40,64}$", "description": "The token from the emailed link (the last part of /samples/confirm/{token}). Only a press of the confirmation page's button sends it, so a link scanner that opens the page uses nothing up." } }, "required": [ "token" ], "additionalProperties": false, "description": "The emailed token." }, "SampleRequest": { "type": "object", "properties": { "id": { "type": "string", "pattern": "^smr_[0-7][0-9A-HJKMNP-TV-Z]{25}$", "description": "Format: a sample request id: smr_ followed by a 26 character ULID in upper case Crockford base32, such as smr_01JB4P2Q5W8ZAK8Q2V7XN3M9R6.", "examples": [ "smr_01JB4P2Q5W8ZAK8Q2V7XN3M9R6" ] }, "count_id": { "type": "string", "pattern": "^cnt_[A-Z2-7]{20}$", "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" ] }, "status": { "type": "string", "enum": [ "awaiting_email", "email_sent", "confirmed", "downloaded", "expired" ], "description": "awaiting_email until the address is sent; email_sent once it was checked (a refused address reads the same); confirmed once the link is opened; downloaded once the sample is served; expired after its time." }, "created_at": { "type": "string", "format": "date-time" }, "expires_at": { "type": "string", "format": "date-time", "description": "When the request, or the link emailed for it, stops working: 24 hours." } }, "required": [ "id", "count_id", "status", "created_at", "expires_at" ], "description": "A request for a sample of a counted audience. It never shows the address or the records." }, "SampleRequestCreate": { "type": "object", "properties": { "count_id": { "type": "string", "pattern": "^cnt_[A-Z2-7]{20}$", "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" ] } }, "required": [ "count_id" ], "additionalProperties": false, "description": "The count to sample." }, "SampleRequestEmail": { "type": "object", "properties": { "email": { "type": "string", "maxLength": 254, "format": "email", "description": "The person's work email address, sent by the calling server from its own form, never through a model. Free webmail addresses are refused." }, "follow_up": { "type": "boolean", "description": "Whether the person ticked the box allowing Emailmovers to email them about the sample." }, "wording": { "type": "string", "minLength": 1, "maxLength": 40, "description": "The version of the wording the person saw beside the field and the box." } }, "required": [ "email", "follow_up", "wording" ], "additionalProperties": false, "description": "The address to confirm, and the person's choice on follow-up." }, "SampleRequestEmailAccepted": { "type": "object", "properties": { "status": { "type": "string", "const": "check_your_inbox", "description": "The same answer whether the address was accepted or refused (a suppressed address, an objection, a limit), so the call cannot be used to test addresses." } }, "required": [ "status" ], "description": "The request was taken." }, "SavedAudience": { "type": "object", "properties": { "id": { "type": "string", "pattern": "^aud_[0-7][0-9A-HJKMNP-TV-Z]{25}$", "description": "Format: an audience id: aud_ followed by a 26 character ULID in upper case Crockford base32, such as aud_01JB4H2K9V6XN3M9R6T1Y5W8ZA.", "examples": [ "aud_01JB4H2K9V6XN3M9R6T1Y5W8ZA" ] }, "name": { "type": "string" }, "audience": { "$ref": "#/components/schemas/Audience" }, "brief": { "description": "The brief it was compiled from, if any.", "type": [ "string", "null" ] }, "current_count": { "anyOf": [ { "$ref": "#/components/schemas/AudienceCountSummary" }, { "type": "null" } ] }, "last_refreshed_at": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ] }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" }, "created_by": { "type": "string", "pattern": "^usr_[0-7][0-9A-HJKMNP-TV-Z]{25}$", "description": "Format: a user id: usr_ followed by a 26 character ULID in upper case Crockford base32, such as usr_01JA0Q3V7XN3M9R6T1Y5W8ZAK8.", "examples": [ "usr_01JA0Q3V7XN3M9R6T1Y5W8ZAK8" ] }, "url": { "type": "string", "format": "uri", "description": "The audience in the app, mydatahub.emailmovers.com/audiences/{id}." } }, "required": [ "id", "name", "audience", "brief", "current_count", "last_refreshed_at", "created_at", "updated_at", "created_by", "url" ], "description": "A named audience shared across the organisation, with its current count." }, "SavedAudienceList": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/SavedAudience" } }, "has_more": { "type": "boolean", "description": "Whether another page follows." }, "next_cursor": { "anyOf": [ { "type": "string", "minLength": 1, "maxLength": 512, "description": "An opaque cursor from next_cursor. Pass it back unchanged." }, { "type": "null" } ], "description": "Pass as cursor to fetch the next page; null on the last page." } }, "required": [ "data", "has_more", "next_cursor" ], "description": "A page of saved audiences, newest first." }, "SavedAudienceRequest": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 200 }, "audience": { "$ref": "#/components/schemas/Audience" }, "brief": { "type": "string", "maxLength": 2000 } }, "required": [ "name", "audience" ], "additionalProperties": false, "description": "A named audience to save." }, "SavedAudienceUpdate": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 200 }, "audience": { "$ref": "#/components/schemas/Audience" }, "brief": { "anyOf": [ { "type": "string", "maxLength": 2000 }, { "type": "null" } ] } }, "additionalProperties": false, "description": "Members to change on a saved audience, at least one.", "minProperties": 1 }, "SicCode": { "type": "object", "properties": { "code": { "type": "string" }, "label": { "type": "string" } }, "required": [ "code", "label" ], "description": "A SIC 2007 code and its label, such as 25620 Machining." }, "SinceFilter": { "type": "object", "properties": { "field": { "type": "string", "enum": [ "contact.last_validated_at", "email.last_verified_at", "signal.type", "signal.observed_at" ] }, "op": { "type": "string", "const": "since" }, "days": { "type": "integer", "minimum": 1, "maximum": 3650 }, "values": { "description": "For signal.type only: the signal types to look for, such as company.incorporated.", "minItems": 1, "maxItems": 10000, "type": "array", "items": { "type": "string", "minLength": 1, "maxLength": 200 } } }, "required": [ "field", "op", "days" ], "additionalProperties": false, "description": "Within the last N days: a date field, or a Companies House signal of the listed types on signal.type.", "examples": [ { "field": "signal.type", "op": "since", "values": [ "company.incorporated" ], "days": 90 } ], "allOf": [ { "if": { "type": "object", "properties": { "field": { "const": "contact.last_validated_at" } }, "required": [ "field" ] }, "then": { "type": "object", "properties": { "values": false } } }, { "if": { "type": "object", "properties": { "field": { "const": "email.last_verified_at" } }, "required": [ "field" ] }, "then": { "type": "object", "properties": { "values": false } } }, { "if": { "type": "object", "properties": { "field": { "const": "signal.type" } }, "required": [ "field" ] }, "then": { "type": "object", "required": [ "values" ], "properties": { "values": { "type": "array", "items": { "type": "string", "enum": [ "company.incorporated", "company.name_changed", "company.registered_office_moved", "company.sic_changed", "company.charge_created", "company.accounts_overdue", "company.confirmation_statement_overdue" ] } } } } }, { "if": { "type": "object", "properties": { "field": { "const": "signal.observed_at" } }, "required": [ "field" ] }, "then": { "type": "object", "properties": { "values": false } } } ] }, "StandardApiKey": { "type": "object", "properties": { "id": { "type": "string", "pattern": "^key_[0-7][0-9A-HJKMNP-TV-Z]{25}$", "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" ] }, "label": { "type": "string" }, "mode": { "type": "string", "enum": [ "live", "test" ], "description": "live keys (mdh_live_) spend real credits; test keys (mdh_test_) return synthetic data and never charge." }, "prefix": { "type": "string", "description": "The first characters of the secret, such as mdh_live_7Kq2." }, "scopes": { "type": "array", "items": { "type": "string", "enum": [ "account:read", "counts:read", "previews:read", "audiences:read", "audiences:write", "quotes:read", "orders:read", "orders:write", "records:read", "enrich:write", "suppressions:read", "suppressions:write", "pushes:write", "webhooks:write", "samples:request", "admin" ] } }, "ip_allowlist": { "type": "array", "items": { "anyOf": [ { "type": "string", "pattern": "^((25[0-5]|2[0-4][0-9]|1[0-9][0-9]|[1-9][0-9]|[0-9])\\.){3}(25[0-5]|2[0-4][0-9]|1[0-9][0-9]|[1-9][0-9]|[0-9])\\/([0-9]|[1-2][0-9]|3[0-2])$" }, { "type": "string", "pattern": "^(([0-9a-fA-F]{1,4}:){7}[0-9a-fA-F]{1,4}|([0-9a-fA-F]{1,4}:){1,7}:|([0-9a-fA-F]{1,4}:){1,6}:[0-9a-fA-F]{1,4}|([0-9a-fA-F]{1,4}:){1,5}(:[0-9a-fA-F]{1,4}){1,2}|([0-9a-fA-F]{1,4}:){1,4}(:[0-9a-fA-F]{1,4}){1,3}|([0-9a-fA-F]{1,4}:){1,3}(:[0-9a-fA-F]{1,4}){1,4}|([0-9a-fA-F]{1,4}:){1,2}(:[0-9a-fA-F]{1,4}){1,5}|[0-9a-fA-F]{1,4}:((:[0-9a-fA-F]{1,4}){1,6})|:((:[0-9a-fA-F]{1,4}){1,7}|:))\\/(12[0-8]|1[01][0-9]|[1-9]?[0-9])$" } ], "description": "An IPv4 or IPv6 range in CIDR notation, such as 203.0.113.0/24." }, "description": "CIDR ranges the key may be used from; empty allows any address." }, "created_at": { "type": "string", "format": "date-time" }, "created_by": { "type": "string", "pattern": "^usr_[0-7][0-9A-HJKMNP-TV-Z]{25}$", "description": "Format: a user id: usr_ followed by a 26 character ULID in upper case Crockford base32, such as usr_01JA0Q3V7XN3M9R6T1Y5W8ZAK8.", "examples": [ "usr_01JA0Q3V7XN3M9R6T1Y5W8ZAK8" ] }, "last_used_at": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ] }, "expires_at": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ] }, "revoked_at": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ] }, "kind": { "type": "string", "const": "standard" } }, "required": [ "id", "label", "mode", "prefix", "scopes", "ip_allowlist", "created_at", "created_by", "last_used_at", "expires_at", "revoked_at", "kind" ], "description": "An API key for your own code." }, "SubProcessor": { "type": "object", "properties": { "name": { "type": "string" }, "purpose": { "type": "string" }, "location": { "type": "string" }, "transfer_mechanism": { "type": "string" }, "added_at": { "type": "string", "format": "date" } }, "required": [ "name", "purpose", "location", "transfer_mechanism", "added_at" ], "description": "One sub-processor on the trust page." }, "SubProcessorChange": { "type": "object", "properties": { "date": { "type": "string", "format": "date" }, "name": { "type": "string" }, "change": { "type": "string", "enum": [ "added", "removed", "changed" ] }, "summary": { "type": "string" } }, "required": [ "date", "name", "change", "summary" ], "description": "One entry in the change log." }, "SuppressionCheck": { "type": "object", "properties": { "checked_at": { "type": "string", "format": "date-time" }, "results": { "type": "array", "items": { "type": "object", "properties": { "record_id": { "type": "string", "pattern": "^contact_[0-7][0-9A-HJKMNP-TV-Z]{25}$", "description": "Format: a contact id: contact_ followed by a 26 character ULID in upper case Crockford base32, such as contact_01JA9X2V7XN3M9R6T1Y5W8ZAK8.", "examples": [ "contact_01JA9X2V7XN3M9R6T1Y5W8ZAK8" ] }, "suppressed": { "type": "boolean" }, "suppression_status": { "type": "string", "enum": [ "none", "objected_to_emailmovers", "objected_to_licensee", "deceased", "left_company" ] }, "list_ids": { "type": "array", "items": { "type": "string", "pattern": "^sup_[0-7][0-9A-HJKMNP-TV-Z]{25}$", "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" ] } } }, "required": [ "record_id", "suppressed", "suppression_status", "list_ids" ] } } }, "required": [ "checked_at", "results" ], "description": "Suppression status per record, as of now." }, "SuppressionCheckRequest": { "type": "object", "properties": { "record_ids": { "minItems": 1, "maxItems": 1000, "type": "array", "items": { "type": "string", "pattern": "^contact_[0-7][0-9A-HJKMNP-TV-Z]{25}$", "description": "Format: a contact id: contact_ followed by a 26 character ULID in upper case Crockford base32, such as contact_01JA9X2V7XN3M9R6T1Y5W8ZAK8.", "examples": [ "contact_01JA9X2V7XN3M9R6T1Y5W8ZAK8" ] } } }, "required": [ "record_ids" ], "additionalProperties": false, "description": "Records to check before a send." }, "SuppressionChecksum": { "type": "object", "properties": { "list_id": { "type": "string", "pattern": "^sup_[0-7][0-9A-HJKMNP-TV-Z]{25}$", "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" ] }, "checksum": { "type": "string" }, "row_count": { "type": "integer", "minimum": 0 } }, "required": [ "list_id", "checksum", "row_count" ], "description": "A suppression list as the count read it." }, "SuppressionCreatedEvent": { "type": "object", "properties": { "id": { "type": "string", "pattern": "^evt_[0-7][0-9A-HJKMNP-TV-Z]{25}$", "description": "Also sent as the webhook-id header; your idempotency key.", "examples": [ "evt_01JB4NB7T1Y5W8ZAK8Q2V7XN3M" ] }, "type": { "type": "string", "const": "suppression.created" }, "timestamp": { "type": "string", "format": "date-time" }, "api_version": { "type": "string", "pattern": "^[0-9]{4}-(0[1-9]|1[0-2])-(0[1-9]|[12][0-9]|3[01])$", "description": "A dated MyDataHub-Version, such as 2027-01-15." }, "data": { "$ref": "#/components/schemas/SuppressionNotice" } }, "required": [ "id", "type", "timestamp", "api_version", "data" ], "description": "An objection reached a record your organisation holds. Suppress it before any send." }, "SuppressionList": { "type": "object", "properties": { "id": { "type": "string", "pattern": "^sup_[0-7][0-9A-HJKMNP-TV-Z]{25}$", "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" ] }, "name": { "type": "string" }, "kind": { "type": "string", "enum": [ "email", "domain", "phone", "company_number", "title_term" ] }, "source": { "type": "string", "enum": [ "upload", "objections" ], "description": "upload for a list you sent; objections for the organisation's own list, which gathers objections you report and database-wide objections on records you hold." }, "row_count": { "type": "integer", "minimum": 0 }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" }, "created_by": { "anyOf": [ { "type": "string", "pattern": "^usr_[0-7][0-9A-HJKMNP-TV-Z]{25}$", "description": "Format: a user id: usr_ followed by a 26 character ULID in upper case Crockford base32, such as usr_01JA0Q3V7XN3M9R6T1Y5W8ZAK8.", "examples": [ "usr_01JA0Q3V7XN3M9R6T1Y5W8ZAK8" ] }, { "type": "null" } ] }, "added_since": { "description": "With since: the records added to this list after that time, for pull.", "type": "array", "items": { "$ref": "#/components/schemas/SuppressionNotice" } } }, "required": [ "id", "name", "kind", "source", "row_count", "created_at", "updated_at", "created_by" ], "description": "A named list of hashed emails, domains, phones, company numbers or title terms, applied to every count and order at no charge." }, "SuppressionListPage": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/SuppressionList" } }, "has_more": { "type": "boolean" }, "next_cursor": { "anyOf": [ { "type": "string", "minLength": 1, "maxLength": 512, "description": "An opaque cursor from next_cursor. Pass it back unchanged." }, { "type": "null" } ] } }, "required": [ "data", "has_more", "next_cursor" ], "description": "A page of suppression lists." }, "SuppressionListRequest": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 200 }, "kind": { "type": "string", "enum": [ "email", "domain", "phone", "company_number", "title_term" ] }, "values": { "minItems": 1, "maxItems": 100000, "type": "array", "items": { "type": "string", "minLength": 1, "maxLength": 320 }, "description": "Raw values (trimmed, lower cased and hashed on arrival) or SHA-256 hex hashes. Domains may use a wildcard such as *.gmail.com; phones are E.164; company numbers are eight characters." }, "hashed": { "description": "True when values are already SHA-256 hashes, each 64 lower case hex characters. Default false.", "default": false, "type": "boolean" }, "dpa_accepted_version": { "description": "The version of the Article 28 data processing agreement the person uploading accepts: the account's agreements.dpa.version. The app sends it with the first upload, and again when a new version is in force. Only a signed-in person accepts it.", "type": "string", "minLength": 1, "maxLength": 100 } }, "required": [ "name", "kind", "values" ], "additionalProperties": false, "description": "A list to upload. Values are stored as SHA-256 hashes only. The first upload asks you to accept the Article 28 DPA in the app, and the account's agreements.dpa keeps who accepted which version and when.", "allOf": [ { "if": { "type": "object", "properties": { "hashed": { "const": true } }, "required": [ "hashed" ] }, "then": { "type": "object", "properties": { "values": { "type": "array", "items": { "type": "string", "pattern": "^[0-9a-f]{64}$" } } } } } ] }, "SuppressionNotice": { "type": "object", "properties": { "record_id": { "type": "string", "pattern": "^contact_[0-7][0-9A-HJKMNP-TV-Z]{25}$", "description": "Format: a contact id: contact_ followed by a 26 character ULID in upper case Crockford base32, such as contact_01JA9X2V7XN3M9R6T1Y5W8ZAK8.", "examples": [ "contact_01JA9X2V7XN3M9R6T1Y5W8ZAK8" ] }, "reason": { "type": "string", "enum": [ "none", "objected_to_emailmovers", "objected_to_licensee", "deceased", "left_company" ] }, "scope": { "type": "string", "enum": [ "licensee", "emailmovers" ] }, "suppressed_at": { "type": "string", "format": "date-time" } }, "required": [ "record_id", "reason", "scope", "suppressed_at" ], "description": "A record you hold that is now suppressed, as the suppression.created webhook carries it." }, "SuppressionRemoval": { "type": "object", "properties": { "list_id": { "type": "string", "pattern": "^sup_[0-7][0-9A-HJKMNP-TV-Z]{25}$", "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" ] }, "removed": { "type": "integer", "minimum": 0 } }, "required": [ "list_id", "removed" ], "description": "Records one suppression list removed." }, "SuppressionUpload": { "type": "object", "properties": { "list": { "$ref": "#/components/schemas/SuppressionList" }, "rows_read": { "type": "integer", "minimum": 0 }, "rows_valid": { "type": "integer", "minimum": 0 }, "rows_skipped": { "type": "array", "items": { "type": "object", "properties": { "row": { "type": "integer", "minimum": 1 }, "reason": { "type": "string" } }, "required": [ "row", "reason" ] } } }, "required": [ "list", "rows_read", "rows_valid", "rows_skipped" ], "description": "A saved list and what the upload read: rows read, valid and skipped with reasons." }, "TitleExpansion": { "type": "object", "properties": { "dataset_version": { "type": "string", "pattern": "^[0-9]{4}-W(0[1-9]|[1-4][0-9]|5[0-3])$", "description": "The immutable weekly build a count is bound to, such as 2026-W39. The last 52 stay queryable.", "examples": [ "2026-W39" ] }, "mode": { "type": "string", "enum": [ "contains", "starts_with", "exact" ], "description": "contains (the default) matches titles containing a term, starts_with matches titles beginning with it, exact takes verbatim titles with no expansion." }, "expand": { "type": "array", "items": { "type": "string", "enum": [ "plural_singular", "department_synonyms", "ampersand_and", "abbreviations", "permutations" ] } }, "terms": { "type": "array", "items": { "$ref": "#/components/schemas/ExpandedTerm" } }, "total_contacts": { "$ref": "#/components/schemas/CellCount" }, "bundle": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "string", "enum": [ "sdm", "manager_and_above", "owner_managed" ] }, "label": { "type": "string" }, "status": { "type": "string", "enum": [ "confirmed", "proposed", "to_confirm" ] }, "resolves_to": { "$ref": "#/components/schemas/WhereNode" } }, "required": [ "id", "label", "status", "resolves_to" ] }, { "type": "null" } ] }, "filter": { "anyOf": [ { "$ref": "#/components/schemas/Filter" }, { "type": "null" } ], "description": "A ready matches filter for the terms, or null for a bundle." }, "disclosure": { "$ref": "#/components/schemas/Disclosure" } }, "required": [ "dataset_version", "mode", "expand", "terms", "total_contacts", "bundle", "filter", "disclosure" ], "description": "Every expanded title with a count, or what a bundle resolves to. Nothing is resolved silently." }, "TitleExpansionRequest": { "type": "object", "properties": { "terms": { "description": "Title keywords to expand, such as marketing manager.", "minItems": 1, "maxItems": 50, "type": "array", "items": { "type": "string", "minLength": 1, "maxLength": 200 } }, "bundle": { "description": "A title bundle to show: sdm, manager_and_above or owner_managed.", "type": "string", "enum": [ "sdm", "manager_and_above", "owner_managed" ] }, "mode": { "type": "string", "enum": [ "contains", "starts_with", "exact" ], "description": "contains (the default) matches titles containing a term, starts_with matches titles beginning with it, exact takes verbatim titles with no expansion." }, "expand": { "description": "Expansion sets to apply, each once. Left out, the four default sets apply.", "uniqueItems": true, "type": "array", "items": { "type": "string", "enum": [ "plural_singular", "department_synonyms", "ampersand_and", "abbreviations", "permutations" ] } }, "dataset": { "type": "string", "enum": [ "uk_contacts", "ie_contacts", "global_contacts" ], "description": "The dataset an audience draws from. uk_contacts is live; ie_contacts and global_contacts are listed but not yet served." } }, "additionalProperties": false, "description": "Keywords or a bundle to expand into an editable title list: exactly one of terms or bundle.", "oneOf": [ { "type": "object", "properties": { "terms": true }, "required": [ "terms" ] }, { "type": "object", "properties": { "bundle": true }, "required": [ "bundle" ] } ] }, "TpsScreen": { "type": "object", "properties": { "screened_at": { "anyOf": [ { "type": "string", "format": "date" }, { "type": "null" } ], "description": "The version's TPS and CTPS screen date (quality.tps_ctps_screened_at); null when no number in it is screened." }, "age_days": { "anyOf": [ { "type": "integer", "minimum": 0 }, { "type": "null" } ], "description": "Days from the screen date to today; null when no number is screened." }, "status": { "type": "string", "enum": [ "ok", "warning", "expired" ], "description": "ok up to 21 days, warning from 22 to 28 days, and expired after 28 days, when counts, samples, quotes and orders with telephone in play are refused with tps-screen-expired. ok when no number is screened." } }, "required": [ "screened_at", "age_days", "status" ], "description": "The TPS and CTPS screen of the current dataset version, on today's date." }, "TrustDocument": { "type": "object", "properties": { "updated_at": { "type": "string", "format": "date-time" }, "company": { "type": "object", "properties": { "legal_name": { "type": "string" }, "company_number": { "type": "string" }, "trading_as": { "type": "string" } }, "required": [ "legal_name", "company_number", "trading_as" ] }, "ico_registration": { "type": "object", "properties": { "number": { "type": "string" }, "expires_on": { "type": "string", "format": "date" }, "register_url": { "type": "string", "format": "uri" } }, "required": [ "number", "expires_on", "register_url" ] }, "lawful_basis": { "type": "object", "properties": { "basis": { "type": "string", "enum": [ "legitimate_interests_art6_1_f" ] }, "lia_ref": { "type": "string" }, "lia_url": { "type": "string", "format": "uri" } }, "required": [ "basis", "lia_ref", "lia_url" ] }, "privacy_notice": { "type": "object", "properties": { "version": { "type": "string" }, "url": { "type": "string", "format": "uri" }, "versions": { "type": "array", "items": { "$ref": "#/components/schemas/NoticeVersion" }, "description": "Every version of the Article 14 notice, newest first." } }, "required": [ "version", "url", "versions" ], "description": "The Article 14 privacy notice for contacts, with its history." }, "residency": { "type": "object", "properties": { "statement": { "type": "string" }, "version": { "type": "string" } }, "required": [ "statement", "version" ] }, "sub_processors": { "type": "object", "properties": { "version": { "type": "string" }, "notice_days": { "type": "integer", "exclusiveMinimum": 0 }, "notice_channels": { "type": "array", "items": { "type": "string", "enum": [ "email", "webhook" ] }, "description": "How customers hear of a change 30 days ahead: by email and by webhook." }, "list": { "type": "array", "items": { "$ref": "#/components/schemas/SubProcessor" } }, "changes": { "type": "array", "items": { "$ref": "#/components/schemas/SubProcessorChange" }, "description": "The change log, newest first." } }, "required": [ "version", "notice_days", "notice_channels", "list", "changes" ] }, "retention": { "type": "array", "items": { "type": "object", "properties": { "category": { "type": "string" }, "period": { "type": "string" }, "status": { "type": "string", "enum": [ "confirmed", "to_confirm" ] } }, "required": [ "category", "period", "status" ] } }, "complaints": { "type": "object", "properties": { "url": { "type": "string", "format": "uri", "description": "The complaints form." }, "email": { "anyOf": [ { "type": "string", "format": "email" }, { "type": "null" } ], "description": "The complaints address; null until published." }, "acknowledgement_days": { "type": "integer", "exclusiveMinimum": 0 } }, "required": [ "url", "email", "acknowledgement_days" ] }, "data_protection_lead": { "anyOf": [ { "type": "object", "properties": { "name": { "type": "string" }, "email": { "type": "string", "format": "email" } }, "required": [ "name", "email" ] }, { "type": "null" } ], "description": "Named person and email; null until confirmed." }, "datasets": { "type": "array", "items": { "$ref": "#/components/schemas/Dataset" }, "description": "Every dataset with owner, source, licence, refresh, residency, regulator, warranty and credits per record." }, "security": { "type": "object", "properties": { "certifications": { "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string" }, "status": { "type": "string", "enum": [ "held", "target" ] }, "date": { "type": "string", "description": "Year and month, such as 2026-10." } }, "required": [ "name", "status", "date" ] } }, "encryption": { "type": "object", "properties": { "at_rest": { "type": "string", "description": "Such as AES-256." }, "in_transit_minimum": { "type": "string", "description": "Such as TLS 1.2." }, "key_rotation": { "type": "string", "description": "Such as KMS managed key rotation." } }, "required": [ "at_rest", "in_transit_minimum", "key_rotation" ], "description": "How data is encrypted, as the trust centre publishes it." }, "data_flow_diagram_url": { "anyOf": [ { "type": "string", "format": "uri" }, { "type": "null" } ], "description": "The UK data flow diagram; null until published." }, "pen_test_summary_url": { "anyOf": [ { "type": "string", "format": "uri" }, { "type": "null" } ], "description": "The latest penetration test summary; null until one is published." }, "caiq_url": { "anyOf": [ { "type": "string", "format": "uri" }, { "type": "null" } ], "description": "CAIQ v4 answers; null until published." }, "status_page": { "type": "string", "format": "uri" }, "security_txt": { "type": "string", "format": "uri" } }, "required": [ "certifications", "encryption", "data_flow_diagram_url", "pen_test_summary_url", "caiq_url", "status_page", "security_txt" ] } }, "required": [ "updated_at", "company", "ico_registration", "lawful_basis", "privacy_notice", "residency", "sub_processors", "retention", "complaints", "data_protection_lead", "datasets", "security" ], "description": "The trust page as data, mirrored at https://mydatahub.emailmovers.com/trust.json and the mydatahub://compliance resource." }, "ValidationReportLinks": { "type": "object", "properties": { "pdf_url": { "type": "string", "format": "uri" }, "json_url": { "type": "string", "format": "uri" } }, "required": [ "pdf_url", "json_url" ], "description": "The per-order validation report: dataset version, status distribution, verification age, expected bounce band, TPS screen date, provider locations and the guarantee window." }, "VerificationBadge": { "oneOf": [ { "$ref": "#/components/schemas/VerifiedBadge" }, { "$ref": "#/components/schemas/OtherBadge" } ], "description": "A badge on a sample row. Every verified has a date.", "discriminator": { "propertyName": "badge", "mapping": { "verified": "#/components/schemas/VerifiedBadge", "re_checking": "#/components/schemas/OtherBadge", "unverified": "#/components/schemas/OtherBadge", "suppressed": "#/components/schemas/OtherBadge" } } }, "VerifiedBadge": { "type": "object", "properties": { "badge": { "type": "string", "const": "verified" }, "date": { "type": "string", "format": "date", "description": "The verification date. Every verified has one." }, "label": { "type": "string", "description": "Such as Verified 12 September 2026." } }, "required": [ "badge", "date", "label" ], "description": "Verified, with the date it was verified." }, "Warranty": { "type": "object", "properties": { "policy": { "type": "string", "enum": [ "replace_over_threshold_hard_bounce", "replace_any_hard_bounce_30d" ], "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." }, "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.", "type": "number", "minimum": 0, "maximum": 100 }, "url": { "type": "string", "format": "uri" } }, "required": [ "policy", "url" ], "description": "The bounce warranty that covers delivered records, with the threshold it was issued under.", "allOf": [ { "if": { "type": "object", "properties": { "policy": { "const": "replace_over_threshold_hard_bounce" } }, "required": [ "policy" ] }, "then": { "type": "object", "properties": { "threshold_percent": true }, "required": [ "threshold_percent" ] }, "else": { "type": "object", "not": { "type": "object", "properties": { "threshold_percent": true }, "required": [ "threshold_percent" ] } } } ] }, "WarrantyReplacementEvent": { "type": "object", "properties": { "id": { "type": "string", "pattern": "^evt_[0-7][0-9A-HJKMNP-TV-Z]{25}$", "description": "Also sent as the webhook-id header; your idempotency key.", "examples": [ "evt_01JB4NB7T1Y5W8ZAK8Q2V7XN3M" ] }, "type": { "type": "string", "const": "warranty.replacement_issued" }, "timestamp": { "type": "string", "format": "date-time" }, "api_version": { "type": "string", "pattern": "^[0-9]{4}-(0[1-9]|1[0-2])-(0[1-9]|[12][0-9]|3[01])$", "description": "A dated MyDataHub-Version, such as 2027-01-15." }, "data": { "type": "object", "properties": { "order_id": { "type": "string", "pattern": "^ord_[0-7][0-9A-HJKMNP-TV-Z]{25}$", "description": "Format: an order id: ord_ followed by a 26 character ULID in upper case Crockford base32, such as ord_01JB4N9S3W2X6Y7Z8A1B2C3D4E.", "examples": [ "ord_01JB4N9S3W2X6Y7Z8A1B2C3D4E" ] }, "retired_record_id": { "type": "string", "pattern": "^contact_[0-7][0-9A-HJKMNP-TV-Z]{25}$", "description": "Format: a contact id: contact_ followed by a 26 character ULID in upper case Crockford base32, such as contact_01JA9X2V7XN3M9R6T1Y5W8ZAK8.", "examples": [ "contact_01JA9X2V7XN3M9R6T1Y5W8ZAK8" ] }, "replacement_record_id": { "anyOf": [ { "type": "string", "pattern": "^contact_[0-7][0-9A-HJKMNP-TV-Z]{25}$", "description": "Format: a contact id: contact_ followed by a 26 character ULID in upper case Crockford base32, such as contact_01JA9X2V7XN3M9R6T1Y5W8ZAK8.", "examples": [ "contact_01JA9X2V7XN3M9R6T1Y5W8ZAK8" ] }, { "type": "null" } ] }, "reason": { "type": "string", "enum": [ "hard_bounce", "job_change" ] }, "credits_refunded": { "type": "number", "minimum": 0, "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)." } }, "required": [ "order_id", "retired_record_id", "replacement_record_id", "reason", "credits_refunded" ] } }, "required": [ "id", "type", "timestamp", "api_version", "data" ], "description": "A bounced or job-changed record was replaced, or re-credited." }, "WebhookEndpoint": { "type": "object", "properties": { "id": { "type": "string", "pattern": "^whk_[0-7][0-9A-HJKMNP-TV-Z]{25}$", "description": "Format: a webhook endpoint id: whk_ followed by a 26 character ULID in upper case Crockford base32, such as whk_01JB3Y8Q2V7XN3M9R6T1Y5W8ZA.", "examples": [ "whk_01JB3Y8Q2V7XN3M9R6T1Y5W8ZA" ] }, "url": { "type": "string", "format": "uri" }, "events": { "type": "array", "items": { "type": "string", "enum": [ "order.ready", "order.failed", "audience.refreshed", "credits.low", "credits.topped_up", "warranty.replacement_issued", "suppression.created", "push.completed", "push.partial", "push.failed", "connection.expired" ] } }, "api_version": { "type": "string", "pattern": "^[0-9]{4}-(0[1-9]|1[0-2])-(0[1-9]|[12][0-9]|3[01])$", "description": "Pinned when the endpoint is created." }, "status": { "type": "string", "enum": [ "active", "disabled" ] }, "description": { "type": [ "string", "null" ] }, "created_at": { "type": "string", "format": "date-time" } }, "required": [ "id", "url", "events", "api_version", "status", "description", "created_at" ], "description": "Where to deliver events, and which ones." }, "WebhookEndpointCreated": { "type": "object", "properties": { "endpoint": { "$ref": "#/components/schemas/WebhookEndpoint" }, "secret": { "type": "string", "pattern": "^whsec_[A-Za-z0-9+/]{32,86}={0,2}$", "description": "The signing secret (whsec_), shown once. Rotate it from the app." } }, "required": [ "endpoint", "secret" ], "description": "A new endpoint and its signing secret, shown once." }, "WebhookEndpointList": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/WebhookEndpoint" } }, "has_more": { "type": "boolean", "description": "Whether another page follows." }, "next_cursor": { "anyOf": [ { "type": "string", "minLength": 1, "maxLength": 512, "description": "An opaque cursor from next_cursor. Pass it back unchanged." }, { "type": "null" } ], "description": "Pass as cursor to fetch the next page; null on the last page." } }, "required": [ "data", "has_more", "next_cursor" ], "description": "A page of webhook endpoints, newest first." }, "WebhookEndpointRequest": { "type": "object", "properties": { "url": { "type": "string", "format": "uri", "pattern": "^https://" }, "events": { "minItems": 1, "type": "array", "items": { "type": "string", "enum": [ "order.ready", "order.failed", "audience.refreshed", "credits.low", "credits.topped_up", "warranty.replacement_issued", "suppression.created", "push.completed", "push.partial", "push.failed", "connection.expired" ] } }, "description": { "type": "string", "maxLength": 200 } }, "required": [ "url", "events" ], "additionalProperties": false, "description": "A new endpoint, pinned to the MyDataHub-Version of the request." }, "WebhookEvent": { "oneOf": [ { "$ref": "#/components/schemas/OrderReadyEvent" }, { "$ref": "#/components/schemas/OrderFailedEvent" }, { "$ref": "#/components/schemas/AudienceRefreshedEvent" }, { "$ref": "#/components/schemas/CreditsLowEvent" }, { "$ref": "#/components/schemas/CreditsToppedUpEvent" }, { "$ref": "#/components/schemas/WarrantyReplacementEvent" }, { "$ref": "#/components/schemas/SuppressionCreatedEvent" }, { "$ref": "#/components/schemas/PushCompletedEvent" }, { "$ref": "#/components/schemas/PushPartialEvent" }, { "$ref": "#/components/schemas/PushFailedEvent" }, { "$ref": "#/components/schemas/ConnectionExpiredEvent" } ], "description": "A Standard Webhooks payload: {type, timestamp, data} plus the event id and the pinned api_version.", "discriminator": { "propertyName": "type", "mapping": { "order.ready": "#/components/schemas/OrderReadyEvent", "order.failed": "#/components/schemas/OrderFailedEvent", "audience.refreshed": "#/components/schemas/AudienceRefreshedEvent", "credits.low": "#/components/schemas/CreditsLowEvent", "credits.topped_up": "#/components/schemas/CreditsToppedUpEvent", "warranty.replacement_issued": "#/components/schemas/WarrantyReplacementEvent", "suppression.created": "#/components/schemas/SuppressionCreatedEvent", "push.completed": "#/components/schemas/PushCompletedEvent", "push.partial": "#/components/schemas/PushPartialEvent", "push.failed": "#/components/schemas/PushFailedEvent", "connection.expired": "#/components/schemas/ConnectionExpiredEvent" } } }, "WebhookTest": { "type": "object", "properties": { "event_id": { "type": "string", "pattern": "^evt_[0-7][0-9A-HJKMNP-TV-Z]{25}$", "description": "Format: an event id: evt_ followed by a 26 character ULID in upper case Crockford base32, such as evt_01JB4NB7T1Y5W8ZAK8Q2V7XN3M.", "examples": [ "evt_01JB4NB7T1Y5W8ZAK8Q2V7XN3M" ] }, "delivered": { "type": "boolean" }, "status_code": { "type": [ "integer", "null" ] }, "duration_ms": { "anyOf": [ { "type": "integer", "minimum": 0 }, { "type": "null" } ] } }, "required": [ "event_id", "delivered", "status_code", "duration_ms" ], "description": "The result of sending a test event to an endpoint." }, "WhereNode": { "anyOf": [ { "$ref": "#/components/schemas/AllGroup" }, { "$ref": "#/components/schemas/AnyGroup" }, { "$ref": "#/components/schemas/NotGroup" }, { "$ref": "#/components/schemas/BundleNode" }, { "$ref": "#/components/schemas/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." }, "WhyItMatches": { "type": "object", "properties": { "pointer": { "type": "string", "description": "JSON pointer to the filter in the audience." }, "field": { "type": "string" }, "value": { "description": "The record's actual value.", "anyOf": [ { "type": "string" }, { "type": "number" }, { "type": "boolean" } ] }, "explanation": { "type": "string", "description": "Such as Marketing Director matched marketing manager through expansion." } }, "required": [ "pointer", "field", "value", "explanation" ], "description": "One predicate the record satisfies, with its value." }, "WithinRadiusFilter": { "type": "object", "properties": { "field": { "type": "string", "enum": [ "site.location" ] }, "op": { "type": "string", "const": "within_radius" }, "centre": { "$ref": "#/components/schemas/RadiusCentre" }, "radius_miles": { "type": "number", "minimum": 1, "maximum": 100, "description": "Radius in miles, 1 to 100. Under 5 miles needs an account." } }, "required": [ "field", "op", "centre", "radius_miles" ], "additionalProperties": false, "description": "Sites within radius_miles of the centre. The count reports the centroid used and the postcodes matched.", "examples": [ { "field": "site.location", "op": "within_radius", "centre": { "place": "Leeds" }, "radius_miles": 20 } ] } }, "responses": { "BadRequest": { "description": "The request could not be read, or an Idempotency-Key is missing.", "headers": { "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "default": { "summary": "Example", "value": { "type": "https://emailmovers.com/mydatahub/docs/errors/idempotency-key-required", "title": "An Idempotency-Key header is required", "status": 400, "code": "idempotency-key-required", "detail": "POST /v1/orders needs an Idempotency-Key header.", "next_step": "Send an Idempotency-Key header (a V4 UUID is a good choice) and reuse it on every retry.", "instance": "/v1/orders" } } } } } }, "Unauthorized": { "description": "Sign in (OAuth) or send an API key (authentication-required), or create a free account for what the anonymous tier does not cover (account-required).", "headers": { "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" }, "WWW-Authenticate": { "$ref": "#/components/headers/WWW-Authenticate" } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "default": { "summary": "Example", "value": { "type": "https://emailmovers.com/mydatahub/docs/errors/authentication-required", "title": "Sign in or send an API key", "status": 401, "code": "authentication-required", "detail": "GET /v1/orders needs a token with orders:read.", "next_step": "Send Authorization: Bearer with an mdh_ API key. Sign-in through https://mydatahub.emailmovers.com/id is planned.", "instance": "/v1/orders" } } } } } }, "InsufficientCredits": { "description": "The balance does not cover the machine quote, which is carried here. Nothing was charged; top up on mydatahub.emailmovers.com and retry with the same quote_id.", "headers": { "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/InsufficientCreditsProblem" }, "examples": { "default": { "summary": "Example", "value": { "type": "https://emailmovers.com/mydatahub/docs/errors/insufficient-credits", "title": "Not enough credits", "status": 402, "code": "insufficient-credits", "detail": "The machine quote needs 5,000 credits and the balance is 1,200.", "next_step": "Top up at the top_up_url, then retry with the same machine quote_id (or the same enrichment request).", "instance": "/v1/orders", "quote_id": "qte_01JB4M2R6T1Y5W8ZAK8Q2V7XN3", "quote": { "id": "qte_01JB4M2R6T1Y5W8ZAK8Q2V7XN3", "kind": "machine", "dataset_version": "2026-W39", "records": 5000, "removed": { "already_held": 312, "suppressed": 41 }, "credits_required": 5000, "credits_available": 6200, "gbp_ex_vat": 1249, "licence": { "type": "multi_use_12m", "reuse_until": "2027-09-26", "resale_prohibited": true, "permitted_channels": [ "email", "telephone", "post" ], "warranty_url": "https://emailmovers.com/trust/warranty", "terms_version": "2026-09" }, "warranty": { "policy": "replace_over_threshold_hard_bounce", "threshold_percent": 10, "url": "https://emailmovers.com/trust/warranty" }, "expires_at": "2026-09-27T10:14:00Z", "blockers": [], "organisation_id": "org_01JA0Q2V7XN3M9R6T1Y5W8ZAK8", "count_id": "cnt_7K2PQ4MAXN3R6TBY5WDZ", "credits_per_record": 1, "balance_after": 1200, "purchase": { "credits_to_buy": 0, "cheapest": null, "gbp_ex_vat": 0, "options": [] }, "signature": { "alg": "ES256", "kid": "qte-2026-09", "jwks_url": "https://mydatahub.emailmovers.com/.well-known/jwks.json", "jws": "eyJhbGciOiJFUzI1NiIsImtpZCI6InF0ZS0yMDI2LTA5In0.eyJpZCI6InF0ZV8wMUpCNE0yUjZUMVk1VzhaQUs4UTJWN1hOMyJ9.MEUCIQDexampleSignatureOnly" } }, "credits_required": 5000, "credits_available": 1200, "top_up_url": "https://mydatahub.emailmovers.com/billing/top-up?quote=qte_01JB4M2R6T1Y5W8ZAK8Q2V7XN3" } } } } } }, "Forbidden": { "description": "The token lacks a scope (insufficient-scope, with required_scope and a WWW-Authenticate step-up challenge); no person confirmed the spend and no agent key covers it (confirmation-required, with an approval_url); an agent key's per-order cap or monthly budget does not cover it (agent-budget-exceeded); an account made by self-serve sign-up has not yet confirmed its business name and that it is a UK business, which its first order needs (business-details-required); the order needs the Data Licence and Sharing Agreement accepted at the version in force (licence-acceptance-required); or a suppression upload comes before the organisation has accepted the Article 28 data processing agreement in force (dpa-acceptance-required). Nothing is charged.", "headers": { "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" }, "WWW-Authenticate": { "$ref": "#/components/headers/WWW-Authenticate-InsufficientScope" } }, "content": { "application/problem+json": { "schema": { "anyOf": [ { "$ref": "#/components/schemas/AgentBudgetProblem" }, { "$ref": "#/components/schemas/ConfirmationRequiredProblem" }, { "$ref": "#/components/schemas/Problem" } ] }, "examples": { "confirmation": { "summary": "A person must confirm", "value": { "type": "https://emailmovers.com/mydatahub/docs/errors/confirmation-required", "title": "A person must confirm this spend", "status": 403, "code": "confirmation-required", "detail": "A standard API key cannot spend on its own. Nothing was charged; keep the machine quote and ask the user to approve it.", "next_step": "Nothing was charged. Keep the machine quote_id and give the user the approval_url; retry with the confirmation_token it returns, or use an agent key whose limits cover the spend.", "instance": "/v1/orders", "action": "order", "quote_id": "qte_01JB4M2R6T1Y5W8ZAK8Q2V7XN3", "approval_url": "https://mydatahub.emailmovers.com/quotes/qte_01JB4M2R6T1Y5W8ZAK8Q2V7XN3/approve", "expires_at": "2026-09-27T10:14:00Z" } }, "budget": { "summary": "Agent budget exceeded", "value": { "type": "https://emailmovers.com/mydatahub/docs/errors/agent-budget-exceeded", "title": "The agent key budget does not cover this spend", "status": 403, "code": "agent-budget-exceeded", "detail": "The machine quote needs 5,000 credits; this key may spend 500 an order and has 600 left this month.", "next_step": "Keep the machine quote_id and ask the key owner to approve it at approval_url, or top up at top_up_url.", "instance": "/v1/orders", "budget": { "monthly_credits": 1000, "spent": 400, "remaining": 600, "resets_at": "2026-10-01T00:00:00Z" }, "per_order_max_credits": 500, "quote_id": "qte_01JB4M2R6T1Y5W8ZAK8Q2V7XN3", "credits_required": 5000, "approval_url": "https://mydatahub.emailmovers.com/quotes/qte_01JB4M2R6T1Y5W8ZAK8Q2V7XN3/approve", "top_up_url": "https://mydatahub.emailmovers.com/billing/top-up" } }, "scope": { "summary": "Missing scope", "value": { "type": "https://emailmovers.com/mydatahub/docs/errors/insufficient-scope", "title": "The token lacks a scope", "status": 403, "code": "insufficient-scope", "detail": "Creating an order needs the orders:write scope.", "next_step": "Ask the user to approve the scope named in required_scope, then retry.", "instance": "/v1/orders", "required_scope": "orders:write" } } } } } }, "NotFound": { "description": "No such object for this organisation.", "headers": { "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "default": { "summary": "Example", "value": { "type": "https://emailmovers.com/mydatahub/docs/errors/not-found", "title": "Not found", "status": 404, "code": "not-found", "detail": "No order ord_01JB4N9S3W2X6Y7Z8A1B2C3D4E in this organisation.", "next_step": "Check the id; ids are prefixed, such as ord_ for orders and aud_ for audiences.", "instance": "/v1/orders/ord_01JB4N9S3W2X6Y7Z8A1B2C3D4E" } } } } } }, "Conflict": { "description": "An Idempotency-Key reused with different parameters, an expired machine quote, or an object in the wrong state.", "headers": { "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "default": { "summary": "Example", "value": { "type": "https://emailmovers.com/mydatahub/docs/errors/quote-expired", "title": "The machine quote has expired", "status": 409, "code": "quote-expired", "detail": "Machine quote qte_01JB4M2R6T1Y5W8ZAK8Q2V7XN3 expired at 2026-09-27T10:14:00Z.", "next_step": "Call quote_order (POST /v1/quotes) again; a machine quote is valid for 24 hours.", "instance": "/v1/orders" } } } } } }, "ValidationFailed": { "description": "The request is not valid. errors lists every problem with a JSON pointer and did_you_mean.", "headers": { "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "default": { "summary": "Example", "value": { "type": "https://emailmovers.com/mydatahub/docs/errors/validation-failed", "title": "The request is not valid", "status": 422, "detail": "Unknown field company.employees.", "instance": "/v1/counts", "code": "validation-failed", "next_step": "Fix each entry in errors, using did_you_mean where given, and send it again.", "errors": [ { "pointer": "/audience/where/all/0/field", "code": "invalid_value", "message": "Unknown field company.employees.", "did_you_mean": [ "company.employee_band" ] } ] } } } } } }, "RateLimited": { "description": "Too many requests. Wait for Retry-After.", "headers": { "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" }, "Retry-After": { "$ref": "#/components/headers/Retry-After" } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "default": { "summary": "Example", "value": { "type": "https://emailmovers.com/mydatahub/docs/errors/rate-limited", "title": "Too many requests", "status": 429, "code": "rate-limited", "detail": "60 counts an hour per IP for anonymous callers; the next resets in 42 seconds.", "next_step": "Wait for the seconds in Retry-After, then retry.", "instance": "/v1/counts", "retry_after_seconds": 42 } } } } } }, "ServerError": { "description": "Something failed on our side (500 internal-error) or the service is briefly unavailable (503 service-unavailable, with Retry-After). Nothing was charged; retry with the same Idempotency-Key. A count, sample, quote or order with telephone in play is also refused with 503 tps-screen-expired, with no Retry-After, while the dataset version's TPS and CTPS screen is more than 28 days old.", "headers": { "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" }, "Retry-After": { "$ref": "#/components/headers/Retry-After" } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "default": { "summary": "Example", "value": { "type": "https://emailmovers.com/mydatahub/docs/errors/service-unavailable", "title": "The service is briefly unavailable", "status": 503, "code": "service-unavailable", "detail": "The serving store is failing over; counts resume within a minute.", "next_step": "Wait for the seconds in Retry-After, then retry with the same Idempotency-Key. The status page shows incidents.", "instance": "/v1/counts", "retry_after_seconds": 30 } } } } } } }, "parameters": { "MyDataHubVersion": { "name": "MyDataHub-Version", "in": "header", "required": false, "description": "The dated API version, pinned per key when left out. Non-breaking changes ship as new dates; the path major changes only for breaking changes, with a 12 month deprecation window.", "schema": { "type": "string", "pattern": "^[0-9]{4}-[0-9]{2}-[0-9]{2}$" }, "example": "2027-01-15" }, "IdempotencyKey": { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Makes the request safe to retry: the same key returns the stored response. Keys are kept for the life of the organisation.", "schema": { "type": "string", "minLength": 1, "maxLength": 255 }, "example": "6f1c3b2a-9d4e-4f8a-b1c2-7e5d9a0f3c21" }, "IdempotencyKeyRequired": { "name": "Idempotency-Key", "in": "header", "required": true, "description": "Required. A retry with the same key never charges twice; a different request with the same key returns 409. Keys are kept for the life of the organisation.", "schema": { "type": "string", "minLength": 1, "maxLength": 255 }, "example": "6f1c3b2a-9d4e-4f8a-b1c2-7e5d9a0f3c21" } }, "headers": { "RateLimit": { "description": "IETF RateLimit field: one item for each window that applies (counts-hourly, counts-daily, counts-per-minute or requests), each with the remaining quota (r) and the seconds to reset (t).", "schema": { "type": "string" }, "example": "\"counts-hourly\";r=59;t=3522, \"counts-daily\";r=599;t=50322, \"requests\";r=119;t=42" }, "RateLimit-Policy": { "description": "IETF RateLimit-Policy field: one item for each window that applies, each with the quota (q) and the window in seconds (w). Anonymous callers get 60 counts an hour and 600 a day per IP and fingerprint.", "schema": { "type": "string" }, "example": "\"counts-hourly\";q=60;w=3600, \"counts-daily\";q=600;w=86400, \"requests\";q=120;w=60" }, "Retry-After": { "description": "Seconds to wait before retrying.", "schema": { "type": "integer", "minimum": 0 }, "example": 42 }, "ETag": { "description": "For a count, the count id in quotes: the same definition gives the same ETag.", "schema": { "type": "string" }, "example": "\"cnt_7K2PQ4MAXN3R6TBY5WDZ\"" }, "Location": { "description": "Where the new resource, or the signed file, lives: a path on https://mydatahub.emailmovers.com, resolved against the origin.", "schema": { "type": "string", "format": "uri-reference" }, "example": "/v1/orders/ord_01JB4N9S3W2X6Y7Z8A1B2C3D4E" }, "WWW-Authenticate": { "description": "The Bearer challenge, naming the protected resource metadata and the scopes to request.", "schema": { "type": "string" }, "example": "Bearer resource_metadata=\"https://mydatahub.emailmovers.com/.well-known/oauth-protected-resource/v1\", scope=\"counts:read previews:read audiences:read\"" }, "WWW-Authenticate-InsufficientScope": { "description": "The step-up challenge on 403 insufficient-scope (RFC 6750): error=\"insufficient_scope\" with the scope to request, which MCP and OAuth clients read to ask the user, such as orders:write on the first create_order.", "schema": { "type": "string" }, "example": "Bearer error=\"insufficient_scope\", scope=\"orders:write\", resource_metadata=\"https://mydatahub.emailmovers.com/.well-known/oauth-protected-resource/v1\"" } }, "securitySchemes": { "OAuth2": { "type": "oauth2", "description": "OAuth 2.1 at https://mydatahub.emailmovers.com/id, the one issuer for the app, REST and MCP: authorization code with PKCE (S256 only), rotating refresh tokens, 60 minute JWT access tokens with aud set to https://mydatahub.emailmovers.com/v1. Scopes are stepped up: the first challenge asks for counts:read previews:read audiences:read, and the first spend answers 403 insufficient_scope naming orders:write.", "flows": { "authorizationCode": { "authorizationUrl": "https://mydatahub.emailmovers.com/id/authorize", "tokenUrl": "https://mydatahub.emailmovers.com/id/token", "refreshUrl": "https://mydatahub.emailmovers.com/id/token", "scopes": { "account:read": "Read the balance, plan, prices, rate limits, usage and key budgets.", "account:write": "Set the business name and confirm that it is a UK business (PATCH /v1/account). A signed-in owner only; admin covers it too.", "counts:read": "Run counts and breakdowns with the account's exact figures and New to you.", "previews:read": "Draw masked samples.", "audiences:read": "Read saved audiences.", "audiences:write": "Save, update, refresh and delete audiences.", "quotes:read": "Create and read machine quotes with the account's balance.", "orders:read": "Read orders, compliance receipts and CRM pushes.", "orders:write": "Spend credits: create and cancel orders.", "records:read": "Fetch and download delivered records under licence.", "enrich:write": "Spend credits: enrich a known contact, charged only on a confident match.", "suppressions:read": "Read suppression lists and check records before a send.", "suppressions:write": "Upload suppression lists and report objections.", "pushes:write": "Connect CRMs, check overlap and push delivered records.", "webhooks:write": "Manage webhook endpoints and read the event log.", "samples:request": "Ask for a sample of a counted audience, sent by email to a confirmed work address. Never returns records.", "admin": "Manage API keys, agent keys and the plan, including cancellation. Keys are made and changed by signed-in people only, and an agent key never holds admin." } } } }, "ApiKey": { "type": "http", "scheme": "bearer", "bearerFormat": "mdh_live_ or mdh_test_ API key", "description": "An API key or agent key as Authorization: Bearer, never a custom header or query string. mdh_test_ keys return synthetic data and never charge. Keys carry scopes like OAuth tokens. A standard key never spends on its own: a spend needs a person's confirmation or an agent key within its limits." } } } }