Enrich v1

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_credits",
  "message": "Insufficient records budget — please purchase more credits",
  "api_request_id": "c3d4e5f6-a7b8-2345-cdef-123456789012",
  "details": {
    "records_remaining": 45,
    "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"
}

POST

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_credits",
  "message": "Insufficient records budget — please purchase more credits",
  "api_request_id": "c3d4e5f6-a7b8-2345-cdef-123456789012",
  "details": {
    "records_remaining": 45,
    "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"
}

Overview

The Enrich 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. Note: Consider upgrading to /v2/enrich for direct PID/LinkedIn lookups, selective field returns, and improved performance.

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.

Show Record object properties

string

required

Your unique identifier for this record

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

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)

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 of personal email addresses with ranking

Show Email object properties

integer

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

string

Email address

array

Array of professional email addresses with ranking

Show Email object properties

integer

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

string

Email address

array

Array of phone numbers with type and ranking

Show Phone object properties

integer

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

string

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

string

Phone number

Result Object - Address History

array

Array of address records with property details

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

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

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_credits",
  "message": "Insufficient records budget — please purchase more credits",
  "api_request_id": "c3d4e5f6-a7b8-2345-cdef-123456789012",
  "details": {
    "records_remaining": 45,
    "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 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 field names, data types, or values)
429 - Too Many Requests: Rate limit exceeded
500 - Internal Server Error: Unexpected server error

Notes

Maximum 500 records per request (lower than /resolve due 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

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. The example above scores 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.

Practical guidance:

Every record returned with is_match: true already 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_score is null when is_match is false.
Scores are rounded to two decimal places.
Raising your own threshold trades recall for precision. If you need higher precision, prefer /v2/enrich with match_condition_fields, which filters on data availability rather than on an opaque score.

⌘I

Getting Started

Core Endpoints

Validation Workflows

Person Search

Usage

Storage

Segments

Quick Answer

Overview

Request

Headers

Request Body

Request Example

Response

Response Structure

Result Object - Demographics

Result Object - Financial

Result Object - Legal Records

Result Object - Contact Information

Result Object - Address History

Result Object - Work Experience

Result Object - Education

Result Object - Other Fields

Error Responses

Notes

Interpreting `match_score`

​Quick Answer

​Overview

​Request

​Headers

​Request Body

​Request Example

​Response

​Response Structure

​Result Object - Demographics

​Result Object - Financial

​Result Object - Social & Professional

​Result Object - Legal Records

​Result Object - Contact Information

​Result Object - Address History

​Result Object - Work Experience

​Result Object - Education

​Result Object - Other Fields

​Error Responses

​Notes

​Interpreting match_score

Quick Answer

Overview

Request

Headers

Request Body

Request Example

Response

Response Structure

Result Object - Demographics

Result Object - Financial

Result Object - Social & Professional

Result Object - Legal Records

Result Object - Contact Information

Result Object - Address History

Result Object - Work Experience

Result Object - Education

Result Object - Other Fields

Error Responses

Notes

Interpreting `match_score`