> ## Documentation Index
> Fetch the complete documentation index at: https://docs.markifact.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Create Image Ad

> Create responsive image ads in Microsoft Audience Network ad groups, singly or in bulk, from image URLs or existing media IDs

Create responsive image ads in Microsoft Audience Network ad groups, singly or in bulk, from image URLs or existing media IDs. Defaults to PAUSED. Creative-only mode uploads media and returns ad payloads without creating ads; it is not a dry run.

| | |
| - | - |
| **App** | Microsoft Ads |
| **Operation ID** | `microsoft_ads_create_image_ad` |
| **Type** | Action |
| **Connection** | `microsoft_ads` (required) |
| **Credits per run** | 1 |
| **Agent / MCP tool** | Yes |
| **Requires approval** | Yes (write operation) |

## Inputs

| Field | Type | Required | Default | Description |
| - | - | - | - | - |
| `ad_group_id` | string or SelectItem | No | - | Destination Audience ad group ID. Required per bulk row; never inherited from the top level. Not required for creative\_only. |
| `business_name` | string | No | - | Business name, required per ad, up to 25 characters. |
| `headlines` | string or array of string | No | - | Required per ad. Short headlines as an array or JSON array string. Microsoft supports 1–15 headlines, up to 30 final characters each. |
| `long_headlines` | string or array of string | No | - | Required per ad. Long headlines as an array or JSON array string. Microsoft supports 1–5 long headlines, up to 90 characters each. |
| `descriptions` | string or array of string | No | - | Required per ad. Descriptions as an array or JSON array string, up to 90 final characters each. |
| `final_url` | string | No | - | Landing page URL, required per ad. |
| `image_url` | string | No | - | Default image to upload. Accepts direct URLs, Google Drive share links with sharing set to 'Anyone with the link', or files uploaded through Markifact. Recommended 1200×628. Use this or image\_media\_id or native advanced\_fields.Images. |
| `image_media_id` | string | No | - | Existing Microsoft image media ID from the same ad account. Use instead of image\_url to reuse media. |
| `image_subtype` | string | No | `OriginalImage` | ImageAsset SubType for the default image. Default: OriginalImage (current Audience default). Microsoft also supports LandscapeImageMedia and SquareImageMedia; native crop settings and additional images can be supplied through advanced\_fields.Images. |
| `ad_status` | string or SelectableOption | No | `PAUSED` | Initial status. Default: PAUSED. Also the default for bulk rows. |
| `tracking_url_template` | string | No | - | Optional Microsoft tracking template, for example \{lpurl}?source=microsoft. |
| `final_url_suffix` | string | No | - | Optional URL suffix, for example utm\_source=microsoft\&utm\_medium=paid. |
| `advanced_fields` | object or string | No | - | Additional native ResponsiveAd fields or JSON object, including Images asset links/crops, ImpressionTrackingUrls, FinalMobileUrls or UrlCustomParameters. Example: \{"Images":\[\{"Asset":\{"Type":"ImageAsset","Id":123,"SubType":"OriginalImage"}}]}. Named inputs take precedence. Type and Status are controlled by this operation. Do not combine Images with image\_url/image\_media\_id. |
| `account` | object or array of object or MicrosoftAdsAccountItem or string or integer | Yes | - | Microsoft Ads account that owns the ad groups and image media. |
| `update_type` | enum (`single`, `bulk`) | No | `single` | Create one image ad or supply structured\_data for bulk creation. |
| `structured_data` | array of object or string | No | - | Array of image-ad rows or JSON array string. Each row requires ad\_group\_id unless creative\_only. All other top-level ad fields act as defaults; row values win. Rows use the same fields as single mode. |
| `creative_only` | boolean | No | `False` | Upload/resolve images and return ResponsiveAd payloads without creating ads. This still uploads image media; it is not a dry run. Microsoft has no independent ad-creative object. |
| `return_detailed_results` | boolean | No | `False` | Return per-row success/error details, including IDs of ads already created. Mixed results are always returned to avoid hiding successful writes. If all rows fail, raises unless enabled. |

### MicrosoftAdsAccountItem

| Field | Type | Required | Default | Description |
| - | - | - | - | - |
| `value` | string | Yes | - | |
| `label` | string | Yes | - | |
| `customerId` | string | No | - | The Microsoft Ads customer ID used for REST CustomerId headers. If omitted, it is resolved from the account ID. |

### SelectItem

| Field | Type | Required | Default | Description |
| - | - | - | - | - |
| `value` | string | Yes | - | The value of the selectable item. |
| `label` | string | Yes | - | The label of the selectable item, used for display purposes. If not provided, defaults to the value. |

### SelectableOption

| Field | Type | Required | Default | Description |
| - | - | - | - | - |
| `value` | string | Yes | - | |
| `label` | string | Yes | - | |

## Output

**Type**: `Dict`

Returns per-row ad IDs/status, errors and uploaded media IDs. Creative-only results contain ResponsiveAd payloads. Mixed outcomes retain successful IDs so callers retry only failed rows. Credits: one per created ad, or one per successful creative-only run.

**Fields**: `created_count`, `prepared_count`, `failed_count`, `results`


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.