Upsert Audience

Overview

An audience is a durable, named dataset in ZoomInfo: accounts or contacts, with columns you define and rows you load. Upsert Audience creates one from an agent. It also renames or reorganizes one that already exists.

This is the first write call in any audience workflow. Columns and rows both need the id this tool returns, passed as audienceId on every later call, so no other write can happen until it runs. Discovery still comes before it: a search-driven audience starts from Search Companies or Search Contacts, and an existing audience is found with Browse Audiences.

What You'll Get

An audience record: id, name, type, folder, description, notes. Everything downstream needs that id. On create with search criteria attached, a job pulls every matching ZoomInfo record into the audience, and each row arrives with the baseline company or contact fields described under Manage Audience Rows.

Best For

• Standing up a prospecting list from ZoomInfo search criteria
• Creating an empty audience to load your own records into
• Renaming an audience or moving it between folders
• Updating the description or notes so the team knows what a dataset is for

To load records into an audience, use Manage Audience Rows; to add columns, Manage Audience Columns; to find an existing audience's id, Browse Audiences. To run enrichment and finish the workflow, open the audience in ZoomInfo.

How It Works

Two paths, chosen by whether you pass an audienceId:

Create. Omit audienceId and provide name, type (CONTACT or COMPANY), and agentInstruction; folderId is optional.

Update. Provide audienceId and agentInstruction. Any of name, folderId, description, and notes you omit keep their current values.

Then fill it, two ways:

From ZoomInfo search

Call Search Companies or Search Contacts first, then pass those exact parameters as searchQuery. A job pulls every matching record into the audience with no row limit.

From your own data

Create the audience without searchQuery, then load records with Manage Audience Rows, up to 50 per call.

Technical Details

Credits

Creating or updating the audience record itself is free. Ingesting records is not. Every ingest path costs data credits and checks Records Under Management first, so a record your organization already enriched in the past 12 months costs nothing to bring in again.

Unmatched rows are fully usable, and AI enrichment columns run against them, subject to the per-capability requirements on Manage Audience Columns. See Credits & Billing.

Limits

An audience supports up to 40 million cells. That is a few hundred columns across hundreds of thousands of rows, or a handful of columns across millions of rows; the ceiling is the product of the two, not either one alone.

In practice your working limit is usually the credit allocation your admin has set for you. Check with your ZoomInfo admin.

Immutable fields

type and searchQuery cannot be changed after creation. Both are silently ignored if passed on update, never rejected with an error. To change either, create a new audience.

The searchQuery rule

If Search Companies or Search Contacts was called to fulfill the request, its exact parameters must be passed through as searchQuery. Omitting it creates an empty audience with no error, which is the most common failure on this tool.

The rule carries across conversation turns. A follow-up like "create an audience for that" inherits the earlier search's parameters, and if the criteria were refined across several calls, only the final confirmed version belongs in searchQuery.

Requirements

A ZoomInfo subscription with bulk data credits enabled. MCP does not work with recurring monthly credits.

agentInstruction is required on both create and update. A downstream agent reads that field and executes it without access to your conversation, so it has to carry the full request on its own. If the instruction text conflicts with a structured field like name or type, the structured field wins.

Automatic Tool Selection

The AI reaches for Upsert Audience when you describe a set of records you want to work with as a group: "build me a list of", "create an audience for", "save these as". When it's genuinely unclear whether you mean a new audience or an update, or whether records should come from ZoomInfo prospecting or your own data, it should ask rather than guess.

Example Prompts

"Find software companies in Boston with 100 to 500 employees and save them as an audience."

"Create an empty company audience called Q3 Win-Back so I can load our CRM export into it."

"Rename my Boston Tech audience to FY26 Expansion Targets and move it to the Marketing folder."

"Add a note to the win-back audience saying marketing signed off on the definition."