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:
- An account on the IQM platform
- See Before you begin to create an account and request a Client ID and Client Secret
- A CSV or XLSX file for matching
- Download a sample file
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
- One of the following system field combinations is required for matching
- 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
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 name | Description | Documentation |
|---|---|---|
getAudienceColumnCombinations | Get valid matched audience column combinations | Matched column combinations |
create_matched_audience | Create a Matched audience from the uploaded file | Create Matched audience |
createSegmentedAudience | Create a new segmented audience | Create Segmented audience |
updateAudienceName | Update an audience's name | Update audience name |
getSegmentedAudience | Get segmented audience details by ID | Segmented audience details |
getAudienceList | Get a detailed list of audiences with insights details | Audience details list |
getAudienceCountByType | Get audience counts grouped by type | Audience count by type |
getAudienceTypes | Get the list of audience types | Audience type list |