Enrich v1
curl --request POST \
--url https://api.minerva.io/v1/enrich \
--header 'Content-Type: <content-type>' \
--header 'x-api-key: <api-key>' \
--data '
{
"records": [
{
"record_id": "<string>",
"first_name": "<string>",
"middle_name": "<string>",
"last_name": "<string>",
"full_name": "<string>",
"name_suffix": "<string>",
"emails": [
"<string>"
],
"phones": [
"<string>"
]
}
]
}
'import requests
url = "https://api.minerva.io/v1/enrich"
payload = { "records": [
{
"record_id": "<string>",
"first_name": "<string>",
"middle_name": "<string>",
"last_name": "<string>",
"full_name": "<string>",
"name_suffix": "<string>",
"emails": ["<string>"],
"phones": ["<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>',
first_name: '<string>',
middle_name: '<string>',
last_name: '<string>',
full_name: '<string>',
name_suffix: '<string>',
emails: ['<string>'],
phones: ['<string>']
}
]
})
};
fetch('https://api.minerva.io/v1/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/v1/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>',
'first_name' => '<string>',
'middle_name' => '<string>',
'last_name' => '<string>',
'full_name' => '<string>',
'name_suffix' => '<string>',
'emails' => [
'<string>'
],
'phones' => [
'<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/v1/enrich"
payload := strings.NewReader("{\n \"records\": [\n {\n \"record_id\": \"<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 }\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/v1/enrich")
.header("x-api-key", "<api-key>")
.header("Content-Type", "<content-type>")
.body("{\n \"records\": [\n {\n \"record_id\": \"<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 }\n ]\n}")
.asString();require 'uri'
require 'net/http'
url = URI("https://api.minerva.io/v1/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 \"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 }\n ]\n}"
response = http.request(request)
puts response.read_body{
"api_request_id": "req_abc123xyz789",
"request_completed_at": "2024-01-15T10:30:45.123456+00:00",
"results": [
{
"record_id": "user_001",
"is_match": true,
"minerva_pid": "p-a1b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6",
"full_name": "JOHN M SMITH",
"first_name": "JOHN",
"middle_name": "M",
"last_name": "SMITH",
"name_suffix": null,
"gender": "M",
"dob": "1990-05-15",
"age": 34,
"marital_status": "M",
"minerva_household_id": "h-a1b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6",
"minerva_spouse_pid": null,
"number_of_children": 2,
"is_retired": false,
"estimated_income_range": "$101K - $250K",
"estimated_wealth_range": "$1M-$2M",
"home_ownership_status": null,
"linkedin_url": "https://www.linkedin.com/in/johnsmith",
"linkedin_title": "Senior Software Engineer | Technology Leader",
"linkedin_industry": null,
"is_likely_remote_worker": false,
"facebook_url": null,
"twitter_url": null,
"has_bankruptcy_records": false,
"has_judgment_records": false,
"personal_emails": [
{
"email_rank": 1,
"email_address": "john.smith@gmail.com"
},
{
"email_rank": 2,
"email_address": "jsmith@email.com"
},
{
"email_rank": 3,
"email_address": "johnsmith123@yahoo.com"
}
],
"professional_emails": [],
"phones": [
{
"phone_rank": 1,
"phone_type": "Mobile",
"phone_number": "(555) 123-4567"
},
{
"phone_rank": 2,
"phone_type": "Mobile",
"phone_number": "(555) 234-5678"
},
{
"phone_rank": 3,
"phone_type": "Landline/Services",
"phone_number": "(555) 345-6789"
}
],
"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-01-15",
"last_seen_date": "2024-01-15"
},
{
"address_rank": 2,
"minerva_address_id": "a-b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6e7",
"address_line_1": "456 OAK AVE",
"address_line_2": null,
"address_city": "PALO ALTO",
"address_state": "CA",
"address_zipcode": "94301",
"address_zipcode4": "5678",
"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": "2020-06-01",
"last_seen_date": "2023-01-14"
},
{
"address_rank": 3,
"minerva_address_id": "a-c3d4e5f6a7b8c9d0e1f2a3b4c5d6e7f8",
"address_line_1": "789 ELM ST",
"address_line_2": null,
"address_city": "MOUNTAIN VIEW",
"address_state": "CA",
"address_zipcode": "94040",
"address_zipcode4": "9012",
"ownership_status": "Owned",
"is_current_owner": false,
"purchase_date": "2015-03-20",
"purchase_price": null,
"estimated_current_value": 1493190.0,
"estimated_rental_value": 7189.0,
"home_current_tax_liability": null,
"outstanding_loan_principal": null,
"current_property_equity_amount": null,
"sqft": 2979.0,
"num_beds": 4.0,
"num_baths": 2.5,
"first_seen_date": "2015-03-20",
"last_seen_date": "2020-05-31"
}
],
"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/tech-solutions",
"work_company_website": null,
"work_company_industry": null,
"work_company_naics_code": null,
"work_company_naics_description": null,
"work_company_sic_code": null,
"work_company_sic_description": null,
"work_title": "Senior Software Engineer",
"standard_work_title": "Senior Software Engineer",
"work_seniority_level": "Senior",
"work_department": "Engineering",
"work_employment_type": "Full-Time",
"work_status": "current",
"work_start_date": "2020-01-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": "Startup Ventures",
"work_company_linkedin_url": "https://www.linkedin.com/company/startup-ventures",
"work_company_website": "https://startupventures.com",
"work_company_industry": "Technology",
"work_company_naics_code": null,
"work_company_naics_description": null,
"work_company_sic_code": null,
"work_company_sic_description": null,
"work_title": "Software Engineer",
"standard_work_title": "Software Engineer",
"work_seniority_level": "Mid",
"work_department": "Engineering",
"work_employment_type": "Full-Time",
"work_status": "previous",
"work_start_date": "2018-06-01",
"work_end_date": "2019-12-31",
"work_city": "San Francisco",
"work_state": "CA",
"work_country": "US"
},
{
"experience_rank": 3,
"minerva_experience_id": "w-c3d4e5f6a7b8c9d0e1f2a3b4c5d6e7f8",
"work_company_name": "Financial Corp",
"work_company_linkedin_url": "https://www.linkedin.com/company/financial-corp",
"work_company_website": "https://financialcorp.com",
"work_company_industry": "Financial Services",
"work_company_naics_code": "523930",
"work_company_naics_description": "Investment Advice",
"work_company_sic_code": "6282",
"work_company_sic_description": "Investment Advice",
"work_title": "Junior Developer",
"standard_work_title": "Junior Developer",
"work_seniority_level": "Entry",
"work_department": "Technology",
"work_employment_type": "Full-Time",
"work_status": "previous",
"work_start_date": "2016-08-01",
"work_end_date": "2018-05-31",
"work_city": "New York",
"work_state": "NY",
"work_country": "US"
},
{
"experience_rank": 4,
"minerva_experience_id": "w-d4e5f6a7b8c9d0e1f2a3b4c5d6e7f8a9",
"work_company_name": "Financial Corp",
"work_company_linkedin_url": "https://www.linkedin.com/company/financial-corp",
"work_company_website": "https://financialcorp.com",
"work_company_industry": "Financial Services",
"work_company_naics_code": "523930",
"work_company_naics_description": "Investment Advice",
"work_company_sic_code": "6282",
"work_company_sic_description": "Investment Advice",
"work_title": "Summer Analyst",
"standard_work_title": "Summer Analyst",
"work_seniority_level": "Intern",
"work_department": "Technology",
"work_employment_type": "Part-Time",
"work_status": "previous",
"work_start_date": "2015-06-01",
"work_end_date": "2015-08-31",
"work_city": "New York",
"work_state": "NY",
"work_country": "US"
},
{
"experience_rank": 5,
"minerva_experience_id": "w-e5f6a7b8c9d0e1f2a3b4c5d6e7f8a9b0",
"work_company_name": "Tech Innovations",
"work_company_linkedin_url": "https://www.linkedin.com/company/tech-innovations",
"work_company_website": "https://techinnovations.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": "Software Engineering Intern",
"standard_work_title": "Software Engineering Intern",
"work_seniority_level": "Intern",
"work_department": "Engineering",
"work_employment_type": "Part-Time",
"work_status": "previous",
"work_start_date": "2014-06-01",
"work_end_date": "2014-08-31",
"work_city": "Seattle",
"work_state": "WA",
"work_country": "US"
},
{
"experience_rank": 6,
"minerva_experience_id": "w-f6a7b8c9d0e1f2a3b4c5d6e7f8a9b0c1",
"work_company_name": "Startup Labs",
"work_company_linkedin_url": null,
"work_company_website": null,
"work_company_industry": null,
"work_company_naics_code": null,
"work_company_naics_description": null,
"work_company_sic_code": null,
"work_company_sic_description": null,
"work_title": "Co-Founder",
"standard_work_title": "Co-Founder",
"work_seniority_level": "Executive",
"work_department": "Executive",
"work_employment_type": "Full-Time",
"work_status": "previous",
"work_start_date": "2013-01-01",
"work_end_date": "2013-12-31",
"work_city": null,
"work_state": null,
"work_country": null
},
{
"experience_rank": 7,
"minerva_experience_id": "w-a7b8c9d0e1f2a3b4c5d6e7f8a9b0c1d2",
"work_company_name": "Research Institute",
"work_company_linkedin_url": null,
"work_company_website": null,
"work_company_industry": null,
"work_company_naics_code": null,
"work_company_naics_description": null,
"work_company_sic_code": null,
"work_company_sic_description": null,
"work_title": "Research Assistant",
"standard_work_title": "Research Assistant",
"work_seniority_level": "Entry",
"work_department": "Research",
"work_employment_type": "Part-Time",
"work_status": "previous",
"work_start_date": "2012-09-01",
"work_end_date": "2013-05-31",
"work_city": null,
"work_state": null,
"work_country": null
},
{
"experience_rank": 8,
"minerva_experience_id": "w-b8c9d0e1f2a3b4c5d6e7f8a9b0c1d2e3",
"work_company_name": "Community Organization",
"work_company_linkedin_url": "https://www.linkedin.com/company/community-org",
"work_company_website": "https://communityorg.org",
"work_company_industry": "Nonprofit",
"work_company_naics_code": "813920",
"work_company_naics_description": "Professional Organizations",
"work_company_sic_code": "8621",
"work_company_sic_description": "Professional organizations",
"work_title": "Volunteer Coordinator",
"standard_work_title": "Volunteer Coordinator",
"work_seniority_level": "Entry",
"work_department": "Operations",
"work_employment_type": "Full-Time",
"work_status": "previous",
"work_start_date": "2011-06-01",
"work_end_date": "2011-11-30",
"work_city": null,
"work_state": null,
"work_country": null
},
{
"experience_rank": 9,
"minerva_experience_id": "w-c9d0e1f2a3b4c5d6e7f8a9b0c1d2e3f4",
"work_company_name": "Consulting Group",
"work_company_linkedin_url": "https://www.linkedin.com/company/consulting-group",
"work_company_website": "https://consultinggroup.com",
"work_company_industry": "Management Consulting",
"work_company_naics_code": "541614",
"work_company_naics_description": "Process, Physical Distribution, and Logistics Consulting Services",
"work_company_sic_code": "8742",
"work_company_sic_description": "Management consulting services",
"work_title": "Summer Intern",
"standard_work_title": "Summer Intern",
"work_seniority_level": "Intern",
"work_department": null,
"work_employment_type": "Part-Time",
"work_status": "previous",
"work_start_date": "2010-06-01",
"work_end_date": "2010-08-31",
"work_city": null,
"work_state": null,
"work_country": null
}
],
"education_experience": [
{
"experience_rank": 1,
"minerva_experience_id": "e-a1b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6",
"institution_name": "State University",
"institution_linkedin_url": "https://www.linkedin.com/school/state-university",
"education_information": "Bachelor of Science (B.S.), Computer Science",
"education_level": "Bachelors",
"education_majors": [
"Computer Science",
"Mathematics"
],
"education_minors": [],
"education_start_date": "2012-09-01",
"education_end_date": "2016-05-31"
}
],
"match_score": 110.0,
"validation_errors": null
}
]
}
{
"code": "bad_request",
"message": "Input data must contain a 'records' key with a list of inputs",
"api_request_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890"
}
{
"code": "unauthorized",
"message": "Unauthorized",
"api_request_id": "b2c3d4e5-f6a7-1234-bcde-f12345678901"
}
{
"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": "c3d4e5f6-a7b8-2345-cdef-123456789012",
"details": {
"records_available": 45,
"allowance_records_available": 45,
"overage_records_available": 0,
"records_requested": 250
}
}
{
"code": "payload_too_large",
"message": "Maximum number of records for /v1/enrich endpoint is 500",
"api_request_id": "d4e5f6a7-b8c9-3456-def0-234567890123"
}
{
"code": "unprocessable_entity",
"message": "Input data must contain a 'records' key with a list of inputs",
"api_request_id": "e5f6a7b8-c9d0-4567-ef01-345678901234"
}
{
"code": "rate_limit_reached",
"message": "You reached your total request-rate limit, please contact help@minerva.io for help",
"api_request_id": "f6a7b8c9-d0e1-5678-f012-456789012345"
}
Enrich
Enrich v1
Do not use Enrich v1. This endpoint is deprecated and remains available only for backward compatibility. Use Enrich v2 for all enrichment workflows. Migrate existing v1 integrations to v2 as soon as possible.
POST
/
v1
/
enrich
Enrich v1
curl --request POST \
--url https://api.minerva.io/v1/enrich \
--header 'Content-Type: <content-type>' \
--header 'x-api-key: <api-key>' \
--data '
{
"records": [
{
"record_id": "<string>",
"first_name": "<string>",
"middle_name": "<string>",
"last_name": "<string>",
"full_name": "<string>",
"name_suffix": "<string>",
"emails": [
"<string>"
],
"phones": [
"<string>"
]
}
]
}
'import requests
url = "https://api.minerva.io/v1/enrich"
payload = { "records": [
{
"record_id": "<string>",
"first_name": "<string>",
"middle_name": "<string>",
"last_name": "<string>",
"full_name": "<string>",
"name_suffix": "<string>",
"emails": ["<string>"],
"phones": ["<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>',
first_name: '<string>',
middle_name: '<string>',
last_name: '<string>',
full_name: '<string>',
name_suffix: '<string>',
emails: ['<string>'],
phones: ['<string>']
}
]
})
};
fetch('https://api.minerva.io/v1/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/v1/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>',
'first_name' => '<string>',
'middle_name' => '<string>',
'last_name' => '<string>',
'full_name' => '<string>',
'name_suffix' => '<string>',
'emails' => [
'<string>'
],
'phones' => [
'<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/v1/enrich"
payload := strings.NewReader("{\n \"records\": [\n {\n \"record_id\": \"<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 }\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/v1/enrich")
.header("x-api-key", "<api-key>")
.header("Content-Type", "<content-type>")
.body("{\n \"records\": [\n {\n \"record_id\": \"<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 }\n ]\n}")
.asString();require 'uri'
require 'net/http'
url = URI("https://api.minerva.io/v1/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 \"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 }\n ]\n}"
response = http.request(request)
puts response.read_body{
"api_request_id": "req_abc123xyz789",
"request_completed_at": "2024-01-15T10:30:45.123456+00:00",
"results": [
{
"record_id": "user_001",
"is_match": true,
"minerva_pid": "p-a1b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6",
"full_name": "JOHN M SMITH",
"first_name": "JOHN",
"middle_name": "M",
"last_name": "SMITH",
"name_suffix": null,
"gender": "M",
"dob": "1990-05-15",
"age": 34,
"marital_status": "M",
"minerva_household_id": "h-a1b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6",
"minerva_spouse_pid": null,
"number_of_children": 2,
"is_retired": false,
"estimated_income_range": "$101K - $250K",
"estimated_wealth_range": "$1M-$2M",
"home_ownership_status": null,
"linkedin_url": "https://www.linkedin.com/in/johnsmith",
"linkedin_title": "Senior Software Engineer | Technology Leader",
"linkedin_industry": null,
"is_likely_remote_worker": false,
"facebook_url": null,
"twitter_url": null,
"has_bankruptcy_records": false,
"has_judgment_records": false,
"personal_emails": [
{
"email_rank": 1,
"email_address": "john.smith@gmail.com"
},
{
"email_rank": 2,
"email_address": "jsmith@email.com"
},
{
"email_rank": 3,
"email_address": "johnsmith123@yahoo.com"
}
],
"professional_emails": [],
"phones": [
{
"phone_rank": 1,
"phone_type": "Mobile",
"phone_number": "(555) 123-4567"
},
{
"phone_rank": 2,
"phone_type": "Mobile",
"phone_number": "(555) 234-5678"
},
{
"phone_rank": 3,
"phone_type": "Landline/Services",
"phone_number": "(555) 345-6789"
}
],
"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-01-15",
"last_seen_date": "2024-01-15"
},
{
"address_rank": 2,
"minerva_address_id": "a-b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6e7",
"address_line_1": "456 OAK AVE",
"address_line_2": null,
"address_city": "PALO ALTO",
"address_state": "CA",
"address_zipcode": "94301",
"address_zipcode4": "5678",
"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": "2020-06-01",
"last_seen_date": "2023-01-14"
},
{
"address_rank": 3,
"minerva_address_id": "a-c3d4e5f6a7b8c9d0e1f2a3b4c5d6e7f8",
"address_line_1": "789 ELM ST",
"address_line_2": null,
"address_city": "MOUNTAIN VIEW",
"address_state": "CA",
"address_zipcode": "94040",
"address_zipcode4": "9012",
"ownership_status": "Owned",
"is_current_owner": false,
"purchase_date": "2015-03-20",
"purchase_price": null,
"estimated_current_value": 1493190.0,
"estimated_rental_value": 7189.0,
"home_current_tax_liability": null,
"outstanding_loan_principal": null,
"current_property_equity_amount": null,
"sqft": 2979.0,
"num_beds": 4.0,
"num_baths": 2.5,
"first_seen_date": "2015-03-20",
"last_seen_date": "2020-05-31"
}
],
"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/tech-solutions",
"work_company_website": null,
"work_company_industry": null,
"work_company_naics_code": null,
"work_company_naics_description": null,
"work_company_sic_code": null,
"work_company_sic_description": null,
"work_title": "Senior Software Engineer",
"standard_work_title": "Senior Software Engineer",
"work_seniority_level": "Senior",
"work_department": "Engineering",
"work_employment_type": "Full-Time",
"work_status": "current",
"work_start_date": "2020-01-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": "Startup Ventures",
"work_company_linkedin_url": "https://www.linkedin.com/company/startup-ventures",
"work_company_website": "https://startupventures.com",
"work_company_industry": "Technology",
"work_company_naics_code": null,
"work_company_naics_description": null,
"work_company_sic_code": null,
"work_company_sic_description": null,
"work_title": "Software Engineer",
"standard_work_title": "Software Engineer",
"work_seniority_level": "Mid",
"work_department": "Engineering",
"work_employment_type": "Full-Time",
"work_status": "previous",
"work_start_date": "2018-06-01",
"work_end_date": "2019-12-31",
"work_city": "San Francisco",
"work_state": "CA",
"work_country": "US"
},
{
"experience_rank": 3,
"minerva_experience_id": "w-c3d4e5f6a7b8c9d0e1f2a3b4c5d6e7f8",
"work_company_name": "Financial Corp",
"work_company_linkedin_url": "https://www.linkedin.com/company/financial-corp",
"work_company_website": "https://financialcorp.com",
"work_company_industry": "Financial Services",
"work_company_naics_code": "523930",
"work_company_naics_description": "Investment Advice",
"work_company_sic_code": "6282",
"work_company_sic_description": "Investment Advice",
"work_title": "Junior Developer",
"standard_work_title": "Junior Developer",
"work_seniority_level": "Entry",
"work_department": "Technology",
"work_employment_type": "Full-Time",
"work_status": "previous",
"work_start_date": "2016-08-01",
"work_end_date": "2018-05-31",
"work_city": "New York",
"work_state": "NY",
"work_country": "US"
},
{
"experience_rank": 4,
"minerva_experience_id": "w-d4e5f6a7b8c9d0e1f2a3b4c5d6e7f8a9",
"work_company_name": "Financial Corp",
"work_company_linkedin_url": "https://www.linkedin.com/company/financial-corp",
"work_company_website": "https://financialcorp.com",
"work_company_industry": "Financial Services",
"work_company_naics_code": "523930",
"work_company_naics_description": "Investment Advice",
"work_company_sic_code": "6282",
"work_company_sic_description": "Investment Advice",
"work_title": "Summer Analyst",
"standard_work_title": "Summer Analyst",
"work_seniority_level": "Intern",
"work_department": "Technology",
"work_employment_type": "Part-Time",
"work_status": "previous",
"work_start_date": "2015-06-01",
"work_end_date": "2015-08-31",
"work_city": "New York",
"work_state": "NY",
"work_country": "US"
},
{
"experience_rank": 5,
"minerva_experience_id": "w-e5f6a7b8c9d0e1f2a3b4c5d6e7f8a9b0",
"work_company_name": "Tech Innovations",
"work_company_linkedin_url": "https://www.linkedin.com/company/tech-innovations",
"work_company_website": "https://techinnovations.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": "Software Engineering Intern",
"standard_work_title": "Software Engineering Intern",
"work_seniority_level": "Intern",
"work_department": "Engineering",
"work_employment_type": "Part-Time",
"work_status": "previous",
"work_start_date": "2014-06-01",
"work_end_date": "2014-08-31",
"work_city": "Seattle",
"work_state": "WA",
"work_country": "US"
},
{
"experience_rank": 6,
"minerva_experience_id": "w-f6a7b8c9d0e1f2a3b4c5d6e7f8a9b0c1",
"work_company_name": "Startup Labs",
"work_company_linkedin_url": null,
"work_company_website": null,
"work_company_industry": null,
"work_company_naics_code": null,
"work_company_naics_description": null,
"work_company_sic_code": null,
"work_company_sic_description": null,
"work_title": "Co-Founder",
"standard_work_title": "Co-Founder",
"work_seniority_level": "Executive",
"work_department": "Executive",
"work_employment_type": "Full-Time",
"work_status": "previous",
"work_start_date": "2013-01-01",
"work_end_date": "2013-12-31",
"work_city": null,
"work_state": null,
"work_country": null
},
{
"experience_rank": 7,
"minerva_experience_id": "w-a7b8c9d0e1f2a3b4c5d6e7f8a9b0c1d2",
"work_company_name": "Research Institute",
"work_company_linkedin_url": null,
"work_company_website": null,
"work_company_industry": null,
"work_company_naics_code": null,
"work_company_naics_description": null,
"work_company_sic_code": null,
"work_company_sic_description": null,
"work_title": "Research Assistant",
"standard_work_title": "Research Assistant",
"work_seniority_level": "Entry",
"work_department": "Research",
"work_employment_type": "Part-Time",
"work_status": "previous",
"work_start_date": "2012-09-01",
"work_end_date": "2013-05-31",
"work_city": null,
"work_state": null,
"work_country": null
},
{
"experience_rank": 8,
"minerva_experience_id": "w-b8c9d0e1f2a3b4c5d6e7f8a9b0c1d2e3",
"work_company_name": "Community Organization",
"work_company_linkedin_url": "https://www.linkedin.com/company/community-org",
"work_company_website": "https://communityorg.org",
"work_company_industry": "Nonprofit",
"work_company_naics_code": "813920",
"work_company_naics_description": "Professional Organizations",
"work_company_sic_code": "8621",
"work_company_sic_description": "Professional organizations",
"work_title": "Volunteer Coordinator",
"standard_work_title": "Volunteer Coordinator",
"work_seniority_level": "Entry",
"work_department": "Operations",
"work_employment_type": "Full-Time",
"work_status": "previous",
"work_start_date": "2011-06-01",
"work_end_date": "2011-11-30",
"work_city": null,
"work_state": null,
"work_country": null
},
{
"experience_rank": 9,
"minerva_experience_id": "w-c9d0e1f2a3b4c5d6e7f8a9b0c1d2e3f4",
"work_company_name": "Consulting Group",
"work_company_linkedin_url": "https://www.linkedin.com/company/consulting-group",
"work_company_website": "https://consultinggroup.com",
"work_company_industry": "Management Consulting",
"work_company_naics_code": "541614",
"work_company_naics_description": "Process, Physical Distribution, and Logistics Consulting Services",
"work_company_sic_code": "8742",
"work_company_sic_description": "Management consulting services",
"work_title": "Summer Intern",
"standard_work_title": "Summer Intern",
"work_seniority_level": "Intern",
"work_department": null,
"work_employment_type": "Part-Time",
"work_status": "previous",
"work_start_date": "2010-06-01",
"work_end_date": "2010-08-31",
"work_city": null,
"work_state": null,
"work_country": null
}
],
"education_experience": [
{
"experience_rank": 1,
"minerva_experience_id": "e-a1b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6",
"institution_name": "State University",
"institution_linkedin_url": "https://www.linkedin.com/school/state-university",
"education_information": "Bachelor of Science (B.S.), Computer Science",
"education_level": "Bachelors",
"education_majors": [
"Computer Science",
"Mathematics"
],
"education_minors": [],
"education_start_date": "2012-09-01",
"education_end_date": "2016-05-31"
}
],
"match_score": 110.0,
"validation_errors": null
}
]
}
{
"code": "bad_request",
"message": "Input data must contain a 'records' key with a list of inputs",
"api_request_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890"
}
{
"code": "unauthorized",
"message": "Unauthorized",
"api_request_id": "b2c3d4e5-f6a7-1234-bcde-f12345678901"
}
{
"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": "c3d4e5f6-a7b8-2345-cdef-123456789012",
"details": {
"records_available": 45,
"allowance_records_available": 45,
"overage_records_available": 0,
"records_requested": 250
}
}
{
"code": "payload_too_large",
"message": "Maximum number of records for /v1/enrich endpoint is 500",
"api_request_id": "d4e5f6a7-b8c9-3456-def0-234567890123"
}
{
"code": "unprocessable_entity",
"message": "Input data must contain a 'records' key with a list of inputs",
"api_request_id": "e5f6a7b8-c9d0-4567-ef01-345678901234"
}
{
"code": "rate_limit_reached",
"message": "You reached your total request-rate limit, please contact help@minerva.io for help",
"api_request_id": "f6a7b8c9-d0e1-5678-f012-456789012345"
}
Quick Answer
How do I enrich a user/person/contact? Do not use Enrich v1. Use Enrich v2 instead. Enrich v1 is deprecated and remains available only for backward compatibility.Common questions this endpoint answers:- How do I enrich a user?
- How do I get more information about a person?
- How do I find contact details for someone?
- How do I get demographic data about a person?
- How do I look up someone’s professional background?
- How do I get email addresses and phone numbers for a contact?
- How can I append data to my customer records?
/v1/enrich integrations to /v2/enrich as soon as possible.Overview
The Enrich v1 endpoint combines resolution and data enrichment in a single call. It first resolves the person identity using fuzzy matching, then returns comprehensive profile data including demographics, work history, education, addresses, and contact information. This reference remains available only to support migrations from v1 to Enrich v2.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.
Request Example
{
"records": [
{
"record_id": "user_001",
"first_name": "John",
"last_name": "Smith",
"emails": ["john.smith@example.com"],
"phones": ["+1-555-123-4567"]
}
]
}
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 - Demographics
string
Your identifier from the request
boolean
Whether a match was found
string
Minerva person identifier
string
Person’s full name
string
First name
string
Middle name
string
Last name
string
Name suffix
string
Gender (“M” for male, “F” for female, or null)
string
Date of birth (ISO 8601 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
Result Object - Financial
boolean
Whether the person is retired
string
Estimated income bracket
string
Estimated wealth bracket
string
Home ownership status (e.g., “Owner”, “Renter”, or null)
Result Object - Social & Professional
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 - Legal Records
boolean
Whether bankruptcy records exist
boolean
Whether judgment records exist
Result Object - Contact Information
array
array
array
Result Object - Address History
array
Array of address records with property details
Show Address object properties
Show Address object properties
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” / “Unknown”)
boolean
Whether person currently owns this property (true / false / null)
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
Show Work experience object properties
Show Work experience object properties
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 (“current” or “previous”)
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
Show Education object properties
Show Education object properties
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
Result Object - Other Fields
number
Confidence score for the match, as an additive point total — not a 0-1 or
0-100 scale. Matches routinely score above 100.
null when is_match is
false. See Interpreting match_score.object
Any validation errors from the input
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": "req_abc123xyz789",
"request_completed_at": "2024-01-15T10:30:45.123456+00:00",
"results": [
{
"record_id": "user_001",
"is_match": true,
"minerva_pid": "p-a1b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6",
"full_name": "JOHN M SMITH",
"first_name": "JOHN",
"middle_name": "M",
"last_name": "SMITH",
"name_suffix": null,
"gender": "M",
"dob": "1990-05-15",
"age": 34,
"marital_status": "M",
"minerva_household_id": "h-a1b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6",
"minerva_spouse_pid": null,
"number_of_children": 2,
"is_retired": false,
"estimated_income_range": "$101K - $250K",
"estimated_wealth_range": "$1M-$2M",
"home_ownership_status": null,
"linkedin_url": "https://www.linkedin.com/in/johnsmith",
"linkedin_title": "Senior Software Engineer | Technology Leader",
"linkedin_industry": null,
"is_likely_remote_worker": false,
"facebook_url": null,
"twitter_url": null,
"has_bankruptcy_records": false,
"has_judgment_records": false,
"personal_emails": [
{
"email_rank": 1,
"email_address": "john.smith@gmail.com"
},
{
"email_rank": 2,
"email_address": "jsmith@email.com"
},
{
"email_rank": 3,
"email_address": "johnsmith123@yahoo.com"
}
],
"professional_emails": [],
"phones": [
{
"phone_rank": 1,
"phone_type": "Mobile",
"phone_number": "(555) 123-4567"
},
{
"phone_rank": 2,
"phone_type": "Mobile",
"phone_number": "(555) 234-5678"
},
{
"phone_rank": 3,
"phone_type": "Landline/Services",
"phone_number": "(555) 345-6789"
}
],
"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-01-15",
"last_seen_date": "2024-01-15"
},
{
"address_rank": 2,
"minerva_address_id": "a-b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6e7",
"address_line_1": "456 OAK AVE",
"address_line_2": null,
"address_city": "PALO ALTO",
"address_state": "CA",
"address_zipcode": "94301",
"address_zipcode4": "5678",
"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": "2020-06-01",
"last_seen_date": "2023-01-14"
},
{
"address_rank": 3,
"minerva_address_id": "a-c3d4e5f6a7b8c9d0e1f2a3b4c5d6e7f8",
"address_line_1": "789 ELM ST",
"address_line_2": null,
"address_city": "MOUNTAIN VIEW",
"address_state": "CA",
"address_zipcode": "94040",
"address_zipcode4": "9012",
"ownership_status": "Owned",
"is_current_owner": false,
"purchase_date": "2015-03-20",
"purchase_price": null,
"estimated_current_value": 1493190.0,
"estimated_rental_value": 7189.0,
"home_current_tax_liability": null,
"outstanding_loan_principal": null,
"current_property_equity_amount": null,
"sqft": 2979.0,
"num_beds": 4.0,
"num_baths": 2.5,
"first_seen_date": "2015-03-20",
"last_seen_date": "2020-05-31"
}
],
"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/tech-solutions",
"work_company_website": null,
"work_company_industry": null,
"work_company_naics_code": null,
"work_company_naics_description": null,
"work_company_sic_code": null,
"work_company_sic_description": null,
"work_title": "Senior Software Engineer",
"standard_work_title": "Senior Software Engineer",
"work_seniority_level": "Senior",
"work_department": "Engineering",
"work_employment_type": "Full-Time",
"work_status": "current",
"work_start_date": "2020-01-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": "Startup Ventures",
"work_company_linkedin_url": "https://www.linkedin.com/company/startup-ventures",
"work_company_website": "https://startupventures.com",
"work_company_industry": "Technology",
"work_company_naics_code": null,
"work_company_naics_description": null,
"work_company_sic_code": null,
"work_company_sic_description": null,
"work_title": "Software Engineer",
"standard_work_title": "Software Engineer",
"work_seniority_level": "Mid",
"work_department": "Engineering",
"work_employment_type": "Full-Time",
"work_status": "previous",
"work_start_date": "2018-06-01",
"work_end_date": "2019-12-31",
"work_city": "San Francisco",
"work_state": "CA",
"work_country": "US"
},
{
"experience_rank": 3,
"minerva_experience_id": "w-c3d4e5f6a7b8c9d0e1f2a3b4c5d6e7f8",
"work_company_name": "Financial Corp",
"work_company_linkedin_url": "https://www.linkedin.com/company/financial-corp",
"work_company_website": "https://financialcorp.com",
"work_company_industry": "Financial Services",
"work_company_naics_code": "523930",
"work_company_naics_description": "Investment Advice",
"work_company_sic_code": "6282",
"work_company_sic_description": "Investment Advice",
"work_title": "Junior Developer",
"standard_work_title": "Junior Developer",
"work_seniority_level": "Entry",
"work_department": "Technology",
"work_employment_type": "Full-Time",
"work_status": "previous",
"work_start_date": "2016-08-01",
"work_end_date": "2018-05-31",
"work_city": "New York",
"work_state": "NY",
"work_country": "US"
},
{
"experience_rank": 4,
"minerva_experience_id": "w-d4e5f6a7b8c9d0e1f2a3b4c5d6e7f8a9",
"work_company_name": "Financial Corp",
"work_company_linkedin_url": "https://www.linkedin.com/company/financial-corp",
"work_company_website": "https://financialcorp.com",
"work_company_industry": "Financial Services",
"work_company_naics_code": "523930",
"work_company_naics_description": "Investment Advice",
"work_company_sic_code": "6282",
"work_company_sic_description": "Investment Advice",
"work_title": "Summer Analyst",
"standard_work_title": "Summer Analyst",
"work_seniority_level": "Intern",
"work_department": "Technology",
"work_employment_type": "Part-Time",
"work_status": "previous",
"work_start_date": "2015-06-01",
"work_end_date": "2015-08-31",
"work_city": "New York",
"work_state": "NY",
"work_country": "US"
},
{
"experience_rank": 5,
"minerva_experience_id": "w-e5f6a7b8c9d0e1f2a3b4c5d6e7f8a9b0",
"work_company_name": "Tech Innovations",
"work_company_linkedin_url": "https://www.linkedin.com/company/tech-innovations",
"work_company_website": "https://techinnovations.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": "Software Engineering Intern",
"standard_work_title": "Software Engineering Intern",
"work_seniority_level": "Intern",
"work_department": "Engineering",
"work_employment_type": "Part-Time",
"work_status": "previous",
"work_start_date": "2014-06-01",
"work_end_date": "2014-08-31",
"work_city": "Seattle",
"work_state": "WA",
"work_country": "US"
},
{
"experience_rank": 6,
"minerva_experience_id": "w-f6a7b8c9d0e1f2a3b4c5d6e7f8a9b0c1",
"work_company_name": "Startup Labs",
"work_company_linkedin_url": null,
"work_company_website": null,
"work_company_industry": null,
"work_company_naics_code": null,
"work_company_naics_description": null,
"work_company_sic_code": null,
"work_company_sic_description": null,
"work_title": "Co-Founder",
"standard_work_title": "Co-Founder",
"work_seniority_level": "Executive",
"work_department": "Executive",
"work_employment_type": "Full-Time",
"work_status": "previous",
"work_start_date": "2013-01-01",
"work_end_date": "2013-12-31",
"work_city": null,
"work_state": null,
"work_country": null
},
{
"experience_rank": 7,
"minerva_experience_id": "w-a7b8c9d0e1f2a3b4c5d6e7f8a9b0c1d2",
"work_company_name": "Research Institute",
"work_company_linkedin_url": null,
"work_company_website": null,
"work_company_industry": null,
"work_company_naics_code": null,
"work_company_naics_description": null,
"work_company_sic_code": null,
"work_company_sic_description": null,
"work_title": "Research Assistant",
"standard_work_title": "Research Assistant",
"work_seniority_level": "Entry",
"work_department": "Research",
"work_employment_type": "Part-Time",
"work_status": "previous",
"work_start_date": "2012-09-01",
"work_end_date": "2013-05-31",
"work_city": null,
"work_state": null,
"work_country": null
},
{
"experience_rank": 8,
"minerva_experience_id": "w-b8c9d0e1f2a3b4c5d6e7f8a9b0c1d2e3",
"work_company_name": "Community Organization",
"work_company_linkedin_url": "https://www.linkedin.com/company/community-org",
"work_company_website": "https://communityorg.org",
"work_company_industry": "Nonprofit",
"work_company_naics_code": "813920",
"work_company_naics_description": "Professional Organizations",
"work_company_sic_code": "8621",
"work_company_sic_description": "Professional organizations",
"work_title": "Volunteer Coordinator",
"standard_work_title": "Volunteer Coordinator",
"work_seniority_level": "Entry",
"work_department": "Operations",
"work_employment_type": "Full-Time",
"work_status": "previous",
"work_start_date": "2011-06-01",
"work_end_date": "2011-11-30",
"work_city": null,
"work_state": null,
"work_country": null
},
{
"experience_rank": 9,
"minerva_experience_id": "w-c9d0e1f2a3b4c5d6e7f8a9b0c1d2e3f4",
"work_company_name": "Consulting Group",
"work_company_linkedin_url": "https://www.linkedin.com/company/consulting-group",
"work_company_website": "https://consultinggroup.com",
"work_company_industry": "Management Consulting",
"work_company_naics_code": "541614",
"work_company_naics_description": "Process, Physical Distribution, and Logistics Consulting Services",
"work_company_sic_code": "8742",
"work_company_sic_description": "Management consulting services",
"work_title": "Summer Intern",
"standard_work_title": "Summer Intern",
"work_seniority_level": "Intern",
"work_department": null,
"work_employment_type": "Part-Time",
"work_status": "previous",
"work_start_date": "2010-06-01",
"work_end_date": "2010-08-31",
"work_city": null,
"work_state": null,
"work_country": null
}
],
"education_experience": [
{
"experience_rank": 1,
"minerva_experience_id": "e-a1b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6",
"institution_name": "State University",
"institution_linkedin_url": "https://www.linkedin.com/school/state-university",
"education_information": "Bachelor of Science (B.S.), Computer Science",
"education_level": "Bachelors",
"education_majors": [
"Computer Science",
"Mathematics"
],
"education_minors": [],
"education_start_date": "2012-09-01",
"education_end_date": "2016-05-31"
}
],
"match_score": 110.0,
"validation_errors": null
}
]
}
{
"code": "bad_request",
"message": "Input data must contain a 'records' key with a list of inputs",
"api_request_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890"
}
{
"code": "unauthorized",
"message": "Unauthorized",
"api_request_id": "b2c3d4e5-f6a7-1234-bcde-f12345678901"
}
{
"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": "c3d4e5f6-a7b8-2345-cdef-123456789012",
"details": {
"records_available": 45,
"allowance_records_available": 45,
"overage_records_available": 0,
"records_requested": 250
}
}
{
"code": "payload_too_large",
"message": "Maximum number of records for /v1/enrich endpoint is 500",
"api_request_id": "d4e5f6a7-b8c9-3456-def0-234567890123"
}
{
"code": "unprocessable_entity",
"message": "Input data must contain a 'records' key with a list of inputs",
"api_request_id": "e5f6a7b8-c9d0-4567-ef01-345678901234"
}
{
"code": "rate_limit_reached",
"message": "You reached your total request-rate limit, please contact help@minerva.io for help",
"api_request_id": "f6a7b8c9-d0e1-5678-f012-456789012345"
}
Error Responses
400- Bad Request: Missing required fields or malformed JSON401- Unauthorized: Invalid or missing API key402- Payment Required: The new records exceed available plan allowance and monthly overage capacity.detailsincludesrecords_requested,records_available,allowance_records_available, andoverage_records_available. Increase the monthly spend limit or upgrade before retrying.413- Payload Too Large: More than 500 records in request422- Unprocessable Entity: Validation errors in record data (invalid field names, data types, or values)429- Too Many Requests: Rate limit exceeded500- Internal Server Error: Unexpected server error
Notes
- Maximum 500 records per request (lower than
/resolvedue to data volume) - All list fields (emails, phones, addresses, work, education) 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
Interpreting match_score
match_score is an additive point total, not a normalized 0-1 or 0-100
confidence. 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 every input email and phone that matches the person, weighted by how strongly that email or phone is associated with them
110.0.
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.
- Every record returned with
is_match: truealready cleared Minerva’s internal match threshold and scores at least 50. You don’t need your own floor unless you want to be stricter than Minerva. match_scoreisnullwhenis_matchis false.- Scores are rounded to two decimal places.
- Raising your own threshold trades recall for precision. If you need higher
precision, prefer
/v2/enrichwithmatch_condition_fields, which filters on data availability rather than on an opaque score.
Was this page helpful?