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

> Resolve person identity from name and contact information to a Minerva PID

<div style={{ display: 'none' }} aria-hidden="false">
  ## Quick Answer

  **How do I resolve a person's identity?** Use this endpoint to match a person to their unique Minerva PID (person identifier) using their name and contact information.

  **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 identify someone from their name and email?
  * How can I deduplicate or match records?
  * How do I get a unique identifier for a contact?

  **What you need:** Name (first + last or full name) AND contact information (email or phone).

  **What you get back:** Minerva PID (unique person identifier) and match confidence score.

  **Note:** Consider upgrading to `/v2/resolve` for more flexible matching options including reverse lookup by email or phone only.
</div>

## Overview

The Resolve endpoint matches person identity data (name, email, phone) to a unique Minerva Person ID (minerva\_pid). This is typically the first step before enriching person data. This endpoint uses fuzzy matching to handle variations in names and contact information.

## 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" required>
      Your unique identifier for this record
    </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>

### Request Example

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

## 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
</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="match_score" type="number">
  Confidence score for the match (0-1 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 reading the HTTP status code and the top-level `api_request_id` / `error_message` fields directly.
</Note>

<ResponseExample>
  ```json 200 theme={null}
  {
    "api_request_id": "req_xyz789abc",
    "results": [
      {
        "record_id": "user_001",
        "is_match": true,
        "minerva_pid": "p-a1b2c3d4e5f6g7h8i9j0",
        "match_score": 110.0,
        "is_resolvable_record": true,
        "validation_errors": null
      },
      {
        "record_id": "user_002",
        "is_match": false,
        "minerva_pid": null,
        "match_score": null,
        "is_resolvable_record": true,
        "validation_errors": null
      }
    ],
    "request_completed_at": "2025-11-12T19:19:37.061415+00:00"
  }
  ```

  ```json 400 theme={null}
  {
    "api_request_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "error_message": "Input data must contain a 'records' key with a list of inputs"
  }
  ```

  ```json 401 theme={null}
  {
    "api_request_id": "b2c3d4e5-f6a7-1234-bcde-f12345678901",
    "error_message": "Unauthorized"
  }
  ```

  ```json 402 theme={null}
  {
    "api_request_id": "c3d4e5f6-a7b8-2345-cdef-123456789012",
    "error_message": "Insufficient records budget — please purchase more credits",
    "records_remaining": 23,
    "records_requested": 100
  }
  ```

  ```json 413 theme={null}
  {
    "api_request_id": "d4e5f6a7-b8c9-3456-def0-234567890123",
    "error_message": "Maximum number of records for /v1/resolve endpoint is 1000"
  }
  ```

  ```json 422 theme={null}
  {
    "api_request_id": "e5f6a7b8-c9d0-4567-ef01-345678901234",
    "error_message": "Input data must contain a 'records' key with a list of inputs"
  }
  ```

  ```json 429 theme={null}
  {
    "api_request_id": "f6a7b8c9-d0e1-5678-f012-456789012345",
    "error_message": "You reached your total request-rate limit, please contact help@minerva.io for help"
  }
  ```
</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
* `429` - Too Many Requests: Rate limit exceeded
* `500` - Internal Server Error: Server error occurred

## Notes

### Input Requirements

* **Name**: Required - provide either (`first_name` AND `last_name`) OR `full_name`
* **Contact**: Required - provide at least one `emails` or `phones`
* Both name and contact information are required for V1 resolve

### Matching Quality

* The matching algorithm uses fuzzy matching to handle variations in names and contact information
* Match scores above 0.8 typically indicate high confidence matches
* Providing both accurate name and contact information improves match accuracy

### Migration to V2

Consider upgrading to V2 for:

* Reverse lookup capabilities (email or phone only, no name required)
* LinkedIn URL in response
* Match condition filters to ensure data availability