# Potarix Enricher - Full Reference (llms-full.txt)

> Long-form machine-readable reference for the Potarix Enricher API. A small REST API for company websites, verified emails, LinkedIn-to-email, and company email discovery. Built for AI agents: one auth header, JSON in and JSON out, no subscription, credits never expire.

Homepage: https://enricher.potarix.com
Base URL: https://api.potarix.com/enricher
OpenAPI spec: https://enricher.potarix.com/openapi.yaml
Agent guide: https://enricher.potarix.com/AGENTS.md
Short crawler summary: https://enricher.potarix.com/llms.txt
Agent card (A2A): https://enricher.potarix.com/.well-known/agent-card.json
Pricing (machine-readable): https://enricher.potarix.com/pricing.md

## Links

- [Homepage](https://enricher.potarix.com)
- [OpenAPI spec](https://enricher.potarix.com/openapi.yaml)
- [Agent guide (AGENTS.md)](https://enricher.potarix.com/AGENTS.md)
- [Authentication reference](https://enricher.potarix.com/auth.md)
- [Pricing (machine-readable)](https://enricher.potarix.com/pricing.md)
- [Short crawler summary (llms.txt)](https://enricher.potarix.com/llms.txt)
- [A2A agent card](https://enricher.potarix.com/.well-known/agent-card.json)
- [MCP discovery manifest](https://enricher.potarix.com/.well-known/mcp.json)
- [Hosted MCP server (Streamable HTTP)](https://api.potarix.com/mcp)
- [MCP server source (GitHub)](https://github.com/Potarix/potarix-mcp)
- [Agent skill (GitHub)](https://github.com/Potarix/potarix-enricher)
- [npm package: potarix-mcp](https://www.npmjs.com/package/potarix-mcp)

## What it is

Potarix Enricher exposes a few exact enrichment primitives instead of a broad dashboard. Six billable endpoints plus account/billing endpoints. Buyers pay per lookup with no minimum commitment. Operated by Potarix Labs.

## Authentication

Every billable and account endpoint takes a bearer token: an API key that starts with `ptk_live_`.

```
Authorization: Bearer ptk_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
```

Mint a key headlessly (no browser):
- New account: `POST /auth/signup` with `{ "email", "password" }` returns the key once plus 25 free trial credits.
- Existing account: `POST /auth/api-keys` with `{ "email", "password" }` returns a fresh key once.

Never embed the key in client-side code. Rotate from the dashboard Settings page if exposed.

## Signup and billing flow (headless)

1. `POST /auth/signup` body `{ "email", "password" }` -> `{ "api_key": "ptk_live_...", "credits_remaining": 25 }`.
2. `POST /billing/checkout` body `{ "tier_key": "5k" }` with the bearer header -> `{ "url": "https://checkout.stripe.com/..." }`. A human clicks this once to add a card. Cards cannot be entered headlessly.
3. After a card is on file, `POST /billing/topup` body `{ "tier_key": "1k" | "5k" | "25k" }` tops up silently with no browser.
4. Run lookups. On `402` (out of credits), top up then retry.

## Enrichment endpoints

All are `POST`, JSON in / JSON out. Every response includes `cached` (bool) and `credits_remaining` (int).

### POST /find-website  (2 credits)
Input:
```json
{ "company_name": "Stripe Inc.", "context": "fintech payments (optional)" }
```
Output:
```json
{
  "company_name": "Stripe Inc.",
  "website_url": "https://stripe.com",
  "confidence": 0.99,
  "source": "primary_match",
  "cached": false,
  "credits_remaining": 4127
}
```

### POST /find-email/person  (25 credits)
Input (full_name OR first_name+last_name; domain preferred over company_name):
```json
{ "full_name": "Jane Doe", "domain": "stripe.com" }
```
Output: `{ "email", "email_status", "source", "cached", "credits_remaining" }`. Email verified via a four-provider waterfall (Findymail, AnyMailFinder, Hunter, BetterContact).

### POST /find-email/decision-maker  (25 credits)
Input:
```json
{ "domain": "stripe.com", "decision_maker_category": "ceo" }
```
`decision_maker_category` is one of: ceo, sales, operations, buyer, finance, hr, marketing.
Output: `{ "name", "email", "linkedin_url", "job_title", "email_status", "source", "cached", "credits_remaining" }`.

### POST /find-email/linkedin  (10 credits)
Input:
```json
{ "linkedin_url": "https://linkedin.com/in/patrickcollison" }
```
Output: `{ "email", "name", "linkedin_url", "job_title", "email_status", "source", "cached", "credits_remaining" }`.

### POST /find-email/company  (25 credits, flat)
Input:
```json
{ "domain": "stripe.com" }
```
Output: `{ "emails": [...], "count", "source", "cached", "credits_remaining" }`. Up to 500 emails with names, titles, and LinkedIn URLs where available. Flat cost regardless of count.

### POST /find-all  (sum of sub-calls that hit)
Input:
```json
{ "company_name": "Stripe Inc.", "context": "optional", "dm_categories": ["ceo", "sales", "operations"], "skip_company_emails": false }
```
Resolves the website, runs /find-email/company on the resulting domain, and pulls decision-maker emails for each requested category (default ceo, sales, operations; max 6).
Output: `{ "company_name", "domain", "website", "decision_makers": [...], "company_emails": [...], "total_emails", "credits_charged", "credits_remaining", "errors": [...] }`.
Cost: sum of the sub-calls that hit. Default worst case: 2 + 25 + 3 x 25 = 102 credits. Whiffed sub-calls cost zero. Each leg caches per user.

## Account endpoints

- `POST /auth/signup` (no auth): create account, mint first key, 25 free trial credits.
- `POST /auth/api-keys` (no auth): mint a fresh key for an existing account from email + password.
- `GET /me` (auth): profile, credit balance, has_saved_card, API-key count.
- `GET /credits` (auth): credit balance only.
- `GET /billing/products` (no auth): credit pack tiers.
- `POST /billing/checkout` (auth): Stripe Checkout URL to add a card (one human browser trip).
- `POST /billing/topup` (auth): silent off-session top-up once a card is on file.

## Pricing

- $0.01 per credit. No subscription. Credits never expire.
- Packs: 1,000 ($10), 5,000 ($50), 25,000 ($250).
- 25 free trial credits on signup.
- Whiffed lookups cost zero. Repeat lookups of the same input by the same account are cached and free.

## Key facts

- Match rate: 99.2% on the benchmarked dataset of public companies.
- Index size: 10M+ companies.
- Median latency: 840ms (p50).
- Email waterfall: Findymail, AnyMailFinder, Hunter, BetterContact.

## Curl examples

```bash
# Website lookup
curl -X POST https://api.potarix.com/enricher/find-website \
  -H "Authorization: Bearer ptk_live_..." \
  -H "Content-Type: application/json" \
  -d '{ "company_name": "Stripe Inc." }'

# Decision-maker email
curl -X POST https://api.potarix.com/enricher/find-email/decision-maker \
  -H "Authorization: Bearer ptk_live_..." \
  -H "Content-Type: application/json" \
  -d '{ "domain": "stripe.com", "decision_maker_category": "ceo" }'
```

## Integrations

- Clay native action for website lookups; email endpoints via Clay HTTP API action. BYOK, billed against Potarix credits. Walkthrough: https://enricher.potarix.com/clay and https://enricher.potarix.com/clay-fallback
- Any HTTPS pipeline: Make.com, n8n, Zapier, Python (requests/httpx), Node (fetch/axios), CRM webhooks.
- ChatGPT Actions / Custom GPT: import https://enricher.potarix.com/openapi.yaml and set API key auth as Authorization: Bearer ptk_live_...

## Company

Potarix Labs builds focused B2B data products. Parent brand https://potarix.com tracks newly formed and newly funded companies for outbound sales teams. Contact: omar@potarix.com.