MCP Insights tutorial
Use IQM Model Context Protocol (MCP) to interact with the Insights API.
Overview
This tutorial guides you through using IQM MCP to generate Insights reports and templates.
Before you begin
To manage Insights reports 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
- IQM MCP set up on your computer
- See the MCP Setup guide to set up MCP with your authorization credentials
- An audience and campaign that meet the eligibility requirements for generating Insights reports
- Audience Insights - Create Audience Insights report
- Audience Quality reports - AQ Insights report eligibility requirements
- Voter Level Data reports - VLD Insights eligibility requirements
- Script Lift Study reports - SLS Insights eligibility requirements
- Report templates - PLD Insights eligibility requirements
- Report templates - NLD Insights eligibility requirements
- Report templates - ICT Insights eligibility requirements
About IQM Insights
Insights reports are one of IQM's analytics tools that help Advertisers quickly identify trends and apply precise adjustments to deliver better results for campaigns.
With pre-defined metrics and dimensions, Insights reports can be generated for the following areas:
| Type | Description |
|---|---|
| Campaign Bidding Insights | Campaign Bidding Insights capture rejected campaigns and segment them based on rejection reason, allowing you to assess which parameters are limiting a campaign's success. |
| Audience Insights | Audience Insights provide in-depth reports of audience characteristics, interests, and behaviors to give you a deeper understanding of your target audience and create targeted and personalized advertising strategies. |
| Audience Quality (AQ) | AQ Insights leverage third-party healthcare data from PurpleLab to confirm audience exposure based on patient-level targeting criteria including prescriptions, diagnoses, and procedures. |
| Voter Level Data (VLD) | VLD Insights offer Insights about targeting in current or prior political campaigns. These reports include ad exposure, engagement data, demographic data, and voting-history details by voter. |
| Script Lift Study (SLS) | SLS Insights include key details about prescribing behaviors and how they're influenced by current and previous healthcare campaigns. |
| Provider Level Data (PLD) | PLD Insights include details about healthcare professionals targeted in your campaigns, and provide similar details as VLD Insights while adhering to healthcare data privacy regulations. |
| Nurse Level Data (NLD) | NLD Insights offer deeper visibility into how Non-NPI nurses engage with your campaigns. They uncover ad-exposure, engagement, demographic, and physician-specialty data to reveal reach and impact. |
| Integrated Care Team (ICT) | ICT Insights uncover key details about the ICT audiences you've targeted in previous and current campaigns. |
Some Insights reports need to be enabled by an administrator before you can access them. By default, VLD, PLD, SLS, and AQ reports are not accessible to advertiser users.
You can check an advertiser's access to Insights reports with the Get Customer Config Details endpoint.
More resources
- Insights API guidelines
- Create an Insights report
- Reporting and analytics
- Audience Quality Insights reports
- Voter Level Data (VLD) Insights reports
- Script Lift Study (SLS) Insights reports
- Provider Level Data (PLD) Insights reports
- Nurse Level Data (NLD) Insights reports
- Integrated Care Team (ICT) Insights reports
Generate Audience Insights reports
You can use IQM MCP to generate Insights reports for eligible audiences. Use the following prompts to generate Insights reports for your audiences:
| Prompt | Response example | Notes |
|---|---|---|
| Show me a list of audiences eligible for generating Insights reports | Check for Insights-eligible audiences first, or provide an Audience ID directly to generate reports for. | |
| Generate an Insights report for each of those audiences | ||
| Create download links for each of those reports |
Create Insights report templates
You can also use IQM MCP to create Insights report templates for PLD, NLD, and ICT. Use the following prompts to create report templates:
| Prompt | Response example | Notes |
|---|---|---|
| Get a list of eligible audiences for the PLD templates for the healthcare Workspace | MCP notes that PLD templates require eligible campaigns, not audiences, and suggests the correct tool. | |
| Create a PLD template for campaign 590512 | MCP prompts the user for the necessary template details: frequency, aggregation, and name. MCP then uses tools to validate the name and find frequency details. | |
| Create an NLD template with these details: campaign 590516, frequency monthly, name "NLD Report 1", and not aggregated | MCP validates the request details and asks for any missing parameters. | |
| Get me a list of MCP templates | ||
| Update template 705 to be inactive, then update template 700 to weekly frequency | MCP notes that it has to update the start date in order to update the template correctly. |
Tools index
The table below lists the tools that MCP uses in this tutorial, with links to their API documentation. For every Insights API tool available in MCP, see the Insights API section of the Tools index.
| Tool name | Description | Documentation |
|---|---|---|
getInsightsCreateEligibleAudienceList | Get a list of audiences eligible for Audience Insights report generation | Get a list of eligible audiences |
createInsightsDetails | Create an Audience Insights report for one or more audiences | Create Audience Insights report |
downloadInsights | Download an Audience Insights report (PDF or XLSX) | Download Insights report |
getStatusWiseCampaignsForInsightsReports | Get a status-wise list of campaigns eligible for Insights reports | Get eligible campaigns |
createTemplate | Create a report template | Create report template |
validateTemplateName | Validate a report template name | Validate template name |
getFrequencyMetadata | Get delivery frequency metadata for scheduling templates | Get scheduling frequencies |
getTemplates | Get a list of report templates | Get list of templates |
updateTemplate | Update a report template | Update report template |