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

x-api-key

string

required

Your API key for authentication

Content-Type

string

required

application/json

Request Body

records

object[]

required

An array of person records to resolve. Maximum 1000 records per request.

Show Record object properties

record_id

string

Your unique identifier for this record (optional in V2)

first_name

string

Person’s first name

middle_name

string

Person’s middle name

last_name

string

Person’s last name

full_name

string

Person’s full name (alternative to first/last name)

name_suffix

string

Name suffix (e.g., “Jr.”, “Sr.”, “III”)

emails

string[]

Array of email addresses

phones

string[]

Array of phone numbers

match_condition_fields

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

{
  "records": [
    {
      "record_id": "user_001",
      "first_name": "John",
      "last_name": "Smith",
      "emails": ["[email protected]"],
      "phones": ["+1-555-123-4567"]
    }
  ]
}

Reverse Lookup (Email Only, No Name)

{
  "records": [
    {
      "record_id": "user_002",
      "emails": ["[email protected]"]
    }
  ]
}

Reverse Lookup (Phone Only, No Name)

{
  "records": [
    {
      "record_id": "user_003",
      "phones": ["+1-555-987-6543"]
    }
  ]
}

With Match Condition Filter

{
  "records": [
    {
      "first_name": "Jane",
      "last_name": "Doe",
      "emails": ["[email protected]"]
    }
  ],
  "match_condition_fields": ["linkedin_url"]
}

Response

Response Structure

api_request_id

string

Unique identifier for this API request

results

array

Array of resolution results, one per input record

request_completed_at

string

ISO 8601 timestamp when the request was completed

Result Object

record_id

string

Your identifier from the request (may be null if not provided)

is_match

boolean

Whether a match was found in the Minerva database

minerva_pid

string

Minerva person identifier (only present if is_match is true)

linkedin_url

string

New in V2: LinkedIn profile URL (only present if is_match is true and LinkedIn data is available)

match_score

number

Confidence score for the match (0-100 scale, only present if is_match is true)

is_resolvable_record

boolean

Whether the input record had sufficient valid data to attempt resolution

validation_errors

object

Object containing any validation errors encountered with the input data

{
  "api_request_id": "req_abc123xyz",
  "results": [
    {
      "record_id": "user_001",
      "is_match": true,
      "minerva_pid": "p-a1b2c3d4e5f6g7h8i9j0",
      "linkedin_url": "https://www.linkedin.com/in/johnsmith",
      "match_score": 110.0,
      "is_resolvable_record": true,
      "validation_errors": {}
    },
    {
      "record_id": "user_002",
      "is_match": true,
      "minerva_pid": "p-b2c3d4e5f6a7b8c9d0e1",
      "linkedin_url": "https://www.linkedin.com/in/janedoe",
      "match_score": 50.0,
      "is_resolvable_record": true,
      "validation_errors": {}
    },
    {
      "record_id": "user_003",
      "is_match": false,
      "minerva_pid": null,
      "linkedin_url": null,
      "match_score": null,
      "is_resolvable_record": true,
      "validation_errors": {}
    }
  ],
  "request_completed_at": "2025-11-12T19:19:25.679685+00:00"
}

Error Responses

Common Errors

400 - Bad Request: Invalid input format or missing required fields
401 - Unauthorized: Invalid or missing API key
413 - Payload Too Large: More than 1000 records in request
422 - Unprocessable Entity: Invalid data format or invalid match_condition_fields
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 match scores based on confidence (typically 0-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
match_score for reverse lookups is fixed at 50.0
match_score for fuzzy matches ranges from 0-100, with scores above 80 indicating high confidence

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:

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

Getting Started

Core Endpoints

Validation Workflows

Segments

Quick Answer

Overview

Key Enhancements in V2

Request

Headers

Request Body

Request Examples

Standard Fuzzy Matching

Reverse Lookup (Email Only, No Name)

Reverse Lookup (Phone Only, No Name)

With Match Condition Filter

Response

Response Structure

Result Object

Error Responses

Common Errors

Notes

Matching Modes

1. Fuzzy Matching Mode

2. Reverse Lookup Mode

Input Requirements

Match Condition Fields

Response Fields

Validation

Migration from V1

Getting Started

Core Endpoints

Validation Workflows

Segments

​Quick Answer

​Overview

​Key Enhancements in V2

​Request

​Headers

​Request Body

​Request Examples

​Standard Fuzzy Matching

​Reverse Lookup (Email Only, No Name)

​Reverse Lookup (Phone Only, No Name)

​With Match Condition Filter

​Response

​Response Structure

​Result Object

​Error Responses

​Common Errors

​Notes

​Matching Modes

​1. Fuzzy Matching Mode

​2. Reverse Lookup Mode

​Input Requirements

​Match Condition Fields

​Response Fields

​Validation

​Migration from V1

Quick Answer

Overview

Key Enhancements in V2

Request

Headers

Request Body

Request Examples

Standard Fuzzy Matching

Reverse Lookup (Email Only, No Name)

Reverse Lookup (Phone Only, No Name)

With Match Condition Filter

Response

Response Structure

Result Object

Error Responses

Common Errors

Notes

Matching Modes

1. Fuzzy Matching Mode

2. Reverse Lookup Mode

Input Requirements

Match Condition Fields

Response Fields

Validation

Migration from V1