Skip to main content
POST
Resolve v2

Quick Answer

How do I resolve a person’s identity? Use this endpoint to find someone’s Minerva PID (person identifier) and LinkedIn URL based on their name, email, or phone number.Common questions this endpoint answers:
  • How do I match a person to get their ID?
  • How do I find someone’s Minerva PID?
  • How do I look up a person by email?
  • How do I search for someone by phone number?
  • How do I get a person’s LinkedIn profile?
  • How can I identify someone from basic contact information?
  • How do I deduplicate or match records to unique people?
What you need: Name and/or contact information (email or phone).What you get back: Minerva PID (unique person identifier) and LinkedIn URL if available.Use cases:
  • Get a person’s PID to use with other endpoints (enrich, segments)
  • Match email addresses or phone numbers to unique individuals
  • Find LinkedIn profiles for contacts
  • Deduplicate customer records

Overview

The V2 Resolve endpoint provides enhanced identity resolution with two powerful matching modes: traditional fuzzy matching and reverse lookup. This version improves flexibility and adds LinkedIn URL to the response.

Key Enhancements in V2

  • Reverse Lookup: Resolve by single email or phone without requiring a name
  • LinkedIn URL: Returns LinkedIn profile URL in addition to Minerva PID
  • Match Condition Filters: Ensure matched records have specific data fields
  • Flexible Name Requirements: Name is optional when contact information is provided
  • Optional Record ID: Record ID is now optional for V2

Request

Headers

string
required
Your API key for authentication
string
required
application/json

Request Body

object[]
required
An array of person records to resolve. Maximum 1000 records per request.
string[]
New in V2: Optional list of fields that must be present in the matched record for it to be returned as a match. This filters results to only include matches that have these data fields available.Valid options: minerva_pid, linkedin_urlExample: ["linkedin_url"] will only return matches that have a LinkedIn profileExample: ["minerva_pid", "linkedin_url"] will only return matches that have both

Request Examples

Standard Fuzzy Matching

Reverse Lookup (Email Only, No Name)

Reverse Lookup (Phone Only, No Name)

With Match Condition Filter

Response

Response Structure

string
Unique identifier for this API request
array
Array of resolution results, one per input record
string
ISO 8601 timestamp when the request was completed

Result Object

string
Your identifier from the request (may be null if not provided)
boolean
Whether a match was found in the Minerva database
string
Minerva person identifier (only present if is_match is true)
string
New in V2: LinkedIn profile URL (only present if is_match is true and LinkedIn data is available)
number
Confidence score for the match, as an additive point total — not a 0-1 or 0-100 scale. Fuzzy matches score at least 50 and routinely exceed 100; reverse lookups are fixed at 50.0. null unless is_match is true. See Interpreting match_score.
boolean
Whether the input record had sufficient valid data to attempt resolution
object
Object containing any validation errors encountered with the input data
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.)

Error Responses

Common Errors

  • 400 - Bad Request: Invalid input format or missing required fields
  • 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 1000 records in request
  • 422 - Unprocessable Entity: Invalid data format or invalid match_condition_fields
  • 429 - Too Many Requests: Rate limit exceeded
  • 500 - Internal Server Error: Server error occurred

Notes

Matching Modes

V2 supports two distinct matching modes:

1. Fuzzy Matching Mode

  • Provide name information (first/last OR full_name) and/or contact information (emails/phones)
  • At least one of name or contact info must be provided
  • Uses advanced fuzzy matching algorithm
  • Returns an additive match_score — at least 50, and often above 100

2. Reverse Lookup Mode

  • Activated when: No name provided AND exactly one email OR exactly one phone
  • Performs direct lookup in unique matching database
  • Faster than fuzzy matching
  • Returns match score of 50.0 for reverse lookup matches
  • Does not support multiple emails or phones simultaneously

Input Requirements

For Fuzzy Matching:
  • Provide either name OR contact information (or both)
  • If providing name, must include both first_name and last_name (or full_name)
  • Can provide multiple emails and/or phones
For Reverse Lookup:
  • Provide exactly ONE email OR exactly ONE phone
  • Do NOT provide name information
  • Cannot provide both email and phone

Match Condition Fields

Use match_condition_fields to filter results based on data availability:
  • minerva_pid - Only return matches where we have a Minerva PID
  • linkedin_url - Only return matches where we have LinkedIn profile data
This is useful when you need to ensure the matched person has specific data fields available before considering them a valid match.

Response Fields

  • record_id is optional in requests and may be null in responses
  • linkedin_url is new in V2 and only returned when available

Interpreting match_score

match_score is an additive point total, not a normalized 0-1 or 0-100 confidence. For a fuzzy match it is the sum of two components:
  • Name — up to 60 points, based on how closely the input name matches the person’s known names and aliases
  • Contact info — points for 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. Every fuzzy match returned with is_match: true has already cleared Minerva’s internal threshold and scores at least 50.
Compare scores against each other, not against a fixed ceiling. Thresholding on a percentage (for example, “accept above 0.8” or “above 80%”) will not behave the way you expect.
Reverse lookups don’t run the scoring algorithm at all — they match a single email or phone directly — so they return a fixed 50.0. That value carries no information about match quality, and comparing it against a fuzzy score is meaningless. match_score is null when is_match is false, and scores are rounded to two decimal places. If you need stricter results, prefer match_condition_fields over a score threshold: it filters on which data is actually populated, which is both verifiable and stable across matching modes.

Validation

  • Phone numbers must be valid US phone numbers
  • Email addresses must be valid email format
  • Names must have at least first and last name components
  • Records that fail validation will have is_resolvable_record: false and details in validation_errors

Migration from V1

If you’re upgrading from V1:
  1. URL changes from /v1/resolve to /v2/resolve
  2. record_id is now optional (was required in V1)
  3. Name is now optional if you provide contact information
  4. New linkedin_url field in response
  5. Use reverse lookup for faster email/phone-only matching
  6. Use match_condition_fields to filter results by data availability
  7. Match scores may differ slightly due to improved algorithm