create_conversion_goal
Create conversion goals in Microsoft Advertising to track user actions like purchases, signups, or offline conversions. Set goal type, value, and conversion window for performance measurement.
Instructions
Create a conversion goal. Goals are created Active (a goal does not spend; a paused goal silently fails to record conversions) — pass status="Paused" to override.
Conversion goals CANNOT be deleted (Microsoft has no delete API) — they can only be paused or renamed, so name them deliberately.
Microsoft has no native "calls from ads" goal. The bid-eligible path for phone calls is an "OfflineConversion" goal fed by apply_offline_conversions (keyed by MSCLKID) — create that goal here, then upload qualifying calls with apply_offline_conversions.
Input Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| name | Yes | Goal name. For an OfflineConversion goal, this is the name you pass as conversion_name to apply_offline_conversions. | |
| value | No | ||
| status | No | "Active" (default) or "Paused". | |
| tag_id | No | UET tag id (from get_uet_tags) — REQUIRED for the web goals, must be omitted for OfflineConversion (it is keyed by MSCLKID, not a UET tag). | |
| goal_type | Yes | One of "OfflineConversion", "Url", "Event", "Duration", "PagesViewedPerVisit". The four web goals require tag_id; OfflineConversion does not (it keys on MSCLKID). | |
| count_type | No | "All" (every conversion per click) or "Unique" (one per click). | |
| revenue_type | No | Value model — "FixedValue" (requires revenue_value), "VariableValue", or "NoValue". | |
| url_operator | No | Url goal — match operator: "Equals" (default), "BeginsWith", "RegularExpression", "Contains". | Equals |
| goal_category | No | Reporting category, e.g. "Purchase", "SubmitLeadForm", "Contact". Required for "Event" and "OfflineConversion" goals (Microsoft rejects them with InvalidGoalCategory if omitted); recommended for the others too. | |
| revenue_value | No | Revenue amount (required for "FixedValue"). | |
| label_operator | No | ||
| url_expression | No | Url goal — the URL to match (required for "Url"). | |
| value_operator | No | ||
| action_operator | No | ||
| label_expression | No | ||
| action_expression | No | ||
| category_operator | No | ||
| category_expression | No | ||
| exclude_from_bidding | No | Omit to inherit Microsoft's default (false = included in bidding); true excludes the goal from the Conversions column and ECPC/tCPA bid math. | |
| minimum_pages_viewed | No | PagesViewedPerVisit goal — minimum pages per visit (required for "PagesViewedPerVisit"). | |
| revenue_currency_code | No | ISO currency code for revenue_value, e.g. "USD". | |
| minimum_duration_in_seconds | No | Duration goal — minimum time-on-site in seconds (required for "Duration"). Note: this measures UET dwell time, NOT phone-call length. | |
| conversion_window_in_minutes | No | Click-to-conversion lookback in minutes (e.g. 43200 = 30 days). |
Output Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| ok | Yes | ||
| ids | No | ||
| message | Yes | ||
| partial_errors | No |