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

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>"]
}
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>']
  })
};

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>'
    ]
  ]),
  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}")

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

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

{
  "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_credits",
  "message": "Insufficient records budget — please purchase more credits",
  "api_request_id": "d4e5f6a7-b8c9-0123-def4-567890abcdef",
  "details": {
    "records_remaining": 23,
    "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>"
  ]
}
'

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>"]
}
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>']
  })
};

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>'
    ]
  ]),
  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}")

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

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

{
  "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_credits",
  "message": "Insufficient records budget — please purchase more credits",
  "api_request_id": "d4e5f6a7-b8c9-0123-def4-567890abcdef",
  "details": {
    "records_remaining": 23,
    "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
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, 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"
    }
  ]
}

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 - Personal Information

object

Object containing personal demographic details

Show personal_information properties

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)

Result Object - Household Information

object

Object containing household and family details

Show household_information properties

string

Household identifier

string

Spouse’s Minerva PID if available

integer

Number of children

Result Object - Financial Information

object

Object containing financial and legal record details

Show financial_information properties

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

Object containing social media profiles and professional information

Show social_media properties

string

LinkedIn profile URL

string

Current title from LinkedIn

string

Industry from LinkedIn

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

{
  "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_credits",
  "message": "Insufficient records budget — please purchase more credits",
  "api_request_id": "d4e5f6a7-b8c9-0123-def4-567890abcdef",
  "details": {
    "records_remaining": 23,
    "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,
      "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
402 - Payment Required: Minerva credits exhausted. Response body includes records_remaining (estimated records remaining based on your credit balance) and records_requested (batch size that was rejected)
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
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
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

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

URL Change: /v1/enrich → /v2/enrich
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
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 within their respective nested objects
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

⌘I

​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 - Personal Information

​Result Object - Household Information

​Result Object - Financial Information

​Result Object - Social Media

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

​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 - Personal Information

Result Object - Household Information

Result Object - Financial Information

Result Object - Social Media

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

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`