PredictLeads

HOW in lib/predictleads.py. Index: reference/docs/predictleads/raw/endpoints.md.

⚠️ Status — read first

• CONFIRMED: base https://predictleads.com/api/v3, JSON:API shape, meta.count only when page is sent, the /financing_events discover path, and the billing model.
• INFERRED — verify on first pilot: the auth header names, the per-dataset slugs, and all filter param names. docs.predictleads.com is a JS-gated SPA; it was not spec-scraped (no Firecrawl/API key at build time). Run a 1-record pilot on each endpoint before bulk; re-derive by Firecrawl-scraping the detail pages (or pasting the Authentication + endpoint pages) when a key is available.

Auth & config

• Base: https://predictleads.com/api/v3. Auth (inferred): headers X-Api-Key + X-Api-Token, env PREDICTLEADS_API_KEY / PREDICTLEADS_API_TOKEN. Managed credits by default; BYOK optional (your own PredictLeads account).
• Pagination: page param (JSON:API). iter_discover_financing_events / iter_discover_job_openings auto-walk it. meta.count appears only when page is sent.

Billing

• Company endpoints (/companies/{id}/{dataset}) bill per request (0.8 credits/req, up to 1000 records) — cheapest relative to a broad discover sweep; use when you have the domain.
• Discover endpoints (/{dataset}) bill 0.8 credits/result — use only for broad search. technologies() (the tracked-technologies catalog) is the priciest at 2.4 credits/request.
• Avoid follow/unfollow workflows (webhook/recurring-billing oriented, not one-shot).

Operations

• Funding (the headline use): discover_financing_events(...) = recently funded companies by round type (e.g. Series A) + date → the discovery Apollo can't do by stage. financing_events(domain) = one company's rounds.
• Hiring: discover_job_openings(...) = companies hiring a role (e.g. "Account Executive") + recency; job_openings(domain) = a company's open roles (title, categories, onet, salary, dates).
• News: discover_news_events / news_events(domain) / get_news_event(id).
• Technographics: technology_detections(domain) / discover_technology_detections / technologies().
• Relationships: similar_companies, connections, products, github_repositories (all by domain).
• Generic: company_dataset(domain, dataset, **p) and discover(dataset, **p) cover any dataset; request() covers anything unwrapped.

Do not guess fields

Method names + paths come from the contract; filter param names are inferred — read the method's doc_ref (reference/docs/predictleads/raw/endpoints.md) and confirm on a 1-record pilot before relying on a filter (round type, date, title, category, location). Don't invent param keys.

Handoff — the Series-A-SaaS-with-AE-roles flow (why we built this)

discover_financing_events(round=Series A, recent) → filter SaaS → confirm AE roles via discover_job_openings(title="Account Executive") or job_openings(domain) → qualify vs ICP → dedupe (recruit_crm.search_companies) → recruit_crm.create_company (approval-gated). PredictLeads gives us Funding and hiring discovery with a Hyreflow recruiting-CRM write target.

Callable surface — lib/predictleads.py

Import: from lib.predictleads import PredictLeads → instantiate PredictLeads() (reads key from env). Base: https://predictleads.com/api/v3. Generic passthrough: request(method, path, *, params, json).

• api_subscription() -> Any — GET /api_subscription — subscription status + monthly credit quota/used on the caller's own PredictLeads account; requires the workspace's own key.
• company(identifier: str, **params) -> Any — GET /companies/{domain_or_id} — one company (name, location, ticker, parent, similar). CONFIRMED.
• connections(identifier: str, **params) -> Any — GET /companies/{id}/connections — partner/vendor/integration/investor/parent connections.
• discover_companies(**params) -> Any — GET /discover/companies — discover companies by location + sizes (e.g. ['11-50','201-500']).
• discover_financing_events(**params) -> Any — GET /discover/financing_events — discover funding rounds by financing_types_normalized (e.g. ['series_a','series_a1']) + company_location, ordered by updated date. Per result. CONFIRMED.
• discover_job_openings(**params) -> Any — GET /discover/job_openings — discover openings by onet_codes (ONET, e.g. '15-1252.00' software devs, '41-3091.00' sales) + location. Per result. Filters by ONET occupation, NOT free-text title.
• discover_news_events(**params) -> Any — GET /discover/news_events — discover news events by categories + company_location. Per result. CONFIRMED.
• discover_portfolio_companies(**params) -> Any — GET /discover/portfolio_companies/connections — portfolio companies of VCs/accelerators (investor connections). Per result. Filters: first/last_seen_at_from/until. CONFIRMED.
• discover_products(**params) -> Any — GET /discover/products/latest — latest products by sources (['menu','pricing']) + date. Per result. CONFIRMED.
• discover_startup_platform_posts(**params) -> Any — GET /discover/startup_platform_posts — Hacker News Show/Job posts (hiring/launching). Filters: published_at_from/until, post_types (['show_hn','job_hn']). Per result. CONFIRMED.
• discover_technology_detections(technology_id_or_fuzzy_name: str, **params) -> Any — GET /discover/technologies/{tech_id_or_fuzzy_name}/technology_detections — companies using a specific technology (e.g. 'HubSpot'). Per result. CONFIRMED. Resolve the tech via technologies().
• financing_events(identifier: str, **params) -> Any — GET /companies/{id}/financing_events — a company's funding rounds (financing_type_normalized, amount_normalized, effective_date, investors). Filters: first_seen_at_from/until, page, limit. CONFIRMED.
• follow_company(identifier: str, **params) -> Any — POST /companies/{id}/follow — follow a company (webhook delivery). No PredictLeads credit.
• followings(**params) -> Any — GET /followings — companies you follow (for webhook delivery). 1 PredictLeads credit (vendor-side; hyreflow's price is this method's cost block). CONFIRMED.
• get_extended_technology_detection(detection_id: str, **params) -> Any — GET /extended_technology_detections/{id} — detection detail (how it was found). CONFIRMED.
• get_job_opening(opening_id: str, **params) -> Any — GET /job_openings/{id} — a single job opening by UUID. CONFIRMED.
• get_news_event(event_id: str, **params) -> Any — GET /news_events/{id} — a single news event by UUID. CONFIRMED.
• get_product(product_id: str, **params) -> Any — GET /products/{id} — a single product by UUID. CONFIRMED.
• get_technology(id_or_fuzzy_name: str, **params) -> Any — GET /technologies/{id_or_fuzzy_name} — a single technology by id or fuzzy name. CONFIRMED.
• github_repositories(identifier: str, **params) -> Any — GET /companies/{id}/github_repositories — a company's public repos + stars/forks timeseries. CONFIRMED.
• iter_discover_financing_events(*, max_records: int = 1000, **params) -> Iterator[dict] — Auto-paginate /discover/financing_events via page (bounded by max_records).
• iter_discover_job_openings(*, max_records: int = 1000, **params) -> Iterator[dict] — Auto-paginate /discover/job_openings via page (bounded by max_records).
• job_openings(identifier: str, **params) -> Any — GET /companies/{id}/job_openings — a company's roles. Filters: active_only, not_closed, first_seen_at_from/until, last_seen_at_from/until, with_description_only, with_location_only, categories (e.g. 'sales','software_development'), page, limit≤1000. CONFIRMED.
• news_events(identifier: str, **params) -> Any — GET /companies/{id}/news_events — a company's news events. Filters: found_at_from/until, categories (e.g. 'receives_financing','increases_headcount_by','hires'), page, limit. CONFIRMED.
• products(identifier: str, **params) -> Any — GET /companies/{id}/products — products/services/solutions detected for a company. CONFIRMED.
• similar_companies(identifier: str, **params) -> Any — GET /companies/{id}/similar_companies — lookalikes (score, reason; top 20). limit≤50. CONFIRMED.
• technologies(**params) -> Any — GET /technologies — catalog of ~54k tracked technologies (pricing/spend, categories). Filters: fuzzy_name, order_by. 3 PredictLeads credits/request, flat regardless of how many records come back (vendor-side; the hyreflow price you budget with is this method's cost block). CONFIRMED.
• technology_detections(identifier: str, **params) -> Any — GET /companies/{id}/technology_detections — a company's tech stack. Filters: first/last_seen_at_from/until. CONFIRMED.
• unfollow_company(identifier: str, **params) -> Any — POST /companies/{id}/unfollow — unfollow a company. 1 PredictLeads credit (vendor-side; hyreflow's price is this method's cost block). CONFIRMED.
• website_evolution(identifier: str, **params) -> Any — GET /companies/{id}/website_evolution — subpages added over time (careers, blog…) = growth signal. CONFIRMED.