Skip to main content

MCP audience tutorial

Use IQM Model Context Protocol (MCP) to interact with the Audience API.

Overview​

This tutorial guides you through using IQM MCP to access and manage audiences with the Audience API. You'll learn how to upload a Matched audience and create a Segmented audience using the MCP interface.

The Audience MCP supports all audience operations as documented in the Audience API guidelines, so you can manage all types of audiences using the MCP.

Before you begin​

To create an audience using IQM MCP, the following are required:

  1. An account on the IQM platform
    • See Before you begin to create an account and request a Client ID and Client Secret
  2. A CSV or XLSX file for matching
info

File requirements for audience matching:

  • CSV or XLSX file for audience matching with maximum 1GB or 5M records
  • Without Voter ID / Email / Phone / Address in the file
    • One of the following system field combinations is required for matching
      • First Name, Last Name, ZIP, State
      • Last Name, Street Address, ZIP, State
      • Street Address, ZIP, state
    • Other fields are optional and can be added along with the above fields
  • With Voter ID / Email / Phone / Address in the file
    • Only one of these fields is required - Voter ID or Email or Phone, or Address. The preferred format for full address is Street, City, ZIP, and State
    • Other fields are optional and can be added along with one of the above fields

About IQM audiences​

The Audience API allows you to create different types of audiences for campaign targeting based on desired specifications. You can create new audiences, retrieve details about existing audiences, and update or delete audiences as needed.

The following table describes each type of audience:

TypeDescription
Matched audienceUpload a CSV or XLSX file with audience details, which is then matched with IQM's user database to create a custom audience segment.
Retargeted audienceAdd a tracking tag to your website allowing you to track users who visit so they can be retargeted to receive ads in the future.
Geofarmed audienceDefine an audience by a custom geographical area.
Campaign audienceRetarget an audience associated with a campaign.
Segmented audienceGroup users by common characteristics to reach specific target audiences.
Pre-bid audienceSelect multiple pre-bid segments and group them together into an audience.
Contextual audienceIQM adds users to an audience when they visit sites featuring specified keywords or URLs.
Lookalike audienceAnalyzes an existing audience and generates a new one based on specified size and similarity percentage.
ABM audienceAn Account Based Marketing (ABM) audience for Healthcare campaigns.
ICT audienceAn Integrated Care Team (ICT) audience is a type of Matched audience intended for healthcare-audience expansion. See the Healthcare vertical for more information.
Custom Voter audience (CVA)Audiences for Political campaigns based on voter segments which are defined by a combination of demographic, psychographic, and behavioral attributes.

More resources​

Upload a Matched audience​

You can use the MCP to upload a Matched audience by performing the following actions:

PromptResponse exampleNotes
Let's upload a Matched audienceMCP prompts the user to choose the type of audience and to upload the audience file.
Use this file and call it Matched1MCP confirms the file upload and assigns the specified name to the Matched audience. It also reads the file to extract the audience columns and creates the relevant column combinations.

Create a Segmented audience​

You can also use the MCP to create a Segmented audience by providing the segment details and the desired AND/OR relationship.

PromptResponse exampleNotes
Now let's create a Segmented audience. Use segment IDs 1045525 and 1045523 in an OR relationship
tip

Ask the MCP to explain the AND/OR relationship or check out our Help Center article for more information.

Update that Segmented audience with the name Segmented1

Get audience details​

You can ask the MCP to show you the details of any of your audiences by providing the audience name, ID, or by asking for a list of audiences.

PromptResponse exampleNotes
show me the details of audience Segmented1
Show me a list of all audiencesMCP shows a list of all audiences associated with the active Workspace, including their names and IDs.
Show me the audience count by type
What are the audience types? Please provide a brief explanation of what they areMCP shows the different types of audiences associated with the active Workspace, along with a brief explanation of each type.

Tools index​

The table below lists the tools that MCP uses in this tutorial, with links to their API documentation. For every Audience API tool available in MCP, see the Audience API section of the Tools index.

Tool nameDescriptionDocumentation
getAudienceColumnCombinationsGet valid matched audience column combinationsMatched column combinations
create_matched_audienceCreate a Matched audience from the uploaded fileCreate Matched audience
createSegmentedAudienceCreate a new segmented audienceCreate Segmented audience
updateAudienceNameUpdate an audience's nameUpdate audience name
getSegmentedAudienceGet segmented audience details by IDSegmented audience details
getAudienceListGet a detailed list of audiences with insights detailsAudience details list
getAudienceCountByTypeGet audience counts grouped by typeAudience count by type
getAudienceTypesGet the list of audience typesAudience type list
Have a question?
Was this page helpful?