Reference

Enrich a contact (spends credits)

POST /v1/contacts/enrich. The full record for one known person, by email or by name and company.

Generated from the contractsView as Markdown

POST /v1/contacts/enrich

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.

Property	Value
Endpoint	`POST https://mydatahub.emailmovers.com/v1/contacts/enrich`
Operation id	`enrichContact`
Cost	1 credit on a confident match; 0 on no match or when already licensed.
Access	An API key or an OAuth 2.1 token with the scope `enrich:write`.
Idempotency-Key	Required. A retry never charges twice.
MCP tool	`enrich_contact`
Tag	Lookups

Request

Parameters

Name	In	Type	Required	Description
`MyDataHub-Version`	header	string	no	The dated API version, pinned per key when left out. Non-breaking changes ship as new dates; the path major changes only for breaking changes, with a 12 month deprecation window.
`Idempotency-Key`	header	string	yes	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.

Body

Member	Type	Required	Description
`email`	string (email)	no
`first_name`	string	no
`last_name`	string	no
`company_name`	string	no
`company_number`	string	no	Eight characters in upper case, such as 05046417 or SC123456.
`domain`	string	no
`confirmation_token`	string	no	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`	string	no	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.

Example request

curl -X POST "https://mydatahub.emailmovers.com/v1/contacts/enrich" \
  -H "Authorization: Bearer $MYDATAHUB_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  --data '{
  "first_name": "Jo",
  "last_name": "Example",
  "company_number": "12345678"
}'

Responses

200: The match, or no match.

Headers: RateLimit, RateLimit-Policy.

Member	Type	Always present	Description
`matched`	boolean	yes
`match_confidence`	number (0 to 1) or null	yes
`already_licensed`	boolean	yes	True when you already hold the record, so it costs 0.
`record`	`ContactRecord` or null	yes
`record.id`	string	yes	The record id, pushed to CRMs as mydatahub_record_id.
`record.dataset_version`	string	yes	The immutable weekly build a count is bound to, such as 2026-W39. The last 52 stay queryable.
`record.contact`	object	yes
`record.email`	object or null	yes
`record.phone`	object or null	yes	Present when the field set includes telephone and a number is held.
`record.company`	object	yes
`record.site`	object	yes
`record.compliance`	`ComplianceObject`	yes	Carried by every preview row, order record, lookup and enrichment, and repeated as CSV columns and as the MyDataHub property group on CRM push.
`record.licence_expires_at`	string (date) or null	yes
`credits_charged`	number (0 or more)	yes	1 on a confident match, otherwise 0.
`credits_remaining`	number (0 or more)	yes	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`	number (0 or more)	yes	Pounds sterling excluding VAT, to two decimal places.
`licence_expires_at`	string (date) or null	yes

Example response

{
  "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": "[email protected]",
      "type": "named",
      "deliverability_score": 88,
      "verified_at": "2026-09-10",
      "result": "ok"
    },
    "phone": {
      "e164": "+441130000001",
      "line_type": "landline",
      "tps_ctps_status": "clear",
      "screened_at": "2026-09-12"
    },
    "company": {
      "name": "Example Manufacturing Ltd",
      "companies_house_number": "12345678",
      "status": "active",
      "type": "ltd",
      "subscriber_class": "ltd",
      "sic_2007": [
        {
          "code": "25620",
          "label": "Machining"
        }
      ],
      "employee_band": "100-199",
      "turnover_band": "11M-20M",
      "website_domain": "example.co.uk"
    },
    "site": {
      "address_lines": ["1 Example Street"],
      "town": "Leeds",
      "county": "West Yorkshire",
      "postcode": "LS11 5AA",
      "region": "yorkshire_and_the_humber"
    },
    "compliance": {
      "lawful_basis": "legitimate_interests_art6_1_f",
      "lia_ref": "EM-LIA-2026-03",
      "subscriber_class": "ltd",
      "corporate_subscriber": true,
      "email_marketing_basis": "pecr_corporate_subscriber",
      "subscriber_evidence": {
        "companies_house_number": "12345678",
        "company_type": "ltd"
      },
      "article14_status": "notified",
      "article14_notified_at": "2026-06-14",
      "notice_version": "2026-02",
      "provenance": {
        "company": {
          "source": "companies_house",
          "as_of": "2026-09-21"
        },
        "contact": {
          "source": "emailmovers_research",
          "compiled_at": "2026-05-02",
          "last_verified_at": "2026-08-30",
          "method": "telephone"
        },
        "email": {
          "verified_at": "2026-09-10",
          "result": "ok",
          "provider_location": "EU"
        }
      },
      "tps_ctps_status": "clear",
      "tps_ctps_screened_at": "2026-09-12",
      "tps_ctps_valid_until": "2026-10-10",
      "suppression_status": "none",
      "record_age_days": 147,
      "attribution": "Contains public sector information licensed under the Open Government Licence v3.0"
    },
    "licence_expires_at": "2027-09-26"
  },
  "credits_charged": 1,
  "credits_remaining": 1199,
  "cost_gbp": 0.3,
  "licence_expires_at": "2027-09-26"
}

Errors

Every error is a problem object with a code and a next_step. Every response carries the RateLimit and RateLimit-Policy headers; see Rate limits.

Status	Problem codes	When
400	`invalid-request`, `idempotency-key-required`, `unsupported-version`	The request could not be read, or an Idempotency-Key is missing.
401	`authentication-required`, `account-required`	Sign in (OAuth) or send an API key (authentication-required), or create a free account for what the anonymous tier does not cover (account-required).
402	`insufficient-credits`	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.
403	`insufficient-scope`, `confirmation-required`, `business-details-required`, `licence-acceptance-required`, `dpa-acceptance-required`, `agent-budget-exceeded`	The token lacks a scope (insufficient-scope, with required_scope and a WWW-Authenticate step-up challenge); no person confirmed the spend and no agent key covers it (confirmation-required, with an approval_url); an agent key's per-order cap or monthly budget does not cover it (agent-budget-exceeded); an account made by self-serve sign-up has not yet confirmed its business name and that it is a UK business, which its first order needs (business-details-required); the order needs the Data Licence and Sharing Agreement accepted at the version in force (licence-acceptance-required); or a suppression upload comes before the organisation has accepted the Article 28 data processing agreement in force (dpa-acceptance-required). Nothing is charged.
409	`idempotency-key-reused`, `quote-expired`, `order-not-ready`, `order-not-cancellable`	An Idempotency-Key reused with different parameters, an expired machine quote, or an object in the wrong state.
422	`validation-failed`, `quote-required`, `dataset-unavailable`	The request is not valid. errors lists every problem with a JSON pointer and did_you_mean.
429	`rate-limited`	Too many requests. Wait for Retry-After.
Any other failure	`internal-error`, `service-unavailable`, `tps-screen-expired`	Something failed on our side (500 internal-error) or the service is briefly unavailable (503 service-unavailable, with Retry-After). Nothing was charged; retry with the same Idempotency-Key. A count, sample, quote or order with telephone in play is also refused with 503 tps-screen-expired, with no Retry-After, while the dataset version's TPS and CTPS screen is more than 28 days old.