Metadata-Version: 2.4
Name: potarix-enricher
Version: 0.1.0
Summary: Typed Python client for the Potarix Enricher API (company-name to website, verified work emails, decision-maker lookup, company email rosters).
Project-URL: Homepage, https://enricher.potarix.com
Author: Potarix
License: MIT
Keywords: company-data,decision-maker,email-finder,enricher,lead-enrichment,potarix
Requires-Python: >=3.8
Requires-Dist: requests>=2.25
Description-Content-Type: text/markdown

# potarix-enricher (Python)

Typed client for the [Potarix Enricher API](https://enricher.potarix.com). Resolve a company name to its website, find verified work emails, recover decision-maker contacts from a domain, turn a LinkedIn URL into an email, scrape a company-wide email roster, or run the whole enricher in one call.

## Install

```bash
pip install potarix-enricher
```

## Auth

Every call uses a Potarix API key that starts with `ptk_live_`, sent as a bearer token. Mint one at [enricher.potarix.com](https://enricher.potarix.com) or headlessly via `POST /auth/signup`. New accounts get 25 free trial credits.

## Quick start

```python
import os
from potarix_enricher import PotarixEnricher

client = PotarixEnricher(os.environ["POTARIX_API_KEY"])

# Resolve a company name to its website (2 credits)
site = client.find_website("Tycho", context="company that raised funding")
print(site.website_url, site.confidence, site.credits_remaining)

# Find a person's verified work email (25 credits on a hit)
person = client.find_email_person(first_name="Jane", last_name="Doe", domain="acme.com")
print(person.email, person.email_status, person.source)

# Find a decision-maker by role (25 credits on a hit)
dm = client.find_email_decision_maker(decision_maker_category="ceo", domain="acme.com")
print(dm.name, dm.email, dm.job_title)

# LinkedIn URL to email (10 credits on a hit)
li = client.find_email_linkedin("https://www.linkedin.com/in/janedoe")
print(li.email)

# Company-wide email roster (flat 25 credits)
roster = client.find_email_company("acme.com")
print(roster.count, [e.email for e in roster.emails])

# Everything in one call (cost = sum of the sub-calls that hit)
result = client.find_all("Acme Inc", dm_categories=["ceo", "sales"])
print(result.website.url, result.decision_makers, result.credits_charged)

# Account
me = client.me()            # profile + balance + has_saved_card
bal = client.credits()      # just the balance
print(me.credits_remaining, bal.total_purchased)
```

## Constructor

```python
PotarixEnricher(
    api_key: str,
    base_url: str = "https://api.potarix.com/enricher",
    timeout: float = 60.0,
    session: requests.Session | None = None,
)
```

## Methods and credit costs

| Method | Endpoint | Credits |
| --- | --- | --- |
| `find_website(company_name, context=None)` | `POST /find-website` | 2 |
| `find_email_person(first_name=, last_name=, full_name=, domain=, company_name=)` | `POST /find-email/person` | 25 (on hit) |
| `find_email_decision_maker(decision_maker_category, domain)` | `POST /find-email/decision-maker` | 25 (on hit) |
| `find_email_linkedin(linkedin_url)` | `POST /find-email/linkedin` | 10 (on hit) |
| `find_email_company(domain)` | `POST /find-email/company` | 25 (flat) |
| `find_all(company_name, context=None, dm_categories=None, skip_company_emails=False)` | `POST /find-all` | sum of sub-calls |
| `me()` | `GET /me` | 0 |
| `credits()` | `GET /credits` | 0 |

Whiffed lookups (no result) are not charged. A repeat lookup of the same input by the same caller is served from cache for free (`cached` is True).

Every response object also carries a `.raw` dict with the unparsed JSON payload, so a field added to the API later is reachable even before the model is updated.

## Errors

Non-2xx responses raise `PotarixEnricherError` with `.status` (HTTP code) and `.body` (parsed response). Common cases: 401 (bad key), 402 (insufficient credits), 404 (no email found, on the find-email endpoints).

```python
from potarix_enricher import PotarixEnricher, PotarixEnricherError

try:
    client.find_email_person(full_name="Jane Doe", domain="acme.com")
except PotarixEnricherError as err:
    if err.status == 404:
        print("No email found")
    elif err.status == 402:
        print("Out of credits")
    else:
        raise
```

## License

MIT
