# Enrich a contact (spends credits)

> enrich_contact: Returns the full record for one known person, matched by email or by name with a company name, number or domain.

Source: https://emailmovers.com/mydatahub/docs/reference/mcp/enrich_contact

Returns the full record for one known person, matched by email or by name with a company name, number or domain. It spends 1 credit only on a confident match, and 0 on no match or when you already hold the record under licence, so a repeat never charges twice. Like create_order it needs the user's confirmation (a form, or the confirmation_token from an approval_url) or an agent key whose allowed_tools include enrich_contact within its per-order cap and monthly budget; otherwise nothing is charged and it returns confirmation-required or agent-budget-exceeded. It needs enrich:write; use it for a single named person, and the result gives credits_charged and the balance left. Lawful basis is UK GDPR Article 6(1)(f) legitimate interests; email audiences include corporate subscribers only by default (PECR), so sole traders and ordinary partnerships are left out unless the toggle is changed.

| Property | Value |
| --- | --- |
| Tool name | `enrich_contact` |
| Position in tools/list | 19 of 22 |
| Cost | 1 credit on match |
| Scope | `enrich:write` |
| Annotations | readOnlyHint false, destructiveHint false, idempotentHint true, openWorldHint false |
| Kind | Write; idempotent, not destructive, closed world |
| REST equivalent | [`POST /v1/contacts/enrich`](https://emailmovers.com/mydatahub/docs/reference/rest/enrich-contact.md) |

> **Not yet live.** MyDataHub v2 is built and tested locally and is not yet live. The v2 hosts open at launch, date to confirm. This is what `tools/list` returns from https://mydatahub.emailmovers.com/mcp once v2 launches.

## Input

The schema sets `additionalProperties` to false, so a member that is not listed is refused.

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

## Example call

The `params` of a `tools/call` request:

```json
{
  "name": "enrich_contact",
  "arguments": {
    "first_name": "Jo",
    "last_name": "Example",
    "company_number": "12345678"
  }
}
```

## Output

The result carries `structuredContent` that matches this schema, and one line of text that leads with the number.

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

## Errors

A failed call returns `isError` true. The text content leads with the sentence a person acts on, then the whole problem as JSON, with `code`, `detail`, `next_step` and `did_you_mean`. A 401 and a step-up 403 are answered at HTTP level so the client can start authorisation. See [Errors](https://emailmovers.com/mydatahub/docs/errors.md).