Data Dictionary

The headings below group fields by topic for readability only. In the response every one of them is a top-level key of the result object — the payload is flat. There are no personal_information, household_information, financial_information, or social_media wrapper objects.

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, as an additive point total — not a 0-1 or 0-100 scale. Fuzzy matches score at least 50 and often above 100; direct lookups return fixed values or `null`. See Interpreting `match_score`
`validation_errors`	object	Any validation errors from the input (null if none)

Personal Information

Returned at the top level of each result 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

Returned at the top level of each result 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

Returned at the top level of each result 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`

Returned at the top level of each result 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
`linkedin_profile_pic_url`	string	LinkedIn profile picture URL
`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"`

The relatives array is included when returning all fields, and can also be requested explicitly via return_fields.

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

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

Empty Arrays

All list fields (emails, phones, addresses, work, education, relatives) return empty arrays [] if no data is available.

Date Format

All dates are returned in ISO 8601 format: YYYY-MM-DD

Currency

All financial figures (property values, prices, etc.) are in USD.

Ranking

Arrays are ordered by rank field, with rank=1 being the most recent or most reliable.

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, linkedin_profile_pic_url, 
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, relatives

Each name is a top-level key of the result object, and selected fields are returned at the top level — return_fields never introduces wrapper objects.

Using return_fields reduces response size and improves API latency. Request only the data you need!

Getting Started

Core Endpoints

Validation Workflows

Person Search

Usage

Storage

Segments

Base Fields

Personal Information

Household Information

Financial Information

Contact Information

Personal Emails

Professional Emails

Phone Numbers

Family Relationships

Address History

Core Address Fields

Ownership & Residency

Property Details

Work Experience

Position Identification

Company Information

Industry Codes

Role Details

Dates & Location

Education Experience

Notes

Empty Arrays

Date Format

Currency

Ranking

Using return_fields

​Base Fields

​Personal Information

​Household Information

​Financial Information

​Social Media

​Contact Information

​Personal Emails

​Professional Emails

​Phone Numbers

​Family Relationships

​Address History

​Core Address Fields

​Ownership & Residency

​Property Details

​Work Experience

​Position Identification

​Company Information

​Industry Codes

​Role Details

​Dates & Location

​Education Experience

​Notes

Empty Arrays

Date Format

Currency

Ranking

​Using return_fields

Base Fields

Personal Information

Household Information

Financial Information

Social Media

Contact Information

Personal Emails

Professional Emails

Phone Numbers

Family Relationships

Address History

Core Address Fields

Ownership & Residency

Property Details

Work Experience

Position Identification

Company Information

Industry Codes

Role Details

Dates & Location

Education Experience

Notes

Using return_fields