---
title: "Gatekeeper: ZoomInfo"
type: entity
tags: [gatekeepers, developer, advanced, well-established]
created: 2026-08-05
updated: 2026-08-05
sources: ["raw/github_doc-packages-gatekeeper-zoominfo-readme-md.md"]
confidence: high
cfos_snapshot: "2026-08-05"
---

## 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](https://api.zoominfo.com/).
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

- [[concepts/gatekeepers]]
- [[concepts/writing-a-gatekeeper]]
- [[entities/gatekeeper-supabase]] — comparable OAuth2 + Management/GTM API connector with approval-gated writes
- [[entities/gatekeepers-catalog]]