---
updatedAt: 2026-04-30T18:19:50.000Z
agentTools:
  projectIndex: https://docs.fullcontact.com/llms.txt
---

# Tool Reference: enrich_person

`enrich_person` is the primary tool exposed by the FullContact MCP Server. It accepts one or more identifiers for a person and returns a unified, agent-friendly profile drawn from FullContact's identity graph.

This tool is a thin wrapper over [`POST /v3/person.enrich`](https://docs.fullcontact.com/docs/multi-field-request). Anything documented for that endpoint — input combinations, hashed identifier behavior, Insight Bundles — applies here unchanged.

## Inputs

The tool accepts the following parameters. At least one identifier must be supplied; combining multiple identifiers improves match rates.

| Parameter         | Type   | Description                                                                                                                                      |
| ----------------- | ------ | ------------------------------------------------------------------------------------------------------------------------------------------------ |
| `email`           | string | Email address, or an MD5 / SHA-1 / SHA-256 hash of an email.                                                                                     |
| `phone`           | string | Phone number in E.164 format (e.g. `+13035551234`).                                                                                              |
| `name`            | string | Full name. **Required** when using `location`. Improves match quality when combined with any other identifier. **Can not be used as sole input** |
| `name`+`location` | object | Postal address. Must be paired with `name`. See the schema below.                                                                                |
| `linkedin`        | string | LinkedIn profile URL.                                                                                                                            |
| `twitter`         | string | Twitter / X username (with or without `@`) or full twitter URL.                                                                                  |

### `location` object

| Field          | Type   | Description                                 |
| -------------- | ------ | ------------------------------------------- |
| `addressLine1` | string | Street address, e.g. `1234 Sherman St`.     |
| `city`         | string | City, e.g. `Denver`.                        |
| `region`       | string | Full state or region name, e.g. `Colorado`. |
| `regionCode`   | string | Two-letter state or region code, e.g. `CO`. |
| `postalCode`   | string | Postal or ZIP code.                         |
| `country`      | string | Country code or name, e.g. `US`.            |

> 📘 **Tip — combine identifiers**
>
> The more contact data you provide, the better. A request that includes `email` + `name` + `location` typically resolves at a much higher rate than `email` alone.

## Example invocations

### Email only

```json
{
  "email": "bart@fullcontact.com"
}
```

### Multi-field request

```json
{
  "email": "bart@fullcontact.com",
  "name": "Bart Lorang",
  "location": {
    "addressLine1": "1530 16th St",
    "city": "Denver",
    "regionCode": "CO",
    "postalCode": "80202",
    "country": "US"
  }
}
```

### Hashed email

```json
{
  "email": "5cdb9db4ad7d75d99ed28cae7ce8ff95"
}
```

When only a hashed identifier is supplied, the response will omit clear-text PII fields (name, plain email, phone, social handles) per FullContact's privacy controls.

## Output

A successful call returns a structured person profile. Fields are populated when available in the identity graph; missing fields are simply absent from the response.

```json
{
  "fullName": "Bart Lorang",
  "ageRange": "35-44",
  "gender": "Male",
  "location": "Denver, Colorado, United States",
  "title": "Managing Partner",
  "organization": "V1.VC",
  "twitter": "https://twitter.com/lorangb",
  "linkedin": "https://www.linkedin.com/in/bartlorang",
  "bio": "Co-founder of FullContact. Investor at V1.VC.",
  "avatar": "https://img.fullcontact.com/static/...",
  "details": {
    "emails": [
      { "value": "bart@fullcontact.com", "type": "work" }
    ],
    "employment": [
      { "name": "FullContact", "title": "Co-founder", "current": false },
      { "name": "V1.VC",       "title": "Managing Partner", "current": true }
    ],
    "locations": [
      { "city": "Denver", "region": "Colorado", "country": "United States" }
    ]
  }
}
```

The MCP Server returns the same response shape as the underlying `person.enrich` API. Refer to [Person Summary Object](https://docs.fullcontact.com/docs/multi-field-request#example-person-summary-object) for the full field catalog. Premium **Insight Bundles** (employment depth, household demographics, interests, online behaviors, and more) are returned in the same response when enabled on your account — contact your FullContact account team to add Bundles to your plan.

## Errors

If a request cannot be fulfilled, the tool returns a normalized error payload rather than raising an exception in the agent. Common cases:

```json
{
  "error": {
    "code": "not_found",
    "message": "No person matched the supplied identifiers."
  }
}
```

```json
{
  "error": {
    "code": "invalid_input",
    "message": "`location` requires `name` to be supplied."
  }
}
```

See the full taxonomy in [Errors and FAQ](./05-mcp-errors-and-faq.md).

## Calling from an agent

Most users do not call the tool directly — they let the model decide when to invoke it. A natural-language request such as:

> *Look up <bart@fullcontact.com> on FullContact and tell me where she works.*

is enough for the agent to issue an `enrich_person` call with `email: "bart@fullcontact.com"` and summarize the response. For deterministic workflows (e.g., batch enrichment), you can prompt the model with explicit field names:

> *For each row in the attached CSV, call `enrich_person` with the `email` column and write `fullName`, `title`, and `organization` back into the spreadsheet.*

## Next steps

* [Errors and FAQ](./05-mcp-errors-and-faq.md) — Error codes and common questions.
* [Authentication](./03-mcp-authentication.md) — Detailed credential handling and rate limits.

***

*Updated May 2026*