# Pinterest Ads: Audiences & Conversion Tracking

## Phase 5: Audience & Targeting

### Create audience

```python
pinterest_ads_audiences_create(
    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:**

| Type | Rule example |
| --- | --- |
| `VISITOR` | `{"visitor_source_id": "<TAG_ID>", "type": "visitors"}` |
| `ENGAGEMENT` | `{"source": "AUDIENCE_RETENTION"}` (do NOT include `retention_days`) |
| `CUSTOMER_LIST` | `{"list_type": "EMAIL"}` |
| `ACTALIKE` | `{"source_id": "<SEED_AUDIENCE_ID>", "country": "US", "percentage": 5}` |

### Create customer list

```python
pinterest_ads_customer_lists_create(
    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

```python
pinterest_ads_conversion_tags_list(ad_account_id="<AD_ACCOUNT_ID>")
```

### Create conversion tag

```python
pinterest_ads_conversion_tags_create(
    ad_account_id="<AD_ACCOUNT_ID>",
    name="Purchase Tracking",
    aem_enabled=true,
)
```

### Send conversion event

```python
pinterest_ads_conversion_events_send(
    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`.

# Pinterest Ads: Campaign Creation

Read [discovery.md](discovery.md) first — the account audit and strategy confirmation must be complete.

## 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

| Objective | Use case |
| --- | --- |
| `AWARENESS` | Brand visibility, impressions |
| `CONSIDERATION` | Traffic, engagement |
| `VIDEO_VIEW` | Video completion |
| `WEB_CONVERSION` | Purchases, signups, leads |
| `CATALOG_SALES` | Shopping / product catalog |
| `WEB_SESSIONS` | Website visits |

### CBO vs Non-CBO

| Setting | CBO campaign | Non-CBO campaign |
| --- | --- | --- |
| Budget location | Campaign level (`daily_spend_cap` or `lifetime_spend_cap`) | Ad group level (`budget_in_micro_currency`) |
| `is_campaign_budget_optimization` | `true` | `false` |
| Ad group budget | Managed by Pinterest | Set per ad group |

## Phase 4: Campaign Creation

### 1. Create campaign

```python
pinterest_ads_campaigns_create(
    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

| Campaign `objective_type` | Required `billable_event` | `bid_in_micro_currency` | `optimization_goal_metadata` |
| --- | --- | --- | --- |
| `AWARENESS` | `IMPRESSION` | REQUIRED (integer) | Not needed |
| `CONSIDERATION` | `CLICKTHROUGH` | REQUIRED (integer) | Not needed |
| `VIDEO_VIEW` | `VIDEO_V_50_MRC` | Optional | Not needed |
| `WEB_CONVERSION` | `IMPRESSION` | Optional | **REQUIRED** |
| `CATALOG_SALES` | `CLICKTHROUGH` | REQUIRED (integer) | Not needed |
| `WEB_SESSIONS` | `CLICKTHROUGH` | Optional | Not needed |

#### Template: CONSIDERATION campaign (simplest, non-CBO)

```python
pinterest_ads_ad_groups_create(
    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)

```python
pinterest_ads_ad_groups_create(
    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**.

```python
pinterest_ads_ad_groups_create(
    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):

| `click_window_days` | `engagement_window_days` | `view_window_days` | Shorthand |
| --- | --- | --- | --- |
| 30 | 30 | 30 | 30/30/30 |
| 30 | 30 | 7 | 30/30/7 |
| 30 | 30 | 1 | 30/30/1 (default) |
| 7 | 7 | 7 | 7/7/7 |
| 7 | 7 | 1 | 7/7/1 |
| 7 | 0 | 0 | 7/0/0 |
| 1 | 1 | 1 | 1/1/1 |
| 1 | 0 | 0 | 1/0/0 |

> 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

```python
pinterest_ads_ad_groups_create(
    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

```python
pinterest_ads_create(
    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`.

# Pinterest Ads: Discovery & Account Assessment

## Phase 1: Account Discovery

Call `pinterest_ads_ad_accounts_list()` 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:

```python
pinterest_ads_campaigns_list(ad_account_id="<AD_ACCOUNT_ID>")
pinterest_ads_ad_groups_list(ad_account_id="<AD_ACCOUNT_ID>")
pinterest_ads_list(ad_account_id="<AD_ACCOUNT_ID>")
pinterest_ads_audiences_list(ad_account_id="<AD_ACCOUNT_ID>")
pinterest_ads_conversion_tags_list(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.

# Pinterest Ads: Keywords, Analytics & Updates

## Phase 7: Keywords

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

```python
pinterest_ads_keywords_create(
    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

```python
pinterest_ads_campaign_analytics_get(
    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_campaigns_update`, `pinterest_ads_ad_groups_update`, and `pinterest_ads_update` 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).

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