Skip to main content

​
What is the Minerva API?

The Minerva API helps you enrich people data and resolve identities to build comprehensive customer profiles. Whether you need to find contact information, match records to unique individuals, or organize people into segments, Minerva provides the data and tools you need.Common use cases:
  • Enrich customer records with demographics, work history, and contact info
  • Match email addresses or names to unique person identifiers
  • Find email addresses and phone numbers for contacts
  • Build and manage segments for marketing campaigns
  • Monitor life events like deaths for list hygiene
Getting started is simple:
  1. Get an API key from your account manager
  2. Use /resolve to match people and get their Minerva PID
  3. Use /enrich to get comprehensive profile data
  4. Create segments to organize and monitor cohorts

​
Overview

The Minerva API provides person data enrichment and identity resolution services. Use our API to:
  • Resolve person identities to unique Minerva PIDs
  • Enrich profiles with demographics, work history, education, and contact information
  • Validate email addresses and infer geographic locations
  • Segment and organize people for tracking and analysis
  • Monitor life event signals like address changes and death records

​
Getting Started

​
Authentication

All API requests require authentication using an API key in the x-api-key header: 
x-api-key: 'YOUR_STATIC_TOKEN'
Contact your Minerva account manager to obtain your API key.

​
Base URLs

Production: https://api.minerva.com

​
API Versions

We support two API versions:
  • v1: Core resolve and enrich functionality
  • v2: Enhanced features including segments, validation, and additional endpoints
Specify the version in the URL path: /v1/resolve or /v2/segments/create

​
Core Concepts

​
Minerva PID

The Minerva Person ID (PID) is a unique identifier for each person in our database. PIDs follow the format p-{hash}, for example: p-a1b2c3d4e5f6. Use the /resolve or /enrich endpoints to obtain a Minerva PID from name and contact information.

​
Resolution

Resolution matches your input data (name, email, phone) to a unique person in our database. Our matching algorithm uses:
  • Fuzzy name matching
  • Email and phone matching
  • Address matching
  • Confidence scoring

​
Enrichment

Enrichment returns comprehensive profile data for a resolved person:
  • Demographics (age, gender, marital status)
  • Contact information (emails, phones)
  • Address history with property details
  • Work experience and employment data
  • Education history
  • Financial indicators (income range, wealth range)
  • Social media profiles

​
Segments

Segments are groups of people identified by Minerva PIDs. Use them to:
  • Organize leads or customers
  • Track specific cohorts
  • Monitor life events and signals
  • Export targeted lists

​
API Endpoints

​
Core Endpoints

Resolve → Match person identity to a unique Minerva PID Enrich → Get comprehensive person profile data Get LinkedIn Contact Info → Retrieve contact info for LinkedIn profiles

​
Validation Endpoints

Validate Emails → Verify email addresses in the Minerva database Infer Record Country → Determine country location from contact information

​
Segments

Create Segment → Create a new segment Get Segment Members → Retrieve members of a segment Add Members → Add people to a segment Remove Members → Remove people from a segment Death Signals → Get death signals for segment members

​
Rate Limits

API rate limits vary by endpoint and subscription tier:
EndpointMax Records per Request
/v1/resolve1,000
/v1/enrich500
/v1/get_li_contact_info1,000
/v2/validate_emails2,000
/v2/infer_record_country1,000
/v2/segments/members5,000 per page
Contact your account manager for information about request rate limits.

​
Response Format

Successful responses return: 
{
  "api_request_id": "unique-request-identifier",
  "results": [...],
  "request_completed_at": "2024-01-15T10:30:45.123456Z"
}

​
Error Handling

Errors return: 
{
  "error": "Description of the error",
  "status_code": 400
}

​
Common HTTP Status Codes

  • 200 - Success
  • 400 - Bad Request (invalid input)
  • 401 - Unauthorized (invalid API key)
  • 404 - Not Found (resource doesn’t exist)
  • 413 - Payload Too Large (exceeded record limit)
  • 422 - Unprocessable Entity (validation error)
  • 500 - Internal Server Error

​
Best Practices

​
Batch Requests

Batch multiple records in a single request rather than making individual calls: 
// Good: Batch multiple records together
POST https://api.minerva.io/v1/resolve
{
  "records": [
    { "record_id": "1", ... },
    { "record_id": "2", ... },
    { "record_id": "3", ... }
  ]
}

// Avoid: Separate requests for each record
POST https://api.minerva.io/v1/resolve { "records": [{ "record_id": "1", ... }] }
POST https://api.minerva.io/v1/resolve { "records": [{ "record_id": "2", ... }] }

​
Handle Partial Failures

Individual records can fail validation while others succeed. Check the is_match and validation_errors fields: 
response.results.forEach(result => {
  if (result.is_match) {
    // Process successful match
  } else if (result.validation_errors) {
    // Handle validation errors
  } else {
    // No match found
  }
});

​
Use Record IDs

Include unique record_id values to match responses back to your source data: 
{
  "records": [
    {
      "record_id": "customer_12345",
      "first_name": "John",
      "last_name": "Smith"
    }
  ]
}

​
Provide More Data for Better Matches

More input data improves match rates:
  • Name + Email + Phone (best)
  • Name + Email (good)
  • Name + Phone (good)

​
Support

For technical support or questions:

​
Changelog

​
v2 (Current)

  • Added segments management endpoints
  • Added email validation endpoint
  • Added country inference endpoint
  • Enhanced death signals monitoring

​
v1

  • Initial release with resolve and enrich endpoints
  • LinkedIn contact information lookup