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

# Data Dictionary

> Complete reference of all fields returned by the Minerva Enrich v2 API

## Base Fields

These fields are always returned in every response, regardless of `return_fields` settings.

| Field               | Type    | Description                                                         |
| ------------------- | ------- | ------------------------------------------------------------------- |
| `record_id`         | string  | Your unique identifier from the request                             |
| `is_match`          | boolean | Whether a match was found for this record                           |
| `minerva_pid`       | string  | Minerva person identifier (format: `p-` + 32 hex characters)        |
| `match_score`       | number  | Confidence score for the match (0-1 scale, higher = more confident) |
| `validation_errors` | object  | Any validation errors from the input (null if none)                 |

***

## Personal Information

Contained within the `personal_information` object.

| Field            | Type    | Description            | Example Values                             |
| ---------------- | ------- | ---------------------- | ------------------------------------------ |
| `full_name`      | string  | Person's complete name | `"JOHN M SMITH"`                           |
| `first_name`     | string  | First name             | `"JOHN"`                                   |
| `middle_name`    | string  | Middle name or initial | `"M"`                                      |
| `last_name`      | string  | Last name / surname    | `"SMITH"`                                  |
| `name_suffix`    | string  | Name suffix            | `"Jr."`, `"Sr."`, `"III"`                  |
| `gender`         | string  | Gender                 | `"M"`, `"F"`, or `null`                    |
| `dob`            | string  | Date of birth          | `"1990-01-15"` (YYYY-MM-DD)                |
| `age`            | integer | Current calculated age | `34`                                       |
| `marital_status` | string  | Marital status         | `"M"` (married), `"S"` (single), or `null` |

***

## Household Information

Contained within the `household_information` object.

| Field                  | Type    | Description                         |
| ---------------------- | ------- | ----------------------------------- |
| `minerva_household_id` | string  | Unique household identifier         |
| `minerva_spouse_pid`   | string  | Spouse's Minerva PID (if available) |
| `number_of_children`   | integer | Number of children in household     |

***

## Financial Information

Contained within the `financial_information` object.

| Field                    | Type    | Description                          | Example Values                   |
| ------------------------ | ------- | ------------------------------------ | -------------------------------- |
| `is_retired`             | boolean | Whether the person is retired        | `true`, `false`                  |
| `estimated_income_range` | string  | Estimated annual income bracket      | `"$101K - $250K"`                |
| `estimated_wealth_range` | string  | Estimated total wealth bracket       | `"$1M-$2M"`                      |
| `home_ownership_status`  | string  | Home ownership status                | `"Owner"`, `"Renter"`, or `null` |
| `has_bankruptcy_records` | boolean | Whether bankruptcy records exist     | `true`, `false`                  |
| `has_judgment_records`   | boolean | Whether court judgment records exist | `true`, `false`                  |

***

## Social Media

Contained within the `social_media` object.

| Field                     | Type    | Description                              |
| ------------------------- | ------- | ---------------------------------------- |
| `linkedin_url`            | string  | LinkedIn profile URL                     |
| `linkedin_title`          | string  | Current title from LinkedIn profile      |
| `linkedin_industry`       | string  | Industry listed on LinkedIn              |
| `is_likely_remote_worker` | boolean | Whether the person likely works remotely |
| `facebook_url`            | string  | Facebook profile URL                     |
| `twitter_url`             | string  | Twitter/X profile URL                    |

***

## Contact Information

### Personal Emails

Array of personal email addresses. Each email object contains:

| Field           | Type    | Description                                             |
| --------------- | ------- | ------------------------------------------------------- |
| `email_rank`    | integer | Priority ranking (1 = highest priority / most reliable) |
| `email_address` | string  | The email address                                       |

### Professional Emails

Array of work/professional email addresses. Each email object contains:

| Field           | Type    | Description                                             |
| --------------- | ------- | ------------------------------------------------------- |
| `email_rank`    | integer | Priority ranking (1 = highest priority / most reliable) |
| `email_address` | string  | The email address                                       |

### Phone Numbers

Array of phone numbers. Each phone object contains:

| Field          | Type    | Description                             | Example Values           |
| -------------- | ------- | --------------------------------------- | ------------------------ |
| `phone_rank`   | integer | Priority ranking (1 = highest priority) | `1`, `2`, `3`            |
| `phone_type`   | string  | Type of phone line                      | `"Mobile"`, `"Landline"` |
| `phone_number` | string  | Formatted phone number                  | `"(555) 123-4567"`       |

***

## Family Relationships

The `relatives` array contains family relationship information. Each relative object contains:

| Field                   | Type   | Description                     | Example Values                            |
| ----------------------- | ------ | ------------------------------- | ----------------------------------------- |
| `relative_minerva_pid`  | string | Minerva PID of the relative     | `"p-b2c3d4..."`                           |
| `relative_first_name`   | string | Relative's first name           | `"ROBERT"`                                |
| `relative_last_name`    | string | Relative's last name            | `"SMITH"`                                 |
| `relationship_label`    | string | Type of relationship            | `"child-parent"`, `"sibling"`, `"spouse"` |
| `relationship_sublabel` | string | Additional relationship details | `"son-father"`, `"brother-sister"`        |

<Note>
  The `relatives` field is automatically included when returning all fields, but cannot be explicitly requested via the `return_fields` parameter.
</Note>

***

## Address History

Array of address records ordered by recency. Each address object contains:

### Core Address Fields

| Field                | Type    | Description                                      |
| -------------------- | ------- | ------------------------------------------------ |
| `address_rank`       | integer | Recency rank (1 = most recent / current address) |
| `minerva_address_id` | string  | Unique address identifier                        |
| `address_line_1`     | string  | Street address                                   |
| `address_line_2`     | string  | Apartment, suite, or unit number                 |
| `address_city`       | string  | City name                                        |
| `address_state`      | string  | State abbreviation                               |
| `address_zipcode`    | string  | 5-digit ZIP code                                 |
| `address_zipcode4`   | string  | ZIP+4 extension                                  |

### Ownership & Residency

| Field              | Type    | Description                                   | Example Values                     |
| ------------------ | ------- | --------------------------------------------- | ---------------------------------- |
| `ownership_status` | string  | Whether property is owned or rented           | `"Owned"`, `"Rented"`, `"Unknown"` |
| `is_current_owner` | boolean | Whether person currently owns this property   | `true`, `false`                    |
| `first_seen_date`  | string  | First date person was associated with address | `"2018-08-01"`                     |
| `last_seen_date`   | string  | Last date person was associated with address  | `"2023-09-30"`                     |

### Property Details

| Field                            | Type   | Description                    | Units      |
| -------------------------------- | ------ | ------------------------------ | ---------- |
| `purchase_date`                  | string | Date property was purchased    | YYYY-MM-DD |
| `purchase_price`                 | number | Original purchase price        | USD        |
| `estimated_current_value`        | number | Current estimated market value | USD        |
| `estimated_rental_value`         | number | Estimated monthly rental value | USD        |
| `home_current_tax_liability`     | number | Annual property tax            | USD        |
| `outstanding_loan_principal`     | number | Outstanding mortgage balance   | USD        |
| `current_property_equity_amount` | number | Estimated equity in property   | USD        |
| `sqft`                           | number | Square footage of property     | sq ft      |
| `num_beds`                       | number | Number of bedrooms             | count      |
| `num_baths`                      | number | Number of bathrooms            | count      |

***

## Work Experience

Array of employment history records ordered by recency. Each work experience object contains:

### Position Identification

| Field                   | Type    | Description                                       |
| ----------------------- | ------- | ------------------------------------------------- |
| `experience_rank`       | integer | Recency rank (1 = most recent / current position) |
| `minerva_experience_id` | string  | Unique experience identifier                      |

### Company Information

| Field                       | Type   | Description                       |
| --------------------------- | ------ | --------------------------------- |
| `work_company_name`         | string | Company name                      |
| `work_company_linkedin_url` | string | Company's LinkedIn page URL       |
| `work_company_website`      | string | Company's website URL             |
| `work_company_industry`     | string | Company's industry classification |

### Industry Codes

| Field                            | Type   | Description                        |
| -------------------------------- | ------ | ---------------------------------- |
| `work_company_naics_code`        | string | NAICS industry classification code |
| `work_company_naics_description` | string | NAICS industry description         |
| `work_company_sic_code`          | string | SIC industry classification code   |
| `work_company_sic_description`   | string | SIC industry description           |

### Role Details

| Field                  | Type   | Description                       | Example Values                                    |
| ---------------------- | ------ | --------------------------------- | ------------------------------------------------- |
| `work_title`           | string | Job title as listed               | `"Senior Software Engineer"`                      |
| `standard_work_title`  | string | Standardized/normalized job title | `"Software Engineer"`                             |
| `work_seniority_level` | string | Seniority level                   | `"Entry"`, `"Senior"`, `"Manager"`, `"Executive"` |
| `work_department`      | string | Department within company         | `"Engineering"`, `"Sales"`, `"Marketing"`         |
| `work_employment_type` | string | Type of employment                | `"Full-Time"`, `"Part-Time"`, `"Contract"`        |
| `work_status`          | string | Current or past position          | `"current"`, `"previous"`                         |

### Dates & Location

| Field             | Type   | Description                           |
| ----------------- | ------ | ------------------------------------- |
| `work_start_date` | string | Employment start date (YYYY-MM-DD)    |
| `work_end_date`   | string | Employment end date (null if current) |
| `work_city`       | string | Work location city                    |
| `work_state`      | string | Work location state                   |
| `work_country`    | string | Work location country code            |

***

## Education Experience

Array of education records ordered by recency. Each education object contains:

| Field                      | Type    | Description                     | Example Values                                       |
| -------------------------- | ------- | ------------------------------- | ---------------------------------------------------- |
| `experience_rank`          | integer | Recency rank (1 = most recent)  | `1`, `2`                                             |
| `minerva_experience_id`    | string  | Unique experience identifier    | `"e-a1b2c3..."`                                      |
| `institution_name`         | string  | School/university name          | `"Stanford University"`                              |
| `institution_linkedin_url` | string  | Institution's LinkedIn page URL |                                                      |
| `education_information`    | string  | Additional education details    | `"Bachelor of Science (B.S.), Computer Science"`     |
| `education_level`          | string  | Degree level attained           | `"High School"`, `"Bachelors"`, `"Masters"`, `"PhD"` |
| `education_majors`         | array   | Array of major fields of study  | `["Computer Science", "Mathematics"]`                |
| `education_minors`         | array   | Array of minor fields of study  | `["Business"]`                                       |
| `education_start_date`     | string  | Enrollment start date           | `"2013-08-15"`                                       |
| `education_end_date`       | string  | Graduation/completion date      | `"2017-05-31"`                                       |

***

## Notes

<CardGroup cols={2}>
  <Card title="Empty Arrays" icon="brackets-square">
    All list fields (emails, phones, addresses, work, education, relatives) return empty arrays `[]` if no data is available.
  </Card>

  <Card title="Date Format" icon="calendar">
    All dates are returned in ISO 8601 format: `YYYY-MM-DD`
  </Card>

  <Card title="Currency" icon="dollar-sign">
    All financial figures (property values, prices, etc.) are in USD.
  </Card>

  <Card title="Ranking" icon="ranking-star">
    Arrays are ordered by rank field, with rank=1 being the most recent or most reliable.
  </Card>
</CardGroup>

## Using return\_fields

You can optimize your API response by specifying only the fields you need using the `return_fields` parameter. Base fields are always included.

**Available return\_fields options:**

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

<Tip>
  Using `return_fields` reduces response size and improves API latency. Request only the data you need!
</Tip>