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_pidorlinkedin_urlfor instant results without fuzzy matching - Match Conditions: Control which fields must be present for a match to be returned
- Selective Returns: Use
return_fieldsto get only the data you need and optimize response size - New Data: Includes
relativesfield 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
Your API key for authentication
application/json
Request Body
An array of person records to enrich. Maximum 500 records per request.
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_statusExample: ["email"] or ["phone", "linkedin_url"]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_errorsAvailable 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, phonesNote: 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"]Request Examples
Standard Fuzzy Matching with Selective Returns
Direct Minerva PID Lookup
Direct LinkedIn URL Lookup
Mixed Lookup Types in One Request
record_id(string, required): Your unique identifier for this recordminerva_pid(string): New in V2 - Direct Minerva Person ID lookup for instant enrichment. Format:p-followed by 32 hexadecimal characterslinkedin_url(string): New in V2 - LinkedIn profile URL or username for direct enrichmentfirst_name(string): Person’s first namemiddle_name(string): Person’s middle namelast_name(string): Person’s last namefull_name(string): Person’s full namename_suffix(string): Name suffix (e.g., “Jr.”, “Sr.”, “III”)emails(array): Array of email addressesphones(array): Array of phone numbers
/v2/enrich accepts minerva_pid and linkedin_url as direct lookup fields, while /v2/resolve does not.
Response
Response Structure
Unique identifier for this API request
Array of enrichment results
ISO 8601 timestamp when the request was completed
Result Object - Base Fields (Always Returned)
Your identifier from the request
Whether a match was found
Minerva person identifier
Confidence score for the match (0-1 scale)
Any validation errors from the input
Result Object - Personal Information
Object containing personal demographic details
Result Object - Household Information
Object containing household and family details
Result Object - Financial Information
Object containing financial and legal record details
Result Object - Social Media
Object containing social media profiles and professional information
Result Object - Contact Information
Array of personal email addresses with ranking
Array of professional email addresses with ranking
Array of phone numbers with type and ranking
Email Object
Rank/priority of this email (1 = highest priority)
Email address
Phone Object
Rank/priority of this phone (1 = highest priority)
Phone type (e.g., “Mobile”, “Landline”)
Phone number
Result Object - Family Relationships (New in V2)
New in V2: Array of family relationships
Relative Object
Minerva PID of the relative
Relative’s first name
Relative’s last name
Type of relationship (e.g., “Parent”, “Child”, “Sibling”)
Additional relationship details
Result Object - Address History
Array of address records with property details
Address Object
Rank of address (1 = most recent/current)
Unique address identifier
Street address
Apartment/unit number
City
State
ZIP code
ZIP+4 extension
Ownership status (“Owned” / “Rented”)
Whether person currently owns this property (TRUE / FALSE)
Date property was purchased
Purchase price in USD
Current estimated value in USD
Estimated monthly rental value in USD
Annual property tax in USD
Outstanding mortgage balance in USD
Estimated equity in USD
Square footage
Number of bedrooms
Number of bathrooms
First date person was associated with this address
Last date person was associated with this address
Result Object - Work Experience
Array of work history records
Work Experience Object
Rank (1 = most recent)
Unique experience identifier
Company name
Company LinkedIn URL
Company website
Company industry
NAICS industry classification code
NAICS industry description
SIC industry code
SIC industry description
Job title
Standardized job title
Seniority level (e.g., “Senior”, “Manager”, “Executive”)
Department
Employment type (e.g., “Full-time”, “Part-time”)
Employment status (e.g., “Current”, “Past”)
Start date
End date (null if current)
Work location city
Work location state
Work location country
Result Object - Education
Array of education records
Education Object
Rank (1 = most recent)
Unique experience identifier
School/university name
Institution LinkedIn URL
Additional education details
Degree level (e.g., “Bachelor’s”, “Master’s”, “PhD”)
Array of major fields of study
Array of minor fields of study
Start date
Graduation date
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:
Error Responses
400- Bad Request: Missing required fields or malformed JSON401- Unauthorized: Invalid or missing API key413- Payload Too Large: More than 500 records in request422- Unprocessable Entity: Validation errors in record data, invalidmatch_condition_fields, or invalidreturn_fields500- 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_pidfield (format:p-+ 32 hex characters) - When provided,
minerva_pidtakes 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_urlfield (full URL or username) - Only used if
minerva_pidis 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_nameandlast_name(orfull_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)
record_id(required)linkedin_url(required for this mode)- No
minerva_pidprovided - All other fields optional (but validated if provided)
record_id(required)- Name: Provide (
first_nameANDlast_name) ORfull_name - Contact: Provide at least one
emailsorphones - Must provide either name OR contact info (or both for better accuracy)
Performance Optimization
- Use
return_fieldsto 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/resolvedue to enriched data volume) - Mix lookup modes in a single request for optimal performance
Match Condition Fields
match_condition_fieldsfilters 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
relativesfield is included in full responses but is not available as an explicitreturn_fieldsoption - Related fields are grouped into nested objects:
personal_information,household_information,financial_information, andsocial_media - When using
return_fields, only requested fields are included within their respective nested objects
Validation
minerva_pidmust be in format:p-followed by exactly 32 hexadecimal characterslinkedin_urlaccepts 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_errorspopulated and may haveis_match: false
New Features in V2
- Direct Lookups:
minerva_pidandlinkedin_urlas input fields for instant enrichment - Structured Response: Fields are organized into logical nested objects (
personal_information,household_information,financial_information,social_media) relativesfield provides family relationship data with linked Minerva PIDsreturn_fieldsallows 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:- URL Change:
/v1/enrich→/v2/enrich - Response Structure Change: Fields are now organized into nested objects:
personal_information: Contains name, gender, DOB, age, marital statushousehold_information: Contains household ID, spouse PID, number of childrenfinancial_information: Contains income/wealth estimates, home ownership, bankruptcy/judgment recordssocial_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
- New Direct Lookup Options:
- Add
minerva_pidto your input records if you have previously resolved persons - Add
linkedin_urlif you have LinkedIn profiles - These provide instant enrichment without fuzzy matching
- Add
- Performance Optimization: Use
return_fieldsto 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
- Data Quality Control: Use
match_condition_fieldsto ensure matches have required data - New Data:
relativesfield now provides family relationship information - Flexible Input: Name is no longer required when using direct PID or LinkedIn lookups
- Same Record Limit: Maximum 500 records per request (unchanged from V1)
Key Differences from /v2/resolve
/v2/enrichacceptsminerva_pidandlinkedin_urlas INPUT fields for direct lookups/v2/resolvedoes NOT accept these fields as inputs (uses reverse lookup instead via single email/phone)/v2/enrichrequiresrecord_idto be provided/v2/resolvehas optionalrecord_id/v2/enrichreturns comprehensive enrichment data/v2/resolveonly returns match information and LinkedIn URL

