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

> Enhanced enrichment with direct lookups, flexible matching, and selective field returns

<div style={{ display: 'none' }} aria-hidden="false">
  ## Quick Answer

  **How do I enrich a user/person/contact?** Use this endpoint to get detailed information about a person including their work history, contact details, demographics, addresses, and more.

  **Common questions this endpoint answers:**

  * How do I enrich a user?
  * How do I get comprehensive data about a person?
  * How do I find someone's email and phone number?
  * How do I look up a person's job history and education?
  * How do I get demographic and financial information about someone?
  * How can I enrich my customer database with additional fields?
  * How do I append data to my contact records?

  **Three ways to enrich:**

  1. **By Minerva PID** - If you already resolved someone, use their PID for instant enrichment
  2. **By LinkedIn URL** - Provide someone's LinkedIn profile for quick lookup
  3. **By name/email/phone** - Provide basic info and we'll match and enrich the person

  **What you get back:** Comprehensive profile with work experience, education, contact info (emails, phones), addresses, demographics, family relationships, financial estimates, and social profiles.
</div>

## Overview

The V2 Enrich endpoint combines identity resolution and comprehensive data enrichment with enhanced features for better control and performance. It supports three lookup modes: direct Minerva PID lookups, LinkedIn URL lookups, and traditional fuzzy matching with name/contact information.

## Key Enhancements in V2

* **Direct Lookups**: Enrich by `minerva_pid` or `linkedin_url` for instant results without fuzzy matching
* **Match Conditions**: Control which fields must be present for a match to be returned
* **Selective Returns**: Use `return_fields` to get only the data you need and optimize response size
* **New Data**: Includes `relatives` field with family relationship information
* **Flexible Inputs**: Name is optional when using direct PID or LinkedIn lookups
* **Improved Performance**: Optimized data retrieval with parallel processing and support for mixed lookup modes

## Request

### Headers

<ParamField header="x-api-key" type="string" required>
  Your API key for authentication
</ParamField>

<ParamField header="Content-Type" type="string" required>
  application/json
</ParamField>

### Request Body

<ParamField body="records" type="object[]" required>
  An array of person records to enrich. Maximum 500 records per request.

  <Expandable title="Record object properties">
    <ParamField body="record_id" type="string" required>
      Your unique identifier for this record
    </ParamField>

    <ParamField body="minerva_pid" type="string">
      **New in V2**: Direct Minerva Person ID lookup for instant enrichment
    </ParamField>

    <ParamField body="linkedin_url" type="string">
      **New in V2**: LinkedIn profile URL for direct enrichment
    </ParamField>

    <ParamField body="first_name" type="string">
      Person's first name
    </ParamField>

    <ParamField body="middle_name" type="string">
      Person's middle name
    </ParamField>

    <ParamField body="last_name" type="string">
      Person's last name
    </ParamField>

    <ParamField body="full_name" type="string">
      Person's full name
    </ParamField>

    <ParamField body="name_suffix" type="string">
      Name suffix (e.g., "Jr.", "Sr.", "III")
    </ParamField>

    <ParamField body="emails" type="string[]">
      Array of email addresses
    </ParamField>

    <ParamField body="phones" type="string[]">
      Array of phone numbers
    </ParamField>
  </Expandable>
</ParamField>

<ParamField body="match_condition_fields" type="string[]">
  Optional list of fields that must be present in the enriched data for a record to be returned as a match. Maximum 3 fields.

  Valid options: `linkedin_url`, `gender`, `estimated_income_range`, `estimated_wealth_range`, `email`, `personal_email`, `professional_email`, `phone`, `mobile_phone`, `home_ownership_status`

  Example: `["email"]` or `["phone", "linkedin_url"]`
</ParamField>

<ParamField body="return_fields" type="string[]">
  Optional list of additional fields to return beyond the base fields. Use this to control response size and reduce latency. If not specified, all available fields are returned.

  Base fields (always returned): `record_id`, `is_match`, `minerva_pid`, `match_score`, `validation_errors`

  Available fields: `full_name`, `first_name`, `middle_name`, `last_name`, `name_suffix`, `gender`, `dob`, `age`, `marital_status`, `minerva_household_id`, `minerva_spouse_pid`, `number_of_children`, `is_retired`, `estimated_income_range`, `estimated_wealth_range`, `home_ownership_status`, `linkedin_url`, `linkedin_title`, `linkedin_industry`, `is_likely_remote_worker`, `facebook_url`, `twitter_url`, `has_bankruptcy_records`, `has_judgment_records`, `address_history`, `education_experience`, `work_experience`, `personal_emails`, `professional_emails`, `phones`

  **Note**: When using `return_fields`, only the requested fields are included, but they are returned within their respective nested objects (`personal_information`, `household_information`, `financial_information`, `social_media`). The `relatives` field is automatically included when returning all fields, but cannot be explicitly requested via `return_fields`.

  Example: `["full_name", "personal_emails", "phones"]`
</ParamField>

### Request Examples

#### Standard Fuzzy Matching with Selective Returns

```json theme={null}
{
  "records": [
    {
      "record_id": "user_001",
      "first_name": "John",
      "last_name": "Smith",
      "emails": ["john.smith@example.com"]
    }
  ],
  "match_condition_fields": ["email"],
  "return_fields": ["full_name", "linkedin_url", "personal_emails", "phones"]
}
```

#### Direct Minerva PID Lookup

```json theme={null}
{
  "records": [
    {
      "record_id": "user_002",
      "minerva_pid": "p-a1b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6"
    }
  ]
}
```

#### Direct LinkedIn URL Lookup

```json theme={null}
{
  "records": [
    {
      "record_id": "user_003",
      "linkedin_url": "https://www.linkedin.com/in/janedoe"
    }
  ]
}
```

#### Mixed Lookup Types in One Request

```json theme={null}
{
  "records": [
    {
      "record_id": "user_001",
      "first_name": "John",
      "last_name": "Smith",
      "emails": ["john.smith@example.com"]
    },
    {
      "record_id": "user_002",
      "minerva_pid": "p-a1b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6"
    },
    {
      "record_id": "user_003",
      "linkedin_url": "https://www.linkedin.com/in/janedoe"
    }
  ],
  "return_fields": ["full_name", "linkedin_url", "personal_emails", "work_experience"]
}
```

**Record Object Fields**:

* `record_id` (string, required): Your unique identifier for this record
* `minerva_pid` (string): **New in V2** - Direct Minerva Person ID lookup for instant enrichment. Format: `p-` followed by 32 hexadecimal characters
* `linkedin_url` (string): **New in V2** - LinkedIn profile URL or username for direct enrichment
* `first_name` (string): Person's first name
* `middle_name` (string): Person's middle name
* `last_name` (string): Person's last name
* `full_name` (string): Person's full name
* `name_suffix` (string): Name suffix (e.g., "Jr.", "Sr.", "III")
* `emails` (array): Array of email addresses
* `phones` (array): Array of phone numbers

**Note**: `/v2/enrich` accepts `minerva_pid` and `linkedin_url` as direct lookup fields, while `/v2/resolve` does not.

## Response

### Response Structure

<ResponseField name="api_request_id" type="string">
  Unique identifier for this API request
</ResponseField>

<ResponseField name="results" type="array">
  Array of enrichment results
</ResponseField>

<ResponseField name="request_completed_at" type="string">
  ISO 8601 timestamp when the request was completed
</ResponseField>

#### Result Object - Base Fields (Always Returned)

<ResponseField name="record_id" type="string">
  Your identifier from the request
</ResponseField>

<ResponseField name="is_match" type="boolean">
  Whether a match was found
</ResponseField>

<ResponseField name="minerva_pid" type="string">
  Minerva person identifier
</ResponseField>

<ResponseField name="match_score" type="number">
  Confidence score for the match (0-1 scale)
</ResponseField>

<ResponseField name="validation_errors" type="object">
  Any validation errors from the input
</ResponseField>

#### Result Object - Personal Information

<ResponseField name="personal_information" type="object">
  Object containing personal demographic details

  <Expandable title="personal_information properties">
    <ResponseField name="full_name" type="string">
      Person's full name
    </ResponseField>

    <ResponseField name="first_name" type="string">
      First name
    </ResponseField>

    <ResponseField name="middle_name" type="string">
      Middle name
    </ResponseField>

    <ResponseField name="last_name" type="string">
      Last name
    </ResponseField>

    <ResponseField name="name_suffix" type="string">
      Name suffix
    </ResponseField>

    <ResponseField name="gender" type="string">
      Gender ("M", "F", or null)
    </ResponseField>

    <ResponseField name="dob" type="string">
      Date of birth (YYYY-MM-DD format)
    </ResponseField>

    <ResponseField name="age" type="integer">
      Current age
    </ResponseField>

    <ResponseField name="marital_status" type="string">
      Marital status ("M" for married, "S" for single, or null)
    </ResponseField>
  </Expandable>
</ResponseField>

#### Result Object - Household Information

<ResponseField name="household_information" type="object">
  Object containing household and family details

  <Expandable title="household_information properties">
    <ResponseField name="minerva_household_id" type="string">
      Household identifier
    </ResponseField>

    <ResponseField name="minerva_spouse_pid" type="string">
      Spouse's Minerva PID if available
    </ResponseField>

    <ResponseField name="number_of_children" type="integer">
      Number of children
    </ResponseField>
  </Expandable>
</ResponseField>

#### Result Object - Financial Information

<ResponseField name="financial_information" type="object">
  Object containing financial and legal record details

  <Expandable title="financial_information properties">
    <ResponseField name="is_retired" type="boolean">
      Whether the person is retired
    </ResponseField>

    <ResponseField name="estimated_income_range" type="string">
      Estimated income bracket
    </ResponseField>

    <ResponseField name="estimated_wealth_range" type="string">
      Estimated wealth bracket
    </ResponseField>

    <ResponseField name="home_ownership_status" type="string">
      Home ownership status (e.g., "Owner", "Renter", or null)
    </ResponseField>

    <ResponseField name="has_bankruptcy_records" type="boolean">
      Whether bankruptcy records exist
    </ResponseField>

    <ResponseField name="has_judgment_records" type="boolean">
      Whether judgment records exist
    </ResponseField>
  </Expandable>
</ResponseField>

#### Result Object - Social Media

<ResponseField name="social_media" type="object">
  Object containing social media profiles and professional information

  <Expandable title="social_media properties">
    <ResponseField name="linkedin_url" type="string">
      LinkedIn profile URL
    </ResponseField>

    <ResponseField name="linkedin_title" type="string">
      Current title from LinkedIn
    </ResponseField>

    <ResponseField name="linkedin_industry" type="string">
      Industry from LinkedIn
    </ResponseField>

    <ResponseField name="is_likely_remote_worker" type="boolean">
      Whether the person likely works remotely
    </ResponseField>

    <ResponseField name="facebook_url" type="string">
      Facebook profile URL
    </ResponseField>

    <ResponseField name="twitter_url" type="string">
      Twitter profile URL
    </ResponseField>
  </Expandable>
</ResponseField>

#### Result Object - Contact Information

<ResponseField name="personal_emails" type="array">
  Array of personal email addresses with ranking
</ResponseField>

<ResponseField name="professional_emails" type="array">
  Array of professional email addresses with ranking
</ResponseField>

<ResponseField name="phones" type="array">
  Array of phone numbers with type and ranking
</ResponseField>

##### Email Object

<ResponseField name="email_rank" type="integer">
  Rank/priority of this email (1 = highest priority)
</ResponseField>

<ResponseField name="email_address" type="string">
  Email address
</ResponseField>

##### Phone Object

<ResponseField name="phone_rank" type="integer">
  Rank/priority of this phone (1 = highest priority)
</ResponseField>

<ResponseField name="phone_type" type="string">
  Phone type (e.g., "Mobile", "Landline")
</ResponseField>

<ResponseField name="phone_number" type="string">
  Phone number
</ResponseField>

#### Result Object - Family Relationships (New in V2)

<ResponseField name="relatives" type="array">
  **New in V2**: Array of family relationships
</ResponseField>

##### Relative Object

<ResponseField name="relative_minerva_pid" type="string">
  Minerva PID of the relative
</ResponseField>

<ResponseField name="relative_first_name" type="string">
  Relative's first name
</ResponseField>

<ResponseField name="relative_last_name" type="string">
  Relative's last name
</ResponseField>

<ResponseField name="relationship_label" type="string">
  Type of relationship (e.g., "Parent", "Child", "Sibling")
</ResponseField>

<ResponseField name="relationship_sublabel" type="string">
  Additional relationship details
</ResponseField>

#### Result Object - Address History

<ResponseField name="address_history" type="array">
  Array of address records with property details
</ResponseField>

##### Address Object

<ResponseField name="address_rank" type="integer">
  Rank of address (1 = most recent/current)
</ResponseField>

<ResponseField name="minerva_address_id" type="string">
  Unique address identifier
</ResponseField>

<ResponseField name="address_line_1" type="string">
  Street address
</ResponseField>

<ResponseField name="address_line_2" type="string">
  Apartment/unit number
</ResponseField>

<ResponseField name="address_city" type="string">
  City
</ResponseField>

<ResponseField name="address_state" type="string">
  State
</ResponseField>

<ResponseField name="address_zipcode" type="string">
  ZIP code
</ResponseField>

<ResponseField name="address_zipcode4" type="string">
  ZIP+4 extension
</ResponseField>

<ResponseField name="ownership_status" type="string">
  Ownership status ("Owned" / "Rented")
</ResponseField>

<ResponseField name="is_current_owner" type="boolean">
  Whether person currently owns this property (TRUE / FALSE)
</ResponseField>

<ResponseField name="purchase_date" type="string">
  Date property was purchased
</ResponseField>

<ResponseField name="purchase_price" type="number">
  Purchase price in USD
</ResponseField>

<ResponseField name="estimated_current_value" type="number">
  Current estimated value in USD
</ResponseField>

<ResponseField name="estimated_rental_value" type="number">
  Estimated monthly rental value in USD
</ResponseField>

<ResponseField name="home_current_tax_liability" type="number">
  Annual property tax in USD
</ResponseField>

<ResponseField name="outstanding_loan_principal" type="number">
  Outstanding mortgage balance in USD
</ResponseField>

<ResponseField name="current_property_equity_amount" type="number">
  Estimated equity in USD
</ResponseField>

<ResponseField name="sqft" type="number">
  Square footage
</ResponseField>

<ResponseField name="num_beds" type="number">
  Number of bedrooms
</ResponseField>

<ResponseField name="num_baths" type="number">
  Number of bathrooms
</ResponseField>

<ResponseField name="first_seen_date" type="string">
  First date person was associated with this address
</ResponseField>

<ResponseField name="last_seen_date" type="string">
  Last date person was associated with this address
</ResponseField>

#### Result Object - Work Experience

<ResponseField name="work_experience" type="array">
  Array of work history records
</ResponseField>

##### Work Experience Object

<ResponseField name="experience_rank" type="integer">
  Rank (1 = most recent)
</ResponseField>

<ResponseField name="minerva_experience_id" type="string">
  Unique experience identifier
</ResponseField>

<ResponseField name="work_company_name" type="string">
  Company name
</ResponseField>

<ResponseField name="work_company_linkedin_url" type="string">
  Company LinkedIn URL
</ResponseField>

<ResponseField name="work_company_website" type="string">
  Company website
</ResponseField>

<ResponseField name="work_company_industry" type="string">
  Company industry
</ResponseField>

<ResponseField name="work_company_naics_code" type="string">
  NAICS industry classification code
</ResponseField>

<ResponseField name="work_company_naics_description" type="string">
  NAICS industry description
</ResponseField>

<ResponseField name="work_company_sic_code" type="string">
  SIC industry code
</ResponseField>

<ResponseField name="work_company_sic_description" type="string">
  SIC industry description
</ResponseField>

<ResponseField name="work_title" type="string">
  Job title
</ResponseField>

<ResponseField name="standard_work_title" type="string">
  Standardized job title
</ResponseField>

<ResponseField name="work_seniority_level" type="string">
  Seniority level (e.g., "Senior", "Manager", "Executive")
</ResponseField>

<ResponseField name="work_department" type="string">
  Department
</ResponseField>

<ResponseField name="work_employment_type" type="string">
  Employment type (e.g., "Full-time", "Part-time")
</ResponseField>

<ResponseField name="work_status" type="string">
  Employment status (e.g., "Current", "Past")
</ResponseField>

<ResponseField name="work_start_date" type="string">
  Start date
</ResponseField>

<ResponseField name="work_end_date" type="string">
  End date (null if current)
</ResponseField>

<ResponseField name="work_city" type="string">
  Work location city
</ResponseField>

<ResponseField name="work_state" type="string">
  Work location state
</ResponseField>

<ResponseField name="work_country" type="string">
  Work location country
</ResponseField>

#### Result Object - Education

<ResponseField name="education_experience" type="array">
  Array of education records
</ResponseField>

##### Education Object

<ResponseField name="experience_rank" type="integer">
  Rank (1 = most recent)
</ResponseField>

<ResponseField name="minerva_experience_id" type="string">
  Unique experience identifier
</ResponseField>

<ResponseField name="institution_name" type="string">
  School/university name
</ResponseField>

<ResponseField name="institution_linkedin_url" type="string">
  Institution LinkedIn URL
</ResponseField>

<ResponseField name="education_information" type="string">
  Additional education details
</ResponseField>

<ResponseField name="education_level" type="string">
  Degree level (e.g., "Bachelor's", "Master's", "PhD")
</ResponseField>

<ResponseField name="education_majors" type="array">
  Array of major fields of study
</ResponseField>

<ResponseField name="education_minors" type="array">
  Array of minor fields of study
</ResponseField>

<ResponseField name="education_start_date" type="string">
  Start date
</ResponseField>

<ResponseField name="education_end_date" type="string">
  Graduation date
</ResponseField>

<Note>
  Error responses include `statusCode` and `body` fields for backward compatibility with existing integrations. These are deprecated — prefer the HTTP status code and the top-level `code` / `message` / `api_request_id` fields directly. (The deprecated nested `body` still carries the legacy `error_message`.)
</Note>

<ResponseExample>
  ```json 200 theme={null}
  {
    "api_request_id": "7916d5a4-f0d0-4f20-8153-83eeb458817a",
    "request_completed_at": "2024-11-12T15:29:05.828776+00:00",
    "results": [
      {
        "record_id": "user_001",
        "is_match": true,
        "minerva_pid": "p-a1b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6",
        "match_score": 110.0,
        "validation_errors": null,
        "personal_information": {
          "full_name": "JOHN M SMITH",
          "first_name": "JOHN",
          "middle_name": "M",
          "last_name": "SMITH",
          "name_suffix": null,
          "gender": "M",
          "dob": "1990-01-01",
          "age": 34,
          "marital_status": "M"
        },
        "household_information": {
          "minerva_household_id": "h-a1b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6",
          "minerva_spouse_pid": null,
          "number_of_children": 0
        },
        "financial_information": {
          "is_retired": false,
          "estimated_income_range": "$101K - $250K",
          "estimated_wealth_range": "$1M-$2M",
          "home_ownership_status": null,
          "has_bankruptcy_records": false,
          "has_judgment_records": false
        },
        "social_media": {
          "linkedin_url": "https://www.linkedin.com/in/example-profile",
          "linkedin_title": "Senior Software Engineer | Tech Enthusiast",
          "linkedin_industry": null,
          "is_likely_remote_worker": false,
          "facebook_url": null,
          "twitter_url": null
        },
        "personal_emails": [
          {
            "email_rank": 1,
            "email_address": "john.smith@gmail.com"
          },
          {
            "email_rank": 2,
            "email_address": "jsmith@example.com"
          }
        ],
        "professional_emails": [],
        "phones": [
          {
            "phone_rank": 1,
            "phone_type": "Mobile",
            "phone_number": "(555) 123-4567"
          },
          {
            "phone_rank": 2,
            "phone_type": "Mobile",
            "phone_number": "(555) 987-6543"
          }
        ],
        "relatives": [
          {
            "relative_minerva_pid": "p-b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6e7",
            "relative_first_name": "ROBERT",
            "relative_last_name": "SMITH",
            "relationship_label": "child-parent",
            "relationship_sublabel": "son-father"
          },
          {
            "relative_minerva_pid": "p-c3d4e5f6a7b8c9d0e1f2a3b4c5d6e7f8",
            "relative_first_name": "MARY",
            "relative_last_name": "SMITH",
            "relationship_label": "child-parent",
            "relationship_sublabel": null
          }
        ],
        "address_history": [
          {
            "address_rank": 1,
            "minerva_address_id": "a-a1b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6",
            "address_line_1": "123 MAIN ST",
            "address_line_2": null,
            "address_city": "SAN FRANCISCO",
            "address_state": "CA",
            "address_zipcode": "94102",
            "address_zipcode4": "1234",
            "ownership_status": "Unknown",
            "is_current_owner": null,
            "purchase_date": null,
            "purchase_price": null,
            "estimated_current_value": null,
            "estimated_rental_value": null,
            "home_current_tax_liability": null,
            "outstanding_loan_principal": null,
            "current_property_equity_amount": null,
            "sqft": null,
            "num_beds": null,
            "num_baths": null,
            "first_seen_date": "2023-10-31",
            "last_seen_date": "2025-09-04"
          },
          {
            "address_rank": 2,
            "minerva_address_id": "a-b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6e7",
            "address_line_1": "456 OAK AVE",
            "address_line_2": "APT 2B",
            "address_city": "PALO ALTO",
            "address_state": "CA",
            "address_zipcode": "94301",
            "address_zipcode4": "1111",
            "ownership_status": "Rented",
            "is_current_owner": null,
            "purchase_date": null,
            "purchase_price": null,
            "estimated_current_value": 1020000.0,
            "estimated_rental_value": 6221.0,
            "home_current_tax_liability": null,
            "outstanding_loan_principal": null,
            "current_property_equity_amount": null,
            "sqft": 2789.0,
            "num_beds": 4.0,
            "num_baths": 4.0,
            "first_seen_date": "2018-08-01",
            "last_seen_date": "2023-09-30"
          }
        ],
        "work_experience": [
          {
            "experience_rank": 1,
            "minerva_experience_id": "w-a1b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6",
            "work_company_name": "Tech Solutions Inc",
            "work_company_linkedin_url": "https://www.linkedin.com/company/example-company",
            "work_company_website": "https://example.com",
            "work_company_industry": "Computer Software",
            "work_company_naics_code": "511210",
            "work_company_naics_description": "Software Publishers",
            "work_company_sic_code": "7372",
            "work_company_sic_description": "Prepackaged Software",
            "work_title": "Senior Software Engineer",
            "standard_work_title": "Software Engineer",
            "work_seniority_level": "Senior",
            "work_department": "Engineering",
            "work_employment_type": "Full-Time",
            "work_status": "current",
            "work_start_date": "2023-05-01",
            "work_end_date": null,
            "work_city": "San Francisco",
            "work_state": "CA",
            "work_country": "US"
          },
          {
            "experience_rank": 2,
            "minerva_experience_id": "w-b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6e7",
            "work_company_name": "Financial Services Corp",
            "work_company_linkedin_url": "https://www.linkedin.com/company/example-finance",
            "work_company_website": "https://example-finance.com",
            "work_company_industry": "Investment Management",
            "work_company_naics_code": "523930",
            "work_company_naics_description": "Investment Advice",
            "work_company_sic_code": "6282",
            "work_company_sic_description": "Investment Advice",
            "work_title": "Software Developer",
            "standard_work_title": "Software Developer",
            "work_seniority_level": "Entry",
            "work_department": "Technology",
            "work_employment_type": "Full-Time",
            "work_status": "previous",
            "work_start_date": "2017-08-01",
            "work_end_date": "2023-04-30",
            "work_city": "New York",
            "work_state": "NY",
            "work_country": "US"
          }
        ],
        "education_experience": [
          {
            "experience_rank": 1,
            "minerva_experience_id": "e-a1b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6",
            "institution_name": "State University",
            "institution_linkedin_url": "https://www.linkedin.com/school/example-university",
            "education_information": "Bachelor of Science (B.S.), Computer Science",
            "education_level": "Bachelors",
            "education_majors": ["Computer Science"],
            "education_minors": [],
            "education_start_date": "2013-08-15",
            "education_end_date": "2017-05-31"
          }
        ]
      }
    ]
  }
  ```

  ```json 400 theme={null}
  {
    "code": "bad_request",
    "message": "Input data must contain a 'records' key with a list of inputs",
    "api_request_id": "8931445e-91f1-42c6-a53d-7381de862dc8"
  }
  ```

  ```json 401 theme={null}
  {
    "code": "unauthorized",
    "message": "Unauthorized",
    "api_request_id": "c1d2e3f4-a5b6-7890-cdef-1234567890ab"
  }
  ```

  ```json 402 theme={null}
  {
    "code": "insufficient_credits",
    "message": "Insufficient records budget — please purchase more credits",
    "api_request_id": "d4e5f6a7-b8c9-0123-def4-567890abcdef",
    "details": {
      "records_remaining": 23,
      "records_requested": 100
    }
  }
  ```

  ```json 413 theme={null}
  {
    "code": "payload_too_large",
    "message": "Maximum number of records for /v2/enrich endpoint is 500",
    "api_request_id": "e5f6a7b8-c9d0-1234-ef56-7890abcdef01"
  }
  ```

  ```json 422 theme={null}
  {
    "code": "unprocessable_entity",
    "message": "Invalid match_condition_fields: ['invalid_field']. Valid options are: linkedin_url, gender, estimated_income_range, estimated_wealth_range, emails, personal_email, professional_email, phone, mobile_phone, home_ownership_status",
    "api_request_id": "f6a7b8c9-d0e1-2345-f678-90abcdef0123"
  }
  ```
</ResponseExample>

### Alternative Response Example (With `return_fields`)

When using `return_fields: ["full_name", "linkedin_url", "personal_emails"]`, only the requested fields are returned alongside the base fields:

```json theme={null}
{
  "api_request_id": "req_xyz789",
  "results": [
    {
      "record_id": "user_003",
      "is_match": true,
      "minerva_pid": "p-a1b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6",
      "match_score": 95.0,
      "validation_errors": null,
      "personal_information": {
        "full_name": "Jane Doe"
      },
      "social_media": {
        "linkedin_url": "https://www.linkedin.com/in/janedoe"
      },
      "personal_emails": [
        {
          "email_rank": 1,
          "email_address": "jane.doe@gmail.com"
        }
      ]
    }
  ],
  "request_completed_at": "2024-01-15T10:30:45.123456Z"
}
```

## Error Responses

* `400` - Bad Request: Missing required fields or malformed JSON
* `401` - Unauthorized: Invalid or missing API key
* `402` - Payment Required: Minerva credits exhausted. Response body includes `records_remaining` (estimated records remaining based on your credit balance) and `records_requested` (batch size that was rejected)
* `413` - Payload Too Large: More than 500 records in request
* `422` - Unprocessable Entity: Validation errors in record data, invalid `match_condition_fields`, or invalid `return_fields`
* `429` - Too Many Requests: Rate limit exceeded
* `500` - Internal Server Error: Unexpected server error

## Notes

### Lookup Modes

V2 Enrich supports three distinct lookup modes that can be mixed in a single request:

#### 1. Direct Minerva PID Lookup (Fastest)

* Provide `minerva_pid` field (format: `p-` + 32 hex characters)
* When provided, `minerva_pid` takes precedence over all other fields
* Name and contact information are optional but will be validated if provided
* Instant lookup with no fuzzy matching required
* Invalid PIDs will return validation errors

#### 2. LinkedIn URL Lookup (Fast)

* Provide `linkedin_url` field (full URL or username)
* Only used if `minerva_pid` is not provided
* Name and contact information are optional but will be validated if provided
* Direct lookup in LinkedIn mapping database
* Supports both full URLs (`https://www.linkedin.com/in/username`) and usernames (`username`)

#### 3. Fuzzy Matching (Standard)

* Provide name and/or contact information
* Uses advanced matching algorithm to find best match
* Requires either name OR contact information (or both)
* If providing name, must include both `first_name` and `last_name` (or `full_name`)
* Returns match scores based on confidence

### Input Requirements

**For Direct PID Lookup:**

* `record_id` (required)
* `minerva_pid` (required for this mode)
* All other fields optional (but validated if provided)

**For LinkedIn Lookup:**

* `record_id` (required)
* `linkedin_url` (required for this mode)
* No `minerva_pid` provided
* All other fields optional (but validated if provided)

**For Fuzzy Matching:**

* `record_id` (required)
* Name: Provide (`first_name` AND `last_name`) OR `full_name`
* Contact: Provide at least one `emails` or `phones`
* Must provide either name OR contact info (or both for better accuracy)

### Performance Optimization

* **Use `return_fields`** to request only needed data - significantly reduces response size and improves latency
* **Direct PID lookups** (`minerva_pid`) are fastest - use when you have previously resolved a person
* **LinkedIn URL lookups** provide quick resolution when you have LinkedIn profiles
* **Fuzzy matching** is comprehensive but slower - use when you need identity resolution
* Maximum 500 records per request (lower than `/v2/resolve` due to enriched data volume)
* Mix lookup modes in a single request for optimal performance

### Match Condition Fields

* `match_condition_fields` filters results to only return matches that have the specified fields populated
* Helps maintain data quality requirements by ensuring minimum data availability
* Maximum 3 fields can be specified
* Available condition fields: `linkedin_url`, `gender`, `estimated_income_range`, `estimated_wealth_range`, `email`, `personal_email`, `professional_email`, `phone`, `mobile_phone`, `home_ownership_status`
* Example: `["email", "linkedin_url"]` will only return matches that have both an email and LinkedIn profile

### Data Availability

* All list fields (emails, phones, addresses, work, education, relatives) return empty arrays `[]` if no data is available
* Dates are returned in ISO 8601 format (YYYY-MM-DD)
* Financial figures are in USD
* Arrays are ordered by rank, with rank=1 being the most recent/relevant
* The `relatives` field is included in full responses but is not available as an explicit `return_fields` option
* Related fields are grouped into nested objects: `personal_information`, `household_information`, `financial_information`, and `social_media`
* When using `return_fields`, only requested fields are included within their respective nested objects

### Validation

* `minerva_pid` must be in format: `p-` followed by exactly 32 hexadecimal characters
* `linkedin_url` accepts full URLs or just the username portion
* Phone numbers must be valid US phone numbers
* Email addresses must be valid email format
* Names must have at least first and last name components
* Records with validation errors will have `validation_errors` populated and may have `is_match: false`

### New Features in V2

* **Direct Lookups**: `minerva_pid` and `linkedin_url` as input fields for instant enrichment
* **Structured Response**: Fields are organized into logical nested objects (`personal_information`, `household_information`, `financial_information`, `social_media`)
* **`relatives`** field provides family relationship data with linked Minerva PIDs
* **`return_fields`** allows precise control over response payload for cost optimization
* **Flexible input requirements**: Name is optional when using direct lookups

## Migration from V1

If you're upgrading from V1:

1. **URL Change**: `/v1/enrich` → `/v2/enrich`
2. **Response Structure Change**: Fields are now organized into nested objects:
   * `personal_information`: Contains name, gender, DOB, age, marital status
   * `household_information`: Contains household ID, spouse PID, number of children
   * `financial_information`: Contains income/wealth estimates, home ownership, bankruptcy/judgment records
   * `social_media`: Contains LinkedIn, Facebook, Twitter URLs and professional details
   * Array fields (`address_history`, `work_experience`, `education_experience`, `personal_emails`, `professional_emails`, `phones`, `relatives`) remain at the top level
3. **New Direct Lookup Options**:
   * Add `minerva_pid` to your input records if you have previously resolved persons
   * Add `linkedin_url` if you have LinkedIn profiles
   * These provide instant enrichment without fuzzy matching
4. **Performance Optimization**: Use `return_fields` to request only needed data
   * Reduces response payload size significantly
   * Lowers latency and data transfer costs
   * Base fields always returned: `record_id`, `is_match`, `minerva_pid`, `match_score`, `validation_errors`
   * Requested fields are returned within their respective nested objects
5. **Data Quality Control**: Use `match_condition_fields` to ensure matches have required data
6. **New Data**: `relatives` field now provides family relationship information
7. **Flexible Input**: Name is no longer required when using direct PID or LinkedIn lookups
8. **Same Record Limit**: Maximum 500 records per request (unchanged from V1)

### Key Differences from `/v2/resolve`

* **`/v2/enrich`** accepts `minerva_pid` and `linkedin_url` as INPUT fields for direct lookups
* **`/v2/resolve`** does NOT accept these fields as inputs (uses reverse lookup instead via single email/phone)
* **`/v2/enrich`** requires `record_id` to be provided
* **`/v2/resolve`** has optional `record_id`
* **`/v2/enrich`** returns comprehensive enrichment data
* **`/v2/resolve`** only returns match information and LinkedIn URL