> ## Documentation Index
> Fetch the complete documentation index at: https://docs.enricho.co/llms.txt
> Use this file to discover all available pages before exploring further.

# Recipes

> Copyable end-to-end code for common jobs: clean a list before a campaign, screen developer candidates, prospect target accounts and page through results safely.

Each recipe is a complete script. Set `ENRICHO_API_KEY` to a key from the [API keys page](https://app.enricho.co/keys) and run it. All of them spend credits; start with a small input to see the cost.

## A small client

The recipes share this helper. It sends JSON, unwraps the [response envelope](https://docs.enricho.co/api-reference/overview.md#response-envelope), waits and retries on `429`, and raises on every other error without retrying, because a paid request that timed out may already have been charged.

```javascript enricho.js theme={null}
const BASE = "https://api.enricho.co"

export async function enricho(path, body, { method = "POST" } = {}) {
  for (let attempt = 0; ; attempt++) {
    const res = await fetch(BASE + path, {
      method,
      headers: {
        Authorization: `Bearer ${process.env.ENRICHO_API_KEY}`,
        "Content-Type": "application/json",
      },
      body: body ? JSON.stringify(body) : undefined,
      signal: AbortSignal.timeout(120_000),
    })
    const json = await res.json()
    if (res.status === 429 && attempt < 3) {
      const wait = Number(res.headers.get("Retry-After")) || 2 ** attempt * 5
      await new Promise((r) => setTimeout(r, wait * 1000))
      continue
    }
    if (!json.success) {
      throw new Error(`${res.status} ${json.result?.code}: ${json.message}`)
    }
    return json.result
  }
}
```

```python enricho.py theme={null}
import os, time, requests

BASE = "https://api.enricho.co"
session = requests.Session()
session.headers["Authorization"] = f"Bearer {os.environ['ENRICHO_API_KEY']}"

def enricho(path, body=None, method="POST"):
    for attempt in range(4):
        res = session.request(method, BASE + path, json=body, timeout=120)
        data = res.json()
        if res.status_code == 429 and attempt < 3:
            time.sleep(float(res.headers.get("Retry-After") or 5 * 2**attempt))
            continue
        if not data["success"]:
            raise RuntimeError(f"{res.status_code} {data['result'].get('code')}: {data['message']}")
        return data["result"]
```

## Clean a list before a campaign

Run `validity` and `compliance` on every address, then split the list into send, hold and remove. A request takes up to 100 checks (addresses × checks), so two checks means 50 addresses per request.

```javascript clean-list.js theme={null}
import { enricho } from "./enricho.js"

const CHECKS = ["validity", "compliance"]
const PER_REQUEST = Math.floor(100 / CHECKS.length) // 50 addresses

export async function cleanList(emails) {
  const send = [], hold = [], remove = []
  let credits = 0
  for (let i = 0; i < emails.length; i += PER_REQUEST) {
    const batch = emails.slice(i, i + PER_REQUEST)
    const result = await enricho("/api/directory/email/intelligence", { emails: batch, checks: CHECKS })
    credits += result.credits_used
    for (const r of result.results) {
      const status = r.validity?.status
      const verdict = r.compliance?.verdict
      if (!r.valid || status === "invalid" || verdict === "do_not_send") remove.push(r.email)
      else if (status === "valid" && verdict === "allowed") send.push({ email: r.email, conditions: r.compliance.conditions })
      else hold.push({ email: r.email, status, verdict, reason: r.compliance?.reason })
    }
  }
  return { send, hold, remove, credits }
}
```

```python clean_list.py theme={null}
from enricho import enricho

CHECKS = ["validity", "compliance"]
PER_REQUEST = 100 // len(CHECKS)  # 50 addresses

def clean_list(emails):
    send, hold, remove, credits = [], [], [], 0
    for i in range(0, len(emails), PER_REQUEST):
        result = enricho("/api/directory/email/intelligence",
                         {"emails": emails[i:i + PER_REQUEST], "checks": CHECKS})
        credits += result["credits_used"]
        for r in result["results"]:
            status = (r.get("validity") or {}).get("status")
            verdict = (r.get("compliance") or {}).get("verdict")
            if not r["valid"] or status == "invalid" or verdict == "do_not_send":
                remove.append(r["email"])
            elif status == "valid" and verdict == "allowed":
                send.append({"email": r["email"], "conditions": r["compliance"]["conditions"]})
            else:
                hold.append({"email": r["email"], "status": status, "verdict": verdict})
    return send, hold, remove, credits
```

`hold` collects risky mailboxes (catch-all, shared inboxes), `unknown` answers and `consent_required` verdicts for a person to review. Running the script again on the same list is free for the addresses already checked.

## Screen developer candidates

Look up to 10 GitHub profiles per request and rank candidates by pull requests merged into other people's projects, then by stars.

```javascript screen-candidates.js theme={null}
import { enricho } from "./enricho.js"

export async function screen(profiles) {
  const found = []
  for (let i = 0; i < profiles.length; i += 10) {
    const result = await enricho("/api/directory/github/profiles", { profiles: profiles.slice(i, i + 10) })
    for (const r of result.results) {
      if (r.status === "found") found.push(r.profile)
      else console.warn(r.query, r.status, r.reason) // free: not_found, invalid, rate_limited, unavailable
    }
  }
  return found
    .sort((a, b) => b.pull_requests.merged_external - a.pull_requests.merged_external || b.stars_total - a.stars_total)
    .map((p) => ({
      login: p.login,
      top_language: p.tech_stack[0]?.name,
      merged_external: p.pull_requests.merged_external,
      stars: p.stars_total,
      active_weeks: p.activity.active_weeks,
      highlight: p.highlights[0],
    }))
}
```

```python screen_candidates.py theme={null}
from enricho import enricho

def screen(profiles):
    found = []
    for i in range(0, len(profiles), 10):
        result = enricho("/api/directory/github/profiles", {"profiles": profiles[i:i + 10]})
        for r in result["results"]:
            if r["status"] == "found":
                found.append(r["profile"])
            else:
                print("skipped", r["query"], r["status"])  # free
    found.sort(key=lambda p: (p["pull_requests"]["merged_external"], p["stars_total"]), reverse=True)
    return [{
        "login": p["login"],
        "top_language": p["tech_stack"][0]["name"] if p["tech_stack"] else None,
        "merged_external": p["pull_requests"]["merged_external"],
        "stars": p["stars_total"],
        "active_weeks": p["activity"]["active_weeks"],
    } for p in found]
```

Rank on work, never on name, photo or location. Little public activity isn't evidence of little experience; see [use it fairly](https://docs.enricho.co/intelligence/github-intelligence.md#use-it-fairly).

## Prospect target accounts

Find the companies first, then the decision makers at exactly those companies by passing their domains to people search.

```javascript accounts-to-people.js theme={null}
import { enricho } from "./enricho.js"

const companies = await enricho("/api/directory/companies/search", {
  industry: "software",
  employee_size_band: ["51-200", "201-500"],
  limit: 20,
})
const domains = companies.results.map((c) => c.domain).filter(Boolean)
if (domains.length === 0) throw new Error("No companies matched: widen the company filters.")

const people = await enricho("/api/directory/people/search", {
  company_domain: domains,
  seniority: ["vp", "head", "director"],
  role: "sales",
  has_email: true,
  limit: 50,
})
console.log(`${people.results.length} people, ${companies.credits_used + people.credits_used} credits`)
```

```python accounts_to_people.py theme={null}
from enricho import enricho

companies = enricho("/api/directory/companies/search", {
    "industry": "software",
    "employee_size_band": ["51-200", "201-500"],
    "limit": 20,
})
domains = [c["domain"] for c in companies["results"] if c.get("domain")]
if not domains:
    raise SystemExit("No companies matched: widen the company filters.")

people = enricho("/api/directory/people/search", {
    "company_domain": domains,
    "seniority": ["vp", "head", "director"],
    "role": "sales",
    "has_email": True,
    "limit": 50,
})
print(len(people["results"]), "people,", companies["credits_used"] + people["credits_used"], "credits")
```

Never fall back to searching all people when the company list is empty: that buys records outside your target accounts.

## Page through a search within a budget

Keep the same filters, follow `next_cursor` until `has_more` is false, and stop before you pass a credit budget. Check the balance first so the run doesn't stop halfway on `402`.

```javascript paginate.js theme={null}
import { enricho } from "./enricho.js"

export async function* pages(path, filters, { budget = 500, limit = 50 } = {}) {
  const { credits_remaining } = await enricho("/api/billing/usage", null, { method: "GET" })
  budget = Math.min(budget, credits_remaining)
  const perRecord = path.includes("/people/") ? 2 : 1 // a person costs 2 credits, anything else 1
  let cursor = "", spent = 0
  do {
    const pageLimit = Math.min(limit, Math.floor((budget - spent) / perRecord))
    if (pageLimit < 1) return
    const page = await enricho(path, { ...filters, limit: pageLimit, cursor })
    spent += page.credits_used
    yield page.results
    cursor = page.has_more ? page.next_cursor : ""
  } while (cursor)
}

for await (const people of pages("/api/directory/people/search", { job_title: "head of growth", has_email: true })) {
  console.log(people.length)
}
```

```python paginate.py theme={null}
from enricho import enricho

def pages(path, filters, budget=500, limit=50):
    budget = min(budget, enricho("/api/billing/usage", method="GET")["credits_remaining"])
    per_record = 2 if "/people/" in path else 1  # a person costs 2 credits, anything else 1
    cursor, spent = "", 0
    while True:
        page_limit = min(limit, (budget - spent) // per_record)
        if page_limit < 1:
            return
        page = enricho(path, {**filters, "limit": page_limit, "cursor": cursor})
        spent += page["credits_used"]
        yield page["results"]
        if not page["has_more"]:
            return
        cursor = page["next_cursor"]

for people in pages("/api/directory/people/search", {"job_title": "head of growth", "has_email": True}):
    print(len(people))
```

Changing `limit` between pages is fine; changing any filter needs a new search without a cursor. See [pagination](https://docs.enricho.co/api-reference/overview.md#pagination).

## If a paid request fails midway

A timeout or `503` on a paid request doesn't prove nothing was charged. Before retrying, call [`GET /api/billing/usage`](https://docs.enricho.co/api-reference/usage) or open [Usage](https://app.enricho.co/usage). Retrying the same request is safe for your balance either way: anything already bought comes back free and is counted in `already_purchased`.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.