Resolve v2
Resolve
Resolve v2
Enhanced resolve with reverse lookup capabilities and match condition filters
POST
Resolve v2
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 bothRequest 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 fields401- Unauthorized: Invalid or missing API key402- Payment Required: Minerva credits exhausted. Response body includesrecords_remaining(estimated records remaining based on your credit balance) andrecords_requested(batch size that was rejected)413- Payload Too Large: More than 1000 records in request422- Unprocessable Entity: Invalid data format or invalidmatch_condition_fields429- Too Many Requests: Rate limit exceeded500- 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
- Provide exactly ONE email OR exactly ONE phone
- Do NOT provide name information
- Cannot provide both email and phone
Match Condition Fields
Usematch_condition_fields to filter results based on data availability:
minerva_pid- Only return matches where we have a Minerva PIDlinkedin_url- Only return matches where we have LinkedIn profile data
Response Fields
record_idis optional in requests and may be null in responseslinkedin_urlis 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
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.
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: falseand details invalidation_errors
Migration from V1
If you’re upgrading from V1:- URL changes from
/v1/resolveto/v2/resolve record_idis now optional (was required in V1)- Name is now optional if you provide contact information
- New
linkedin_urlfield in response - Use reverse lookup for faster email/phone-only matching
- Use
match_condition_fieldsto filter results by data availability - Match scores may differ slightly due to improved algorithm