Pinterest Ads

Pinterest Ads

Strategic skill for managing Pinterest Ads campaigns via the Pinterest Ads API v5 surface exposed by the Hyper MCP. Ad-group creation goes through a direct REST call (bypassing SDK model conversion) so parameter types must be sent exactly as documented — strings as strings, integers as integers.

Out of scope — defer to other skills

Requirements

• Hyper MCP installed and connected. https://app.hyperfx.ai/mcp
• Pinterest Ads integration connected at https://app.hyperfx.ai/integrations (Pinterest Business account with ad account access).

If pinterest_ads_list_ad_accounts is not in the tool list, stop and tell the user to enable the Hyper MCP and connect Pinterest Ads.

Tool surface

Critical Rules

CRITICAL: All budgets and bids are in microcurrency. $1.00 = 1,000,000 microdollars. $50/day = 50,000,000. Never pass dollar amounts directly.

CRITICAL: When using is_flexible_daily_budgets: true, you MUST also set is_campaign_budget_optimization: true. FDB requires CBO.

CRITICAL: Lifetime CBO campaigns MUST include end_time (Unix timestamp).

CRITICAL: Create campaigns with status PAUSED initially. Never launch live without user review.

CRITICAL: WEB_CONVERSION ad groups MUST use billable_event="IMPRESSION" (NOT CLICKTHROUGH) and MUST include optimization_goal_metadata with attribution_windows, conversion_event, conversion_tag_id, and cpa_goal_value_in_micro_currency.

CRITICAL: Keyword creation REQUIRES match_type. Without it, the API returns 500 errors.

CRITICAL: CBO campaigns manage budget at the campaign level. Do NOT set budget_in_micro_currency on ad groups under CBO campaigns.

IMPORTANT: retention_days is deprecated for ENGAGEMENT audiences. Omit it from audience rules.

Phase 1: Account Discovery

Call pinterest_ads_list_ad_accounts() to list accessible accounts.

• If multiple: ask the user to select one.
• If single: inform the user and proceed.
• Note the ad_account_id — it's required for every subsequent tool call.

Phase 2: Account Assessment

Existing campaign audit

Run these in parallel to understand the account state:

pinterest_ads_list_campaigns(ad_account_id="<AD_ACCOUNT_ID>")
pinterest_ads_list_ad_groups(ad_account_id="<AD_ACCOUNT_ID>")
pinterest_ads_list_ads(ad_account_id="<AD_ACCOUNT_ID>")
pinterest_ads_list_audiences(ad_account_id="<AD_ACCOUNT_ID>")
pinterest_ads_list_conversion_tags(ad_account_id="<AD_ACCOUNT_ID>")

Research & confirm

• Get the destination URL and creative assets (Pin IDs).
• Understand the campaign objective (awareness, consideration, conversions).
• Confirm daily / lifetime budget.
• Confirm target audience (geo, interests, demographics).
• If WEB_CONVERSION: ensure a conversion tag exists.

Phase 3: Campaign Structure

Pinterest campaign hierarchy

Ad Account
└── Campaign (objective, budget for CBO)
    └── Ad Group (targeting, bidding, schedule)
        └── Ad (creative Pin + tracking)

Campaign objectives

CBO vs Non-CBO

Phase 4: Campaign Creation

1. Create campaign

pinterest_ads_create_campaign(
    ad_account_id="<AD_ACCOUNT_ID>",
    name="Spring Collection 2026",
    objective_type="WEB_CONVERSION",
    status="PAUSED",
    daily_spend_cap=50000000,
    is_campaign_budget_optimization=true,
    is_flexible_daily_budgets=true,
)

Parameter requirements:

• is_flexible_daily_budgets=true → requires is_campaign_budget_optimization=true.
• lifetime_spend_cap → requires end_time.
• All spend caps in microcurrency.

2. Create ad group

CRITICAL: This tool sends a direct REST call to the Pinterest API v5 (bypassing SDK models). Pass parameter values exactly as documented — strings as strings, integers as integers.

CRITICAL: Ad-group parameters depend heavily on the parent campaign's objective_type. Follow the objective-specific templates below exactly.

`billable_event` values: CLICKTHROUGH, IMPRESSION, VIDEO_V_50_MRC.

Objective / billable_event compatibility

Template: CONSIDERATION campaign (simplest, non-CBO)

pinterest_ads_create_ad_group(
    ad_account_id="<AD_ACCOUNT_ID>",
    name="US Women 25-54",
    campaign_id="<CAMPAIGN_ID>",
    billable_event="CLICKTHROUGH",
    bid_in_micro_currency=1000000,
    budget_in_micro_currency=10000000,
    targeting_spec={"LOCATION": ["US"], "GENDER": ["female"], "MINIMUM_AGE": "25", "MAXIMUM_AGE": "54"},
    bid_strategy_type="AUTOMATIC_BID",
    status="PAUSED",
)

Template: CONSIDERATION campaign (CBO — no ad group budget)

pinterest_ads_create_ad_group(
    ad_account_id="<AD_ACCOUNT_ID>",
    name="US Women 25-54",
    campaign_id="<CAMPAIGN_ID>",
    billable_event="CLICKTHROUGH",
    bid_in_micro_currency=1000000,
    targeting_spec={"LOCATION": ["US"], "GENDER": ["female"], "MINIMUM_AGE": "25", "MAXIMUM_AGE": "54"},
    bid_strategy_type="AUTOMATIC_BID",
    status="PAUSED",
)

Template: WEB_CONVERSION campaign (requires optimization_goal_metadata)

CRITICAL: WEB_CONVERSION ad groups MUST use billable_event="IMPRESSION" (NOT CLICKTHROUGH). They MUST provide optimization_goal_metadata with the full nested structure shown below.

TYPE SAFETY: cpa_goal_value_in_micro_currency MUST be a string (e.g., "5000000"), NOT an integer. conversion_tag_id MUST be a string. attribution_windows values MUST be integers.

pinterest_ads_create_ad_group(
    ad_account_id="<AD_ACCOUNT_ID>",
    name="Conversion - Checkout",
    campaign_id="<CAMPAIGN_ID>",
    billable_event="IMPRESSION",
    targeting_spec={"LOCATION": ["US"]},
    bid_strategy_type="AUTOMATIC_BID",
    status="PAUSED",
    optimization_goal_metadata={
        "conversion_tag_v3_goal_metadata": {
            "attribution_windows": {
                "click_window_days": 30,
                "engagement_window_days": 30,
                "view_window_days": 1,
            },
            "conversion_event": "CHECKOUT",
            "conversion_tag_id": "<CONVERSION_TAG_ID>",
            "cpa_goal_value_in_micro_currency": "5000000",
            "is_roas_optimized": false,
        },
    },
)

`conversion_event` values: PAGE_VISIT, SIGNUP, CHECKOUT, CUSTOM, VIEW_CATEGORY, SEARCH, ADD_TO_CART, WATCH_VIDEO, LEAD, APP_INSTALL.

`attribution_windows` — only these exact combos are accepted (click / engage / view):

The tool auto-normalizes: if attribution_windows is missing or uses an invalid combo, it defaults to 30/30/1. It also auto-wraps in conversion_tag_v3_goal_metadata if the wrapper is missing, coerces cpa_goal_value_in_micro_currency to string, and defaults CPA to $10 if omitted.

`cpa_goal_value_in_micro_currency`: STRING (pattern ^[0-9]+$). Set high enough to avoid "CPA goal value below bid floor" errors. Example: "10000000" = $10 CPA.

Optional fields in `conversion_tag_v3_goal_metadata`:

• is_roas_optimized (boolean) — set true only when conversion_event="CHECKOUT" AND bid_strategy_type="AUTOMATIC_BID".
• learning_mode_type (string) — "ACTIVE" or "NOT_ACTIVE". Omit if not needed.

Template: AWARENESS campaign

pinterest_ads_create_ad_group(
    ad_account_id="<AD_ACCOUNT_ID>",
    name="Brand Awareness",
    campaign_id="<CAMPAIGN_ID>",
    billable_event="IMPRESSION",
    bid_in_micro_currency=2000000,
    targeting_spec={"LOCATION": ["US"]},
    bid_strategy_type="AUTOMATIC_BID",
    status="PAUSED",
)

Budget rules for ad groups

• CBO campaigns: Do NOT set budget_in_micro_currency on the ad group. Budget is controlled at the campaign level.
• Non-CBO campaigns: budget_in_micro_currency is REQUIRED at the ad group level.

`bid_strategy_type` values: AUTOMATIC_BID, MAX_BID, TARGET_AVG.

`status`: Always create with status="PAUSED" for review. Set to "ACTIVE" after user approval.

`pacing_delivery_type`: Optional. "STANDARD" (default) or "ACCELERATED".

`targeting_spec` keys (all values are arrays of strings unless noted):

• LOCATION — ISO Alpha-2 country codes or US Nielsen DMA codes (e.g., ["US", "CA"], ["807"]). Required (or use GEO).
• GEO — Region codes (e.g., ["BE-VOV"]) or postal codes (e.g., ["US-94107"]). Alternative to LOCATION.
• GENDER — ["male"], ["female"], or ["unknown"].
• MINIMUM_AGE — string "18" through "65" (use with MAXIMUM_AGE, not with AGE_BUCKET).
• MAXIMUM_AGE — string "18" through "65" or "65+" (use with MINIMUM_AGE).
• AGE_BUCKET — ["18-24", "25-34", "35-44", "45-54", "55-64", "65+"] (legacy, cannot combine with MIN/MAX_AGE).
• INTEREST — interest IDs from Pinterest taxonomy.
• LOCALE — ISO 639-1 language codes (e.g., ["en"]).
• APPTYPE — ["android_mobile", "android_tablet", "ipad", "iphone", "web", "web_mobile"].
• AUDIENCE_INCLUDE — audience IDs to include.
• AUDIENCE_EXCLUDE — audience IDs to exclude.

3. Create ad

pinterest_ads_create_ad(
    ad_account_id="<AD_ACCOUNT_ID>",
    ad_group_id="<AD_GROUP_ID>",
    creative_type="REGULAR",
    pin_id="<PIN_ID>",
    name="Spring Sale Ad",
    status="ACTIVE",
    destination_url="https://example.com/spring-sale",
)

`creative_type` values: REGULAR, VIDEO, SHOPPING, CAROUSEL, MAX_VIDEO, SHOP_THE_PIN, IDEA.

Phase 5: Audience & Targeting

Create audience

pinterest_ads_create_audience(
    ad_account_id="<AD_ACCOUNT_ID>",
    name="Website Visitors",
    audience_type="VISITOR",
    rule={"visitor_source_id": "<TAG_ID>", "type": "visitors"},
)

`audience_type` values: CUSTOMER_LIST, VISITOR, ENGAGEMENT, ACTALIKE.

Rule structure by type:

Create customer list

pinterest_ads_create_customer_list(
    ad_account_id="<AD_ACCOUNT_ID>",
    name="Email Subscribers",
    records="user1@example.com,user2@example.com,...",
    list_type="EMAIL",
)

`list_type` values: EMAIL, IDFA, MAID, LR_ID, DLX_ID, HASHED_PINNER_ID.

Lists must match at least 100 Pinterest accounts after processing.

Phase 6: Conversion Tracking

List existing tags

pinterest_ads_list_conversion_tags(ad_account_id="<AD_ACCOUNT_ID>")

Create conversion tag

pinterest_ads_create_conversion_tag(
    ad_account_id="<AD_ACCOUNT_ID>",
    name="Purchase Tracking",
    aem_enabled=true,
)

Send conversion event

pinterest_ads_send_conversion_event(
    ad_account_id="<AD_ACCOUNT_ID>",
    event_name="checkout",
    action_source="web",
    event_time=1709424000,
    event_id="unique_event_123",
    user_data={
        "em": ["5e884898da28047151d0e56f8dc6292773603d0d6aabbdd62a11ef721d1542d8"],
        "client_ip_address": "192.168.1.1",
        "client_user_agent": "Mozilla/5.0...",
    },
    custom_data={"currency": "USD", "value": "99.99"},
)

`event_name` values: add_to_cart, checkout, custom, lead, page_visit, search, signup, view_category, watch_video.

`action_source` values: app_android, app_ios, web, offline.

`user_data` requirements (at least one identifier required):

• em — array of SHA256-hashed email addresses (NOT plain text).
• hashed_maids — array of hashed mobile ad IDs.
• OR: client_ip_address + client_user_agent.

Phase 7: Keywords

CRITICAL: match_type is REQUIRED. Without it, the Pinterest API returns a 500 error.

pinterest_ads_create_keyword(
    ad_account_id="<AD_ACCOUNT_ID>",
    parent_id="<AD_GROUP_ID>",
    value="spring fashion trends",
    match_type="BROAD",
)

`match_type` values: BROAD, PHRASE, EXACT, EXACT_NEGATIVE, PHRASE_NEGATIVE.

• BROAD — ads show for related searches.
• PHRASE — ads show when search contains the phrase.
• EXACT — ads show only for exact match.
• EXACT_NEGATIVE / PHRASE_NEGATIVE — exclude these terms.

`bid` (optional): Bid in microcurrency for this keyword. Overrides ad group default bid.

Phase 8: Analytics

pinterest_ads_get_campaign_analytics(
    ad_account_id="<AD_ACCOUNT_ID>",
    campaign_ids=["<CAMPAIGN_ID>"],
    start_date="2026-02-01",
    end_date="2026-03-01",
    columns=["SPEND_IN_MICRO_DOLLAR", "TOTAL_IMPRESSION", "TOTAL_CLICKTHROUGH", "CPC_IN_MICRO_DOLLAR", "CTR", "CPM_IN_MICRO_DOLLAR"],
    granularity="DAY",
)

`granularity` values: TOTAL, DAY, HOUR, WEEKLY, MONTHLY.

Common analytics columns: SPEND_IN_MICRO_DOLLAR, TOTAL_IMPRESSION, TOTAL_CLICKTHROUGH, CPC_IN_MICRO_DOLLAR, CPM_IN_MICRO_DOLLAR, CTR, ECTR, TOTAL_CONVERSIONS, TOTAL_CONVERSIONS_VALUE_IN_MICRO_DOLLAR.

Update Operations

pinterest_ads_update_campaign, pinterest_ads_update_ad_group, and pinterest_ads_update_ad all follow the same shape — pass ad_account_id, the entity ID (campaign_id / ad_group_id / ad_id), and any fields you want to change. Statuses use ACTIVE, PAUSED, or ARCHIVED (cannot be unarchived).

pinterest_ads_update_campaign(
    ad_account_id="<AD_ACCOUNT_ID>",
    campaign_id="<CAMPAIGN_ID>",
    name="Updated Name",
    status="PAUSED",
    daily_spend_cap=75000000,
)

Campaign Workflow

Discovery → audit account → research (objectives, audience, assets) → confirm strategy → create campaign (PAUSED) → create ad groups → create ads → review → activate.

Known Limitations

Safety Rules

Never:

• Assume Pin IDs or ad account IDs — always ask or look up.
• Skip the account audit phase.
• Create campaigns without explicit approval.
• Set campaigns to ACTIVE without user consent.
• Pass dollar amounts instead of microcurrency.
• Use retention_days for ENGAGEMENT audiences.
• Create WEB_CONVERSION ad groups without optimization_goal_metadata.
• Use CLICKTHROUGH billable_event for WEB_CONVERSION campaigns (use IMPRESSION).
• Set ad group budgets on CBO campaigns.
• Create keywords without specifying match_type.
• Pass cpa_goal_value_in_micro_currency as an integer (must be a string like "5000000").
• Omit conversion_tag_id from WEB_CONVERSION optimization metadata (list tags first, use a real ID).