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 thex-api-key header:
Create an API key
1
Sign in
Sign in at app.minerva.io and switch to the organization you want to use.
2
Open Settings
Open your account menu in the bottom-left, select Settings, then API.
3
Choose a key type
Choose Personal for a key tied to your account, or Organization for an organization-owned key.
4
Create the key
Select Create API key, enter a Name, and choose an Expiration. Select Create API key again to create it.
5
Copy your key
Copy the key when it is shown and store it securely.
The Legacy tab lets you revoke an existing Legacy key. It does not show the full key or let you create a new Legacy key.
For a Personal or Organization key, open its API key actions menu and select Revoke key. Revocation cannot be undone. Access may continue briefly while revocation takes effect.
Base URLs
Static egress IPs
Outbound traffic from Minerva — activation pushes, webhooks, and any other Minerva-initiated callback to your endpoints — originates from a fixed set of static IPs. If your security policy requires whitelisting third-party traffic, allow these three addresses on inbound rules:You don’t need to allow these IPs to call the Minerva API — outbound traffic
from your side to
api.minerva.io works through normal HTTPS without any
allowlist. The list above only matters for traffic Minerva sends to your
systems (activations / webhooks). If you don’t receive Minerva-initiated
traffic, you can ignore this section.API Versions
We support two API versions:- v1: Core resolve and enrich functionality
- v2: Enhanced features including segments, validation, and additional endpoints
/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 formatp-{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 profilesValidation Endpoints
Validate Emails → Verify email addresses in the Minerva database Infer Record Country → Determine country location from contact informationSegments
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 membersRate Limits
API rate limits vary by endpoint and subscription tier:
Contact your account manager for information about request rate limits.
Response Format
Successful responses return:Error Handling
Errors return:Common HTTP Status Codes
200- Success400- Bad Request (invalid input)401- Unauthorized (invalid API key)402- Payment Required: Insufficient record export capacity (insufficient_record_capacity). The response includes available allowance and overage records; increase your monthly spend limit or upgrade before retrying.404- Not Found (resource doesn’t exist)413- Payload Too Large (exceeded record limit)422- Unprocessable Entity (validation error)429- Too Many Requests (rate limit exceeded)500- Internal Server Error
Best Practices
Batch Requests
Batch multiple records in a single request rather than making individual calls:Handle Partial Failures
Individual records can fail validation while others succeed. Check theis_match and validation_errors fields:
Use Record IDs
Include uniquerecord_id values to match responses back to your source data:
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:- Email: help@minerva.io
- Documentation: https://docs.minerva.io
- Status Page: https://status.minerva.io
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