Skip to main content
POST
/
v2
/
enrich
Enrich v2
curl --request POST \
  --url https://api.minerva.io/v2/enrich \
  --header 'Content-Type: <content-type>' \
  --header 'x-api-key: <api-key>' \
  --data '{
  "records": [
    {
      "record_id": "<string>",
      "minerva_pid": "<string>",
      "linkedin_url": "<string>",
      "first_name": "<string>",
      "middle_name": "<string>",
      "last_name": "<string>",
      "full_name": "<string>",
      "name_suffix": "<string>",
      "emails": [
        "<string>"
      ],
      "phones": [
        "<string>"
      ]
    }
  ],
  "match_condition_fields": [
    "<string>"
  ],
  "return_fields": [
    "<string>"
  ]
}'
{
  "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"
        }
      ]
    }
  ]
}

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.

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

x-api-key
string
required
Your API key for authentication
Content-Type
string
required
application/json

Request Body

records
object[]
required
An array of person records to enrich. Maximum 500 records per request.
match_condition_fields
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_statusExample: ["email"] or ["phone", "linkedin_url"]
return_fields
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_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

{
  "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

{
  "records": [
    {
      "record_id": "user_002",
      "minerva_pid": "p-a1b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6"
    }
  ]
}

Direct LinkedIn URL Lookup

{
  "records": [
    {
      "record_id": "user_003",
      "linkedin_url": "https://www.linkedin.com/in/janedoe"
    }
  ]
}

Mixed Lookup Types in One Request

{
  "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

api_request_id
string
Unique identifier for this API request
results
array
Array of enrichment results
request_completed_at
string
ISO 8601 timestamp when the request was completed

Result Object - Base Fields (Always Returned)

record_id
string
Your identifier from the request
is_match
boolean
Whether a match was found
minerva_pid
string
Minerva person identifier
match_score
number
Confidence score for the match (0-1 scale)
validation_errors
object
Any validation errors from the input

Result Object - Personal Information

personal_information
object
Object containing personal demographic details

Result Object - Household Information

household_information
object
Object containing household and family details

Result Object - Financial Information

financial_information
object
Object containing financial and legal record details

Result Object - Social Media

social_media
object
Object containing social media profiles and professional information

Result Object - Contact Information

personal_emails
array
Array of personal email addresses with ranking
professional_emails
array
Array of professional email addresses with ranking
phones
array
Array of phone numbers with type and ranking
Email Object
email_rank
integer
Rank/priority of this email (1 = highest priority)
email_address
string
Email address
Phone Object
phone_rank
integer
Rank/priority of this phone (1 = highest priority)
phone_type
string
Phone type (e.g., “Mobile”, “Landline”)
phone_number
string
Phone number

Result Object - Family Relationships (New in V2)

relatives
array
New in V2: Array of family relationships
Relative Object
relative_minerva_pid
string
Minerva PID of the relative
relative_first_name
string
Relative’s first name
relative_last_name
string
Relative’s last name
relationship_label
string
Type of relationship (e.g., “Parent”, “Child”, “Sibling”)
relationship_sublabel
string
Additional relationship details

Result Object - Address History

address_history
array
Array of address records with property details
Address Object
address_rank
integer
Rank of address (1 = most recent/current)
minerva_address_id
string
Unique address identifier
address_line_1
string
Street address
address_line_2
string
Apartment/unit number
address_city
string
City
address_state
string
State
address_zipcode
string
ZIP code
address_zipcode4
string
ZIP+4 extension
ownership_status
string
Ownership status (“Owned” / “Rented”)
is_current_owner
boolean
Whether person currently owns this property (TRUE / FALSE)
purchase_date
string
Date property was purchased
purchase_price
number
Purchase price in USD
estimated_current_value
number
Current estimated value in USD
estimated_rental_value
number
Estimated monthly rental value in USD
home_current_tax_liability
number
Annual property tax in USD
outstanding_loan_principal
number
Outstanding mortgage balance in USD
current_property_equity_amount
number
Estimated equity in USD
sqft
number
Square footage
num_beds
number
Number of bedrooms
num_baths
number
Number of bathrooms
first_seen_date
string
First date person was associated with this address
last_seen_date
string
Last date person was associated with this address

Result Object - Work Experience

work_experience
array
Array of work history records
Work Experience Object
experience_rank
integer
Rank (1 = most recent)
minerva_experience_id
string
Unique experience identifier
work_company_name
string
Company name
work_company_linkedin_url
string
Company LinkedIn URL
work_company_website
string
Company website
work_company_industry
string
Company industry
work_company_naics_code
string
NAICS industry classification code
work_company_naics_description
string
NAICS industry description
work_company_sic_code
string
SIC industry code
work_company_sic_description
string
SIC industry description
work_title
string
Job title
standard_work_title
string
Standardized job title
work_seniority_level
string
Seniority level (e.g., “Senior”, “Manager”, “Executive”)
work_department
string
Department
work_employment_type
string
Employment type (e.g., “Full-time”, “Part-time”)
work_status
string
Employment status (e.g., “Current”, “Past”)
work_start_date
string
Start date
work_end_date
string
End date (null if current)
work_city
string
Work location city
work_state
string
Work location state
work_country
string
Work location country

Result Object - Education

education_experience
array
Array of education records
Education Object
experience_rank
integer
Rank (1 = most recent)
minerva_experience_id
string
Unique experience identifier
institution_name
string
School/university name
institution_linkedin_url
string
Institution LinkedIn URL
education_information
string
Additional education details
education_level
string
Degree level (e.g., “Bachelor’s”, “Master’s”, “PhD”)
education_majors
array
Array of major fields of study
education_minors
array
Array of minor fields of study
education_start_date
string
Start date
education_end_date
string
Graduation date
{
  "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"
        }
      ]
    }
  ]
}

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:
{
  "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
  • 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
  • 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