Skip to main content
1

Install

pip install minerva-sdk
Python 3.11+ (tested through 3.14).
2

Set your API key

export MINERVA_API_KEY=mk_live_...
The SDK reads MINERVA_API_KEY from the environment by default. You can also pass it as a constructor arg (handy in tests / notebooks):
mc = Minerva(api_key="mk_live_...")
3

Resolve, enrich

from minerva import Minerva

mc = Minerva()

# Resolve — match records to a Minerva PID (lighter / cheaper than enrich)
match = mc.api.resolve([
    {"record_id": "1", "first_name": "Jane", "last_name": "Doe",
     "emails": ["jane.doe@example.com"]}
])
for r in match.results:
    print(r.record_id, r.is_match, r.minerva_pid, r.match_score)

# Enrich — full person profiles (up to 500 records per call)
people = mc.api.enrich([
    {"record_id": "1", "linkedin_url": "https://www.linkedin.com/in/example"}
])
people.to_df()          # straight to a pandas DataFrame (needs [pandas])
people.to_csv("out.csv")
4

Explore from the terminal

python -m minerva         # banner + cheat-sheet of every namespace
python -m minerva --help  # argparse help with usage epilog
From a REPL:
>>> from minerva import Minerva
>>> help(Minerva)               # full class docstring
>>> help(Minerva.api)           # the data-API namespace

​
What you get

`mc.api`

resolve · enrich · get_li_contact_info · validate_emails · infer_record_country · call

`mc.usage`

tallies() — your per-endpoint API usage

`mc.status`

health() — unauthenticated liveness probe

`mc.io`

enrich_from_sheet / _excel — run the Data API directly off spreadsheets

​
Validate before you call

Every input-bearing method accepts dry_run=True — validates input locally and returns the exact request that would be sent, without spending a credit: 
req = mc.api.enrich(records, dry_run=True)
# -> EnrichRequest (nothing sent); inspect req.model_dump()
See Validation & dry_run for the full pattern.