ZoomInfo

HOW in lib/zoominfo.py. Paths CONFIRMED from the live docs at docs.gtm.ai (2026-09); index: reference/docs/zoominfo/raw/endpoints.md.

Auth & config — OAuth 2.0 Client Credentials

• Host: https://api.zoominfo.com/gtm (families: oauth/v1, data/v1, copilot/v1).
• Token: POST /gtm/oauth/v1/token — HTTP Basic client_id:client_secret, body grant_type=client_credentials (no scope, no refresh token), x-www-form-urlencoded → Bearer (expires_in ~1h). The adapter caches the token, refreshes before expiry, and re-auths once on a 401.
• Env: ZOOMINFO_CLIENT_ID, ZOOMINFO_CLIENT_SECRET (DevPortal app — self-serve BYOK, pasted on the Integrations card as Client ID + Client Secret; connecting it needs the Essential plan or above). Never hardcode. Per-endpoint scopes (api:data:contact, api:data:company, api:insights:read, …) are granted to the app in DevPortal — the token request sends no scope. Data calls send Content-Type/Accept: application/vnd.api+json with JSON:API {"data":{"type":…,"attributes":{…}}} bodies.

Operations

Enrich: enrich_contacts, enrich_companies (≤25 records), enrich_scoops, enrich_intent, enrich_news, enrich_technologies, enrich_org_charts, enrich_corporate_hierarchy, enrich_hashtags. Search: search_contacts, search_companies, search_intent, search_news, search_scoops (filters in data.attributes; page[number]/page[size] 1-100 + sort as query). Copilot: company_lookalikes, contact_lookalikes (filter[referencePersonId]), contact_recommendations (filter[useCaseType] + filter[ziCompanyId]), company_insights, account_summary. lookup(field_name) resolves valid field values; user_usage reports credits. Everything else (agent-teams, ICP/persona/competitor config, audiences, GTM-Studio columns/folders/rows, workflows, engagements) → generic request("POST"|"GET", "data/v1/…"|"copilot/v1/…", json=…).

⚠️ Credits + guardrail

• user_usage, lookup and search_* calls are free on the ZoomInfo side; enrich_* charges per matched record (failed/no-match lookups are NOT charged). user_usage() to check balance. Pilot a 1-record enrich first; gate bulk behind approval. Enrich is capped at 25 records/call.

Handoff

Net-new sourcing + enrichment layer: search_companies/search_contacts (discover) → enrich_* (resolve emails/phones/firmographics) → signals (enrich_intent/enrich_scoops) for prioritization → hand to sequencers / ATS. Premium alternative/complement to [[apollo]] and the waterfall enrichers.

Callable surface — lib/zoominfo.py

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

• account_summary(company_id) -> Any — GET /copilot/v1/companies/{companyId}/account-summary — Copilot account summary for one ZoomInfo company ID.
• company_insights(payload: dict) -> Any — POST /copilot/v1/companies/insights — type CompanyInsightsSearch, attributes {ziCompanyIds: [≤50], signalTypes?}. Sales-intelligence signals filtered by type; scope api:insights:read.
• company_lookalikes(**params) -> Any — GET /copilot/v1/companies/lookalikes — ranked similar companies (≤100, page[size]).
• contact_lookalikes(**params) -> Any — GET /copilot/v1/contacts/lookalikes — ranked contacts similar to a reference person.
• contact_recommendations(**params) -> Any — GET /copilot/v1/contacts/recommendations — ranked contacts at a target company for a sales motion. Requires filter[useCaseType] (e.g. PROSPECTING, DEAL_ACCELERATION) and filter[ziCompanyId].
• enrich_companies(payload: dict) -> Any — POST /data/v1/companies/enrich — type CompanyEnrich, attributes matchCompanyInput ≤25 (companyId|companyName|companyWebsite|…), outputFields, requiredFields.
• enrich_contacts(payload: dict) -> Any — POST /data/v1/contacts/enrich — type ContactEnrich, attributes matchPersonInput ≤25 (personId|emailAddress|phone|fullName|firstName+lastName+companyName|companyId|…), outputFields, requiredFields. 1 ZoomInfo credit per matched record; scope api:data:contact.
• enrich_corporate_hierarchy(payload: dict) -> Any — POST /data/v1/companies/corporate-hierarchy/enrich — type CorporateHierarchyEnrich; full corporate tree for the matched company.
• enrich_hashtags(payload: dict) -> Any — POST /data/v1/companies/hashtags/enrich — type HashtagEnrich; predefined categorical labels for the matched company.
• enrich_intent(payload: dict) -> Any — POST /data/v1/intent/enrich — type IntentEnrich; intent signals for a company.
• enrich_news(payload: dict) -> Any — POST /data/v1/news/enrich — type NewsEnrich; company identifier (companyId|companyName|companyWebsite) required. Charges per returned article.
• enrich_org_charts(payload: dict) -> Any — POST /data/v1/companies/org-chart/enrich — type OrgChartEnrich; a ZoomInfo company identifier + at least one ZoomInfo department identifier are required.
• enrich_scoops(payload: dict) -> Any — POST /data/v1/scoops/enrich — type ScoopEnrich; company identifier (companyId|companyName| companyWebsite) required. Charges per returned scoop.
• enrich_technologies(payload: dict) -> Any — POST /data/v1/companies/technologies/enrich — type TechnologyEnrich; technologies ZoomInfo has identified for the matched company.
• lookup(field_name: str, **filters) -> Any — GET /data/v1/lookup/{fieldName} — valid values for a search/enrich field (e.g. 'management-levels', 'company-rankings'); optional filter[category] for hashtag lookups.
• search_companies(payload: dict, *, page_number: int | None = None, page_size: int | None = None, sort: str | None = None) -> Any — POST /data/v1/companies/search — type CompanySearch, attributes are the filters (companyName, companyWebsite, industryCodes/Keywords, employeeRangeMin/Max, …).
• search_contacts(payload: dict, *, page_number: int | None = None, page_size: int | None = None, sort: str | None = None) -> Any — POST /data/v1/contacts/search — type ContactSearch, attributes are the filters (jobTitle, managementLevel, department, jobFunction, companyName, companyWebsite, state, country, industryKeywords, employeeRangeMin/Max, revenueMin/Max, …; valid values via lookup()). page[number]/page[size] (1-100, default 25) + sort are query params.
• search_intent(payload: dict, *, page_number: int | None = None, page_size: int | None = None) -> Any — POST /data/v1/intent/search — type IntentSearch; intent signals. Requires the Intent SKU.
• search_news(payload: dict, *, page_number: int | None = None, page_size: int | None = None) -> Any — POST /data/v1/news/search — type NewsSearch; at least one input required.
• search_scoops(payload: dict, *, page_number: int | None = None, page_size: int | None = None) -> Any — POST /data/v1/scoops/search — type ScoopSearch; real-time business intelligence signals.
• user_usage(**params) -> Any — GET /data/v1/users/usage — API usage/credits on the caller's own ZoomInfo account (ZoomInfo is BYOK-only). Free call.