potarix-enricher 0.1.0

Typed Python client for the Potarix Enricher API (company-name to website, verified work emails, decision-maker lookup, company email rosters).

potarix-enricher (Python)

Typed client for the Potarix Enricher API. 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

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 or headlessly via POST /auth/signup. New accounts get 25 free trial credits.

Quick start

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

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

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