> ## Documentation Index
> Fetch the complete documentation index at: https://docs.minerva.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Resolve v2

> Enhanced resolve with reverse lookup capabilities and match condition filters

<div style={{ display: 'none' }} aria-hidden="false">
  ## 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
</div>

## 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

<ParamField header="x-api-key" type="string" required>
  Your API key for authentication
</ParamField>

<ParamField header="Content-Type" type="string" required>
  application/json
</ParamField>

### Request Body

<ParamField body="records" type="object[]" required>
  An array of person records to resolve. Maximum 1000 records per request.

  <Expandable title="Record object properties">
    <ParamField body="record_id" type="string">
      Your unique identifier for this record (optional in V2)
    </ParamField>

    <ParamField body="first_name" type="string">
      Person's first name
    </ParamField>

    <ParamField body="middle_name" type="string">
      Person's middle name
    </ParamField>

    <ParamField body="last_name" type="string">
      Person's last name
    </ParamField>

    <ParamField body="full_name" type="string">
      Person's full name (alternative to first/last name)
    </ParamField>

    <ParamField body="name_suffix" type="string">
      Name suffix (e.g., "Jr.", "Sr.", "III")
    </ParamField>

    <ParamField body="emails" type="string[]">
      Array of email addresses
    </ParamField>

    <ParamField body="phones" type="string[]">
      Array of phone numbers
    </ParamField>
  </Expandable>
</ParamField>

<ParamField body="match_condition_fields" type="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_url`

  Example: `["linkedin_url"]` will only return matches that have a LinkedIn profile

  Example: `["minerva_pid", "linkedin_url"]` will only return matches that have both
</ParamField>

### Request Examples

#### Standard Fuzzy Matching

```json theme={null}
{
  "records": [
    {
      "record_id": "user_001",
      "first_name": "John",
      "last_name": "Smith",
      "emails": ["john.smith@example.com"],
      "phones": ["+1-555-123-4567"]
    }
  ]
}
```

#### Reverse Lookup (Email Only, No Name)

```json theme={null}
{
  "records": [
    {
      "record_id": "user_002",
      "emails": ["jane.doe@example.com"]
    }
  ]
}
```

#### Reverse Lookup (Phone Only, No Name)

```json theme={null}
{
  "records": [
    {
      "record_id": "user_003",
      "phones": ["+1-555-987-6543"]
    }
  ]
}
```

#### With Match Condition Filter

```json theme={null}
{
  "records": [
    {
      "first_name": "Jane",
      "last_name": "Doe",
      "emails": ["jane.doe@example.com"]
    }
  ],
  "match_condition_fields": ["linkedin_url"]
}
```

## Response

### Response Structure

<ResponseField name="api_request_id" type="string">
  Unique identifier for this API request
</ResponseField>

<ResponseField name="results" type="array">
  Array of resolution results, one per input record
</ResponseField>

<ResponseField name="request_completed_at" type="string">
  ISO 8601 timestamp when the request was completed
</ResponseField>

#### Result Object

<ResponseField name="record_id" type="string">
  Your identifier from the request (may be null if not provided)
</ResponseField>

<ResponseField name="is_match" type="boolean">
  Whether a match was found in the Minerva database
</ResponseField>

<ResponseField name="minerva_pid" type="string">
  Minerva person identifier (only present if is\_match is true)
</ResponseField>

<ResponseField name="linkedin_url" type="string">
  **New in V2**: LinkedIn profile URL (only present if is\_match is true and LinkedIn data is available)
</ResponseField>

<ResponseField name="match_score" type="number">
  Confidence score for the match (0-100 scale, only present if is\_match is true)
</ResponseField>

<ResponseField name="is_resolvable_record" type="boolean">
  Whether the input record had sufficient valid data to attempt resolution
</ResponseField>

<ResponseField name="validation_errors" type="object">
  Object containing any validation errors encountered with the input data
</ResponseField>

<Note>
  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`.)
</Note>

<ResponseExample>
  ```json 200 theme={null}
  {
    "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"
  }
  ```

  ```json 400 theme={null}
  {
    "code": "bad_request",
    "message": "Input data must contain a 'records' key with a list of inputs",
    "api_request_id": "8931445e-91f1-42c6-a53d-7381de862dc8"
  }
  ```

  ```json 401 theme={null}
  {
    "code": "unauthorized",
    "message": "Unauthorized",
    "api_request_id": "c1d2e3f4-a5b6-7890-cdef-1234567890ab"
  }
  ```

  ```json 402 theme={null}
  {
    "code": "insufficient_credits",
    "message": "Insufficient records budget — please purchase more credits",
    "api_request_id": "d4e5f6a7-b8c9-0123-def4-567890abcdef",
    "details": {
      "records_remaining": 23,
      "records_requested": 100
    }
  }
  ```

  ```json 413 theme={null}
  {
    "code": "payload_too_large",
    "message": "Maximum number of records for /v2/resolve endpoint is 1000",
    "api_request_id": "e5f6a7b8-c9d0-1234-ef56-7890abcdef01"
  }
  ```

  ```json 422 theme={null}
  {
    "code": "unprocessable_entity",
    "message": "Input data must be a JSON object",
    "api_request_id": "f6a7b8c9-d0e1-2345-f678-90abcdef0123"
  }
  ```
</ResponseExample>

## 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 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:

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