ZoomInfo API Guide: Enrichment and CRM Writeback

The safe ZoomInfo API pattern is search first, enrich only selected IDs, preserve match evidence, and write to a CRM through buyer-owned rules. Search is documented as free of bulk-data credits, while a newly enriched contact or company generally uses one credit and is under management for a rolling year. Test tokens make production calls, so use a CRM sandbox, strict scopes, record limits, and a credit budget from the first request.

ZoomInfo API: the recommended data path

ZoomInfo's current API overview is hosted at docs.gtm.ai. The Data API covers contacts, companies, intent, news, Scoops, technologies, organization charts, and corporate hierarchy. Other APIs cover audiences, agents, context, and data quality.

For contact and company enrichment, use four stages:

1. Search with narrow qualification filters.
2. Rank candidate IDs using the returned identity and quality evidence.
3. Enrich only the IDs that pass the acceptance rules.
4. Apply buyer-owned CRM mapping and write controls.

This order separates discovery from paid record access. It also reduces false matches because the integration can inspect the person, company, title, accuracy score, and data dates before requesting contact details.

The base URL is https://api.zoominfo.com/gtm. Contact search uses POST /data/v1/contacts/search, contact enrichment uses POST /data/v1/contacts/enrich, and equivalent company paths are under /data/v1/companies/. Runtime lookup endpoints expose the filters and output fields available to the licensed account.

Our opinion is that the lookup endpoints should control production configuration. A static field list in integration code will drift as entitlements and schemas change.

Authenticate with OAuth and minimum scopes

The new ZoomInfo API uses OAuth 2.0. It does not use a permanent API key. Calls send an access token in the Authorization: Bearer header.

ZoomInfo documents Authorization Code with PKCE for user-delegated applications and Client Credentials for server-to-server work. A Client Credentials application needs an integration user, and API actions are attributed to that user.

Request only the scopes the process needs. Contact data uses api:data:contact, company data uses api:data:company, and intent uses api:data:intent. A server process that only enriches companies should not receive contact, intent, or agent scopes.

Store the client secret and tokens in a secrets manager, not in browser code, logs, source control, or CRM fields. ZoomInfo's refresh-token documentation says each refresh token is single-use and invalidates the previous token after exchange, so the token store must update atomically after a successful refresh.

ZoomInfo's test-access documentation says portal-generated testing tokens are production tokens. Requests use credits and rate limits. There is no documented free Data API sandbox. Point any downstream write at a sandbox, but treat ZoomInfo reads as billable production activity.

Search before enrichment

The Data API workflow recommends Search followed by selected Enrich calls. Contact and company Search are documented as free of bulk-data credits, although requests still count against rate limits.

Contact Search does not return email addresses or phone numbers. It returns evidence that can support a decision to enrich:

• ZoomInfo contact and company IDs;
• name, employer, and job title;
• contactAccuracyScore;
• validDate and lastUpdatedDate;
• flags such as hasEmail, hasDirectPhone, and hasMobilePhone;
• do-not-call indicators.

An availability flag says ZoomInfo has a value. It does not reveal the value or prove that the value is current. Use it as a filter, then verify the enriched result against the acceptance rules.

Search results need a stable ranking policy. For example, require an exact company domain, an approved management level, a validation date within the campaign's freshness window, and the required contact channel. Do not select the first same-name result.

Enrich selected IDs and require fields

ZoomInfo recommends its IDs as enrichment inputs. Contact and company Enrich accept batches of up to 25 inputs. Identity attributes can be used when an ID is unavailable, but more input detail is needed to improve match confidence.

Use outputFields to request only the fields needed by the approved workflow. A contact job that needs business email and role does not need a home address, personal phone, education history, and every company attribute.

Contact Enrich also supports requiredFields. A candidate can be rejected when a required value is absent even if the identity match otherwise succeeds. This is useful when the campaign cannot proceed without a verified business email or another specific field.

Before deployment, call the enrichment lookup endpoint for contact and company entities. It is the live source for valid output fields and account entitlement. Generate an allowlist from that response and fail closed when a field disappears or is no longer licensed.

Preserve match status and quality evidence

The contact enrichment endpoint returns the input and a matchStatus in response metadata. Documented statuses include FULL_MATCH, NO_MATCH, validation-date and required-field failures, COMPANY_ONLY_MATCH, CONTACT_ONLY_MATCH, OPT_OUT, LIMIT_EXCEEDED, and INVALID_INPUT.

The status is part of the record, not an implementation detail. Apply these rules:

Keep contactAccuracyScore, validDate, and lastUpdatedDate with the returned ID. ZoomInfo's current schemas show an endpoint-specific inconsistency: Contact Search describes scores from 75 to 99, while an Enrich minimum filter documents 70 to 99. Do not encode one universal floor without testing the live endpoint and agreeing the business threshold.

A FULL_MATCH is not proof that every returned field is accurate. It says the API matched the input according to its criteria. Sample the email, phone, employer, and role fields independently before a broad writeback.

Understand credits and records under management

ZoomInfo's credit documentation says a contact or company uses one bulk-data credit when first enriched within a rolling 12-month period. The record is then under management for one year from that enrichment date. Re-enrichment during that period does not use another bulk-data credit, but it still counts against the account's record limit.

Search Contacts, Search Companies, lookup, and several recommendation operations are documented as free. Contact, company, and intent enrichment use applicable credits. The usage endpoint at GET /data/v1/users/usage reports subscribed, used, and remaining limits.

ZoomInfo's public pricing FAQ uses broader language that each exported profile costs a credit, including API and integration exports. The marketing description does not explain the Data API's free Search and under-management rules.

Resolve the difference in the order form. List each operation and the wallet it uses: bulk-data credit, record limit, request limit, unique-ID limit, AI action credit, or another allowance. Set batch-level credit ceilings and stop before the account reaches zero.

Record usage immediately before and after an acceptance batch. The difference is stronger evidence than a spreadsheet estimate.

Respect current rate-limit headers

ZoomInfo's rate-limit page, updated in October 2026, lists Builder, Standard, and Scaling packages. It documents 5, 25, and 35 requests per second, with rolling hourly and daily limits for each package.

Every response is documented with second, hour, and day limit and remaining headers. A 429 response adds Retry-After, the rejected bucket, and reset information. Honour those values rather than using a fixed sleep.

A remaining value of -1 means the quota service was unavailable and the request was allowed with unknown quota state. Slow the job and check the usage endpoint instead of treating -1 as unlimited capacity.

Current documentation conflicts on search page size. Endpoint schemas and pagination guidance allow up to 100, while the newer rate page says direct API Search returns up to 25 records per request. Test the licensed tenant and do not build capacity assumptions around the larger number.

Retry only the errors that can succeed later

ZoomInfo's status-code guide distinguishes input, authentication, entitlement, quota, and server failures.

Use this policy:

• Fix 400 validation errors. Do not retry the same payload.
• Refresh or reauthenticate after a 401.
• Stop on 403 and correct scopes, entitlement, or API access.
• Honour Retry-After on 429.
• Retry documented 500 and 504 failures with bounded exponential backoff.
• Stop on credit-limit errors and alert the ZoomInfo administrator.

Log the request ID, endpoint, status, retry count, and safe record identifier. Do not log tokens or full contact payloads.

ZoomInfo does not document an idempotency key or exactly-once guarantee for the reviewed API surfaces. Search and Enrich are reads, but a retry can still create duplicate downstream work. Assign every input a dedupe key and persist its state before any CRM write.

The Data API does not write to your CRM

ZoomInfo's Salesforce and HubSpot product integrations advertise bidirectional synchronization and automated pushes. The Data API Search and Enrich endpoints only return data, so a custom integration must perform its own CRM writes.

The buyer owns:

• CRM authentication and least-privilege permissions;
• object and field mapping;
• fill-only, overwrite, and conflict rules;
• person and company upsert keys;
• duplicate detection and merge review;
• opt-out, do-not-call, and suppression checks;
• audit logs, retries, rollback, and reconciliation.

Start with fill-only rules for empty fields. Put disputed or high-impact changes such as employer, owner, lifecycle stage, and phone number into a review queue. Preserve the old value, new value, ZoomInfo ID, match status, source date, request ID, and operator for every approved update.

Never let a fresh enrichment reactivate a suppressed contact. Suppression is a policy state and must outrank a vendor's new email or job record.

Review data use before connecting production records

ZoomInfo's security overview says customer data is encrypted at rest with AES-256, browser communications use at least TLS 1.2, and customer access supports multi-factor authentication or single sign-on. It references ISO 27001 and SOC 2 controls.

The privacy policy and Submitted and Integrated Data terms describe how information supplied through integrations can be used, subject to agreements and settings. Review the negotiated licence, data-processing terms, admin data-sharing controls, permitted fields, retention, and deletion obligations before production access.

Limit the payload both ways. Send only the match inputs needed by the API, and store only the fields the approved CRM process uses.

Run a sandbox acceptance test

Create an OAuth application with minimum contact, company, and lookup scopes. Use a fixed sample containing exact matches, stale contacts, job changers, duplicate names, missing required fields, opted-out records, and known no-matches.

Run this test:

1. Capture starting usage and rate-limit headers.
2. Search the fixture and freeze the candidate IDs before enrichment.
3. Have a reviewer label the correct person-company match without seeing the API status.
4. Enrich only the selected IDs in batches no larger than 25.
5. Compare match status, required fields, accuracy score, validation date, and returned contact data with the reference.
6. Send approved changes to named sandbox fields under fill-only rules.
7. Force a timeout, 429, invalid input, duplicate event, and credit-stop condition.
8. Prove that retries do not duplicate writes and that opt-outs never enter an outreach queue.
9. Reconcile successful enrichments, record usage, credits, CRM writes, rejects, and rollback logs.

Approve production only after match precision, field accuracy, suppression, duplicate, credit, and recovery thresholds pass across the full fixture.

Need a ZoomInfo API acceptance test?

LeadHaste can define the fixture, matching rules, credit controls, CRM field policy, suppression checks, retries, reconciliation, and rollback before production records change.

Book your free discovery call →