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

# Introduction

> Minerva API documentation

<div style={{ display: 'none' }} aria-hidden="false">
  ## What is the Minerva API?

  The Minerva API helps you **enrich people data** and **resolve identities** to build comprehensive customer profiles. Whether you need to find contact information, match records to unique individuals, or organize people into segments, Minerva provides the data and tools you need.

  **Common use cases:**

  * Enrich customer records with demographics, work history, and contact info
  * Match email addresses or names to unique person identifiers
  * Find email addresses and phone numbers for contacts
  * Build and manage segments for marketing campaigns
  * Monitor life events like deaths for list hygiene

  **Getting started is simple:**

  1. Get an API key from your account manager
  2. Use `/resolve` to match people and get their Minerva PID
  3. Use `/enrich` to get comprehensive profile data
  4. Create segments to organize and monitor cohorts
</div>

## Overview

The Minerva API provides person data enrichment and identity resolution services. Use our API to:

* **Resolve** person identities to unique Minerva PIDs
* **Enrich** profiles with demographics, work history, education, and contact information
* **Validate** email addresses and infer geographic locations
* **Segment** and organize people for tracking and analysis
* **Monitor** life event signals like address changes and death records

## Getting Started

### Authentication

All API requests require authentication using an API key in the `x-api-key` header:

```bash theme={null}
x-api-key: 'YOUR_STATIC_TOKEN'
```

#### Where to get your API key

<Steps>
  <Step title="Sign in">
    Log in at [app.minerva.io](https://app.minerva.io) (not available on the free tier).
  </Step>

  <Step title="Open Settings">
    Click your org name in the **bottom-left** → the three dots (`...`) → **Settings**.
  </Step>

  <Step title="Open the API tab">
    Open the **API** tab and copy your key. Treat it like a password.
  </Step>
</Steps>

### Base URLs

```
Production: https://api.minerva.io
```

### API Versions

We support two API versions:

* **v1**: Core resolve and enrich functionality
* **v2**: Enhanced features including segments, validation, and additional endpoints

Specify the version in the URL path: `/v1/resolve` or `/v2/segments/create`

## Core Concepts

### Minerva PID

The Minerva Person ID (PID) is a unique identifier for each person in our database. PIDs follow the format `p-{hash}`, for example: `p-a1b2c3d4e5f6`.

Use the `/resolve` or `/enrich` endpoints to obtain a Minerva PID from name and contact information.

### Resolution

Resolution matches your input data (name, email, phone) to a unique person in our database. Our matching algorithm uses:

* Fuzzy name matching
* Email and phone matching
* Address matching
* Confidence scoring

### Enrichment

Enrichment returns comprehensive profile data for a resolved person:

* Demographics (age, gender, marital status)
* Contact information (emails, phones)
* Address history with property details
* Work experience and employment data
* Education history
* Financial indicators (income range, wealth range)
* Social media profiles

### Segments

Segments are groups of people identified by Minerva PIDs. Use them to:

* Organize leads or customers
* Track specific cohorts
* Monitor life events and signals
* Export targeted lists

## API Endpoints

### Core Endpoints

**[Resolve](/api-reference/resolve)** → Match person identity to a unique Minerva PID

**[Enrich](/api-reference/enrich)** → Get comprehensive person profile data

**[Get LinkedIn Contact Info](/api-reference/get-li-contact-info)** → Retrieve contact info for LinkedIn profiles

### Validation Endpoints

**[Validate Emails](/api-reference/validate-emails)** → Verify email addresses in the Minerva database

**[Infer Record Country](/api-reference/infer-record-country)** → Determine country location from contact information

### Segments

**[Create Segment](/api-reference/segments-create)** → Create a new segment

**[Get Segment Members](/api-reference/segments-members)** → Retrieve members of a segment

**[Add Members](/api-reference/segments-members-add)** → Add people to a segment

**[Remove Members](/api-reference/segments-members-remove)** → Remove people from a segment

**[Death Signals](/api-reference/segments-signals-deaths)** → Get death signals for segment members

## Rate Limits

API rate limits vary by endpoint and subscription tier:

| Endpoint                   | Max Records per Request |
| -------------------------- | ----------------------- |
| `/v1/resolve`              | 1,000                   |
| `/v1/enrich`               | 500                     |
| `/v1/get_li_contact_info`  | 1,000                   |
| `/v2/validate_emails`      | 2,000                   |
| `/v2/infer_record_country` | 1,000                   |
| `/v2/segments/members`     | 5,000 per page          |

Contact your account manager for information about request rate limits.

## Response Format

Successful responses return:

```json theme={null}
{
  "api_request_id": "unique-request-identifier",
  "results": [...],
  "request_completed_at": "2024-01-15T10:30:45.123456Z"
}
```

## Error Handling

Errors return:

```json theme={null}
{
  "api_request_id": "unique-request-identifier",
  "error_message": "Description of the error"
}
```

### Common HTTP Status Codes

* `200` - Success
* `400` - Bad Request (invalid input)
* `401` - Unauthorized (invalid API key)
* `402` - Payment Required (Minerva credits exhausted — `records_remaining` in the response body is an estimate of how many records you have left)
* `404` - Not Found (resource doesn't exist)
* `413` - Payload Too Large (exceeded record limit)
* `422` - Unprocessable Entity (validation error)
* `429` - Too Many Requests (rate limit exceeded)
* `500` - Internal Server Error

## Best Practices

### Batch Requests

Batch multiple records in a single request rather than making individual calls:

```javascript theme={null}
// Good: Batch multiple records together
POST https://api.minerva.io/v1/resolve
{
  "records": [
    { "record_id": "1", ... },
    { "record_id": "2", ... },
    { "record_id": "3", ... }
  ]
}

// Avoid: Separate requests for each record
POST https://api.minerva.io/v1/resolve { "records": [{ "record_id": "1", ... }] }
POST https://api.minerva.io/v1/resolve { "records": [{ "record_id": "2", ... }] }
```

### Handle Partial Failures

Individual records can fail validation while others succeed. Check the `is_match` and `validation_errors` fields:

```javascript theme={null}
response.results.forEach(result => {
  if (result.is_match) {
    // Process successful match
  } else if (result.validation_errors) {
    // Handle validation errors
  } else {
    // No match found
  }
});
```

### Use Record IDs

Include unique `record_id` values to match responses back to your source data:

```json theme={null}
{
  "records": [
    {
      "record_id": "customer_12345",
      "first_name": "John",
      "last_name": "Smith"
    }
  ]
}
```

### Provide More Data for Better Matches

More input data improves match rates:

* Name + Email + Phone (best)
* Name + Email (good)
* Name + Phone (good)

## Support

For technical support or questions:

* Email: [help@minerva.io](mailto:help@minerva.io)
* Documentation: [https://docs.minerva.io](https://docs.minerva.io)
* Status Page: [https://status.minerva.io](https://status.minerva.io)

## Changelog

### v2 (Current)

* Added segments management endpoints
* Added email validation endpoint
* Added country inference endpoint
* Enhanced death signals monitoring

### v1

* Initial release with resolve and enrich endpoints
* LinkedIn contact information lookup