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
   • Download a sample file

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:

Type	Description
Matched audience	Upload a CSV or XLSX file with audience details, which is then matched with IQM's user database to create a custom audience segment.
Retargeted audience	Add 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 audience	Define an audience by a custom geographical area.
Campaign audience	Retarget an audience associated with a campaign.
Segmented audience	Group users by common characteristics to reach specific target audiences.
Pre-bid audience	Select multiple pre-bid segments and group them together into an audience.
Contextual audience	IQM adds users to an audience when they visit sites featuring specified keywords or URLs.
Lookalike audience	Analyzes an existing audience and generates a new one based on specified size and similarity percentage.
ABM audience	An Account Based Marketing (ABM) audience for Healthcare campaigns.
ICT audience	An 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

• Audience API guidelines
• Create a Contextual audience quickstart guide
• Upload a Matched audience tutorial
• Audience targeting and data management Help Center article

Upload a Matched audience

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

Prompt	Response example	Notes
Let's upload a Matched audience		MCP prompts the user to choose the type of audience and to upload the audience file.
Use this file and call it Matched1		MCP 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.

Prompt	Response example	Notes
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.

Prompt	Response example	Notes
show me the details of audience Segmented1
Show me a list of all audiences		MCP 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 are		MCP shows the different types of audiences associated with the active Workspace, along with a brief explanation of each type.

Tools index

In the tables below you can find the complete set of audience tools available in the MCP, categorized by audience type.

Each tool includes a brief description and a link to the corresponding API documentation for more details on its functionality and usage.

Use this index as a reference to explore the various audience management capabilities of the MCP and how they relate to the Audience API endpoints.

Audience management

Tool name	Description	Documentation
updateAudienceName	Update an audience's name	Update audience name
regenerateAudience	Regenerate a failed audience	Regenerate audience
deleteAudiences	Delete one or more audiences by ID	Delete audience
attachDataPartnerToAudience	Attach a data partner to an audience	Attach data partner
getAudienceInsights	Get a demographic and geographic insights profile for an audience	Get audience Insights
generateInsightsForMatchedAudience	Generate an Audience Insights report for one or more audiences	Create Audience Insights report

Audience lists and counts

Tool name	Description	Documentation
getAudienceList	Get a detailed list of audiences with insights details	Audience details list
getAudienceBasicList	Get a basic list of audiences	Basic audience details
getAudienceCountByStatus	Get audience counts grouped by status	Audience count by status
getAudienceCountByType	Get audience counts grouped by type	Audience count by type

Matched audiences

Tool name	Description	Documentation
createMatchedAudience_1	Create a matched audience for any vertical or subtype	Create Matched audience
updateMatchedAudience	Update the details of a matched audience	Update Matched audience
rematchMatchedAudience	Rematch or refresh a matched audience	Refresh Matched audience
getMatchedAudienceById	Get matched audience details by ID	Matched audience details
getAudienceFileUrl	Get a presigned download URL for an audience file
getDataFormats	Get the list of supported data formats for matched audiences	Data formats list for Matched audience
getAudienceDataPartners	Get matched audience data partners by vertical and subtype	Data partners list for Matched audience
getAudienceColumnWithDataFormats	Get matched audience columns by type, vertical, and subtype	Matched column list
getAudienceColumnCombinations	Get valid matched audience column combinations	Matched column combinations

Segmented audiences

Tool name	Description	Documentation
createSegmentedAudience	Create a new segmented audience	Create Segmented audience
updateSegmentedAudience	Update an existing segmented audience	Update Segmented audience
getSegmentedAudience	Get segmented audience details by ID	Segmented audience details
getSegmentsSearchList	Search the segments list	Search Segmented audiences
downloadSegmentsSearchList	Download the segments search list
getSegmentPartnerProviderList	Get the list of segment partner providers	Segment partner provider list
getSegmentsListByParentOrProvider	Get segments by parent or provider ID	Segment list by provider/partner IDs
getSegmentReachRange	Get the reach range list for segments	Reach range list for Segmented audiences
getSegmentPriceRange	Get the price range list for segments	Price range list for Segmented audiences

Retargeted audiences

Tool name	Description	Documentation
createRetargetedAudience	Create a new retargeted audience	Create Retargeted audience
updateRetargetedAudience	Update an existing retargeted audience	Update Retargeted audience
sendRetargetedPixelCodeEmail	Email a retargeted audience's pixel code to recipients	Retargeted audience email notification

Geofarmed audiences

Tool name	Description	Documentation
createGeoFarmedAudience	Create a new geofarmed audience	Create Geofarmed audience
getGeofarmedAudience	Get geofarmed audience details by ID	Geofarmed audience details

Contextual audiences

Tool name	Description	Documentation
createContextualAudiences	Create a new contextual audience	Create Contextual audience
getContextualAudienceDetails	Get contextual audience details by ID	Contextual audience details
validateProgrammaticUrls	Validate URLs for contextual audience targeting	Validate URL for Contextual audience

Lookalike audiences

Tool name	Description	Documentation
createLookalikeAudience	Create a new lookalike audience	Create Lookalike audience
getLookalikeAudienceById	Get lookalike audience details by ID	Get Lookalike audience details

Campaign audiences

Tool name	Description	Documentation
createCampaignAudience	Create a new campaign audience	Create Campaign audience
getCampaignAudience	Get campaign audience details by ID	Campaign audience details
getAttachedAudienceHistory	Get attached audience history for campaigns	Get Campaign audience history

Pre-bid audiences

Tool name	Description	Documentation
createPrebidAudience	Create a new pre-bid audience	Create Pre-bid audience
updatePrebidAudience	Update an existing pre-bid audience	Update Pre-bid audience
getPrebidAudienceDetails	Get pre-bid audience details by ID	Pre-bid audience details
getPrebidSegmentDetailsBySearch	Search pre-bid segment details by text or segment IDs	Search Pre-bid audience details
getProviderDetailsWithChildSegments	Get pre-bid providers and their immediate child segments	Get pre-bid provider child segment details
getPrebidChildSegmentDetailsByParentId	Get pre-bid child segment details by parent ID	Get pre-bid child segment details
getDvIvtFreePrebidSegments	Get pre-bid segments that are free of DV-IVT charges	DoubleVerify Pre-bid audience segment details

ABM and Healthcare audiences

Tool name	Description	Documentation
createAbmAudience	Create a new ABM audience	Create ABM audience
getAccountBasedAudienceDetailsByAudienceId	Get ABM audience details by ID	ABM audience details
getHealthcareDataFiltersFromFile	Extract ABM filters from an uploaded file	Upload ABM filter file
getHealthcareTitleList	Get the list of healthcare titles	Healthcare titles list
getHealthcareSpecialityList	Get the list of healthcare specialties	Healthcare specialties list
getHealthcareSystemList	Get the list of healthcare systems	Healthcare systems list
getHealthcareData	Get a list of healthcare data by filters	Healthcare data
getHealthcareDataStatistics	Get healthcare data statistics by filters	Healthcare statistics
getAccountTypeList	Get the list of healthcare account types	Healthcare account types
getAccountSubTypeList	Get the list of healthcare account subtypes	Healthcare account subtypes
getAccountNameList	Get the list of healthcare account names	Healthcare account names

ICT audiences

Tool name	Description	Documentation
createICTAudience	Create an ICT audience with optional extension audiences	Create ICT audience
getIctAudienceDetailsByAudienceId	Get ICT audience details by ID	Get ICT audience details
getAudienceSubTypesWithExtensionSubTypes	Get ICT audience subtypes with extension subtypes	ICT audience subtypes and extensions
getAudienceCountByDataPartner	Get ICT audience counts grouped by data partner	Get ICT audience count by data partner

Custom Voter Audiences (CVA)

Tool name	Description	Documentation
createCustomVoterAudience	Create a new Custom Voter Audience	Create Custom Voter Audience
getCustomVoterAudienceDetailsByAudienceId	Get Custom Voter Audience details by ID	Get Custom Voter Audience details
getSegmentDetails	Get segment details from the Custom Voter Audience segment catalogue	Get Custom Voter Audience segment details
getStates	Get the list of states available for Custom Voter Audiences	Get available states for Custom Voter Audiences

Static / reference data

Tool name	Description	Documentation
getAudienceTypes	Get the list of audience types	Audience type list
getAudienceSubtypes	Get the list of audience subtypes	Audience subtype list
getAudienceStatuses	Get the list of audience statuses	Audience status list
getFrequencyTypes	Get the list of active frequency types	Frequency type list
getAudienceProperties	Get platform configuration properties for audiences