Skip to main content
POST
/
v1
/
resolve
Resolve v1
curl --request POST \
  --url https://api.minerva.io/v1/resolve \
  --header 'Content-Type: <content-type>' \
  --header 'x-api-key: <api-key>' \
  --data '
{
  "records": [
    {
      "record_id": "<string>",
      "first_name": "<string>",
      "middle_name": "<string>",
      "last_name": "<string>",
      "full_name": "<string>",
      "name_suffix": "<string>",
      "emails": [
        "<string>"
      ],
      "phones": [
        "<string>"
      ]
    }
  ]
}
'
{
  "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"
}

​
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.

​
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

​
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.

​
Request Example

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

​
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
​
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)
​
match_score
number
Confidence score for the match (0-1 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
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.
{
  "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"
}

​
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