account | DynamicAccount | Yes | - | Select the X Ads account to create the ad in. |
update_type | string or SelectableOption | Yes | - | Choose whether to create a single ad or multiple at once. Options: single or bulk. |
ad_group_id | string or SelectItem | No | - | Ad group (line item) to run the ad in. Required unless post_only is enabled. Keep the ad group or campaign paused until you are ready, since X ads have no status of their own and go live with their ad group. |
ad_name | string | No | - | Internal name for the post and card, up to 80 characters. |
text | string | No | - | The post’s text, up to 280 characters. Required unless media is attached. |
image_urls | string or array of string | No | - | Images to upload (list or comma-separated), up to 4. GIFs work here too, one per post. Accepts direct URLs, Google Drive share links with sharing set to ‘Anyone with the link’, or files uploaded through Markifact. Exactly one image is allowed when a website or app destination is set, because an X card holds one media item. |
media_keys | string or array of string | No | - | Already-uploaded media keys to use instead of image_urls, e.g. from x_ads_upload_media or x_ads_list_media. |
website_url | string | No | - | Landing page URL. Setting this builds a website card with the headline below, which is what X’s composer calls a Website destination. |
headline | string | No | - | Card headline shown under the image. Required with website_url. |
call_to_action | enum (BOOK, CONNECT, INSTALL, OPEN, ORDER, PLAY, SHOP) | No | - | App card button label: BOOK, CONNECT, INSTALL, OPEN, ORDER, PLAY, or SHOP. Required with app store identifiers. |
country_code | string | No | - | ISO alpha-2 country of the app store, e.g. US. Required for app destinations. |
ios_app_store_identifier | string | No | - | Numeric App Store id, e.g. 333903271. Setting it builds an app card. |
googleplay_app_id | string | No | - | Google Play package name, e.g. com.example.app. Setting it builds an app card. |
ios_deep_link | string | No | - | Deep link opened on iOS; only sent alongside the App Store id. |
googleplay_deep_link | string | No | - | Deep link opened on Android; only sent alongside the Google Play id. |
conversation_settings | enum (EVERYONE, FOLLOWING, MENTIONED_USERS) | No | - | Who can reply: EVERYONE (default), FOLLOWING, or MENTIONED_USERS. |
post_only | boolean | No | False | Create the Promoted-only post and card without promoting, so they can be reused across ad groups with x_ads_create_ad_from_post. |
return_detailed_results | boolean | No | False | Include the full post and ad objects in the output. |
structured_data | array (also accepts a comma-separated string) | No | - | Use only when update_type is bulk. Columns: image_urls or media_keys, plus optional text, ad_group_id, ad_name, website_url, headline, call_to_action, country_code, ios_app_store_identifier, googleplay_app_id and the deep links. Up to 100 rows. |
