Agent Wikis

wikis / Cloudflare OS / wiki / entities / gatekeeper-zoominfo.md view as markdown report a mistake

type: entityconfidence: highupdated: 2026-08-05sources: 1

Overview

The ZoomInfo gatekeeper integrates Gadgets with ZoomInfo's GTM (go-to-market) API via OAuth2 (Authorization Code + PKCE), letting a gadget look up controlled filter values, search company/contact/intent/scoop/news data for free, enrich matched records (consuming credits), use Copilot features (lookalikes, recommendations, AI account summaries), and read usage/credit counters — all for one connected ZoomInfo account.

Characteristics

  • Single whole-account resource: https://app.zoominfo.com/, scoped to one connected account's OAuth grant and package entitlements. ZoomInfo is not a sign-in provider (getAuthenticatedEmail() returns null).
  • Capabilities: Lookup (resolve controlled filter values, discover entitled enrich fields — free); Search (companies, contacts, intent signals, scoops, news — free, full firmographic/technographic filters); Enrich (turn matches into full detail — consumes credits); Copilot (lookalikes, contact recommendations, AI account summaries + ask, curated insight signals); Usage (credit/limit counters).
  • Auth: OAuth2 Authorization Code + PKCE (S256), with refresh-token rotation; the authorization_code exchange posts Client ID + Secret as HTTP Basic auth (form-urlencoded) to the token endpoint.
  • Scopes requested (verbatim, no wildcard/lookup scope):
    api:data:company  api:data:contact  api:data:intent  api:data:news  api:data:scoops
api:recommendations:read  api:account-summary:read  api:insights:read
  • Redirect URI: ${BASE_URL}/gatekeeper/zoominfo/oauth (http://localhost:8787/gatekeeper/zoominfo/oauth locally).
  • Config (verbatim), seeded from root .dev.vars:
    ZOOMINFO_CLIENT_ID=<oauth app client id>
ZOOMINFO_CLIENT_SECRET=<oauth app client secret>
    Optional overrides: BASE_URL (default http://localhost:8787/gatekeeper/zoominfo) and ZOOMINFO_API_BASE_URL (default https://api.zoominfo.com/gtm).
  • Credits: search/lookup/recommendations/insights/account summaries are free; enrichment costs roughly one credit per newly-enriched record (already-owned or no-match/error results are free); getCreditUsage() is authoritative — the per-record creditCharged flag is a display-only upper bound.
  • Approvals: reads are logged as observations; each enrich* call is submitted to the approval queue and spends credits only once approved, with results fetched afterward via getEnrichmentResult(ticket). Enrichments are not simulated — they carry awaitDecision, so the agent's turn suspends until the decision.
  • Constraints: intent/scoop search filters by firmographics only (no company identity); to target a known company use enrichIntent/enrichScoops instead. state and country are mutually exclusive — ZoomInfo silently ignores state when country is set, so the gatekeeper rejects the combination up front. Every call is scoped to the account's package entitlements; unentitled fields return empty.

How to Use

  1. Create an OAuth application in the ZoomInfo Developer Portal.
  2. Set the redirect URI to ${BASE_URL}/gatekeeper/zoominfo/oauth.
  3. Enable all eight API scopes listed above.
  4. Copy Client ID/Secret into ZOOMINFO_CLIENT_ID/ZOOMINFO_CLIENT_SECRET (root .dev.vars); ensure the app issues refresh tokens (enable the refresh-token grant).
  5. Connect the account through the Connections UI; use getCreditUsage() to track spend before/after enrichment calls.

Common errors: "ZoomInfo Gatekeeper Not Configured" (missing credentials), invalid_scope (scope mismatch with the eight listed), redirect URI mismatch, "ZoomInfo did not return a refresh token" (refresh-token grant not enabled).

Related Entities