potarix-enricher

name	potarix-enricher
description	Find a company's website and verified work emails for people or whole companies via the Potarix Enricher API. Use when you need a company's official website from just its name, a person's verified work email from their name plus company or a LinkedIn URL, a decision-maker's email by role (ceo, sales, ops) at a domain, or a full company email roster. Trigger when a user asks to "find the website for X", "find an email for [person] at [company]", "get the CEO's email at [domain]", "turn this LinkedIn URL into an email", "scrape emails for [domain]", or "enrich this company". Agents can self-serve an API key with no browser.
compatibility	["claude-code","cursor","codex","windsurf","copilot"]
author	Potarix
version	1.0.0
homepage	https://enricher.potarix.com

Potarix Enricher

Pay-per-result company-data enrichment. Resolve a company name to its website, find a person's verified work email, recover a decision-maker by role, turn a LinkedIn URL into an email, scrape a company-wide email roster, or run the whole thing in one call.

Built for agents: you can mint your own API key over HTTP with no browser. New accounts get 25 free trial credits. Whiffed lookups (no result) are never charged. A repeat lookup of the same input by the same key is served from cache for free.

See references/endpoints.md for the full per-endpoint request/response reference, and references/openapi.yaml for the machine-readable OpenAPI 3.1 spec.

---

Base URL: https://api.potarix.com/enricher

Auth: every billable and account endpoint takes Authorization: Bearer ptk_live_xxx. Signup and login endpoints take no token.

---

Step 1: Get a key

Check for an existing key first. The convention is the POTARIX_API_KEY env var.

echo "POTARIX_API_KEY: ${POTARIX_API_KEY:-not set}"

If a key is already set, confirm it works and check the balance before spending:

curl -s https://api.potarix.com/enricher/me \
  -H "Authorization: Bearer $POTARIX_API_KEY"
# -> {"user_id":"...","email":"...","credits_remaining":861,"has_saved_card":true,...}

If no key is set, mint one. You need an email and a password (min 8 chars). The key is returned ONCE, so capture it immediately.

New account (grants 25 free trial credits):

curl -s -X POST https://api.potarix.com/enricher/auth/signup \
  -H "Content-Type: application/json" \
  -d '{"email":"[e-mail]","password":"a-strong-password","label":"my-agent"}'
# -> {"api_key":"ptk_live_xxx","credits_remaining":25,...}

If signup returns 409 (account already exists), mint a key for the existing account instead:

curl -s -X POST https://api.potarix.com/enricher/auth/api-keys \
  -H "Content-Type: application/json" \
  -d '{"email":"[e-mail]","password":"a-strong-password","label":"my-agent"}'
# -> {"api_key":"ptk_live_xxx",...}

Save the returned api_key to POTARIX_API_KEY for the rest of the session. Tell the user their key once and that it is shown only this one time. Do not invent a password for the user, ask them for one (or for an existing key).

---

Step 2: Run lookups

Pick the endpoint that matches the input you have. All are POST, all take JSON, all need the bearer header. Credit costs are charged only on a hit.

Company name -> website (2 credits)

curl -s -X POST https://api.potarix.com/enricher/find-website \
  -H "Authorization: Bearer $POTARIX_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"company_name":"Tycho","context":"company that raised funding"}'
# -> {"company_name":"Tycho","website_url":"https://tycho.ai","source":"website_guesser","confidence":0.92,"cached":false,"credits_remaining":998}

context is an optional hint to disambiguate namesakes (e.g. "company that raised funding", "new YC startup"). When passed, the shared cache is bypassed for that lookup. Returns 200 with website_url: null if nothing is found (no charge).

Person -> verified work email (25 credits)

Supply either first_name + last_name or full_name, plus either domain (preferred) or company_name.

curl -s -X POST https://api.potarix.com/enricher/find-email/person \
  -H "Authorization: Bearer $POTARIX_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"first_name":"Jane","last_name":"Doe","domain":"acme.com"}'
# -> {"email":"[e-mail]","email_status":"valid","source":"findymail","cached":false,"credits_remaining":973}

Runs a provider waterfall (Findymail, AnyMailFinder, Hunter, BetterContact). Returns 404 if no valid email is found across all providers (no charge).

Decision-maker by role -> email (25 credits)

Give a domain and a decision_maker_category. Common categories: ceo, sales, operations, buyer, finance, hr, marketing.

curl -s -X POST https://api.potarix.com/enricher/find-email/decision-maker \
  -H "Authorization: Bearer $POTARIX_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"decision_maker_category":"ceo","domain":"acme.com"}'
# -> {"name":"Jane Doe","email":"[e-mail]","linkedin_url":"https://www.linkedin.com/in/janedoe","job_title":"Chief Executive Officer","email_status":"valid","source":"anymailfinder","cached":false,"credits_remaining":948}

Returns 404 if no match for that role (no charge).

LinkedIn URL -> email (10 credits)

curl -s -X POST https://api.potarix.com/enricher/find-email/linkedin \
  -H "Authorization: Bearer $POTARIX_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"linkedin_url":"https://www.linkedin.com/in/janedoe"}'
# -> {"name":"Jane Doe","email":"[e-mail]","linkedin_url":"...","job_title":"...","email_status":"valid","source":"findymail","cached":false,"credits_remaining":938}

Returns 404 if no valid email (no charge).

Domain -> company-wide email roster (flat 25 credits)

curl -s -X POST https://api.potarix.com/enricher/find-email/company \
  -H "Authorization: Bearer $POTARIX_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"domain":"acme.com"}'
# -> {"emails":[{"email":"[e-mail]","name":"Jane Doe","title":"CEO","linkedin_url":"..."}],"count":2,"source":"hunter","cached":false,"credits_remaining":913}

Flat 25 credits no matter how many emails return (capped at 500). Returns 404 if no emails found (no charge).

Everything in one call (sum of the sub-calls)

find-all resolves the website, then fans out in parallel to scrape company emails and find decision-makers by role. Cost is the natural sum of the sub-calls that succeed; whiffed sub-calls cost zero. credits_charged reports the net for that specific call. Set skip_company_emails: true to skip the roster scrape and save 25 credits. dm_categories defaults to ceo, sales, operations; max 6.

curl -s -X POST https://api.potarix.com/enricher/find-all \
  -H "Authorization: Bearer $POTARIX_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"company_name":"Acme Inc","context":"company that raised funding","dm_categories":["ceo","sales"],"skip_company_emails":false}'
# -> {"company_name":"Acme Inc","domain":"acme.com","website":{...},"decision_makers":[...],"company_emails":[...],"total_emails":2,"credits_charged":52,"credits_remaining":861,"errors":[]}

Always returns 200 with whatever succeeded; partial failures are listed in the non-fatal errors array.

---

Step 3: Read the results

• cached: true means the result came from this key's cache and cost 0 credits. Always fine to re-run a lookup; you will not be double-charged for the same input.
• email_status is the verification verdict: valid is safe to send to; risky or unknown should be flagged to the user, not treated as confirmed.
• source tells you which provider produced the result (findymail, anymailfinder, hunter, bettercontact, website_guesser, serper). Useful for the user to gauge trust.
• credits_remaining is on every billable response. Surface it so the user knows their balance.
• A null website_url (find-website) or a 404 (the email endpoints) means "not found, not charged", not an error. Report it as a clean miss, not a failure.
• For find-all, report credits_charged (this call) and credits_remaining (balance), and mention anything in errors so the user knows a sub-lookup whiffed.

---

Errors and credits

• 401 invalid or missing key. Re-check POTARIX_API_KEY or mint a new one (Step 1).
• 402 insufficient credits. The body says how many are needed vs held. Top up (below), then retry.
• 400 bad request, usually a missing required field (e.g. domain is required). Fix the payload.
• 404 on an email endpoint is a clean miss, not a failure. No charge.

Topping up credits

Check the balance any time:

curl -s https://api.potarix.com/enricher/credits -H "Authorization: Bearer $POTARIX_API_KEY"

Buying credits needs a card on file. Stripe requires a human to enter the card in a browser exactly ONCE. After that, top-ups are silent. Do not attempt to enter card details yourself; hand the checkout URL to the user.

First top-up (returns a Stripe URL for the user to open once):

curl -s -X POST https://api.potarix.com/enricher/billing/checkout \
  -H "Authorization: Bearer $POTARIX_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"tier_key":"1k"}'
# -> {"url":"https://checkout.stripe.com/c/pay/cs_live_...","session_id":"..."}

Once a card is on file (has_saved_card: true from /me), buy more silently:

curl -s -X POST https://api.potarix.com/enricher/billing/topup \
  -H "Authorization: Bearer $POTARIX_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"tier_key":"1k"}'
# -> {"status":"succeeded","credits_added":1000,"credits_remaining":1861,...}

Tiers: 1k (1,000 credits / $10), 5k (5,000 / $50), 25k (25,000 / $250). If topup returns status: requires_action, hand the next_action_url to the user to confirm. If it returns 402 no_saved_card, do the checkout step first.

---

Notes

• There is also an optional zero-dependency CLI (potarix signup, potarix lookup, potarix find-email-decision-maker, etc.) at https://enricher.potarix.com/cli/potarix if a user prefers a command over raw curl. The HTTP flow above is the canonical path.
• Prefer domain over company_name on the email endpoints when you have it; it is more accurate.
• Batch work: loop single calls. There is no bulk endpoint; cache makes retries free.