Enrich v2 - Minerva Documentation

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>"
      ],
      "full_address": "<string>",
      "address_line_1": "<string>",
      "address_line_2": "<string>",
      "city": "<string>",
      "state": "<string>",
      "zipcode": "<string>"
    }
  ],
  "match_condition_fields": [
    "<string>"
  ],
  "return_fields": [
    "<string>"
  ],
  "include_premium_fields": true
}
'

import requests

url = "https://api.minerva.io/v2/enrich"

payload = {
    "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>"],
            "full_address": "<string>",
            "address_line_1": "<string>",
            "address_line_2": "<string>",
            "city": "<string>",
            "state": "<string>",
            "zipcode": "<string>"
        }
    ],
    "match_condition_fields": ["<string>"],
    "return_fields": ["<string>"],
    "include_premium_fields": True
}
headers = {
    "x-api-key": "<api-key>",
    "Content-Type": "<content-type>"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {'x-api-key': '<api-key>', 'Content-Type': '<content-type>'},
  body: JSON.stringify({
    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>'],
        full_address: '<string>',
        address_line_1: '<string>',
        address_line_2: '<string>',
        city: '<string>',
        state: '<string>',
        zipcode: '<string>'
      }
    ],
    match_condition_fields: ['<string>'],
    return_fields: ['<string>'],
    include_premium_fields: true
  })
};

fetch('https://api.minerva.io/v2/enrich', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.minerva.io/v2/enrich",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    '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>'
                ],
                'full_address' => '<string>',
                'address_line_1' => '<string>',
                'address_line_2' => '<string>',
                'city' => '<string>',
                'state' => '<string>',
                'zipcode' => '<string>'
        ]
    ],
    'match_condition_fields' => [
        '<string>'
    ],
    'return_fields' => [
        '<string>'
    ],
    'include_premium_fields' => true
  ]),
  CURLOPT_HTTPHEADER => [
    "Content-Type: <content-type>",
    "x-api-key: <api-key>"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://api.minerva.io/v2/enrich"

	payload := strings.NewReader("{\n  \"records\": [\n    {\n      \"record_id\": \"<string>\",\n      \"minerva_pid\": \"<string>\",\n      \"linkedin_url\": \"<string>\",\n      \"first_name\": \"<string>\",\n      \"middle_name\": \"<string>\",\n      \"last_name\": \"<string>\",\n      \"full_name\": \"<string>\",\n      \"name_suffix\": \"<string>\",\n      \"emails\": [\n        \"<string>\"\n      ],\n      \"phones\": [\n        \"<string>\"\n      ],\n      \"full_address\": \"<string>\",\n      \"address_line_1\": \"<string>\",\n      \"address_line_2\": \"<string>\",\n      \"city\": \"<string>\",\n      \"state\": \"<string>\",\n      \"zipcode\": \"<string>\"\n    }\n  ],\n  \"match_condition_fields\": [\n    \"<string>\"\n  ],\n  \"return_fields\": [\n    \"<string>\"\n  ],\n  \"include_premium_fields\": true\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("x-api-key", "<api-key>")
	req.Header.Add("Content-Type", "<content-type>")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.post("https://api.minerva.io/v2/enrich")
  .header("x-api-key", "<api-key>")
  .header("Content-Type", "<content-type>")
  .body("{\n  \"records\": [\n    {\n      \"record_id\": \"<string>\",\n      \"minerva_pid\": \"<string>\",\n      \"linkedin_url\": \"<string>\",\n      \"first_name\": \"<string>\",\n      \"middle_name\": \"<string>\",\n      \"last_name\": \"<string>\",\n      \"full_name\": \"<string>\",\n      \"name_suffix\": \"<string>\",\n      \"emails\": [\n        \"<string>\"\n      ],\n      \"phones\": [\n        \"<string>\"\n      ],\n      \"full_address\": \"<string>\",\n      \"address_line_1\": \"<string>\",\n      \"address_line_2\": \"<string>\",\n      \"city\": \"<string>\",\n      \"state\": \"<string>\",\n      \"zipcode\": \"<string>\"\n    }\n  ],\n  \"match_condition_fields\": [\n    \"<string>\"\n  ],\n  \"return_fields\": [\n    \"<string>\"\n  ],\n  \"include_premium_fields\": true\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api.minerva.io/v2/enrich")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["x-api-key"] = '<api-key>'
request["Content-Type"] = '<content-type>'
request.body = "{\n  \"records\": [\n    {\n      \"record_id\": \"<string>\",\n      \"minerva_pid\": \"<string>\",\n      \"linkedin_url\": \"<string>\",\n      \"first_name\": \"<string>\",\n      \"middle_name\": \"<string>\",\n      \"last_name\": \"<string>\",\n      \"full_name\": \"<string>\",\n      \"name_suffix\": \"<string>\",\n      \"emails\": [\n        \"<string>\"\n      ],\n      \"phones\": [\n        \"<string>\"\n      ],\n      \"full_address\": \"<string>\",\n      \"address_line_1\": \"<string>\",\n      \"address_line_2\": \"<string>\",\n      \"city\": \"<string>\",\n      \"state\": \"<string>\",\n      \"zipcode\": \"<string>\"\n    }\n  ],\n  \"match_condition_fields\": [\n    \"<string>\"\n  ],\n  \"return_fields\": [\n    \"<string>\"\n  ],\n  \"include_premium_fields\": true\n}"

response = http.request(request)
puts response.read_body

{
  "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,
      "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",
      "minerva_household_id": "h-a1b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6",
      "minerva_spouse_pid": null,
      "number_of_children": 0,
      "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,
      "linkedin_url": "https://www.linkedin.com/in/example-profile",
      "linkedin_title": "Senior Software Engineer | Tech Enthusiast",
      "linkedin_industry": null,
      "linkedin_profile_pic_url": 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"
        }
      ]
    }
  ]
}

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

{
  "code": "unauthorized",
  "message": "Unauthorized",
  "api_request_id": "c1d2e3f4-a5b6-7890-cdef-1234567890ab"
}

{
  "code": "insufficient_record_capacity",
  "message": "Record export exceeds the available plan allowance and monthly spend limit. Increase the limit or upgrade, then retry.",
  "api_request_id": "d4e5f6a7-b8c9-0123-def4-567890abcdef",
  "details": {
    "records_available": 23,
    "allowance_records_available": 23,
    "overage_records_available": 0,
    "records_requested": 100
  }
}

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

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

POST

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>"
      ],
      "full_address": "<string>",
      "address_line_1": "<string>",
      "address_line_2": "<string>",
      "city": "<string>",
      "state": "<string>",
      "zipcode": "<string>"
    }
  ],
  "match_condition_fields": [
    "<string>"
  ],
  "return_fields": [
    "<string>"
  ],
  "include_premium_fields": true
}
'

import requests

url = "https://api.minerva.io/v2/enrich"

payload = {
    "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>"],
            "full_address": "<string>",
            "address_line_1": "<string>",
            "address_line_2": "<string>",
            "city": "<string>",
            "state": "<string>",
            "zipcode": "<string>"
        }
    ],
    "match_condition_fields": ["<string>"],
    "return_fields": ["<string>"],
    "include_premium_fields": True
}
headers = {
    "x-api-key": "<api-key>",
    "Content-Type": "<content-type>"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {'x-api-key': '<api-key>', 'Content-Type': '<content-type>'},
  body: JSON.stringify({
    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>'],
        full_address: '<string>',
        address_line_1: '<string>',
        address_line_2: '<string>',
        city: '<string>',
        state: '<string>',
        zipcode: '<string>'
      }
    ],
    match_condition_fields: ['<string>'],
    return_fields: ['<string>'],
    include_premium_fields: true
  })
};

fetch('https://api.minerva.io/v2/enrich', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.minerva.io/v2/enrich",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    '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>'
                ],
                'full_address' => '<string>',
                'address_line_1' => '<string>',
                'address_line_2' => '<string>',
                'city' => '<string>',
                'state' => '<string>',
                'zipcode' => '<string>'
        ]
    ],
    'match_condition_fields' => [
        '<string>'
    ],
    'return_fields' => [
        '<string>'
    ],
    'include_premium_fields' => true
  ]),
  CURLOPT_HTTPHEADER => [
    "Content-Type: <content-type>",
    "x-api-key: <api-key>"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://api.minerva.io/v2/enrich"

	payload := strings.NewReader("{\n  \"records\": [\n    {\n      \"record_id\": \"<string>\",\n      \"minerva_pid\": \"<string>\",\n      \"linkedin_url\": \"<string>\",\n      \"first_name\": \"<string>\",\n      \"middle_name\": \"<string>\",\n      \"last_name\": \"<string>\",\n      \"full_name\": \"<string>\",\n      \"name_suffix\": \"<string>\",\n      \"emails\": [\n        \"<string>\"\n      ],\n      \"phones\": [\n        \"<string>\"\n      ],\n      \"full_address\": \"<string>\",\n      \"address_line_1\": \"<string>\",\n      \"address_line_2\": \"<string>\",\n      \"city\": \"<string>\",\n      \"state\": \"<string>\",\n      \"zipcode\": \"<string>\"\n    }\n  ],\n  \"match_condition_fields\": [\n    \"<string>\"\n  ],\n  \"return_fields\": [\n    \"<string>\"\n  ],\n  \"include_premium_fields\": true\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("x-api-key", "<api-key>")
	req.Header.Add("Content-Type", "<content-type>")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.post("https://api.minerva.io/v2/enrich")
  .header("x-api-key", "<api-key>")
  .header("Content-Type", "<content-type>")
  .body("{\n  \"records\": [\n    {\n      \"record_id\": \"<string>\",\n      \"minerva_pid\": \"<string>\",\n      \"linkedin_url\": \"<string>\",\n      \"first_name\": \"<string>\",\n      \"middle_name\": \"<string>\",\n      \"last_name\": \"<string>\",\n      \"full_name\": \"<string>\",\n      \"name_suffix\": \"<string>\",\n      \"emails\": [\n        \"<string>\"\n      ],\n      \"phones\": [\n        \"<string>\"\n      ],\n      \"full_address\": \"<string>\",\n      \"address_line_1\": \"<string>\",\n      \"address_line_2\": \"<string>\",\n      \"city\": \"<string>\",\n      \"state\": \"<string>\",\n      \"zipcode\": \"<string>\"\n    }\n  ],\n  \"match_condition_fields\": [\n    \"<string>\"\n  ],\n  \"return_fields\": [\n    \"<string>\"\n  ],\n  \"include_premium_fields\": true\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api.minerva.io/v2/enrich")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["x-api-key"] = '<api-key>'
request["Content-Type"] = '<content-type>'
request.body = "{\n  \"records\": [\n    {\n      \"record_id\": \"<string>\",\n      \"minerva_pid\": \"<string>\",\n      \"linkedin_url\": \"<string>\",\n      \"first_name\": \"<string>\",\n      \"middle_name\": \"<string>\",\n      \"last_name\": \"<string>\",\n      \"full_name\": \"<string>\",\n      \"name_suffix\": \"<string>\",\n      \"emails\": [\n        \"<string>\"\n      ],\n      \"phones\": [\n        \"<string>\"\n      ],\n      \"full_address\": \"<string>\",\n      \"address_line_1\": \"<string>\",\n      \"address_line_2\": \"<string>\",\n      \"city\": \"<string>\",\n      \"state\": \"<string>\",\n      \"zipcode\": \"<string>\"\n    }\n  ],\n  \"match_condition_fields\": [\n    \"<string>\"\n  ],\n  \"return_fields\": [\n    \"<string>\"\n  ],\n  \"include_premium_fields\": true\n}"

response = http.request(request)
puts response.read_body

{
  "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,
      "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",
      "minerva_household_id": "h-a1b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6",
      "minerva_spouse_pid": null,
      "number_of_children": 0,
      "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,
      "linkedin_url": "https://www.linkedin.com/in/example-profile",
      "linkedin_title": "Senior Software Engineer | Tech Enthusiast",
      "linkedin_industry": null,
      "linkedin_profile_pic_url": 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"
        }
      ]
    }
  ]
}

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

{
  "code": "unauthorized",
  "message": "Unauthorized",
  "api_request_id": "c1d2e3f4-a5b6-7890-cdef-1234567890ab"
}

{
  "code": "insufficient_record_capacity",
  "message": "Record export exceeds the available plan allowance and monthly spend limit. Increase the limit or upgrade, then retry.",
  "api_request_id": "d4e5f6a7-b8c9-0123-def4-567890abcdef",
  "details": {
    "records_available": 23,
    "allowance_records_available": 23,
    "overage_records_available": 0,
    "records_requested": 100
  }
}

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

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

Overview

The V2 Enrich endpoint combines identity resolution and comprehensive data enrichment with enhanced controls and performance. See Enrich Input Rules for accepted identifiers, record shapes, and contact-field requirements.

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
Premium Fields: Opt into separately-licensed household, spending, vehicle, travel, and interest attributes with include_premium_fields
New Data: Includes relatives field with family relationship information
Improved Performance: Optimized data retrieval with parallel processing and support for mixed lookup modes

Request

Headers

string

required

Your API key for authentication

string

required

application/json

Request Body

object[]

required

An array of person records to enrich. Maximum 500 records per request. Each record must follow one of the supported Enrich input rules.

Show Record object properties

string

required

Your unique identifier for this record

string

New in V2: Direct Minerva Person ID lookup for instant enrichment

string

New in V2: LinkedIn profile URL for direct enrichment

string

Person’s first name

string

Person’s middle name

string

Person’s last name

string

Person’s full name

string

Name suffix (e.g., “Jr.”, “Sr.”, “III”)

string[]

Array of email addresses

string[]

Array of phone numbers

string

Complete postal address. Do not combine this with parsed address fields.

string

Street address for a parsed address. Provide either zipcode or both city and state with it.

string

Optional unit, suite, or other secondary line for a parsed address.

string

City for a parsed address. Requires address_line_1 and state unless a zipcode is provided.

string

State for a parsed address. Requires address_line_1 and city unless a zipcode is provided.

string

Postal code for a parsed address. Requires address_line_1.

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

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, 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, relativesNote: return_fields names top-level keys of the result object, and the requested fields are returned at the top level of that object — the response is flat, with no personal_information / social_media-style grouping. Naming a base field returns 422, since base fields are always included.Example: ["full_name", "personal_emails", "phones"]

boolean

default:"false"

Optional. When true, each matched result gains a nested premium_fields object carrying separately-licensed household, spending, vehicle, travel, and interest attributes. See Premium Fields.Requires the api:premium-fields entitlement on your organization — requesting it without the grant returns 403. Contact your Minerva representative to enable it.Must be a boolean; a string such as "true" is rejected with 422 rather than coerced.Defaults to false, in which case the premium_fields key is omitted from the response entirely.Note: premium_fields is returned in addition to whatever return_fields selects — it is not itself a valid return_fields value, and setting return_fields does not suppress it.

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"
    }
  ]
}

Fuzzy Matching with a Full Address

{
  "records": [
    {
      "record_id": "user_004",
      "full_name": "Jordan Example",
      "full_address": "123 Example Street, Austin, TX 78701"
    }
  ]
}

Fuzzy Matching with a Parsed Address

{
  "records": [
    {
      "record_id": "user_005",
      "first_name": "Taylor",
      "last_name": "Example",
      "address_line_1": "456 Sample Avenue",
      "address_line_2": "Suite 200",
      "city": "Austin",
      "state": "TX"
    }
  ]
}

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"]
}

Response

Response Structure

string

Unique identifier for this API request

array

Array of enrichment results

string

ISO 8601 timestamp when the request was completed

Result Object - Base Fields (Always Returned)

string

Your identifier from the request

boolean

Whether a match was found

string

Minerva person identifier

number

Confidence score for the match, as an additive point total — not a 0-1 or 0-100 scale. Fuzzy matches routinely score above 100, direct lookups return fixed values, and the field can be null even on a successful match. See Interpreting match_score.

object

Any validation errors from the input

Result Object - Person Fields

Every person field below is a top-level key of the result object. They are not grouped into personal_information, household_information, financial_information, or social_media objects — those objects do not exist in the response. On a non-match (is_match: false) each is null.

string

Person’s full name

string

First name

string

Middle name

string

Last name

string

Name suffix

string

Gender (“M”, “F”, or null)

string

Date of birth (YYYY-MM-DD format)

integer

Current age

string

Marital status (“M” for married, “S” for single, or null)

string

Household identifier

string

Spouse’s Minerva PID if available

integer

Number of children

boolean

Whether the person is retired

string

Estimated income bracket

string

Estimated wealth bracket

string

Home ownership status (e.g., “Owner”, “Renter”, or null)

boolean

Whether bankruptcy records exist

boolean

Whether judgment records exist

string

LinkedIn profile URL

string

Current title from LinkedIn

string

Industry from LinkedIn

string

LinkedIn profile picture URL

boolean

Whether the person likely works remotely

string

Facebook profile URL

string

Twitter profile URL

Result Object - Contact Information

array

Array of personal email addresses with ranking

array

Array of professional email addresses with ranking

array

Array of phone numbers with type and ranking

Email Object

integer

Rank/priority of this email (1 = highest priority)

string

Email address

Phone Object

integer

Rank/priority of this phone (1 = highest priority)

string

Phone type (e.g., “Mobile”, “Landline”)

string

Phone number

Result Object - Family Relationships (New in V2)

array

New in V2: Array of family relationships

Relative Object

string

Minerva PID of the relative

string

Relative’s first name

string

Relative’s last name

string

Type of relationship (e.g., “Parent”, “Child”, “Sibling”)

string

Additional relationship details

Result Object - Address History

array

Array of address records with property details

Address Object

integer

Rank of address (1 = most recent/current)

string

Unique address identifier

string

Street address

string

Apartment/unit number

string

City

string

State

string

ZIP code

string

ZIP+4 extension

string

Ownership status (“Owned” / “Rented”)

boolean

Whether person currently owns this property (TRUE / FALSE)

string

Date property was purchased

number

Purchase price in USD

number

Current estimated value in USD

number

Estimated monthly rental value in USD

number

Annual property tax in USD

number

Outstanding mortgage balance in USD

number

Estimated equity in USD

number

Square footage

number

Number of bedrooms

number

Number of bathrooms

string

First date person was associated with this address

string

Last date person was associated with this address

Result Object - Work Experience

array

Array of work history records

Work Experience Object

integer

Rank (1 = most recent)

string

Unique experience identifier

string

Company name

string

Company LinkedIn URL

string

Company website

string

Company industry

string

NAICS industry classification code

string

NAICS industry description

string

SIC industry code

string

SIC industry description

string

Job title

string

Standardized job title

string

Seniority level (e.g., “Senior”, “Manager”, “Executive”)

string

Department

string

Employment type (e.g., “Full-time”, “Part-time”)

string

Employment status (e.g., “Current”, “Past”)

string

Start date

string

End date (null if current)

string

Work location city

string

Work location state

string

Work location country

Result Object - Education

array

Array of education records

Education Object

integer

Rank (1 = most recent)

string

Unique experience identifier

string

School/university name

string

Institution LinkedIn URL

string

Additional education details

string

Degree level (e.g., “Bachelor’s”, “Master’s”, “PhD”)

array

Array of major fields of study

array

Array of minor fields of study

string

Start date

string

Graduation date

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

{
  "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,
      "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",
      "minerva_household_id": "h-a1b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6",
      "minerva_spouse_pid": null,
      "number_of_children": 0,
      "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,
      "linkedin_url": "https://www.linkedin.com/in/example-profile",
      "linkedin_title": "Senior Software Engineer | Tech Enthusiast",
      "linkedin_industry": null,
      "linkedin_profile_pic_url": 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"
        }
      ]
    }
  ]
}

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

{
  "code": "unauthorized",
  "message": "Unauthorized",
  "api_request_id": "c1d2e3f4-a5b6-7890-cdef-1234567890ab"
}

{
  "code": "insufficient_record_capacity",
  "message": "Record export exceeds the available plan allowance and monthly spend limit. Increase the limit or upgrade, then retry.",
  "api_request_id": "d4e5f6a7-b8c9-0123-def4-567890abcdef",
  "details": {
    "records_available": 23,
    "allowance_records_available": 23,
    "overage_records_available": 0,
    "records_requested": 100
  }
}

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

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

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,
      "full_name": "Jane Doe",
      "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"
}

Premium Fields

Returned only when the request sets include_premium_fields: true and your organization holds the api:premium-fields entitlement. When the flag is omitted or false, the premium_fields key is absent from every result rather than present-and-null, so existing integrations see a byte-identical response. On a result where is_match is false, premium_fields is null — the same way the core person fields are withheld on a non-match. A matched person with no premium record on file also returns null.

object | null

Show Household composition

boolean | null

Household contains a child aged 0–3

boolean | null

Household contains a child aged 4–6

boolean | null

Household contains a child aged 7–9

boolean | null

Household contains a child aged 10–12

boolean | null

Household contains a child aged 13–18

string | null

Primary language spoken

Show Assets and investments

number | null

Low bound of estimated household assets, in USD

number | null

High bound of estimated household assets, in USD

number | null

Low bound of estimated household investments, in USD

number | null

High bound of estimated household investments, in USD

boolean | null

Holds an American Express card

Show Spending

number | null

Estimated total annual discretionary spending, in USD

number | null

Estimated annual entertainment spending, in USD

number | null

Estimated annual travel spending, in USD

number | null

Estimated annual charitable donations, in USD

integer | null

Propensity score for high-end luxury purchasing

integer | null

Propensity score for high-end retail purchasing

integer | null

Propensity score for bargain seeking

Show Vehicles

integer | null

Number of vehicles in the household

boolean | null

Household owns a luxury vehicle

boolean | null

Household owns an exotic vehicle

string | null

Make of the primary vehicle

string | null

Model of the primary vehicle

integer | null

Model year of the primary vehicle

number | null

MSRP of the primary vehicle, in USD

Show Travel and hospitality

boolean | null

Travels for business

boolean | null

Travels for personal reasons

boolean | null

Takes vacation travel

boolean | null

Propensity for high-end hotels

boolean | null

Propensity for luxury hotels

boolean | null

Propensity for high-end vacations

boolean | null

Propensity for luxury vacations

boolean | null

Broad luxury-lifestyle indicator

Show Sports and interests

boolean | null

Interest in football

boolean | null

Interest in soccer

boolean | null

Affinity for tennis

boolean | null

Tennis participation indicator

boolean | null

Interest in NASCAR

boolean | null

Interest in motor racing

boolean | null

General expressed sports interest

boolean | null

General sports propensity

Premium Fields Request Example

{
  "records": [
    {
      "record_id": "1",
      "full_name": "Jane Smith",
      "city": "Austin",
      "state": "TX"
    }
  ],
  "include_premium_fields": true
}

Premium Fields Response Example

Abbreviated — the core enrich fields are returned alongside premium_fields exactly as usual.

{
  "api_request_id": "550e8400-e29b-41d4-a716-446655440000",
  "results": [
    {
      "record_id": "1",
      "is_match": true,
      "minerva_pid": "abc123",
      "full_name": "Jane Smith",
      "match_score": 0.95,
      "validation_errors": null,
      "premium_fields": {
        "hh_child_aged_0_3_flag": false,
        "hh_child_aged_13_18_flag": true,
        "ind_primary_language": "English",
        "ind_has_amex_card_flag": true,
        "hh_assets_low_dollars": 1000000.0,
        "hh_assets_high_dollars": 2500000.0,
        "hh_annual_spending_travel_dollars": 18000.0,
        "ind_luxury_highend_buyer_propensity": 8,
        "hh_n_vehicles": 2,
        "hh_has_luxury_flag": true,
        "hh_primary_vehicle_make": "Lexus",
        "hh_primary_vehicle_model": "RX 350",
        "hh_primary_vehicle_year": 2022,
        "ind_travel_vacation_flag": true,
        "ind_hotel_luxury_propensity_flag": true,
        "ind_tennis_affinity_flag": true,
        "ind_luxury_life_flag": true
      }
    }
  ],
  "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: The new records exceed available plan allowance and monthly overage capacity. details includes records_requested, records_available, allowance_records_available, and overage_records_available. Increase the monthly spend limit or upgrade before retrying.
403 - Forbidden: include_premium_fields was requested without the api:premium-fields entitlement. Response code is insufficient_organization_entitlements
413 - Payload Too Large: More than 500 records in request
422 - Unprocessable Entity: Validation errors in record data, invalid match_condition_fields, invalid return_fields, or a non-boolean include_premium_fields
429 - Too Many Requests: Rate limit exceeded
500 - Internal Server Error: Unexpected server error

Notes

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

Interpreting `match_score`

match_score is an additive point total, not a normalized 0-1 or 0-100 confidence. For a fuzzy match it is the sum of two components:

Name — up to 60 points, based on how closely the input name matches the person’s known names and aliases
Contact info — points for matching email, phone, and address evidence, weighted by how strongly each value is associated with the person

Because the contact-info component grows with each additional match, there is no upper bound: a record matched on a name plus several emails and phones commonly scores 110-130. Every fuzzy match returned with is_match: true has already cleared Minerva’s internal threshold and scores at least 50.

Compare scores against each other, not against a fixed ceiling. Thresholding on a percentage (for example, “accept above 0.8” or “above 80%”) will not behave the way you expect.

Direct lookups don’t run the scoring algorithm, so V2 reports them differently depending on which lookup modes corroborate each other:

How the record matched	`match_score`
Fuzzy matching only — no `minerva_pid` or `linkedin_url` supplied	Additive point total (at least 50, often above 100)
A direct lookup and fuzzy matching independently agreed on the same person	The fuzzy score, floored at `95.0`
`linkedin_url` supplied, without that agreement	Fixed `75`
`minerva_pid` supplied, without that agreement and without a `linkedin_url`	`null`
No match (`is_match: false`)	`null`

A null score is therefore not a weak match — for a direct minerva_pid lookup it means you addressed the person by identifier, so there was nothing to score. Treat is_match as the source of truth for whether a record matched, and don’t require match_score to be present. Scores are rounded to two decimal places. If you need stricter results, prefer match_condition_fields over a score threshold: it filters on which data is actually populated, which is both verifiable and stable across lookup modes.

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
Every scalar person field is a top-level key of the result object. The response is flat: there are no personal_information, household_information, financial_information, or social_media wrapper objects. The only nested object in a result is premium_fields, and only when explicitly requested
When using return_fields, the requested fields are returned at the top level alongside the base fields

Validation

Input validation follows the Enrich input rules. 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
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:

URL Change: /v1/enrich → /v2/enrich
Response Structure: Unchanged. V2 results are flat, exactly as in V1 — every scalar person field and every array field sits at the top level of the result object. V2 adds two keys (relatives, and premium_fields when requested); no existing key moved or was regrouped, so a V1 decoder keeps working against V2.
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
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 at the top level, alongside the base fields
Data Quality Control: Use match_condition_fields to ensure matches have required data
New Data: relatives field 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/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

​Quick Answer

​Overview

​Key Enhancements in V2

​Request

​Headers

​Request Body

​Request Examples

​Standard Fuzzy Matching with Selective Returns

​Direct Minerva PID Lookup

​Direct LinkedIn URL Lookup

​Fuzzy Matching with a Full Address

​Fuzzy Matching with a Parsed Address

​Mixed Lookup Types in One Request

​Response

​Response Structure

​Result Object - Base Fields (Always Returned)

​Result Object - Person Fields

​Result Object - Contact Information

Email Object

Phone Object

​Result Object - Family Relationships (New in V2)

Relative Object

​Result Object - Address History

Address Object

​Result Object - Work Experience

Work Experience Object

​Result Object - Education

Education Object

​Alternative Response Example (With return_fields)

​Premium Fields

​Premium Fields Request Example

​Premium Fields Response Example

​Error Responses

​Notes

​Performance Optimization

​Interpreting match_score

​Match Condition Fields

​Data Availability

​Validation

​New Features in V2

​Migration from V1

​Key Differences from /v2/resolve

Quick Answer

Overview

Key Enhancements in V2

Request

Headers

Request Body

Request Examples

Standard Fuzzy Matching with Selective Returns

Direct Minerva PID Lookup

Direct LinkedIn URL Lookup

Fuzzy Matching with a Full Address

Fuzzy Matching with a Parsed Address

Mixed Lookup Types in One Request

Response

Response Structure

Result Object - Base Fields (Always Returned)

Result Object - Person Fields

Result Object - Contact Information

Result Object - Family Relationships (New in V2)

Result Object - Address History

Result Object - Work Experience

Result Object - Education

Alternative Response Example (With `return_fields`)

Premium Fields

Premium Fields Request Example

Premium Fields Response Example

Error Responses

Notes

Performance Optimization

Interpreting `match_score`

Match Condition Fields

Data Availability

Validation

New Features in V2

Migration from V1

Key Differences from `/v2/resolve`