> ## Documentation Index
> Fetch the complete documentation index at: https://docs.minerva.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Enrich

> Full person profiles — identity, contact, professional, financial, household, relatives — from a record stub.

```python theme={null}
resp = mc.api.enrich(
    [{"record_id": "1", "linkedin_url": "https://www.linkedin.com/in/example"}],
    match_condition_fields=["linkedin_url"],
    return_fields=["full_name", "professional_emails", "phones"],
)

for r in resp.results:
    print(r.record_id, r.is_match, r.minerva_pid, r.match_score)
    print(r.personal_information)     # full_name, gender, dob, age, ...
    print(r.professional_emails)      # [{email_rank, email_address}, ...]

resp.to_df()                          # one row per record, nested fields flattened
```

## Parameters

<ParamField path="records" type="list[dict]" required>
  Up to 500 per call. Each must have `record_id` + at least one matching field
  (LinkedIn URL, emails, name, etc.).
</ParamField>

<ParamField path="version" type="str" default="&#x22;v2&#x22;">
  API version.
</ParamField>

<ParamField path="match_condition_fields" type="list[str]">
  Quality gate (up to 3). A record only counts as a match if the resolved
  person actually has these fields. Useful when you need contact info you can
  act on (e.g. require a `phone`). Omit to match on resolution alone.
</ParamField>

<ParamField path="return_fields" type="list[str]">
  Narrow the response payload to just these fields. Reduces wire size; doesn't
  affect billing.
</ParamField>

<ParamField path="dry_run" type="bool" default="False">
  Validate input locally without sending. Returns the `EnrichRequest` that
  *would* be sent. See [Validation](/sdk/guides/validation-dry-run).
</ParamField>

## Response shape

Each result includes:

| Field                                    | What                                     |
| ---------------------------------------- | ---------------------------------------- |
| `personal_information`                   | `full_name`, `gender`, `dob`, `age`, ... |
| `household_information`                  | Household composition + income range     |
| `financial_information`                  | Estimated income, net worth, etc.        |
| `social_media`                           | Public profile URLs                      |
| `personal_emails`, `professional_emails` | Ranked email arrays                      |
| `phones`                                 | Verified phone numbers                   |
| `address_history`                        | Past + current addresses                 |
| `work_experience`                        | Employment history                       |
| `education_experience`                   | Schools + degrees                        |
| `relatives`                              | Linked household members                 |

<Note>
  `match_condition_fields` is a **quality gate** — a record only counts as a
  match if the resolved person actually has those fields (e.g. require a
  `phone` you can dial). Omit it to match on resolution alone.
</Note>

## Tabular output

```python theme={null}
resp.to_dicts()        # list[dict]
resp.to_df()           # pandas DataFrame   (needs [pandas])
resp.to_csv("out.csv")
resp.to_table()        # pretty terminal table   (needs [table])
```

Nested fields (e.g. `personal_information.full_name`) flatten into top-level
columns in the DataFrame. See [Output formats](/sdk/guides/output-formats).

## Map onto your own schema

Project any result onto **your** pydantic model — missing fields become
`None` (with a one-time warning), so it never breaks:

```python theme={null}
from pydantic import BaseModel

class Lead(BaseModel):
    record_id: str
    full_name: str | None = None
    estimated_income_range: str | None = None
    crm_id: str | None = None          # not a Minerva field → stays None, warns once

leads = mc.api.enrich(records).map_to(Lead)      # -> list[Lead]
# pass strict=True to validate instead (raises on mismatch)
```

## Limits

* Records per call: **500**
* Validation enforced locally before the call — over-limit records raise
  `MinervaValidationError` without a round-trip
* Billing: credits consumed per matched record — see your plan