FullEnrich

WHAT/guardrails here; HOW in reference/endpoints.md + lib/fullenrich.py. Per-endpoint docs cached at reference/docs/fullenrich/raw/.

Auth & config

• Base URL: https://app.fullenrich.com/api/v2
• Auth: Authorization: Bearer <key> (FullEnrich → Settings → API). Env FULLENRICH_API_KEY; never hardcode.

Async flow (important)

Enrichment is a bulk job, one start method per field: start_work_email_enrichment(datas=[...]) (or start_personal_email_enrichment / start_mobile_enrichment) → returns enrichment_id → poll get_bulk_enrichment(enrichment_id) until terminal (or pass a webhook_url). Same pattern for start_reverse_email / get_reverse_email. datas is a list of contacts ({first_name, last_name, domain, company_name, linkedin_url}) — the job asks for the field its method names.

Guardrails

• Credits: successful enrichments consume credits, priced per field — a personal email costs 3x a work email and a mobile 10x when the result reveals a mobile (most_probable_phone, or any number not flagged as a landline). A start_mobile_enrichment result that's landline-only bills 0, not the cheaper email rate — pick the start method deliberately. Pilot one contact, confirm, then run the batch. Check get_credits() first; verify_key() is a safe read-only auth pilot.

Operations

start_work_email_enrichment, start_personal_email_enrichment, start_mobile_enrichment, get_bulk_enrichment, start_reverse_email, get_reverse_email, search_company, get_credits, verify_key; anything else via generic request().

Handoff

Enrichment layer: take a shortlisted contact list (from Apollo/Exa/sourcing) → FullEnrich for verified emails/phones → write to ATS (recruit-crm) or sequencer (instantly/sourcewhale). Enrich late, on the filtered set. Member of the email_enrichment, personal_email, and phone_enrichment waterfalls.

Field notes (production experience)

Field-shape note: these are vendor-native operational notes. The client returns the raw vendor JSON and uses the method names in this file — read field shapes accordingly (no normalized-wrapper / result.data. prefix).

• Async: bulk_enrich / reverse_email return an enrichment_id -> poll get_result / get_reverse_result for terminal data. Search (people_search/company_search) is synchronous.
• Per-field vendor credit costs: work email = 1; personal email = 3; mobile = 10 when the result reveals a mobile (most_probable_phone, or any number not flagged as a landline) — a landline-only mobile-job result bills 0, not a cheaper rate. Each has its own start method, and the revealed field, not the method itself, picks the price (a work-email job that happens to reveal a mobile bills the mobile rate).
• Email status hierarchy: DELIVERABLE > HIGH_PROBABILITY > CATCH_ALL > INVALID; use the most_probable_work_email field for the best result.
• A LinkedIn URL lifts accuracy notably (emails +5-20%, phones +10-60%).
• forceResults=true on get-result returns partial data while still running.
• Use it for: high-quality waterfall (20+ sources). Not for validation-only.

Callable surface — lib/fullenrich.py

Import: from lib.fullenrich import FullEnrich → instantiate FullEnrich() (reads key from env). Base: https://app.fullenrich.com/api/v2. Generic passthrough: request(method, path, *, params, json).

• get_bulk_enrichment(enrichment_id: str) -> dict — GET /contact/enrich/bulk/{enrichment_id} — poll for the bulk enrichment result.
• get_credits() -> dict — GET /account/credits — current credit balance.
• get_reverse_email(enrichment_id: str) -> dict — GET /contact/reverse/email/bulk/{enrichment_id}.
• search_company(payload: dict) -> dict — POST /company/search — filter-based company search (see cached docs for filters).
• start_mobile_enrichment(datas: list[dict], name: str = 'hyreflow enrichment', webhook_url: str | None = None, **opts) -> dict — POST /contact/enrich/bulk — start a MOBILE PHONE enrichment job. Returns {enrichment_id}.
• start_personal_email_enrichment(datas: list[dict], name: str = 'hyreflow enrichment', webhook_url: str | None = None, **opts) -> dict — POST /contact/enrich/bulk — start a PERSONAL EMAIL enrichment job. Returns {enrichment_id}.
• start_reverse_email(datas: list[dict], name: str = 'hyreflow reverse', webhook_url: str | None = None, **opts) -> dict — POST /contact/reverse/email/bulk — reverse-lookup people from emails.
• start_work_email_enrichment(datas: list[dict], name: str = 'hyreflow enrichment', webhook_url: str | None = None, **opts) -> dict — POST /contact/enrich/bulk — start a WORK EMAIL enrichment job. Returns {enrichment_id}.
• verify_key() -> dict — GET /account/keys/verify — check the API key is valid (good read-only pilot).