Indicates whether all or a subset of an ad group's existing keywords were used to determine the bid landscape.
The first date used to calculate the bid landscape. The start date is usually seven days prior to the end date. The difference between the start and end dates could be less than seven if performance data is not available, for example with a new ad group.
The most recent date used to calculate the bid landscape. The end date should be approximately 2 days prior to today's date when the service is called.
The list of the total estimated clicks, cost, and impressions from StartDate to EndDate given the suggested bid.
The month specified as an integer value in the range of 1 through 12, where 1 is January and 12 is December.
The year specified as a four-digit integer value.
The estimated number of clicks. This element will be nil if there is no estimate available.
The estimated number of impressions in the top or mainline ad results. This element will be nil if there is no estimate available.
The ISO code for the monetary unit of the suggested bid value and estimated performance statistics.
The estimated cost. This element will be nil if there is no estimate available.
Determines whether all or a subset of an ad group's existing keywords should be used to determine the bid landscape. If not specified in a request, the default value is Uniform.
The list of suggested keywords with minimum and maximum traffic estimates. Traffic estimates include average CPC, average position, clicks, CTR, impressions, and total cost.
The minimum traffic estimate. Traffic estimates include average CPC, average position, clicks, CTR, impressions, and total cost.
The maximum traffic estimate. Traffic estimates include average CPC, average position, clicks, CTR, impressions, and total cost.
The Microsoft Advertising identifier of the keyword.
The estimated number of impressions per week.
The estimated number of clicks per week.
The estimated CTR. The formula used to calculate the CTR is (clicks / impressions) * 100.
The estimated average CPC. The formula used to calculate the average CPC is (total cost / clicks).
The estimated average position on the web page for ads that were delivered. Average position is deprecated and from March 31st, 2021 onwards this value is "0" (zero).
The ad group identifier. This element is reserved for future use. The returned estimates are not based on any specific ad group.
The maximum cost per click filter criteria for all keyword estimates in the ad group. You can override this setting for specific keywords with the corresponding keyword estimators.
The list of keyword estimators with your keyword level filter criteria for traffic estimates.
The keyword used for traffic estimates. You can request estimates for Phrase and Broad match types.
The maximum cost per click filter criteria for the keyword. You can set the default maximum CPC for all of the ad group's keywords using the MaxCpc element of the AdGroupEstimator object. Use the keyword estimator if you want to override the max CPC for a specific keyword.
The identifier of the log entry that contains the details of the API call.
An array of operation errors that contains the reasons that explain why the service operation failed when the error is not related to a specific item in the batch of items.
An array of batch errors that identifies the items in the batch of items in the request message that caused the operation to fail. Each object contains the details that explain why the item caused the failure.
A numeric error code that identifies the error.
A symbolic string constant that identifies the error. For example, UserIsNotAuthorized.
A message that provides additional details about the error. This string can be empty.
A message that describes the error. For more information about troubleshooting and error handling, see Handling Service Errors and Exceptions and Operation Error Codes.
A message that provides additional details about the batch error. This string can be empty.
The zero-based index of the item in the batch of items in the request message that failed.
The identifier of the recommendation. Required.
The type of recommendation: ADD_BROAD_MATCH_KEYWORD, CAMPAIGN_BUDGET, KEYWORD, REMOVE_CONFLICTING_NEGATIVE_KEYWORD, RESPONSIVE_SEARCH_AD, or RESPONSIVE_SEARCH_AD_ASSET. Required.
The list of operations to apply recommendations. There is a limit of 100 operations per request. Required.
An array BatchError that contains details for any request items that were not successful. The list of errors does not correspond directly to the list of items in the request. The list can be empty if there were no errors, or it can include one or more error objects corresponding to each unsuccessful list item in the request.
The display URL of another advertiser who participates in the same auctions as you. The competing websites listed in your auction insights data are those who enter the same auctions as you, and are eligible for the same impressions that you are. Competitors aren't necessarily determined on how similar their keywords, match types, or other targeting settings are to your own, and auction insights doesn't provide a full report on these metrics for other advertisers.
The auction insight key performance indicators across all segments for the display domain. The aggregated data is available whether or not you also requested SegmentedKpis.
The list of auction insight key performance indicators for each unique combination of the requested segments. The segmented data is only available when you include an AuctionSegmentSearchParameter object in the GetAuctionInsightData request.
The list of strings identifies a distinct combination of requested segments. The list of segment values is in the same order as the AuctionSegment value set i.e., Day, Week, Month, Quarter, DayOfWeek, and then Device. For example if you requested the Day, Device, and Quarter segments for May 1, 2018, this element will contain a list of three strings in the following order: 5/1/2018 (Day), 4/1/2018 (Quarter), and PC (Device). This element is only applicable for the SegmentedKpis of an AuctionInsightEntry. This element is nil and not applicable for the AggregatedKpi of an AuctionInsightEntry.
The number of times an ad is shown on the Microsoft Advertising Network divided by the total available impressions. Use this to compare your share of impressions to the impression share of advertisers competing against you.
The percentage of time competitors' ads showed up on the search results page when your ad was shown. If the rate is high then this advertiser is a competitor since their ads shows up on the same search results page as yours.
The average position on the web page for ads that were delivered. Although it varies, positions 1-4 appear at the top of the search results page and positions 5-10 appear in other locations (for example, the bottom or the sidebar). Use this to compare your ad position with the average rank of all ads in the auction. Average position is deprecated and from March 31st, 2021 onwards this value is "0" (zero).
The percentage of time competitors' ads showed up higher than your ads on the search results page. If the rate is high then the other advertiser is getting more desirable ad positions than you. A high rate is likely due to a poor quality score or a low bid.
The percentage of time your ad showed up in the mainline, the premium ad position above the organic search results. Ads at the top of the page tend to receive more clicks.
The percentage of time your ad showed up higher on the search results pages than your competitors or your ad showed when theirs did not. If the rate is high, you are getting a more desirable ad position than other advertisers.
The number of times an ad is shown as the very first ad above the organic search results, divided by the total number of impressions it actually received. Ads at the absolute top of the page tend to receive more clicks. This element is not returned by default. To get this element, include the AbsoluteTopOfPageRate value in the ReturnAdditionalFields element when you call the GetAuctionInsightData service operation.
The segments if any were specified via one or more AuctionSegmentSearchParameter in the GetAuctionInsightData request. The list of auction segments is in the same order as the AuctionSegment value set i.e., Day, Week, Month, Quarter, DayOfWeek, and then Device. For example if you requested the Day, Device, and Quarter segments for May 1, 2018, this element will contain a list of three auction segments in the following order: Day, Quarter, and Device.
One or more auction insight entries i.e., one result per domain that you competed with in the auction.
The percent of impressions that were used to generate the auction insight entries. The value can range from 0 to 1.0, for example 0.8 indicates that 80 percent of impressions were used.
The number of keywords that were used to generate the auction insight entries.
Determines how you want the SegmentedKpis data segmented in the result from the GetAuctionInsightData operation. You can request auction insight data segmented by Day, DayOfWeek, Device, Month, Quarter, and Week.
Supported recommendation types in auto-apply mode. We will keep the list updated once new recommendations support auto-apply.Add responsive search ads Add multimedia ads Remove conflicting negative keywords Fix conversion goal setting issue Create conversion goalTo set the auto-apply opt-in status to the supported recommendation types above, please use the following keys as below: ResponsiveSearchAdsOpportunity MultiMediaAdsOpportunity RemoveConflictingNegativeKeywordOpportunity FixConversionGoalSettingsOpportunity CreateConversionGoalOpportunity .
The identifier of the campaign for the ad group that owns the keyword.
The identifier of the ad group that owns the keyword.
The identifier of the keyword to which the bid opportunity applies.
The current keyword bid amount specified for the match type in the MatchType element.
The match type to which the suggested bid value applies. The possible values are BroadMatch, ExactMatch, and PhraseMatch.
The suggested bid based on the last 7 days of performance history for the corresponding ad group.
The estimated impressions opportunities corresponding to the suggested bid.
The estimated clicks opportunities corresponding to the suggested bid.
The estimated increase in spend corresponding to the suggested bid.
An identifier that uniquely identifies the opportunity.
The audience breakdown category is Device.
The audience breakdown category is Gender.
The audience breakdown category is InMarket.
The audience breakdown category is Industry.
The audience breakdown category is JobFunction.
The audience breakdown category is LocationCountry.
The audience breakdown category is Location.
The audience breakdown category is LocationSubGeography.
The audience breakdown category is LocationMetroArea.
The audience breakdown category is LocationCity.
The audience breakdown category is LocationPostalCode.
The audience breakdown category is LocationCounty.
The location information about a location breakdown.
A list of location breakdown global values.
The identifier of the ad group to apply the suggested keyword to.
The identifier of the campaign that owns the ad group.
The name of the ad group to apply the suggested keyword to.
The name of the campaign that owns the ad group.
The match type that the suggested bid applies to. The following are the possible match-type values: 1 - Exact match 2 - Phrase match 3 - Broad match
The suggested bid that may result in your ads serving on the first page of the search query results.
The estimated monthly volume of user search queries that may match the suggested keyword for the corresponding MatchType element.
An indicator of competitive bids for this keyword relative to all search keywords. The competition score ranges from 0 to 1.00, where 0 indicates low competition and 1.00 indicates that there is a high number of advertisers competing for this keyword.
Estimated increase in clicks if the opportunity is applied.
Estimated increase in cost if the opportunity is applied.
Estimated increase in impressions if the opportunity is applied.
Broad match click share in the marketplace.
Broad match average CTR in the marketplace.
Broad match average CPC in the marketplace.
The identifier of an existing reference keyword used by the service to offer the keyword opportunity.
The bid of an existing reference keyword used by the service to offer the keyword opportunity.
The match type of an existing reference keyword used by the service to offer the keyword opportunity. The following are the possible match-type values: 1 - Exact match 2 - Phrase match
Broad match impression share in the marketplace.
A list of up to three broad match search query KPI objects. Each item contains search query statistics of including broad match type keyword bids
The search query corresponding to the keyword.
The identifier of the campaign to which the suggested budget applies.
The suggested budget based on the last 15 days of performance history for the corresponding campaign.
The type of budget that the campaign uses.
The estimated impressions opportunities corresponding to the suggested budget.
The estimated percentage increase in impressions corresponding to the suggested budget.
The estimated clicks opportunities corresponding to the suggested budget.
The estimated percentage increase in clicks corresponding to the suggested budget.
The list of budget points with weekly impressions, clicks and cost estimates for the given budget amount.
A potential new budget. This budget amount is your current campaign budget if the BudgetPointType value is Current.
The type of budget relative to a list of budget points. For example, if the budget point type is Current then this object's BudgetAmount element would be equal to the corresponding campaign's daily budget.
The estimated weekly clicks for the given budget amount.
The estimated weekly cost for the given budget amount.
The estimated weekly impressions for the given budget amount.
Indicates the campaign bid strategy and landscape type.
The first date used to calculate the bid landscape. The start date is usually seven days prior to the end date. The difference between the start and end dates might be less than seven if performance data is not available, e.g., the campaign is new.
The most recent date used to calculate the bid landscape. The end date should be set to approximately two days before the current date when CampaignBidLandscape is called.
A list of CampaignBidLandscapePoint objects with the total estimated performance from StartDate to EndDate by the bid or target.
The CampaignBidLandscapeType is TargetCpa. This element will be nil if the CampaignBidLandscapeType isn't TargetCpa.
The CampaignBidLandscapeType is TargetRoas. This element will be nil if the CampaignBidLandscapeType isn't TargetRoas.
The estimated number of conversions. This element will be nil if there is no estimate available.
The estimated conversion values. This element will be nil if there is no estimate available.
The CampaignBidLandscapeType is MarginalCpc. This element will be nil if the CampaignBidLandscapeType isn't MarginalCpc.
The identifier of the account. Output only.
The campaign ID targeted by this recommendation. Output only. This field will be set for the following recommendation types: KEYWORD, RESPONSIVE_SEARCH_AD
The ad group ID targeted by this recommendation. This will be set only when the recommendation affects a single ad group. Output only. This field will be set for the following recommendation types: KEYWORD, RESPONSIVE_SEARCH_AD.
The type of recommendation. Note: We currently support CAMPAIGN_BUDGET, KEYWORD, and RESPONSIVE_SEARCH_AD. RecommendationType is output only.
The RecommendationType value set has the following values: CampaignBudgetRecommendation, KeywordRecommendation, ResponsiveSearchAdRecommendation.
Actual clicks of the ad group in the past 7 days. Output only.
The estimated click opportunities corresponding to the suggested ad.
Actual spending of the ad group in the past 7 days, in the currency of this account.
The estimated increase in spend corresponding to the suggested ad.
Actual impressions of the ad group in the past 7 days.
The estimated impressions opportunities corresponding to the suggested ad.
Actual conversions of the ad group in the past 7 days. Output only.
The estimated impression opportunities corresponding to the suggested ad.
Whether the recommendation is dismissed or not. Output only.
The recommended budget amount based on the last 15 days of performance history for the corresponding campaign. Output only.
The list of budget points with weekly impressions, clicks and cost estimates for the given budget amount. Output only.
The type of budget that the campaign uses. Output only.
The nested list of suggested keywords for the campaign's ad groups with minimum and maximum traffic estimates. Traffic estimates include average CPC, average position, clicks, CTR, impressions, and total cost.
The campaign identifier. This element is reserved for future use. The returned estimates are not based on any specific campaign.
The daily budget filter criteria for all keyword traffic estimates in the campaign.
The list of campaign level criteria for traffic estimates. Do not try to instantiate a Criterion. You can include one or more the following objects that derive from it: DeviceCriterion, LanguageCriterion, LocationCriterion, and NetworkCriterion. The location, language, and network criterions are required for traffic estimates.
The list of ad group estimators with your ad group and keyword level filter criteria for traffic estimates.
The list of negative keyword filter criteria for all keyword traffic estimates in the campaign.
The Microsoft Advertising identifier of the negative keyword.
The Microsoft Advertising identifier for the keyword category. To get a list of keyword category identifiers, use the GetKeywordIdeaCategories service operation.
The competition levels that you want for the returned keyword ideas. Competition levels are defined by the number of advertisers bidding on this keyword, relative to all other keywords across Microsoft Advertising. Possible values are Low, Medium, and High.
The start date range of monthly search counts for the returned keyword ideas.
The end date range of monthly search counts for the returned keyword ideas.
The rounded value to the nearest scale unit. Output only.
The scale unit: Thousand, Million, Billion, None. Output only.
The device that you want to target. Possible case-sensitive values are All, Computers, Smartphones, and Tablets.
The device criterion for the returned keyword ideas.
The list of operations to dismiss recommendations. There is a limit of 100 operations per request. Required.
The category name. Up to three category levels can be returned, and will be separated by a forward slash ("/"). For example the returned category might be US/CA/SFO.
A score from 0.0 to 1.0 that indicates the percentage of pages in the requested language that belong to a particular domain out of all the pages that Bing has indexed for the same language your website's domain. In other words coverage is the percentage of webpages that match a category and language divided by the total number of webpages using the same language in the domain. For example, if the category US/CA/SFO matches 500 english webpages and US/CA matches 1,000 english webpages, then the coverage will be 0.50 (50 percent).
For account, this is AccountId. For campaign, this is CampaignId. For ad group, this is AdGroupId. For keyword, this is KeywordId. For product group, this is ProductGroupId. For search term/website, this is 0.
For account/campaign/ad group, this is the name information. For keyword, this is the keyword text. For search term, this is the search term text. For product group, this is the node path. For website, this is the website URL.
Defines a string for the type of parameter: string, URL, or a list of demand entities.
The suggested string value to substitute for the message.
The estimated minimum number of clicks per week.
The estimated maximum number of clicks per week.
The estimated average CPC. The formula used to calculate the average CPC is (maximum total cost / maximum number of clicks).
The estimated minimum number of impressions per week.
The estimated maximum number of impressions per week.
The estimated CTR. The formula used to calculate the CTR is (maximum number of clicks / maximum number of impressions) * 100.
The ISO code for the monetary unit of the cost estimates and suggested bid value.
The match type used to determine the estimates.
The keyword match type used to determine the estimates.
The ISO code for the monetary unit of the cost values such as AverageCPC.
The position in the search results given the specified bid. This element is deprecated as of March 31st, 2021 and '0' (zero) is returned going forward.
Determines whether or not to exclude existing account keywords from the returned keyword ideas. By default your existing account keywords will be included with the keyword idea data e.g., suggested bid. If you set the element True then the keyword ideas will not include any keywords for the same match type that already exist in your account.
Respect StoreId when CampaignSubType is set to FeedBasedAds. Add: Optional. Defaults to null. Update: Optional
Respect FeedId when CampaignSubType is set to DynamicFeedBasedAds. Add: Optional. Defaults to null. Update: Optional
The entity level that you want to request auction insight data. The supported values are Account, Campaign, AdGroup, and Keyword. This element is required.
The Microsoft Advertising identifiers for up to 200 campaigns, ad groups, or keywords. This element is required for the campaign, ad group, and keyword entity types. If the EntityType is Account, this element is optional and will override the value set in the CustomerAccountId header. Regardless of the entity type, you must set the CustomerId and CustomerAccountId header elements.
The search parameters define your criteria and filters for the auction insight data. You must include exactly one DateRangeSearchParameter. In addition you can optionally include up to three different AuctionSegmentSearchParameter objects e.g., for Day, DayOfWeek, and Device. Other objects that derive from SearchParameter are not valid for this operation.
The list of additional properties that you want included within each returned auction insight KPI. The additional field values enable you to get the latest features using the current version of the Ad Insight API, and in the next version the corresponding elements will be included by default. This request element is optional.
The Microsoft Advertising identifier of the location that you want to target. You can get keyword ideas and traffic estimates for city, country/region, county, metro area (Microsoft Market Area in the United States), and state locations. Postal code location identifiers are not supported for keyword ideas and traffic estimate requests. Currently this feature is available in the United States, United Kingdom, Canada, Australia, France, and Germany. To get a list of geographical location identifiers use the Campaign Management service i.e., the GetGeoLocationsFileUrl service operation.
The network that you want to target. Possible values are OwnedAndOperatedAndSyndicatedSearch, OwnedAndOperatedOnly, and SyndicatedSearchOnly. Note: As of July 2024, Microsoft no longer offers the SyndicatedSearchOnly option as an ad distribution setting. We highly recommend that you switch to "The entire Microsoft Advertising Network" and leverage auto-biding to let Microsoft help you manage your budget.
The language that you require. Possible case-sensitive values are English, French, and German.
Includes the auction insight entries for the requested entity, date range, and segment search parameters.
The selection of age targeting. Possible values are: EighteenToTwentyFour, TwentyFiveToThirtyFour, ThirtyFiveToFourtyNine, FiftyToSixtyFour, SixtyFiveAndAbove, Unknown. Add: Optional. The default value is null. Update: Optional
The gender to target. Possible values are: Male, Female, Unknown. Add: Optional. The default value is null. Update: Optional
The selection of audience targeting. Supported audience types are: Custom audiences, Combined lists, Customer match lists, Dynamic remarketing lists, In-market audiences, Remarketing lists, and Similar audiences. The values stored in the selection refer to segment IDs. Add: Optional. The default value is null. Update: Optional
The company of LinkedIn profile targeting. The values stored in the selection refer to segment IDs. Add: Optional. The default value is null. Update: Optional
The industry of LinkedIn profile targeting. The values stored in the selection refer to segment IDs. Add: Optional. The default value is null. Update: Optional
The job function The industry of LinkedIn profile targeting. The values stored in the selection refer to segment IDs. Add: Optional. The default value is null. Update: Optional
The selection of location targeting. The values stored in selection refer to location IDs. Add: Optional. The default value is null. Update: Optional
The selection of placement targeting. The values stored in selection refer to placement IDs. Add: Optional. The default value is null. Update: Optional
The selection of topic targeting. The values stored in selection refer to topic IDs. Add: Optional. The default value is null. Update: Optional
Represents the desired geographical area in terms of miles/kilometers. Add: Optional. The default value is null. Update: Optional
Indicates the desired bidding strategy for estimation response. Supported values are: 5: EnhancedCPC, 12: ManualCP. Add: Optional. The default value is Manual. Update: Optional
Indicate the desired ad type for estimation response. Supported values are: 0: StaticAds, 1: FeedBasedAds, 2: DynamicFeedBasedAds. Add: Optional. The default value is StaticAds*. Update: Optional
Respect this parameter only when CampaignSubType is FeedBasedAds or DynamicFeedBasedAds. It specifies the desired feed traffic to count as estimation. Add: Optional. The default value is null. Update: Optional
The locale identifier. Add: Optional. Update: Optional
The category of audience breakdown. Possible values include: All, Demographics, Device, Location, Interest. Add: Optional. Update: Optional
The audience breakdown ad type. Possible values indlude: DisplayAds, StaticAds, VideoAds. Add: Optional. Update: Optional
The traffic matching any value of Includes array is included as an estimation.
The traffic matching any value of Excludes array is excluded as an estimation.
Include the type of desvices present in the DeviceEnum.
Exclude the type of devices present in the DeviceEnum.
Indicates the desired amount of radius units.
Indicates the radius unit. Supports Kilometers or Miles.
Monthly estimated reach user count with rounded results. Output only.
Monthly estimated impression with range result. Output only.
Indicates if the impression is too specific.
Indicates if the estimated audience size passes the privacy check.
Suggested bid value under the current targeting. Output only.
The currency of DailyBudget and Bid. If null, the currency of account setting will be used. Add: Optional. The default value is null. Update: Optional
The daily campaign budget value. If set to null, the suggested budget is used to perform estimation. Add: Optional. The default value is null. Update: Optional
The desired bid setting value. If set to null, the suggested bid is used to perform estimation. Add: Optional Update: Optional
The audience full estimation ad type. Possible values indlude: DisplayAds, StaticAds, VideoAds. Add: Optional. Update: Optional
The start date of the date range that identifies the data that you want to use to determine the audience full estimation. This date must be earlier than or the same as the specified end date.
The end date of the date range that identifies the data that you want to use to determine the audience full estimation. This date must be later than or the same as the specified end date.
Include impressions in the audience breakdown.
Use predictive targeting if the value is true.
Monthly estimated user count with range result. Output only.
Monthly estimated spend with range result. Output only.
Indicates the estimated cost per event. The field meaning varies with CampaignBiddingStrategy request field. Output only. EnhancedCPC: CPC ManualCPM: CPM
Estimated click-through rate (CTR) with range result. Output only.
Suggested daily budget value under the current targeting and bid. Output only.
Indicates event lost count due to insufficient input bid. The event lost type varies with CampaignBiddingStrategy request field. Output only. EnhancedCPC: Click ManualCPM: Impression
Indicates the event lost count due to insufficient input budget. The event lost type varies with CampaignBiddingStrategy request field. Output only. EnhancedCPC: Click ManualCPM: Impression
The estimated click-through rate by type.
The estimated reach of impressions by type.
Indicates the upper bound of range result.
Indicates the lower bound of range result.
Determines the type of recommendations that you want to get the auto-apply opt-in status for. Duplicated inputs are allowed in the same. This field includes the list of recommendation type (case sensitive) as below:ResponsiveSearchAdsOpportunityMultiMediaAdsOpportunityRemoveConflictingNegativeKeywordOpportunityFixConversionGoalSettingsOpportunityCreateConversionGoalOpportunity.You may specify a maximum of 100 input elements.
An array of AutoApplyRecommendationsInfo object which identifies auto-apply opt-in status for the given recommendation types in the request.
An array of ad group identifiers with corresponding bid landscape type input. A list of suggested bid values with estimated performance statistics will be returned for each input. You may specify a maximum of 1,000 input elements.
An array of AdGroupBidLandscape objects. The array contains a AdGroupBidLandscape corresponding to each ad group and bid landscape type input specified in the request. Duplicate input are allowed in the same call and will return the same results. If the specified input is invalid or has no associated data results, all elements within the AdGroupBidLandscape will be nil except the AdGroupId which reflects the ad group identifier specified in the request. If there is data available for the ad group, the AdGroupBidLandscape object will provide a list of suggested bids and estimated performance statistics.
An array of CampaignBidLandscape objects. The array contains a CampaignBidLandscape corresponding to each campaign and bid landscape type input specified in the request. Duplicate input are allowed in the same call and will return the same results. If the specified input is invalid or has no associated data results, all elements within the CampaignBidLandscape will be nil except the CampaignId which reflects the campaign identifier specified in the request. If there is data available for the campaign, the CampaignBidLandscape object will provide a list of suggested bids and estimated performance statistics.
An array of identifiers of the keywords for which you want to get the list of suggested bid values with estimated performance statistics. You may specify a maximum of 1,000 keywords.
When set to false, the suggested bid values might not include the keyword's current bid. The default value is false. When set to true, one of the suggested bid values will be equal to the keyword's current bid.
An array of KeywordBidLandscape objects. The array contains a KeywordBidLandscape corresponding to each keyword specified in the request. Duplicate keyword identifiers are allowed in the same call and will return the same results. If the specified keyword identifier is invalid or has no associated data results, all elements within the KeywordBidLandscape will be nil except the KeywordId which reflects the keyword identifier specified in the request. If there is data available for the keyword, the KeywordBidLandscape object will provide a list of suggested bids and estimated performance statistics.
The first date used to calculate the bid landscape. The start date is usually seven days prior to the end date. The difference between the start and end dates could be less than seven if performance data is not available, for example with a new keyword.
The identifier of the ad group for which you want to determine keyword bid opportunities. If this element is nil or empty, the operation will return all bid opportunities for the specified campaign.
The identifier of the campaign that owns the ad group specified in the AdGroupId element. If this element is nil or empty, then the AdGroupId must also be nil or empty, and the operation will return all bid opportunities for the account.
Determines the type or types of bid opportunities corresponding to your ad position goals. The operation will only return opportunities if there's a suggested increase within 100% of your current bid that will help you achieve the specified goal.
An array of BidOpportunity objects that identifies the keywords whose clicks and impressions may increase if you were to apply the suggested match-type bid value. Currently up to 1,000 list items can be returned although the limit is subject to change.
The identifier of the campaign for which you want to discover possible campaign budget opportunities. If this element is nil or empty, then the operation will return all budget opportunities for the account.
An array of BudgetOpportunity data objects that identify the campaigns whose clicks and impressions may increase if you were to apply the suggested budget. The list will not include opportunities for campaigns that are currently paused by the user. Currently up to 1,000 list items can be returned although the limit is subject to change.
The website name corresponding to the pages you want your ads to target. The maximum length of the domain is 2,048 characters. You do not need to include the http, https, or www prefix.
The language of the website domain. Currently only English is supported, so you must set this element to EN.
The category name filter. If you already know one or more of the categories, then you can optionally filter the list of results by sub-category. Up to three category levels can be specified, and must be separated by a forward slash ("/"). For example you can format the filter as CategoryL1 / CategoryL2 / CategoryL3. If you do not include any category name, then all categories for the domain and language will be returned.
An array of identifiers of the keywords for which you want to get the suggested bid values that could have resulted in your ad appearing in the targeted position in the search results. You may specify a maximum of 1,000 keywords.
The position in which you want your ads to appear in the search results. The default value is MainLine1.
An array of KeywordIdEstimatedBid data objects. The array contains a corresponding item for each keyword specified in the request. If the keyword ID is not valid, the corresponding item in the array will be null. Each KeywordIdEstimatedBid contains a keyword identifier and a KeywordEstimatedBid. If there is data available for the keyword, the KeywordEstimatedBid will provide a suggested bid value that could have resulted in an ad appearing in the targeted position of the search results. Otherwise, the KeywordEstimatedBid element will be set to null.
The identifier of the keyword to which the suggested bid applies.
An object that contains the keyword string and the suggested bid value for each match type.
The keyword to which the estimates apply.
A list of EstimatedBidAndTraffic data objects that contains the suggested bid value for the keyword and match type. If there is data available for the keyword, the EstimatedBidAndTraffic object will provide an estimated bid value. Otherwise, if no data is available the EstimatedBids element will be null. Each object also contains estimates of clicks, average cost per click (CPC), impressions, click-through rate (CTR), and total cost given the suggested bid. If there is no data available for a match type, the array will not include estimates for the match type. Some returned elements of the EstimatedBidAndTraffic may be NULL.
A list of KeywordAndMatchType data objects for which you want to get suggested bid values. You may specify a maximum of 1,000 keywords, and each keyword can contain a maximum of 100 characters.
The position where you want your ads to appear in the search results. The default value is MainLine1.
The language used in parallel with location identifiers for estimating the bids. The language must be supported in each of the locations that you specify in LocationIds. For possible language values, see Ad Languages. If you do not specify the language, the service operation uses the language of the specified AdGroupId or CampaignId. If none of these properties are set, then EN (English) is used by default.
The identifier or identifiers of the geographical locations to use for estimating the bids. All of the locations must support the language specified in the Language element. Although you can specify multiple location identifiers, as a best practice for the most accurate bid estimates per location, you should specify only one location per service call. For possible location identifiers, see Geographical Location Codes. If you do not specify any locations, the service operation uses the location criterions of the specified AdGroupId or CampaignId. If none of these properties are set, then 190 (United States) is used by default.
The ISO code for the monetary unit to use to calculate the cost estimates and suggested bid value. If not set, the service determines the currency from the account specified in the CustomerAccountId header element. If neither Currency or CustomerAccountId is set, the service uses USD.
The identifier of the campaign that owns the ad group specified in AdGroupId. If you do not specify an ad group, the campaign's performance data is used to help determine how well the keyword might perform in the context of the campaign. Specifying a campaign and ad group helps improve the accuracy of the suggested bid. If neither AdGroupId or CampaignId are specified, the operation uses the specified CustomerAccountId header element to help determine how well the keyword might perform in the context of the account.
The identifier of the ad group whose performance data is used to help determine how well the keyword might perform in the context of the ad group. Specifying an ad group helps improve the accuracy of the suggested bid. If you specify an ad group, you must specify the campaign that it belongs to.
Determines whether to return estimates for keyword level bids, ad group level bids, or both. - Set EntityLevelBid to Keyword to get an array of KeywordEstimatedBid corresponding to the specified keywords. - Set EntityLevelBid to AdGroup to get one EstimatedBidAndTraffic for the specified ad group. - Set EntityLevelBid to AllEntities to get an array of KeywordEstimatedBid for keywords and one EstimatedBidAndTraffic for an ad group. If you do not set EntityLevelBid, the default is to return only an array of KeywordEstimatedBid, or the equivalent of setting EntityLevelBid to Keyword. If you set EntityLevelBid to any value other thanKeyword, AdGroup, or AllEntities, the service will return Code 3501 with ErrorCode CampaignServiceBidLevelInvalid.
The corresponding match types for the keyword.
An array of KeywordEstimatedBid data objects. The array contains an item for each keyword specified in the request. If the keyword is not valid, the corresponding item in the array will be null. Each KeywordEstimatedBid contains a keyword and EstimatedPositions element. If data is available for the keyword, the EstimatedPositionAndTraffic will provide the suggested bid value that could have resulted in an ad appearing in the targeted position of the search results. Otherwise, the EstimatedPositions element will be set to null.
Contains estimates of clicks, average cost per click (CPC), impressions, click-through rate (CTR), and total cost for the specified ad group if you would use the suggested bid. The MatchType value within the EstimatedBidAndTraffic will always be Aggregate. In this context, it represents the default search bid for an ad group.
An array of identifiers of the keywords for which you want to get the estimated position in the search results, based on the specified bid value. You may specify a maximum of 1,000 keyword identifiers.
The maximum bid value to use to determine the estimated position in the search results. You must specify the bid value in the currency of the account.
A list of KeywordIdEstimatedPosition data objects. The array contains an item for each keyword specified in the request. If the keyword ID is not valid, the corresponding item in the array will be null. Each KeywordIdEstimatedPosition contains a keyword identifier and a KeywordEstimatedPosition. If data is available for the keyword, the EstimatedPositionAndTraffic will provide the estimated position in the search results, based on the specified bid value. Otherwise, the EstimatedPositions element will be set to null.
The identifier of the keyword to which the estimated position applies.
An object that contains the keyword string and estimated position in the search results given the specified maximum bid.
An array of EstimatedPositionAndTraffic data objects that contains the position in the search results corresponding to the specified maximum bid. Each object also contains estimates of clicks, average cost per click (CPC), impressions, click-through rate (CTR), and total cost given the specified bid. If there is no data available for a match type, the array will not include estimates for the match type.
An array of keywords for which you want to get the estimated position in the search results, based on the specified bid value. You may specify a maximum of 1,000 keywords and each keyword can contains a maximum of 100 characters.
The maximum bid value to use to determine the estimated position in the search results.
The language used in parallel with location identifiers for estimating the position. The language must be supported in each of the locations that you specify in LocationIds. For possible language values, see Ad Languages. If you do not specify the language, the service operation uses the language of the specified AdGroupId or CampaignId. If none of these properties are set, then EN (English) is used by default.
The identifier or identifiers of the geographical locations to use for estimating the position. All of the locations must support the language specified in the Language element. Although you can specify multiple location identifiers, as a best practice for the most accurate position estimates per location, you should specify only one location per service call. For possible location identifiers, see Geographical Location Codes. If you do not specify any locations, the service operation uses the location criterions of the specified AdGroupId or CampaignId. If none of these properties are set, then 190 (United States) is used by default.
An array of unique match types for which you want to get estimates. You may not specify the Content match type.
The identifier of the campaign that owns the ad group specified in AdGroupId. If you do not specify an ad group, the campaign's performance data is used to help determine how well the keyword might perform in the context of the campaign. Specifying a campaign and ad group helps improve the accuracy of the suggested position. If neither AdGroupId or CampaignId are specified, the operation uses the specified CustomerAccountId header element to help determine how well the keyword might perform in the context of the account.
The identifier of the ad group whose performance data is used to help determine how well the keyword might perform in the context of the ad group. Specifying an ad group helps improve the accuracy of the suggested position. If you specify an ad group, you must specify the campaign that it belongs to.
An array of KeywordEstimatedPosition data objects. The array contains an item for each keyword specified in the request. If the keyword is not valid, the corresponding item in the array will be null. If data is available for the keyword, the EstimatedPositionAndTraffic will provide the estimated position in the search results where your ads could appear, based on the specified bid value. Otherwise, the EstimatedPositions element will be set to null.
An array of keywords for which you want to get historical performance statistics. The array can contain a maximum of 1,000 keywords, and each keyword can contain a maximum of 100 characters.
The time period that identifies the data to use to determine the key performance index of the specified keywords. For example, use data from the previous seven days or previous 30 days to determine the keyword performance. The default value is LastDay.
The position of the search results for which you want to get performance data. For example, to get performance data when ads appeared in the first position of the mainline by using the keyword and match type, set this element to MainLine1. To get performance data when ads appeared in any position of the search results by using the keyword and match type, set this element to All. The default value is All. If you specify All for this element, the service will return multiple results per keyword for each supported ad position. If you specify Aggregate, the service will return one aggregated result. Sidebar ads no longer serve on Bing owned and operated sites in the United States. If you only request first page data e.g., FirstPage1 for the United States (US), then the KeywordKPIs element in the result will be nil/empty. If you include additional countries/regions e.g., US and CA in the same request, then any first page results are only attributed to countries/regions outside the United States.
The match types for which you want to get historical data. You may not specify the Content match type.
The language in which the keywords are written. The countries/regions that you specify in the PublisherCountries element must support the specified language. Possible values include Danish, Dutch, English, Finnish, French, German, Italian, Norwegian, Portuguese, Spanish, Swedish, and TraditionalChinese.
The country codes of the countries/regions to use as the source of the historical data. You can specify one or more country codes. Each country/region that you specify must support the language specified in the Language element. The following language and country/region combinations are supported: Danish: DK Dutch: NL English: AU, CA, GB, ID, IN, MY, PH, SG, TH, US, VN Finnish: FI French: CA, FR German: AT, CH, DE Italian: IT Norwegian: NB Portuguese: BR Spanish: AR, CL, CO, ES, MX, PE, VE Swedish: SE TraditionalChinese: HK, TW If this element is null, then by default the service includes all countries/regions that support the specified language.
A list of one or more of the following device types: Computers, NonSmartphones, Smartphones, Tablets. The default is Computers. The response includes keyword performance data for the device types that you specify only, if available. Used to determine a keyword's performance on the specified device types.
An array of KeywordHistoricalPerformance data objects. The array contains an item for each keyword, device, match type, and ad position specified in the request. If the keyword is not valid or has no data available, the corresponding item in the array will be null.
The keyword to which the keyword performance data applies.
An array of KeywordKPI objects that contains the performance data. For each requested keyword that has no available data, the KeywordKPI element will be nil. If the request specified a specific target position, the array will contain only one item per requested keyword. If the request specified All for the target position, then for each requested keyword the array will contain an item for each possible position in the search results. Sidebar ads no longer serve on Bing owned and operated sites in the United States. If you only request first page data e.g., FirstPage1 for the United States (US), then this element will be nil/empty. If you include additional countries/regions e.g., US and CA in the same request, then any first page results are only attributed to countries/regions outside the United States.
The match type that you specified in the request.
The position in the search results in which the ad appeared.
The number of clicks that the keyword and match type generated during the specified time interval.
The number of impressions that the keyword and match type generated during the specified time interval.
The average cost per click (CPC). The average CPC is calculated by dividing the cost of all clicks by the number of clicks.
The click-through rate (CTR) as a percentage. The CTR is calculated by dividing the number of clicks by the number of impressions and multiplying the result by 100.
The cost of using the specified keyword and match type during the specified time interval. The service determines the currency from the account specified in the CustomerAccountId header element. If CustomerAccountId is not set, the service uses USDollar.
An array of keywords for which you want to determine the number of times that the keyword was used in a search query. The array can contain a maximum of 1,000 keywords, and each keyword can contain a maximum of 100 characters.
The language in which the keywords are written. The countries/regions that you specify in the PublisherCountries element must support the specified language. For possible values, see Supported Languages.
The country codes of the countries/regions to use as the source of the historical data. You can specify one or more country codes. Each country/region that you specify must support the language specified in the Language element. For possible values, see Ad Languages. If Null, the default is all countries/regions that support the specified language.
The start date of the date range that identifies the data that you want to use to determine the historical search count. This date must be earlier than or the same as the specified end date. The date should be later than the maximum available historical data range corresponding to the specified TimePeriodRollup element. The effective start date may be adjusted if the specified TimePeriodRollup is Weekly or Monthly.
The end date of the date range that identifies the data that you want to use to determine the historical search count. The date cannot be later than today's date, and must be later than or the same as the specified start date. The effective end date may be adjusted if the specified TimePeriodRollup is Weekly or Monthly.
You may specify whether to return data aggregated daily, weekly, or monthly. For a list of supported values, see the Remarks section below.
A list of one or more of the following device types: Computers, NonSmartphones, Smartphones, Tablets. The default is Computers. The response includes search counts for the device types that you specify only, if available.
An array of KeywordSearchCount data objects. The array contains an item for each keyword specified in the request. If the keyword is not valid, the corresponding item in the array will be null. Each KeywordSearchCount contains an array of SearchCountsByAttributes. The array contains an item for each unique device specified in the request.
The keyword to which the search count data applies.
An array of SearchCountsByAttributes objects that contain search counts for each device and network where the keyword was included in a search query. For each requested keyword that has no available data, the SearchCountsByAttributes element will be nil.
The device of the user who entered the search query.
An array of HistoricalSearchCountPeriodic objects that contain a count of the number of times that the keyword was used in a search query. The array contains an item for each month in the specified date range. The items are ordered by calendar month. For each requested keyword that has no available data, the HistoricalSearchCountPeriodic element will be nil.
The number of times that the keyword was used in a search query on the specified device type during the time period. The count aggregates data from all specified countries or regions.
The time period in which the count was captured. The type of aggregation (daily, weekly, or monthly) that you specify in the request determines the length of the time period. For example, if you specified weekly aggregation, the time period is a week and the date is the Sunday of the week when the count was captured.
An array of keywords for which you want to determine the possible keyword categories that each keyword belongs to. The array can contain a maximum of 1,000 keywords, and each keyword can contain a maximum of 100 characters.
The language in which the keywords are written. You must set this element to English.
The country code of the country/region to use as the source of the category data. You must set this element to US.
The number of categories to include in the results. The maximum number of categories that you can request is 5. The default is 5.
An array of KeywordCategoryResult data objects. Each object contains the keyword and a list of categories to which it belongs. The list will include an item for each keyword that you specified in the request. If the keyword category cannot be determined, the KeywordCategories list will contain a single KeywordCategory. The value of Category will be Unknown Category and the value of ConfidenceScore will be 0.0.
An array of KeywordCategory objects that contains a keyword category and a score that indicates the confidence that the keyword belongs to that keyword category.
The keyword category that the keyword might belong to. If the category is undetermined, this element is set to Unknown Category and the ConfidenceScore element is set to 0.0.
A score from 0.0 to 1.0 that indicates the likelihood that the keyword belongs to the category.
An array of keywords for which you want to get demographics data. The data is also broken out by device type. The array can contain a maximum of 1,000 keywords, and each keyword can contain a maximum of 100 characters.
The language in which the keywords are written. For possible values, see Ad Languages.
The country code of the country/region to use as the source of the demographics data. The country/region that you specify must support the language specified in the Language element. For possible values, see Ad Languages.
An array of devices for which you want to get demographics data. Supported device types include the following: Computers, NonSmartphones, Smartphones, Tablets. The default is Computers. If available the response only includes keyword demographics data for the device types that you specify.
An array of KeywordDemographicResult data objects. The order of the items corresponds directly to the keywords specified in the request. If there is no demographic data available for a keyword, the keyword will be included in the list, but the KeywordDemographics element of the corresponding KeywordDemographicResult will be null. Each KeywordDemographicResult contains an array of KeywordDemographic data objects. The array contains an item for each device specified in the request. Each KeywordDemographic contains the percentage of time that users of a certain age and gender searched for the specified keyword.
An array of KeywordDemographic data objects that contains the percentage of users by age and gender (if known) that searched for the keyword on the device.
The percentage of time that users 18 through 24 years of age searched for the keyword. The value is specified in the range 0.0 through 1.0.
The percentage of time that users 25 through 34 years of age searched for the keyword. The value is specified in the range 0.0 through 1.0.
The percentage of time that users 35 through 49 years of age searched for the keyword. The value is specified in the range 0.0 through 1.0.
The percentage of time that users 50 through 64 years of age searched for the keyword. The value is specified in the range 0.0 through 1.0.
The percentage of time that users 65 years of age or older searched for the keyword. The value is specified in the range 0.0 through 1.0.
The percentage of time that female users searched for the keyword. The value is specified in the range 0.0 through 1.0.
The percentage of time that male users searched for the keyword. The value is specified in the range 0.0 through 1.0.
The Microsoft Advertising identifier of the keyword idea category.
Determines whether you want new keyword ideas, or if you only want keyword attributes for the set of keywords that you specified in the SearchParameters list. If you set this element false, the QuerySearchParameter object must be included in the SearchParameters list.
The keyword idea attributes that you want included in the response e.g., Keyword, Competition, MonthlySearchCounts, and SuggestedBid. The Competition attribute is required. The Keyword attribute will always be returned for each returned KeywordIdea whether or not you include the Keyword value in the requested list of idea attributes.
The search parameters define your criteria and filters for the requested keyword ideas. Do not try to instantiate a SearchParameter. You can include one or more the following objects that derive from it: CategorySearchParameter, CompetitionSearchParameter, DateRangeSearchParameter, DeviceSearchParameter, ExcludeAccountKeywordsSearchParameter, IdeaTextSearchParameter, ImpressionShareSearchParameter, LanguageSearchParameter, LocationSearchParameter, NetworkSearchParameter, QuerySearchParameter, SearchVolumeSearchParameter, SuggestedBidSearchParameter and UrlSearchParameter. Other objects that derive from SearchParameter are not valid for this operation. You cannot include duplicates of any search parameter type. The list must include all of these search parameters: LanguageSearchParameter, LocationSearchParameter, and NetworkSearchParameter. The list must include one or more of these search parameters: CategorySearchParameter, QuerySearchParameter, or UrlSearchParameter. If the ExpandIdeas element is false, then the QuerySearchParameter is required whether or not you included additional search parameters. It can take up to 72 hours for the previous calendar month's data to be available. For example, if you request keyword ideas on August 1st, 2nd or 3rd, and July's data is not ready, the response will be based on June's data. If you do not include the DateRangeSearchParameter in the GetKeywordIdeas request, then you will not be able to confirm whether the first list item is data for the previous month, or the month prior. If the date range is specified and the most recent month's data is not yet available, then GetKeywordIdeas will return an error.
The list of keyword ideas. Currently up to 3,000 list items can be returned although the limit is subject to change.
The negative ad group identifier that groups keyword ideas into suggested new ad groups. Keyword ideas for existing ad group identifiers is not supported. If the ad group ID is null then the keyword idea Source element is set to Seed, and there is not any specific recommended ad group.
The suggested name of the ad group for the keyword idea. If the ad group name is null then the keyword idea Source element is set to Seed, and there is not any specific recommended ad group.
The number of times this keyword was used as a search term for each month within the date range and targeting settings you've selected. By default the size of the list is 12 and the last 12 months of available data are returned. The search counts are sorted in order starting with the most recent month's data at MonthlySeachCounts[0]. It can take up to 72 hours for the previous calendar month's data to be available. For example, if you request keyword ideas on August 1st, 2nd or 3rd, and July's data is not ready, the response will be based on June's data. If you do not include the DateRangeSearchParameter in the GetKeywordIdeas request, then you will not be able to confirm whether the first list item is data for the previous month, or the month prior. If the date range is specified and the most recent month's data is not yet available, then GetKeywordIdeas will return an error.
The suggested minimum bid for this keyword. We create this suggestion using the location and network criterion you included, along with the average cost-per-click (CPC) advertisers are paying for this keyword. This amount is only an estimate and your actual CPC may vary.
Determined by the number of advertisers bidding on this keyword, relative to all other keywords across Microsoft Advertising.
The keyword relevance score. Higher relevance means "more relevant". There is no defined range, but as an example you might see values such as 1.00 or 87,083.82. Although the values are not displayed, relevance is used to sort Keyword Planner results by relevance in the Microsoft Advertising UI.
Ad impression share is the number of impressions you've received divided by the total number of searches for the location and network you're targeting that matched the keyword exactly in the last calendar month.
An array of keywords for which you want to get geographical location information. The data is also broken out by device type. The array can contain a maximum of 1,000 keywords, and each keyword can contain a maximum of 100 characters.
The country code of the country/region to use as the source of the location data. The country/region that you specify must support the language specified in the Language element. For possible values, see Ad Languages.
An array of devices for which you want to get geographical location information. Supported device types include the following: Computers, NonSmartphones, Smartphones, Tablets. The default is Computers. The response includes keyword locations data for only the device types that you specify, if available.
The level at which to aggregate the geographical location data. The following are the possible values: 0 - Country 1 - State/Province 2 - Metropolitan area 3 - City The default value is 1 (State/Province).
The country/region from which the search originated. For possible values, see Geographical Location Codes. The default is US.
The maximum number of locations to return. You can request a maximum of 10 locations. The default value is 10.
An array of KeywordLocationResult data objects. The order of the items corresponds directly to the keywords specified in the request. If there is no location data available for a keyword, the keyword will be included in the list, but the KeywordLocations element of the corresponding KeywordLocationResult object will be null. Each KeywordLocationResult data object contains an array of KeywordLocation. The array contains an item for each device specified in the request. Each KeywordLocation contains the geographical location and percentage of time that users in the geographical location searched for the specified keyword.
An array of KeywordLocation objects that contains the geographical locations and the percentage of times that users searched for the keyword from that location.
The country/region, state, metropolitan area, or city where users entered the search query.
The percentage of time that users searched for the keyword from the location. The value is specified in the range 0.0 through 100.0.
The identifier of the ad group to get keyword suggestions for. The following restrictions apply to the specified ad group: - Its language must be set to English. - Its distribution medium must include Search. - It should contain keywords and ads. The operation will suggest keywords only if the ad group contains one or more ads and keywords; the more keywords and ads that the ad group contains, the richer the set of suggested keywords will be. If AdGroupId is nil or empty, the operation will return all keyword opportunities for the specified campaign.
The identifier of the campaign that owns the specified ad group. If the CampaignId element is nil or empty, then the AdGroupId must also be nil or empty, and the operation will return all keyword opportunities for the account.
Determines the type or types of keyword opportunities that you want. You may include multiple values as flags. How you specify multiple flags depends on the programming language that you use. For example, C# treats these values as flag values and Java treats them as an array of strings. The SOAP should include a string that contains a space-delimited list of values for example, BroadMatch CampaignContext.
A list of KeywordOpportunity data objects that identifies a suggested keyword and bid value. The list will be empty if there are no suggestions, which may occur if the ad group does not contain existing ads and keywords. Currently up to 1,000 list items can be returned although the limit is subject to change.
Defines your campaign, ad group, and keyword level criteria and filters for the requested keyword traffic estimates.
The list of campaign estimates. Within each campaign estimate is a nested list of keyword traffic estimates for each ad group. You can inspect the BatchError Details element to find out which of the requested list items failed. For example if Details contains "CampaignEstimators[0], AdGroupEstimators[1], KeywordEstimators is null or contains no value", the error occurred for the 2nd AdGroupEstimator in the submitted list. The Index element of the BatchError is only a sequential count of returned batch errors, and cannot be used to determine where in the request the error occurred.
The entity level that you want to request performance insights summary data from. We currently support account and campaign level data.
The start date range for performance insights.
The end date range for performance insights. The maximum date range is one month.
Defines the performance insight results from calling the GetPerformanceInsightsDetailDataByAccountId operation.
For account level, this is AccountId. For campaign level, this is CampaignId.
The supported types are account and campaign.
Defines the type of key performance indicator. At the account level, we support impression, click, spend, and conversion. At the campaign level, we support impression, click, and spend.
The date of the detected performance insights.
A message to describe the performance insights.
Messages that describe the root causes in "What happened."
Messages that describe the actions in "What can I do."
Message parameters are used to fill in the template that renders the message string.
Indentation distance or depth when displaying the message. By default, it is 0, which means no indentation distance.
The supported types are: text, URL, and entities.
The identifier of the campaign that owns the ad group specified in the AdGroupId element. If this element is nil or empty, then the AdGroupId must also be nil or empty, and the operation will return all opportunities of a certain recommendation type for the account.
The identifier of the ad group for which you want to determine responsive search ads opportunities. If this element is nil or empty, the operation will return all opportunities of certain recommendation type for the specified campaign.
The identifier of the recommendation type that you want to get. This element can't be nil or empty. One recommendation type per request, e.g., ResponsiveSearchAdsOpportunity.
An array of Recommendation objects. 2,000 list items can be returned at maximum.
The identifier of the campaign for the ad group that owns the recommendation.
The identifier of the ad group that owns the recommendation.
Actual clicks of the ad group in the past 7 days.
Actual conversions of the ad group in the past 7 days.
The list of titles of suggested ads with 3-15 headlines.
The list of descriptions of suggested ad with 2-4 descriptions.
The first part of the optional path that will be appended to the domain portion of your display URL.
The second part of the optional path that will be appended to the domain portion of your display URL.
The last or final URL where a user is ultimately taken, whether or not the click to final URL path included any redirects. The maximum array limit of FinalUrls for each request is 5.
The suggested string value to use for the text asset.
An array BatchError that contain details for any request items that were not successful. The list of errors do not correspond directly to the list of items in the request. The list can be empty if there were no errors, or can include one or more error objects corresponding to each unsuccessful list item in the request.
The Final URL of the ad, keyword, or criterion. Only the first URL in the list is reported. If the URL contains dynamic text substitution parameters (for example, {param1}), the report will contain the URL before substitution.
Text assets that can be reused across multiple ads.
The list of keywords that you explicitly want included in the list of returned keyword ideas. The match type of each keyword must be set to Broad.
The list of keywords that you explicitly want excluded from the list of returned keyword ideas. The match type of each keyword must be set to Broad.
The minimum impression share that you want for keyword ideas.
The maximum impression share that you want for keyword ideas.
A score from 0.0 to 1.0 that indicates the probability that the keyword would match a user's search query.
The text of the keyword (at most 80 characters and 10 words). Output only.
The suggested bid that may result in your ads serving on the first page of the search query results. Output only.
The estimated monthly volume of user search queries that may match the suggested keyword for the corresponding MatchType element. Output only.
The match type that the suggested bid applies to. Output only. The following are the possible match-type values: 1 - Exact match2 - Phrase match3 - Broad match
An indicator of competitive bids for this keyword relative to all search keywords. The competition score ranges from 0 to 1.00, where 0 indicates low competition and 1.00 indicates that there is a high number of advertisers competing for this keyword. Output only.
The keyword to which the suggested keywords apply.
A KeywordAndConfidence array that contains a list of suggested keywords and, for each keyword, a score that indicates the probability that using the keyword would result in an ad being included in the results of a search query. The suggested keywords are sorted in order from keywords with the highest confidence score to those with the lowest confidence score.
The language criterion list for the returned keyword ideas.
The location criterion list for the returned keyword ideas. You must include between 1 to 2,000 locations.
The network criterion for the returned keyword ideas.
Up to 200 words or phrases that describe what you're advertising.
The type of recommendation. Note: We currently support ADD_BROAD_MATCH_KEYWORD, CAMPAIGN_BUDGET, KEYWORD, REMOVE_CONFLICTING_NEGATIVE_KEYWORD, RESPONSIVE_SEARCH_AD, and RESPONSIVE_SEARCH_AD_ASSET. RecommendationType is output only.
The RecommendationType value set has the following values: AddBroadMatchKeywordRecommendation, CampaignBudgetRecommendation, KeywordRecommendation, RemoveConflictingNegativeKeywordRecommendation, ResponsiveSearchAdRecommendation, and ResponsiveSearchAdAssetRecommendation.
The identifier of the recommendation. It is required.
The hash of the recommendation. It is required.
The shared list ID of the negative keyword.
The ad info in the recommendation. Output only.
The max number of returned recommendations. The default value is null. If MaxCount is null or 0, it returns all available recommendations. Optional.
The recommendation type names: ADD_BROAD_MATCH_KEYWORD, CAMPAIGN_BUDGET, KEYWORD, REMOVE_CONFLICTING_NEGATIVE_KEYWORD, RESPONSIVE_SEARCH_AD, or RESPONSIVE_SEARCH_AD_ASSET. Required.
The available recommendations for specific account ID. The types of recommendations are: AddBroadMatchKeywordRecommendation, CampaignBudgetRecommendation, KeywordRecommendation, RemoveConflictingNegativeKeywordRecommendation, ResponsiveSearchAdRecommendation, and ResponsiveSearchAdAssetRecommendation.
Ad id of the responsive search ad that is created by adopting the recommendation. Optional. It is required when you try to tag a recommendation as applied.
The minimum search volume that you want for keyword ideas.
The maximum search volume that you want for keyword ideas.
A string array which identifies auto-apply opt-in status of the given recommendation types in the request. Duplicated input keys are not allowed in the same call. This field includes the list of recommendation types with the auto-apply opt-in status to be specified. The existing key and value pairs are as follows (case sensitive): ResponsiveSearchAdsOpportunity = falseMultiMediaAdsOpportunity = true RemoveConflictingNegativeKeywordOpportunity = false FixConversionGoalSettingsOpportunity = false CreateConversionGoalOpportunity = false .If the value of a key is set to true, then the account will opt-in auto-apply of the corresponding recommendation type. You may specify a maximum of 100 input elements.
The minimum suggested bid that you want for keyword ideas.
The maximum suggested bid that you want for keyword ideas.
The URL of the webpage to scan for possible keywords. The URL can contain a maximum of 2,000 characters.
The language used by the website. For possible values, see Ad Languages. The default is English.
A positive integer value that specifies the maximum number of keywords to return. The maximum value that you can specify is 800. The default is 10.
A filter value that limits the keywords that the service returns to those that have a confidence score that is greater than or equal to the specified score. For example, you can specify that you want the operation to return only keywords that have a confidence score of at least 80 percent (0.8). If null, the confidence score is not used to limit the results.
A value that determines whether the results exclude brand keywords. To exclude brand keywords in the result, set to true. The default is false.
An array of KeywordAndConfidence objects that contains the possible keywords found in the content of the specified URL. In addition, the object includes a score that indicates the probability that using the keyword would result in the URL being included in the results of a search query. The results are sorted in order from keywords with the highest confidence score to those with the lowest confidence score.
An array of keywords for which you want to get suggested keywords that could perform better. The array can contain a maximum of 1,000 keywords, and each keyword can contain a maximum of 100 characters.
The language in which the keyword is written. Possible case-sensitive values are English, French, and German. See the Remarks section below for a list of providers that are supported for each language. The default is English.
The country codes of the countries/regions to use as the source of data for determining the suggested keywords. You can specify one or more country codes. Each country/region that you specify must support the language that you specified in the Language element. For supported values, see the Remarks section below. The default is all countries/regions that support the specified language.
The maximum number of keyword suggestions to return per specified keyword. If SuggestionType is set to 4, you can request a maximum of 200 suggestions per keyword; otherwise the maximum suggestions that you can request is 100. The default is 50.
The provider to use to generate the keyword suggestions. For a list of possible providers, the language and country/region restrictions of each provider, and the default provider by country/region, see the Remarks section below.
A Boolean value that determines whether to remove duplicate keywords from the list of suggested keywords. To remove duplicates, set to true. The default is false.
The identifier of the ad group for suggested keywords. This element is not yet supported and may be used to influence keyword suggestions in a future release
The identifier of the campaign for suggested keywords. This element is not yet supported and may be used to influence keyword suggestions in a future release
An array of KeywordSuggestion data objects. The array contains an item for each keyword specified in the request. The object contains a list of suggested keywords that may perform better than the specified keyword. For each suggested keyword, the object includes a score that indicates the probability that using the keyword would result in an ad being included in the results of a search query. If there are no suggestions for a keyword, the SuggestionsAndConfidence element will be null.
The identifier of the recommendation type that you have applied. This element cannot be nil or empty. One specific recommendation type per request, e.g., ResponsiveSearchAdsOpportunity.
The information for an individual recommendation. Duplicate RecommendationInfo (RecommendationId) will be returned as DuplicateRecommendationInfo error. You may specify a maximum of 100 input elements.
The value must be set to either applied or dismissed
Defines the type of parameter: string, URL, or a list of demand entities.
The URL of your website or a page on your website. Microsoft Advertising extracts keywords from the HTML code on your website or landing page. If your HTML code contains Javascript, which generates content at runtime, Microsoft Advertising will not extract keywords rendered from the Javascript and you'll see fewer or no keywords.
A message that contains additional details about the error. This string can be empty.
An array of AdApiError objects that contains the details that explain why the service operation failed.
The list of key and value strings for forward compatibility to avoid otherwise breaking changes when new elements are added in the current API version.
The text that caused the entity to be disapproved. For text length violations, this element specifies the number of characters by which the specified text exceeds the maximum.
A numeric code that identifies the error. For more information, see Editorial Reason Codes.
The element or property of the entity that caused the entity to be disapproved.
The corresponding country or region for the flagged editorial issue.
The identifier of the campaign to download.
The identifier of the account that owns the campaign to download.
The identifier of the account that contains the campaign data to download. The maximum number of accounts that you can specify is one. The size of the account that you can download is limited to four million keywords. If you try to download an account that contains more than 4 million keywords, the call will fail with error 3207 (AccountTooBigToDownload). If the call fails, please call the DownloadCampaignsByCampaignIds operation to download the account by campaigns. The Details element of the fault includes a comma-delimited list of the campaign IDs that the account owns.
The last time that you requested a download. The date and time is expressed in Coordinated Universal Time (UTC). If you specify the last sync time, only those entities that have changed (added, updated, or deleted) since the specified date and time will be downloaded. If the parent campaign or ad group has been deleted since the specified last sync time, you will only see a deleted record for the deleted parent campaign or ad group. For example if a campaign was deleted, the bulk file will not contain deleted records for the ad groups, criterions, ads, and keywords that were in the campaign. Target criterion are treated slightly different from other entities, and deleted records are not returned. If any changes were made to a campaign or ad group's target, then all currently active sub target criterion records are returned. Typically, you request a full download the first time you call the operation by setting this element to null. On all subsequent calls you set the last sync time to the time stamp of the previous download. The download file contains the time stamp of the download in the Sync Time column of the Account record. You should use the account Sync Time to set this element the next time that you request a download. If you set a date and time that is more than 30 days ago, an error will be returned.
The entities to include in the download. For a list of entities that you can download, see the DownloadEntity value set. You must specify at least one download entity, and otherwise the operation will error.
You may include quality score data such as ad relevance, in addition to entity data such as campaign settings. The default value is EntityData. You may include multiple values as flags. How you specify multiple flags depends on the programming language that you use. For example, C# treats these values as flag values and Java treats them as an array of strings. The SOAP should include a string that contains a space-delimited list of values for example, EntityData QualityScoreData. If BidSuggestionsData or QualityScoreData are included, you must request a full sync. To perform a full sync, do not set LastSyncTimeInUTC i.e., leave it nil.
The file type of the download file. For possible values, see DownloadFileType. The default is CSV.
The format for records of the download file. As a best practice you should always specify the latest format version. Currently the only supported format version for Bing Ads API Version 13 is 6.0. You should manage records according to the Bulk File Schema for the corresponding format version.
The compression type of the download file. For possible values, see CompressionType. The default compression type is Zip.
The identifier of the download request. You use the identifier to call the GetBulkDownloadStatus operation to check the status of the download. The identifier is valid for a maximum of two days. If you have not successfully downloaded the file within this period, it is removed from the download site and you will need to get a new download request identifier. The string has a length up to 40 and can contain any character.
The campaigns to download. You can specify a maximum of 1,000 campaigns. The campaigns that you specify must belong to the same account.
The last time that you requested a download. The date and time is expressed in Coordinated Universal Time (UTC). If you specify the last sync time, only those entities that have changed (added, updated, or deleted) since the specified date and time will be downloaded. If the parent campaign or ad group has been deleted since the specified last sync time, you will only see a deleted record for the deleted parent campaign or ad group. For example if a campaign was deleted, the bulk file will not contain deleted records for the ad groups, criterions, ads, and keywords that were in the campaign. Target criterion are treated slightly different from other entities, and deleted records are not returned. If any changes were made to a campaign or ad group's target, then all currently active sub target criterion records are returned. Typically, you request a full download the first time you call the operation by setting this element to null. On all subsequent calls you set the last sync time to the time stamp of the previous download. The download file contains the time stamp of the download in the Sync Time column of the Account record. You should use the account Sync Time to set this element the next time that you request a download. If you set a date and time that is more than 30 days prior, an error will be returned.
The format of the download file. For possible values, see DownloadFileType. The default is CSV.
The identifier of the download request. The DownloadCampaignsByAccountIds and DownloadCampaignsByCampaignIds operations return this element as the DownloadRequestId. The identifier is valid for a maximum of two days. If you have not successfully downloaded the file within this period, it is removed from the download site and you will need to get a new download request identifier. The string has a length up to 40 and can contain any character.
The status of the download. The possible values are as follows. Completed - The download completed successfully. InProgress - The download is in progress. Failed - The download failed. You may submit a new download with fewer entities, without quality score and bid suggestions data, or try again to submit the same download later. FailedFullSyncRequired - The request's LastSyncTimeInUTC element must be set to null, for example if the specified account was included in a data migration. After requesting a full download, you may begin requesting delta downloads again.
The URL that contains the download data when the RequestStatus value is Completed. You have five minutes from the time this URL is returned to download the file. If you do not start the download within this time period, you will need to call GetBulkDownloadStatus again to get a new URL. You should not take a dependency on the domain of the download URL, as it is subject to change. The download file is compressed (in zip format), so you must unzip the file to access the data. For information about the bulk file format, see Bulk File Schema.
The progress completion percentage for system processing of the bulk download file.
The list of key and value strings for forward compatibility to avoid otherwise breaking changes when new elements are added in the current API version. Forward compatibility changes will be noted here in future releases. There are currently no forward compatibility changes for this operation.
An array of OperationError objects corresponding to errors encountered during the system processing of the bulk file after your download request was submitted.
The identifier of the upload request. The identifier is valid for up to 15 minutes. If you have not successfully uploaded the file within this period, you will need to get a new request identifier and upload URL.
The status of the upload. The following are the possible returned status values. Completed - The upload file was accepted and processed successfully without errors. CompletedWithErrors - The upload completed with one or more errors. While the overall upload was successful, one or more add or update errors could have occurred. As a best practice you should request error information via the ResponseMode element when calling GetBulkUploadUrl and check the ResultFileUrl for any errors. Failed - The entire upload failed due to an unexpected error. You may submit a new upload with fewer entities or try again to submit the same upload later. FileUploaded - The upload request has been received and is in the queue for processing. InProgress - The upload file has been accepted and the upload is in progress. PendingFileUpload - The upload file has not been received for the corresponding RequestId. UploadFileRowCountExceeded - The limit of bulk records in the upload file has been exceeded. For more information about limits and upload best practices, see Bulk Upload. UploadFileFormatNotSupported - The Format Version Name field specified in the upload is not supported for this version of the Bulk API.
The URL of the file that contains the requested results, for example upload error information. The URL must be used within five minutes of the time that the GetBulkUploadStatus operation returns the Completed or CompletedWithErrors status response string. If you do not start the download within this period of time, you will need to call GetBulkUploadStatus again to get a new URL. You should not take a dependency on the domain of the download URL, as it is subject to change.
The progress completion percentage for system processing of the uploaded bulk file. The value range is between 0 and 100. You should also compare the upload status. If the upload fails, the percent complete will reset to zero (0).
An array of OperationError objects corresponding to errors encountered during the system processing of the bulk file after your HTTP POST upload completed. For example, an OperationError would include the BulkServiceFormatVersionNotSupported error code if the uploaded file contains one or more bulk records that are not supported with the corresponding file format version.
Specify whether to return errors and their corresponding data, or only the errors in the results file. The default is ErrorsOnly.
The account identifier corresponding to the data that will be uploaded.
The URL where you may submit your bulk upload file via HTTP POST. The upload URL is valid for up to 15 minutes. If you have not successfully uploaded the file within this period, you will need to get a new request identifier and upload URL.
The number of SharedListItem objects that are added to this shared list. Add: Read-only Update: Read-only
The unique Microsoft Advertising identifier of the shared entity. Add: Read-only Update: Required
The name of the shared entity. The maximum string length is 255. Add: Optional Update: Optional
The type of the shared entity. This value is NegativeKeywordList when you retrieve a NegativeKeywordList. This value is PlacementExclusionList when you retrieve a PlacementExclusionList. This value is AccountNegativeKeywordList when you retrieve an AccountNegativeKeywordList. For more information about shared entity types, see SharedEntity Data Object Remarks. Add: Read-only Update: Read-only
The number of active associations between this shared entity and another entity such as campaign or ad account. For a NegativeKeywordList, the maximum number of active associations between the negative keyword list and campaign is 20. For a PlacementExclusionList, the maximum number of active associations between the website exclusion list and ad account is undefined. Add: Read-only Update: Read-only
The list of key and value strings for forward compatibility to avoid otherwise breaking changes when new elements are added in the current API version. Forward compatibility changes will be noted here in future releases. There are currently no forward compatibility changes for this object.
The Microsoft Advertising identifier of the account.
The list of migration status info for the corresponding account.
The date and time when the migration began. The value is in Coordinated Universal Time (UTC). The date and time value reflects the date and time at the server, not the client. For information about the format of the date and time, see the dateTime entry in Primitive XML Data Types.
The number of Site objects that are added to this shared list. Add: Read-only Update: Read-only
The value of the named account property. The value will vary by account property name. For more information, see Account Property Values in the section below.
The status of the ad extension. The value will always be Active because the Campaign Management service does not return deleted ad extensions. Add: Read-only Update: Read-only
Determines the calendar day and time ranges when the ad extension is eligible to be shown in ads. Add: Optional Update: Optional. If you set this element null, any existing scheduling set for the ad extension will remain unchanged. If you set this to any non-null Schedule object, you are effectively replacing existing scheduling settings for the ad extension. To remove all scheduling set this element to an empty Schedule object.
Not supported for this ad extension type.
The unique Microsoft Advertising identifier of the ad extension. Add: Read-only Update: Read-only and Required
The type of the ad extension. This value is ActionAdExtension when you retrieve an action ad extension. Add: Read-only Update: Read-only For more information about ad extension types, see the Ad Extension Data Object Remarks.
Tracks the number of times the ad extension has been updated. The version is set to 1 when the ad extension is created, and increments by one after each update. Add: Not allowed Update: Not allowed
The action type that you choose here, as well as the Language that you set, determines the text that is displayed on your call-to-action button. Microsoft Advertising does not support all action types for all languages. If you attempt to use an unsupported action type and language combination, an error will be returned. For details see Action Text for Action Ad Extensions. Add: Required Update: Required
The language that the ad extension will be served in. The extension will always be served in this language, regardless of the campaign or ad group's language settings. The supported language strings are: Danish, Dutch, English, Finnish, French, German, Italian, Norwegian, Portuguese, Spanish, Swedish, and TraditionalChinese. Microsoft Advertising does not support all action types for all languages. If you attempt to use an unsupported action type and language combination, an error will be returned. For details see Action Text for Action Ad Extensions. Add: Required Update: Required
This is a mobile-friendly landing page URL when Action Extensions are served on mobile devices. If you specify final mobile URLs, you must also specify FinalUrls. The length of the URL is limited to 2,048 characters. The HTTP or HTTPS protocol string does count towards the 2,048 character limit. Add: Optional Update: Optional. If you set this element null, the previous setting will be deleted.
This is the link to your specific web page or form that corresponds to the action text. When an action URL isn't provided, the ad's final URL will be used. The length of the URL is limited to 2,048 characters. The HTTP or HTTPS protocol string does count towards the 2,048 character limit. Although the data type is a list of strings, only the first list item is used by Microsoft Advertising. Add: Optional Update: Optional. If you set this element null, the previous setting will be deleted.
The tracking template to use as a default for all FinalUrls and FinalMobileUrls. The following validation rules apply to tracking templates. For more details about supported templates and parameters, see the Microsoft Advertising help article What tracking or URL parameters can I use? - Tracking templates defined for lower level entities e.g. ads override those set for higher level entities e.g. campaign. For more information, see Entity Limits. - The length of the tracking template is limited to 2,048 characters. The HTTP or HTTPS protocol string does count towards the 2,048 character limit. - The tracking template must be a well-formed URL beginning with one of the following: http://, https://, {lpurl}, or {unescapedlpurl}. - Microsoft Advertising does not validate whether custom parameters exist. If you use custom parameters in your tracking template and they do not exist, then the landing page URL will include the key and value placeholders of your custom parameters without substitution. For example, if your tracking template is https://tracker.example.com/?season={_season}&promocode={_promocode}&u={lpurl} and neither {_season} or {_promocode} are defined at the campaign, ad group, criterion, keyword, or ad level, then the landing page URL will be the same. Add: Optional Update: Optional. If you set this element null, the previous setting will be deleted.
The final URL suffix can include tracking parameters that will be appended to the end of your landing page URL. We recommend placing tracking parameters that your landing page requires in a final URL suffix so that your customers are always sent to your landing page. For more details and validation rules see Final URL Suffix in the technical guides. Add: Optional Update: Optional. If you set this element null, the previous setting will be deleted.
Your custom collection of key and value parameters for URL tracking. Microsoft Advertising will accept the first 8 CustomParameter objects that you include within the CustomParameters object, and if you include more than 8 custom parameters an error will be returned. Each CustomParameter includes Key and Value elements. For customers in the Custom Parameters Limit Increase Phase 3 pilot (GetCustomerPilotFeatures returns 635), Microsoft Advertising will accept the first 8 custom parameter key and value pairs that you include, and if you include more than 8 custom parameters an error will be returned. Add: Optional Update: Optional. If you set this element null, the previous setting will be deleted.
The list of key and value strings for forward compatibility to avoid otherwise breaking changes when new elements are added in the current API version. There are currently no forward compatibility changes for the AdExtension object. Add: Read-only Update: Read-only
The scheduled start date. The start date is inclusive. For example, if you set StartDate to 5/5/2020, the ad extensions will start being shown at 12:00 AM on 5/5/2020. Add: Required with a FlyerAdExtension; Optional for other ad extension types. If you do not specify a start date, the ad extensions are immediately eligible to be scheduled during the day and time ranges. Update: Optional. For most ad extension types the start date can be shortened or extended, as long as the end date is either null or occurs after the new start date. If set the start date to null, then you are effectively removing the start date and the ad extensions are immediately eligible to be scheduled during the day and time ranges. With a FlyerAdExtension you can cannot remove the start date. The start date can be shortened or extended, as long as the end date occurs up to 30 days after the new start date.
The scheduled end date. The end date is inclusive. For example, if you set EndDate to 12/31/2020, the ad extensions will stop being shown at 11:59 PM on 12/31/2020. Add: Required with a FlyerAdExtension; Optional for other ad extension types. For most ad extension types if you do not specify an end date, the ad extensions will continue to be delivered unless you pause the associated campaigns, ad groups, or ads. Update: Optional. For most ad extension types the end date can be shortened or extended, as long as the start date is either null or occurs before the new end date. If you set the end date to null, then you are effectively removing the end date and the ad extensions will continue to be delivered unless you pause the associated campaigns, ad groups, or ads. With a FlyerAdExtension you can cannot remove the end date; The end date can be shortened or extended, as long as the start date occurs up to 30 days before the new end date.
Determines whether to use the account time zone or the time zone of the search user where the ads could be delivered. Set this property to true if you want the ad extensions to be shown in the search user's time zone, and otherwise set it to false. Add: Optional. If you do not specify this element or leave it null, the default value of false will be set and the account time zone will be used. Update: When you update a schedule the existing settings are replaced with the new setting. Thus if you update a schedule and leave this element null, then you are effectively resetting to the default value of false.
The list of day and time ranges. Each day and time range includes the scheduled day of week, start/end hour, and start/end minute. Add: Optional. If you set this element to null, then ad extensions will be eligible for scheduling anytime during the calendar start and end dates. Update: Optional. The individual DayTime objects cannot be updated. You can effectively update the day and time ranges by sending a new list of all DayTime settings that should replace the prior set. If you set this element to null, then you are effectively removing all existing day and time ranges.
Specifies the year. Add: Required Update: Required
Specifies the month. Add: Required Update: Required
Specifies the day of the month. Add: Required Update: Required
The scheduled day of week. Add: Required. Update: The DayTime object cannot be updated.
The scheduled start hour. The possible values range from 0 to 23, where 0 is equivalent to 12:00AM and 12 is 12:00PM. Add: Required. Update: The DayTime object cannot be updated.
The scheduled start minute. The possible values range from 0 to 60. Add: Required. Update: The DayTime object cannot be updated.
The scheduled end hour. The possible values range from 0 to 24, where 0 is equivalent to 12:00AM and 12 is 12:00PM. Add: Required. Update: The DayTime object cannot be updated.
The scheduled end minute. The possible values range from 0 to 60. Add: Required. Update: The DayTime object cannot be updated.
The collection of key and value custom parameters for URL tracking. For campaigns, ad groups, and ad groups, ad group criterions, and ads Microsoft Advertising will accept the first 8 custom parameter key and value pairs that you include, and if you include more than 8 custom parameters an error will be returned. For action, price, and sitelink ad extensions Microsoft Advertising will accept the first 3 custom parameter key and value pairs that you include, and any additional custom parameters will be ignored. For customers in the Custom Parameters Limit Increase Phase 3 pilot (GetCustomerPilotFeatures returns 635) for action, price, and sitelink ad extensions, Microsoft Advertising will accept the first 8 custom parameter key and value pairs that you include, and if you include more than 8 custom parameters an error will be returned. Add: Required Update: Optional. Once you create this CustomParameters object, the existing custom parameters will be removed or replaced. To remove all existing custom parameters create this CustomParameters object and set the Parameters element to nil. To replace or append to the list of custom parameters, create this CustomParameters object and assign to the Parameters element a new list of CustomParameter objects, including any previous custom parameters that you want to retain. To retain all of the existing custom parameters, set the element that uses this CustomParameters object to nil. For example set the UrlCustomParameters element of an ExpandedTextAd to nil if you do not want to update any of the custom parameters.CustomParameter array
The name of the custom parameter that you want to track. The maximum length of this string is 16, in UTF-8 bytes. With the Campaign Management service you may not specify special characters such as braces and underscore: \"\{\", \"\_\", and \"\}\". With the Bulk service the surrounding braces and underscore are required. The maximum length of 16 UTF-8 bytes does not include the optional braces and underscore: \"\{\", \"\_\", and \"\}\". Add: Required Update: Required
The value to track using your custom parameter. The maximum length of this string is 200, in UTF-8 bytes. You can set the value to an empty string ("") but it cannot be null or empty. The maximum length of the value string is 250 for all entities except action, price, and sitelink ad extensions. The maximum length of the value string is 200 for action, price, and sitelink ad extensions. For action, price, and sitelink ad extensions, the maximum length increases to 250 for customers in the Custom Parameters Limit Increase Phase 3 pilot (GetCustomerPilotFeatures returns 635). Add: Required Update: Required
The unique Microsoft Advertising identifier for the ad.
The type of the ad. For more information about ad types, see the Remarks.
The status of the ad. You can set the ad status to Active or Paused.
The editorial review status of the ad, which indicates whether the ad is pending review, has been approved, or has been disapproved.
Determines the device preference for showing the ad. Device preference is only supported for AppInstallAd and TextAd objects.
The Ad Format Preference is used to indicate whether or not you prefer the ad copy to be shown to users as a search or audience ad. Search ads tend to be written as a call to action, whereas audience ads should be written in more of an informational style. While you have the option to use search ads as audience ads, designating an ad as Audience ads preferred format allows you to optimize its messaging for native delivery. Possible values are AudienceAd and All. If set to All, the ad will be eligible for both search and audience ad formats. If set to AudienceAd, the ad will only be eligible for the audience ad format. Ad Format Preference is only supported for ExpandedTextAd and TextAd objects.
The tracking template to use as a default for all landing page URLs. This element is only supported for AppInstallAd, DynamicSearchAd, ExpandedTextAd, ResponsiveAd, ResponsiveSearchAd, and TextAd objects. It is not supported with the ProductAd object.
The final URL suffix can include tracking parameters that will be appended to the end of your landing page URL. We recommend placing tracking parameters that your landing page requires in a final URL suffix so that your customers are always sent to your landing page. For more details and validation rules see Final URL Suffix in the technical guides. This element is only supported for AppInstallAd, DynamicSearchAd, ExpandedTextAd, ResponsiveAd, and ResponsiveSearchAd objects. It is not supported with the ProductAd and and TextAd objects.
Your custom collection of key and value parameters for URL tracking. This element is only supported for AppInstallAd, DynamicSearchAd, ExpandedTextAd, ResponsiveAd, ResponsiveSearchAd, and TextAd objects. It is not supported with the ProductAd object.
The last or final URL where a user is ultimately taken, whether or not the click to final URL path included any redirects. This element is only supported for AppInstallAd, ExpandedTextAd, ResponsiveAd, ResponsiveSearchAd, and TextAd objects. It is not supported with the DynamicSearchAd and ProductAd objects.
The mobile landing page URL. This element is only supported for ExpandedTextAd, ResponsiveAd, ResponsiveSearchAd, and TextAd objects. It is not supported with the AppInstallAd, DynamicSearchAd, and ProductAd objects.
The asset with a unique Microsoft Advertising identifier that can be reused across multiple ads. For asset links included in a responsive search ad's Headlines and Descriptions lists, the asset must be a TextAsset. Add: Required Update: Required
Determines whether the asset should only be used for a specific ad component, or whether you want Bing AI to optimize the layout for this asset. Unless you have a specific requirement for an asset, don't pin it and let Bing AI optimize the placement. If the Asset is a TextAsset and included in the responsive search ad's Descriptions list, the valid pinned field values are Description1 and Description2. At least one eligible TextAsset must be available for each description position, so you cannot pin all of the assets to the same position. For example you can have 3 text assets pinned to Description1, so long as you have at least one text asset in the responsive search ad's Descriptions list that is either not pinned, or pinned to Description2. If the Asset is a TextAsset and included in the responsive search ad's Headlines list, the valid pinned field values are Headline1, Headline2, and Headline3. At least one eligible TextAsset must be available for each headline position, so you cannot pin all of the assets to the same position. For example you can have 3 text assets pinned to Headline1 and 3 text assets pinned to Headline2, so long as you have at least one text asset in the responsive search ad's Headlines list that is either not pinned, or pinned to Headline3. If you previously pinned an asset to an ad component and later want to remove the pin, you'll need to update the ad with the existing assets and leave the pinned field element empty for the asset or assets that you want to unpin. When you retrieve an asset that is not pinned, the string value is nil or empty. PinnedField shouldn't be set for Performance Max AssetGroup as it doesn't apply. Add: Optional Update: Optional
This lets you know how well the asset is performing. The possible ratings include: - Low: This asset's performance is low and we recommend you replace this asset to improve your ad performance. - Good: This asset is performing well. We recommend you keep this asset and add more assets to improve your ad performance. - Best: This asset's performance is among the best and we recommend that you add more similar assets. - Unrated: We don't have any performance rating for this asset. This can be due to the asset being inactive, not having enough information to determine its performance, or if there aren't enough similar assets to compare against it. - Learning: The asset's performance is being actively evaluated. Once the evaluation is complete, the asset rating will be Low, Good, Best, or Unrated. Add: Read-only. The service will ignore this value if set. Update: Read-only. The service will ignore this value if set.
The editorial review status of the asset link, which indicates whether the asset is pending review, has been approved, or has been disapproved. Add: Read-only Update: Read-only
The unique Microsoft Advertising identifier for the asset in a Microsoft Advertising account. The same asset can be used by multiple ads. For example if Seemless Integration is a text asset, it will have the same asset identifier across all ads in the same Microsoft Advertising account.
The type of the asset. For more information about asset types, see the Remarks.
The unique Microsoft Advertising identifier for the asset in a Microsoft Advertising account. The same image asset identifier can be used multiple times in the same ad for different aspect ratios, and can also be used by multiple ads in the same Microsoft Advertising account. The identifier of image asset with SubType set to LandscapeImageMedia is used for all auto-generated image asset sub types within the same ad. Whether or not you let Microsoft Advertising automatically generate the cropped images, the Id does not need to be unique among the image assets linked to the same ad. You can create media for responsive ads via the AddMedia service operation. Then you can use the returned media identifier as the image asset ID. The aspect ratio of the image that you added must be supported for the image asset SubType. Add: Required Update: Optional. If no value is set for the update, this setting is not changed.
Reserved for future use. Add: Optional Update: Optional. If no value is set for the update, this setting is not changed.
The type of the asset. This value is ImageAsset when you retrieve an image asset. For more information about asset types, see the Asset Data Object Remarks. Add: Read-only Update: Read-only
Represents the aspect ratio for this image asset. The aspect ratio for the sub type must match the effective image asset dimensions. If CropHeight and CropWidth are not used then the aspect ratio for the sub type must match the aspect ratio of the stored image media. If CropHeight and CropWidth are used then the true aspect ratio of the media that is stored in the account level media library can differ, so long as CropHeight and CropWidth result in the correct aspect ratio. In either case the true aspect ratio of the media that is stored in the account level media library will remain unchanged. The sub type must be set to "Logo" if the image is associated with an ad as a "LandscapeLogoMedia" or "SquareLogoMedia". The possible sub type values include OriginalImage, LandscapeLogoMedia, SquareLogoMedia, LandscapeImageMedia, SquareImageMedia, ImageMedia169X100, ImageMedia201X100, ImageMedia120X100, ImageMedia200X100, ImageMedia124X100, ImageMedia153X100. For more details see ResponsiveAd Remarks. Note: As of now, the SubType OriginalImage replaces the role of LandscapeImageMedia as the default image for ResponsiveAd of Audience Campaign. New sub types might be added in the future, so you should not take any dependency on a fixed set of values. Add: Required Update: Read-only. You cannot update the sub type during update.
Starting from the lower left corner of image asset source, this is the number of pixels to skip to the right on the x-axis before applying the CropWidth. Add: Optional. If you do not set this element, the service will automatically crop according to the aspect ratio of the SubType. Update: Optional. If no value is set for the update, this setting is not changed.
Starting from the lower left corner of image asset source, this is the number of pixels to skip upwards on the y-axis before applying the CropHeight. Add: Optional. If you do not set this element, the service will automatically crop according to the aspect ratio of the SubType. Update: Optional. If no value is set for the update, this setting is not changed.
The number of pixels to use from the image asset source, starting from the CropX position and moving to the right. Add: Optional. If you do not set this element, the service will automatically crop according to the aspect ratio of the SubType. Update: Optional. If no value is set for the update, this setting is not changed.
The number of pixels to use from the image asset source, starting from the CropY position and moving upwards. Add: Optional. If you do not set this element, the service will automatically crop according to the aspect ratio of the SubType. Update: Optional. If no value is set for the update, this setting is not changed.
The target width dimension of an image asset.
The target height dimension of an image asset.
The type of the setting. This value is VerifiedTracking when you retrieve a verified tracking setting. For more information about setting types, see the Setting Data Object Remarks. Add: Read-only Update: Read-only
Key-value pairs for the VerifiedTrackingSetting object. VerifiedTrackingSetting relates third-party measurement settings. This allows you to track viewability, brand safety, and invalid traffic metrics via a third-party verification provider, such as Integral Ad Science. This feature is available for native, display, and online video ads using the CPM bid strategy. Note: Currently, IAS is the only supported vendor (vendorName), but other verification providers are coming soon. The example below pertains to IAS. There are 3 key-value pairs for IAS:"vendorName""advertiserEntityID" (client ID for your verification provider)"publisherEntityID" (reporting ID for your verification provider)Example (required for IAS): vendorName : "IAS"advertiserEntityID : "12345678"publisherEntityID : "12345678"
The identifier of the account to add the extensions to.
The list of ad extensions of any type to add to the account. You can specify a maximum of 100 extensions per call.
The status of the ad extension. The value will always be Active because the Campaign Management service does not return deleted ad extensions.
Determines the calendar day and time ranges when the ad extension is eligible to be shown in ads.
This element determines whether the preference is for the ad extension to be displayed on mobile devices or all devices. To specify a preference for mobile devices, set this element to 30001. To specify all devices, set this element to 0 (zero) or leave the element nil. By default, this element will be nil. This element is only applicable for the AppAdExtension and SitelinkAdExtension types.
The unique Microsoft Advertising identifier of the ad extension.
The type of ad extension. For more information, see Remarks.
Tracks the number of times the ad extension has been updated. The version is set to 1 when the ad extension is created, and increments by one after each update.
The first line of the address. The first line can contain a maximum of 80 characters. Add: Required Update: Required
The second line of the address. The second line can contain a maximum of 80 characters. Add: Optional Update: Optional. If you set this element null, the previous setting will be deleted.
The name of the city where the street address is located. The name can contain a maximum of 80 characters. Add: Required Update: Required
A code that identifies the state or province where the street address is located. For example, WA. The code can contain a maximum of 50 characters. You must specify either ProvinceName or ProvinceCode. The ProvinceCode and ProvinceName are not required if the CountryCode element is set to either FR, IE, or SG. Add: Required Update: Required
The name of the state or province where the street address is located. For example, Washington. The name can contain a maximum of 50 characters. You must specify either ProvinceName or ProvinceCode. TheProvinceCode and ProvinceName are not required if the CountryCode element is set to either FR, IE, or SG. Add: Required Update: Required
The postal or zip code. The postal code can contain a maximum of 80 characters. Add: Optional Update: Optional. If you set this element null, the previous setting will be deleted.
The country where the street address is located. The country code must contain a 2 character country code. The supported country code values include AR, AT, AU, BR, CA, CH, CL, CO, DE, DK, ES, FI, FR, GB, HK, ID, IE, IN, IT, MX, MY, NL, NZ, NO, PE, PH, SE, SG, TH, TW, US, VE, and VN. Add: Required Update: Required
The latitude specified in micro degrees. The latitude must be greater than or equal to -85000000 and less than or equal to +85000000.
The longitude specified in micro degrees. The longitude must be greater than or equal to -180000000 and less than or equal to +180000000.
The header that precedes the pricing data. The header can contain a maximum of 25 characters. The header must tie directly to the priceextensiontype that you defined for the PriceAdExtension. Add: Required Update: Optional. If no value is set for the update, this setting is not changed.
The description must provide further information about the header that is also defined in this object. The description can contain a maximum of 25 characters. Add: Required Update: Optional. If no value is set for the update, this setting is not changed.
The landing page URL. The following validation rules apply to Final URLs and Final Mobile URLs. - The length of the URL is limited to 2,048 characters. The HTTP or HTTPS protocol string does count towards the 2,048 character limit. - You may specify up to 10 list items for both FinalUrls and FinalMobileUrls; however, only the first item in each list is used for delivery. The service allows up to 10 list items for potential forward compatibility. - Usage of '{' and '}' is only allowed to delineate tags, for example {lpurl}. - Final URLs must each be a well-formed URL starting with either http:// or https://. - If you specify FinalMobileUrls, you must also specify FinalUrls. - If the TrackingUrlTemplate or UrlCustomParameters elements are set, then at least one final URL is required. Add: Optional Update: Optional. If no value is set for the update, this setting is not changed.
The landing page URL for mobile devices. The following validation rules apply to Final URLs and Final Mobile URLs. - The length of the URL is limited to 2,048 characters. The HTTP or HTTPS protocol string does count towards the 2,048 character limit. - You may specify up to 10 list items for both FinalUrls and FinalMobileUrls; however, only the first item in each list is used for delivery. The service allows up to 10 list items for potential forward compatibility. - Usage of '{' and '}' is only allowed to delineate tags, for example {lpurl}. - Final URLs must each be a well-formed URL starting with either http:// or https://. - If you specify FinalMobileUrls, you must also specify FinalUrls. Add: Optional Update: Optional. If no value is set for the update, this setting is not changed.
The price that you are advertising. Add: Required Update: Optional. If no value is set for the update, this setting is not changed.
The currency code for the listed price. The supported currency codes are ARS, AUD, BRL, CAD, CHF, CLP, CNY, COP, DKK, EUR, GBP, HKD, INR, MXN, NZD, PEN, PHP, PLN, SEK, SGD, USD, TWD, and VEF. Add: Required Update: Optional. If no value is set for the update, this setting is not changed.
The price unit allows you to specify the cost in terms of hour, day, week, etc. The price qualifier for a given product or service e.g., starting from a specific price and up to a maximum price. Possible values include: PerDay, PerHour, PerMonth, PerNight, PerWeek, PerYear, None, and Unknown. Add: Required Update: Optional. If no value is set for the update, this setting is not changed.
The price qualifier for a given product or service e.g., starting from a specific price and up to a maximum price. Possible values include: Average, From, UpTo, None, and Unknown. Add: Required Update: Optional. If no value is set for the update, this setting is not changed.
The identities of the extensions that were added. The list corresponds directly to the list of extensions specified in the request.
An array of BatchErrorCollection objects that contain details for any ad extensions that were not successfully added. The top level error within each BatchErrorCollection object corresponds to potential ad extension errors. The nested list of BatchError objects would include any errors specific to the list items within an ad extension (if applicable). The list of errors do not correspond directly to the list of items in the request. The list can be empty if there were no errors, or can include one or more error objects corresponding to each unsuccessful list item in the request.
The system-generated identifier of the ad extension.
The number of times the contents of the ad extension has been updated. The version is set to 1 when you add the extension and is incremented each time it's revised.
The zero-based top level list index in the request message that failed.
The name of the data object's element where the error occurred. This value is subject to change, so you should not take a dependency on the current string format. This element is not supported for all errors.
A list of batch errors corresponding to the nested list index.
A message that describes the error for the top level list index.
A symbolic string constant that identifies the error for the top level list index.
A numeric error code that identifies the error for the top level list index.
A message that provides additional details about the batch error for the top level list index. This string can be empty.
The name of the data object's element where the error occurred. For example if the TrackingUrlTemplate of a Campaign contains invalid text, the value of this FieldPath element is TrackingUrlTemplate. This value is subject to change, so you should not take a dependency on the current string format. This element is not supported for all errors. The field path is supported for errors related to FinalMobileUrls, FinalUrls, TrackingUrlTemplate, and UrlCustomParameters elements of the respective Campaign, AdGroup, TextAd, ProductAd, BiddableAdGroupCriterion, and Keyword objects. It is also supported for errors related to all fields of the CalloutAdExtension and ReviewAdExtension objects.
The type of criterion to add, for example Webpage. You can specify only one criterion type value per call. To add, delete, or update target criterions i.e., age, company name, day and time, device, gender, industry, job function, location, location intent, placement, radius, and topic criterions, you must specify the CriterionType value as Targets. You can add, delete, and update multiple target criterion types in the same operation. To retrieve these target criterions via GetAdGroupCriterionsByIds you must request the specific type individually i.e., Age, CompanyName, DayTime, Device, Gender, Industry, JobFunction, Location, LocationIntent, Placement, Radius, and Topic. To add, delete, or update audience criterions i.e., custom audiences, in-market audiences, and remarketing lists, you must specify the CriterionType value as Audience. You can add, delete, and update multiple target criterion types in the same operation. To retrieve these audience criterions via GetAdGroupCriterionsByIds you must request the specific type individually i.e., CustomAudience, InMarketAudience, ProductAudience, and RemarketingList. You cannot add a ProductPartition with this operation. Instead, you should use ApplyProductPartitionActions.
A list of ad group criterions. You can include up to 1,000 ad group criterions per request.
The identifier of the ad group to apply the criterion to.
A status value that determines whether to apply the criterion to the ad group.
The criterion to apply to the ad group. The criterion helps determine whether ads in the ad group are served. For a list of available criterion types, see AdGroupCriterionType.
The unique Microsoft Advertising identifier for the ad group criterion.
The type of ad group criterion. For more information, see Remarks.
The type of criterion. For more information, see Remarks.
The condition's operand. The operands implicitly include the equal operator. For example, read Brand as Brand=. Add or Apply: Required Update: Optional
The condition's attribute value. An attribute's value must exactly match the value specified in the customer's Microsoft Merchant Center catalog file. The available Attribute and Operand values vary depending on the campaign type. For supported attribute and operand values, see Remarks below. Add or Apply: Required Update: Optional
The rule item operator. Add: Required Update: Required
The criterion name that you can use to identify the criteria, for example you can filter or sort alphabetically. The criterion name length must be between 1 to 2048, inclusive. Add: Optional. If you do not specify any name, by default the name will be set to a concatenated list of conditions. Each condition will be delimited by the and keyword. For example if the conditions are a) Url contains flower, b) Url contains book, and c) PageContent contains seattle, then the default criterion name will be Url contains flower and Url contains book and PageContent contains seattle. If you do not specify any name, and if no conditions are specified, then you are effectively targeting all webpages and the name will be set to All Webpages. Update: Optional. If you leave this element null or empty the criterion name will not be updated. If you specify an empty string i.e. "", then the criterion name will be updated to the default value i.e. either All Webpages or a concatenated list of criterions.
The webpage conditions or criteria. You may include up to 3 individual WebpageCondition objects in the list. Each WebpageCondition contains an Argument, Operand and Operator element. If you use Operand as URL and Operator as Equals you can only specify one condition. Add: Optional for biddable criterion; Required for negative criterion. If no conditions are specified, then you are effectively targeting all webpages. Update: Not allowed. You cannot update the webpage conditions. To update the conditions you must delete the criterion and add a new criterion.
The webpage condition operand. Add: Required Update: Not applicable. You cannot update the webpage conditions. To update the conditions you must delete the criterion and add a new criterion.
The webpage condition operator. Add: Optional. Default operator is used when it is not defined. Operator is required only when you use Operand=URL and Operator = Equals Update: Not applicable. You cannot update the webpage conditions. To update the conditions you must delete the criterion and add a new criterion. Default values URL/PageTitle/PageContent - Contains, Category/CustomLabel - Equals. Supported values URL - Contains/Equals, PageTitle/PageContent - Contains, CustomLabel/Category - Equals
The webpage condition or criterion. The condition is met if the webpage property that is referenced by the operand contains or equals the argument's value. For example you can set this string to the URL, category, page title, or page content for your site. Note: For Performance Max campaigns, you can only set argument to the URL. Add: Required Update: Not applicable. You cannot update the webpage conditions. To update the conditions you must delete the criterion and add a new criterion.
The type of criterion bid. For more information, see Remarks.
A list of unique system identifiers corresponding to the criterion that were added. The list of identifiers corresponds directly to the list of criterion in the request. Items of the list may be returned as null. For each list index where a criterion was not added, the corresponding element will be null.
An array of BatchErrorCollection objects that contain details for any criterion that were not successfully added. The top level error within each BatchErrorCollection object corresponds to potential criterion errors. The nested list of BatchError objects would include any errors specific to the list of items a criterion can have. The list of errors do not correspond directly to the list of items in the request. The list can be empty if there were no errors, or can include one or more error objects corresponding to each unsuccessful list item in the request.
The identifier of the campaign to add the ad groups to.
An array of AdGroup objects to add to the specified campaign. You can add a maximum of 1,000 ad groups in a single call. Each campaign can have up to 20,000 ad groups.
The system-generated identifier of the ad group. Add: Not allowed. Update: Read-only and Required
The name of the ad group. The name must be unique among all active ad groups within the campaign. The name can contain a maximum of 256 characters. Add: Required Update: Optional. If no value is set for the update, this setting is not changed.
The date that the ads in the ad group can begin serving; otherwise, the service can begin serving the ads in the ad group the day that the ad group becomes active. The start date is inclusive. For example, if you set the start date to 5/5/2021, the ads in the ad group will start at 12:00 AM on 5/5/2021. The time is based on the time zone that you specify at the campaign level. If the associated campaign is campaign managed, the startDate of the adGroup will be set to the Campaign startDate. Add: Optional. If you do not set the start date, then it will default to today's date and the service can begin serving the ads in the ad group as soon as the ad group status is active. Update: Optional. If no value is set for the update, this setting is not changed. The start date cannot be updated after the ad group is submitted i.e., once the start date has arrived.
The date that the ads in the ad group will expire. If you do not specify an end date, the ads will not expire. The end date can be extended to make an ad group's ads eligible for delivery, even after the ad group expires. The end date is inclusive. For example, if you set EndDate to 12/31/2020, the ads in the ad group will expire at 11:59 PM on 12/31/2020. The time is based on the time zone that you specify at the campaign level. Note: If the associated campaign is campaign managed, the endDate of the adGroup will be set to null. Add: Optional. To set no end date when adding an ad group, set this element to null. Update: Optional. If no value is set for the update, this setting is not changed. To delete the existing end date setting, and effectively set no end date when updating an ad group, set the end date equal to or later than January 2, 2050. When you retrieve the ad group next time, this element will be nil i.e. it will not be set to January 2, 2050.
Your ad language setting determines the language you will use when you write your ads and should be the language of your customers. IMPORTANT: If languages are set at both the ad group and campaign level, the ad group level language will override the campaign level language. The supported language strings for Search and Shopping campaigns are: Bulgarian, Croatian, Czech, Danish, Dutch, English, Estonian, Finnish, French, German, Greek, Hungarian, Italian, Latvian, Lithuanian, Maltese, Norwegian, Polish, Portuguese, Romanian, Slovak, Slovenian, Spanish, Swedish, and TraditionalChinese. NOTE: The following languages are not yet available for everyone: Bulgarian, Croatian, Czech, Estonian, Greek, Hungarian, Latvian, Lithuanian, Maltese, Polish, Romanian, Slovak, Slovenian. For Dynamic Search Ads campaigns, the campaign and ad group level language settings are ignored in favor of the website domain language. You should set campaign languages to "All" and leave the ad group level language empty. For ad groups in Audience campaigns, ad group level language is not supported, and you must set the Languages element of the ad group's campaign to "All". Add: Optional if the campaign has one or more languages set, and otherwise the language is required for most campaign types. You are not allowed to set this element for ad groups in Audience campaigns. Update: Optional. If no value is set for the update, this setting is not changed. To remove the language and defer to the campaign level languages, set this element to an empty string value ("").
The status of the ad group. Possible values are Active, Expired, and Paused. The Expired status is read-only. Add: Optional. The default value is Paused. Update: Optional. If no value is set for the update, this setting is not changed.
Indicates whether or not your ad group target criteria e.g., ProfileCriterion are too narrow for ad groups in Audience campaigns. Add: Read-only Update: Read-only
The default bid to use when the user's query and the ad group's keywords match by using either a broad, exact, or phrase match comparison. The minimum and maximum bid range depends on the account's currency. For more information, see Currencies. Specifying a broad, exact, or phrase match bid at the keyword level overrides the ad group's Cpc bid value for the corresponding match type. Add: Optional. If you do not set a bid, it will be set to the minimum depending on your account's currency. Update: Optional. If no value is set for the update, this setting is not changed.
The search networks where you want your ads to display. Supported network values for ad groups within most campaign types are OwnedAndOperatedAndSyndicatedSearch and OwnedAndOperatedOnly. For ad groups in Audience campaigns, ad group level network is not supported. The ad groups are in the Microsoft Audience Network. For ad groups in smart shopping campaigns, you cannot set the network. The service will set the network to OwnedAndOperatedAndSyndicatedSearch. For ad groups in shopping campaigns for brands, the InHousePromotion network (Retailer Network only) is supported in addition to OwnedAndOperatedAndSyndicatedSearch and OwnedAndOperatedOnly. If you select one of the syndicated search options, you can call the SetNegativeSitesToAdGroups or SetNegativeSitesToCampaigns operation to prevent the ads from displaying on specific syndicated search websites. For more information about networks and ad distribution, see the About Ad Distribution help article. Add: Optional. The default is OwnedAndOperatedAndSyndicatedSearch. Update: Optional. If no value is set for the update, this setting is not changed.
Ad rotation sets how often Microsoft Advertising selects which ads to serve, if you have multiple ads within an ad group. Since no more than one ad from your account can show at a time, ad rotation prioritizes ads that appear statistically more likely to perform better. Note: Ad rotation does not apply to Product Ads. Possible values for the ad rotation Type are OptimizeForClicks and RotateAdsEvenly. If set to OptimizeForClicks, Microsoft Advertising prioritizes the ad from the ad group that appears to have the best chance of performing well, based on auction characteristics or factors, such as keyword, search term, device or location. Better-performing ads will show more frequently, and others will be served less often, if at all. If set to RotateAdsEvenly, Microsoft Advertising provides more balance in rotation between your ads. That is, the ads in a particular ad group have a similar chance of being displayed in response to a searcher's query. Ads are prioritized lower if they have lower ad quality, and therefore might display less often, or not at all. - The RotateAdsEvenly setting can allow lower-performing ads to display as often as better-performing ads. This might impact ad group performance. - The RotateAdsEvenly setting will be ignored if you use an automated bid strategy i.e., MaxClicks, MaxConversions, TargetCpa, or TargetRoas, as these bid strategies prioritize better-performing ads. Add: Optional. The default value is OptimizeForClicks. Update: Optional. If no value is set for the update, this setting is not changed.
The percent amount by which to adjust your bid for audience ads above or below the base ad group or keyword bid. This property is available in Search campaigns if the customer is enabled for the Microsoft Audience Network. This property is not available with smart shopping campaigns. Supported values are negative one hundred (-100) through positive nine hundred (900). Setting the bid adjustment to -100 percent will prevent audience ads from showing for this ad group. Set this element to zero (0) if you do not want any bid adjustment for audience ads. If this element is null you will inherit the AudienceAdsBidAdjustment setting of the ad group's Campaign. Add: Optional Update: Optional. This property will only be updated if you also set the UpdateAudienceAdsBidAdjustment element to true, and otherwise this property will be ignored. If the ad group already has a native bid adjustment, and you want to remove it to effectively inherit the AudienceAdsBidAdjustment setting of the ad group's Campaign, set this element to null.
The tracking template to use as a default for all URLs in your ad group. The following validation rules apply to tracking templates. For more details about supported templates and parameters, see the Microsoft Advertising help article What tracking or URL parameters can I use? - Tracking templates defined for lower level entities e.g. ads override those set for higher level entities e.g. campaign. For more information, see Entity Limits. - The length of the tracking template is limited to 2,048 characters. The HTTP or HTTPS protocol string does count towards the 2,048 character limit. - The tracking template must be a well-formed URL beginning with one of the following: http://, https://, {lpurl}, or {unescapedlpurl}. - Microsoft Advertising does not validate whether custom parameters exist. If you use custom parameters in your tracking template and they do not exist, then the landing page URL will include the key and value placeholders of your custom parameters without substitution. For example, if your tracking template is https://tracker.example.com/?season={_season}&promocode={_promocode}&u={lpurl} and neither {_season} or {_promocode} are defined at the campaign, ad group, criterion, keyword, or ad level, then the landing page URL will be the same. Add: Optional Update: Optional. If no value is set for the update, this setting is not changed. If you set this element to an empty string (""), the previous setting will be deleted.
The final URL suffix can include tracking parameters that will be appended to the end of your landing page URL. We recommend placing tracking parameters that your landing page requires in a final URL suffix so that your customers are always sent to your landing page. For more details and validation rules see Final URL Suffix in the technical guides. Add: Optional Update: Optional. If no value is set for the update, this setting is not changed. If you set this element to an empty string (""), the previous setting will be deleted.
Your custom collection of key and value parameters for URL tracking. Microsoft Advertising will accept the first 8 CustomParameter objects that you include within the CustomParameters object, and if you include more than 8 custom parameters an error will be returned. Each CustomParameter includes Key and Value elements. Add: Optional Update: Optional. If no value is set for the update, this setting is not changed. Set the UrlCustomParameters element to null or empty to retain any existing custom parameters. To remove all custom parameters, set the Parameters element of the CustomParameters object to null or empty. To remove a subset of custom parameters, specify the custom parameters that you want to keep in the Parameters element of the CustomParameters object.
The bid strategy type for how you want to manage your bids. NOTE: As of April 2021, you cannot set any bid strategies for ad groups or keywords. If you attempt to set bid strategies for ad groups or keywords, the request will be ignored without error. Ad groups and keywords will inherit their campaign's bid strategy. Add: Optional. If you do not set this element, then InheritFromParentBiddingScheme is used by default. Update: Optional. If no value is set for the update, this setting is not changed.
The ad group settings that typically vary by campaign type. You can include a maximum of one object per setting type in the list of settings e.g., one TargetSetting. The TargetSetting can be used with any campaign type, and determines whether the Age, Audience, CompanyName, Gender, Industry, and JobFunction criterions associated with this ad group use the "target and bid" option or the "bid only" target option. Within the TargetSetting you can have multiple TargetSettingDetail objects i.e., one per CriterionTypeGroup. Add: Optional. If this element does not include a TargetSetting object, the default bid option for all criterion type groups is effectively "bid only". Update: Optional. If no value is set for the update, this setting is not changed.
Determines whether to use the account time zone or the time zone of the search user where the ads could be delivered. Set this property to true if you want the ads to be shown in the search user's time zone, and otherwise set it to false. This element is not returned by default. To get this element, include the AdScheduleUseSearcherTimeZone value in the ReturnAdditionalFields element when you call the GetAdGroupsByCampaignId and GetAdGroupsByIds service operations. Add: Optional. If you do not specify this element or leave it empty, the default value of true will be set and the search user's time zone will be used. After September 30, 2020, if you do not specify this field or leave it empty, the default value of false is set and the account time zone is used. Update: Optional. If no value is set for the update, this setting is not changed.
The ad group type. In a mixed campaign where the CampaignType is "Search", the ExperimentId is not set, and the Settings already have a valid DynamicSearchAdsSetting, the possible values are "SearchDynamic" and "SearchStandard". Otherwise the type of ad groups within "Search" campaigns can only be set to "SearchStandard". If the ad group type is "SearchDynamic", then you can only add dynamic search ads within this ad group. If the ad group type is "SearchStandard", then you can add expanded text ads or responsive search ads within this ad group. The type of ad groups within "DynamicSearchAds" campaigns can only be set to "SearchDynamic". You don't need to set the ad group type for "DynamicSearchAds" campaigns, but please note when you retrieve ad groups this element will be set to "SearchDynamic". This field can be set to HotelAds for "Hotel" or "Search" campaign types. This element cannot be set for "Audience" or "Shopping" campaign types. When you retrieve an ad group within unsupported campaigns, this element will not be set. Add: Optional. The default value for "Search" campaigns is "SearchStandard". The default value for "DynamicSearchAds" campaigns is "SearchDynamic". Update: Read-only. You cannot update the ad group type.
The manual CPV bid strategy type. With the ManualCpv (manual cost per view) bid strategy, you set the highest amount that you'd like to pay per view or per click on a video ad, and Microsoft Advertising uses these bids every time. This element is not returned by default. To get this element, include the Cpv value in the ReturnAdditionalFields element when you call the GetAdGroupsByCampaignId and GetAdGroupsByIds service operations.
The manual CPM bid strategy type. With the ManualCpm (manual cost per thousand) bid strategy, you set the highest amount that you'd like to pay per thousand impressions, and Microsoft Advertising uses these bids every time. This element is not returned by default. To get this element, include the CpmBid value in the ReturnAdditionalFields element when you call the GetAdGroupsByCampaignId and GetAdGroupsByIds service operations.
The manual CPA bid strategy type. With the ManualCpa (manual cost per action) bid strategy, you set your big per advertiser-specified action.
The percent amount by which to adjust your bid for multimedia ads above or below the base ad group or keyword bid.
The commission rate charged to the advertiser when someone books a hotel and stays there.
The percent CPC bid strategy type (total hotel price per night, including taxes and fees).
This will be deprecated. Use UsePredictiveTargeting instead.
Indicates if predictive targeting is enabled for an AdGroup. Note: UsePredictiveTargeting is only available for Audience campaigns. Add: Optional Update: Optional.
The bid value. For details about the valid bid range for your market, see Currencies.
The type of ad rotation to apply to the ad group. Ad rotation sets how often Microsoft Advertising selects which ads to serve, if you have multiple ads within an ad group. Since no more than one ad from your account can show at a time, ad rotation prioritizes ads that appear statistically more likely to perform better. Note: Ad rotation does not apply to Product Ads. Possible values are OptimizeForClicks and RotateAdsEvenly. If set to OptimizeForClicks, Microsoft Advertising prioritizes the ad from the ad group that appears to have the best chance of performing well, based on auction characteristics or factors, such as keyword, search term, device or location. Better-performing ads will show more frequently, and others will be served less often, if at all. If set to RotateAdsEvenly, Microsoft Advertising provides more balance in rotation between your ads. That is, the ads in a particular ad group have a similar chance of being displayed in response to a searcher's query. Ads are prioritized lower if they have lower ad quality, and therefore might display less often, or not at all. - The RotateAdsEvenly setting can allow lower-performing ads to display as often as better-performing ads. This might impact ad group performance. - The RotateAdsEvenly setting will be ignored if you use an automated bid strategy i.e., MaxClicks, MaxConversions, TargetCpa, or TargetRoas, as these bid strategies prioritize better-performing ads. Add: Optional. If not specified, the default value is OptimizeForClicks. Update: Optional
Reserved for future use only. Must be null.
The type of bidding scheme that is set for this campaign, ad group, or keyword. For more information about bidding scheme types, see the Remarks.
The type of setting. For more information, see Remarks.
Defines an object that represents the rate amount.
The smallest time interval to limit ad serves. Values are Hour, Day, Week.
A limit to the number of times an ad is shown.
A list of unique system identifiers corresponding to the ad groups that were added. The list of identifiers corresponds directly to the list of ad groups in the request. Items of the list may be returned as null. For each list index where an ad group was not added, the corresponding element will be null.
An array of BatchError objects that contain details for any request items that were not successful. The list of errors do not correspond directly to the list of items in the request. The list can be empty if there were no errors, or can include one or more error objects corresponding to each unsuccessful list item in the request.
The identifier of the ad group to add the ads to.
An array of up to 50 ads that you want added to the ad group.
A list of unique system identifiers corresponding to the ads that were added. The list of identifiers corresponds directly to the list of ads in the request. Items of the list may be returned as null. For each list index where an ad was not added, the corresponding element will be null.
Array of asset groups to add to the specified campaign. A maximum of 100 asset groups can be specified in a single call.
The name of the asset group. Names should be unique in a campaign and are case sensitive. The length cannot exceed 256 characters. Add: Required Update: Optional
The status of the Asset group. Possible values are Active, Expired and Paused. The Expired status is read-only. Add: Optional. Default is Paused. Update: Optional
The date that the asset group can begin serving; otherwise, the service can begin serving ads the day that the asset group becomes active. The start date is inclusive. For example, if you set the start date to 5/5/2021, the ads created from the asset group will start at 12:00 AM on 5/5/2021. The time is based on the time zone that you specify at the campaign level. Add: Optional. If you do not set the start date, then it will default to today's date and the service can begin serving ads as soon as the asset group status is active. Update: Optional. If no value is set for the update, this setting is not changed. The start date cannot be updated after the asset group is submitted i.e., once the start date has arrived.
The date that the asset group will expire. If you do not specify an end date, the asset group will not expire. The end date can be extended to make an asset group eligible for delivery, even after the asset group expires. The end date is inclusive. For example, if you set EndDate to 12/31/2020, the ads in the asset group will expire at 11:59 PM on 12/31/2020. The time is based on the time zone that you specify at the campaign level. Add: Optional. To set no end date when adding an asset group, set this element to null. Update: Optional. If no value is set for the update, this setting is not changed. To delete the existing end date setting, and effectively set no end date when updating an asset group, set the end date equal to or later than January 2, 2050. When you retrieve the asset group next time, this element will be nil i.e. it will not be set to January 2, 2050.
The first part of the optional path that will be appended to the domain portion of your display URL. The domain portion of your display URL e.g. https://www.contoso.com will be generated from the domain of your Final URL (FinalUrls element). Then if you have specified a value for Path1 it will be appended to the display URL. If you have also specified a value for Path2, then it will also be appended to the display URL after Path1. For example if your FinalUrls contains https://www.contoso.com, Path1 is set to subdirectory1, and Path2 is set to subdirectory2, then the URL displayed will be https://www.contoso.com/subdirectory1/subdirectory2. No more than 15 characters can be input. The ad will fail to display if the length of the final URL domain and the paths combined exceed 67 characters. For languages with double-width characters e.g. Traditional Chinese no more than 7 final characters can be input. The ad will fail to display if the length of the final URL domain and the paths combined exceed 33 characters. The double-width characters are determined by the characters you use instead of the character set of the campaign language settings. Double-width characters include Korean, Japanese and Chinese languages characters as well as Emojis. The path cannot contain the forward slash (/) or newline (\n) characters. If the path includes a space, it will be replaced with an underscore (_) when the ad is shown. Add: Optional Update: Optional
The second part of the optional path that will be appended to the domain portion of your display URL. The domain portion of your display URL e.g. https://www.contoso.com will be generated from the domain of your Final URL (FinalUrls element). Then if you have specified a value for Path1 it will be appended to the display URL. If you have also specified a value for Path2, then it will also be appended to the display URL after Path1. For example if your FinalUrls contains https://www.contoso.com, Path1 is set to subdirectory1, and Path2 is set to subdirectory2, then the URL displayed will be https://www.contoso.com/subdirectory1/subdirectory2. You can only specify Path2 if Path1 is also set. No more than 15 characters can be input. The ad will fail to display if the length of the final URL domain and the paths combined exceed 67 characters. For languages with double-width characters e.g. Traditional Chinese no more than 7 final characters can be input. The ad will fail to display if the length of the final URL domain and the paths combined exceed 33 characters. The double-width characters are determined by the characters you use instead of the character set of the campaign language settings. Double-width characters include Korean, Japanese and Chinese languages characters as well as Emojis. The path cannot contain the forward slash (/) or newline (\n) characters. If the path includes a space, it will be replaced with an underscore (_) when the ad is shown. Add: Optional Update: Optional
The name of the business. Your business's name may appear in your ad, depending on the ad placement. The length of the string is limited to 25 characters. Add: Required. If not provided and parent campaign associates to a store, the store name will be used as the business name. Update: Optional. If no value is set for the update, this setting is not changed.
Headlines are the most prominent text that appears in your ad, so you should make the most out of the available characters. We require multiple headlines so the ad can flexibly display across a variety of publishers and placements. From a data model perspective the descriptions and headlines are each stored as text assets i.e., one TextAsset per AssetLink. The same asset can be used by multiple ads. For example if "Seamless Integration" is a text asset, it will have the same asset identifier across all ads in the same Microsoft Advertising account. You must set between 3-15 headlines. Each headline's Text must contain at least one word. The Text cannot contain the newline (\n) character. If the parent campaign associates to a store and you specify Headlines, you must also specify LongHeadlines, Descriptions, and Images. Add: Optional if its parent campaign associates to a store, required if its parent campaign does not associate to a store. Update: Optional. To retain all of the existing asset links, set or leave this element nil. If you set a value for this element, any headlines that were previously linked to this asset group will be replaced. If the parent campaign associates to a store and you set this element to an empty list, the previous setting will be deleted.
You must set between 1-5 long headlines. Each headline's Text must contain at least one word. The Text cannot contain the newline (\n) character. If the parent campaign associates to a store and you specify LongHeadlines, you must also specify Headlines, Descriptions, and Images. Add: Optional if the parent campaign associates to a store, required if its parent campaign does not associate to a store. Update: Optional. To retain all of the existing asset links, set or leave this element nil. If you set a value for this element, any headlines that were previously linked to this asset group will be replaced. If the parent campaign associates to a store and you set this element to an empty list, the previous setting will be deleted.
The descriptions that are shown below the path in your ad. You must set between 2-5 descriptions. Each description's Text must contain at least one word. The Text cannot contain the newline (\n) character. If the parent campaign associates to a store and you specify Descriptions, you must also specify Headlines, LongHeadlines, and Images. Add: Optional if the parent campaign associates to a store, required if its parent campaign does not associate to a store. Update: Optional. To retain all of the existing asset links, set or leave this element nil. If you set a value for this element, any descriptions that were previously linked to this asset group will be replaced. If the parent campaign associates to a store and you set this element to an empty list, the previous setting will be deleted.
Image assets with different sizes and aspect ratios so they can flexibly display across a variety of publishers and placements. Include one or more AssetLink objects that each contain an ImageAsset with SubType and crop settings that match the desired aspect ratio. The ImageAsset contains the CropHeight, CropWidth, CropX, CropY and SubType fields. The possible sub type values include LandscapeImageMedia, SquareImageMedia, LandscapeLogoMedia, SquareLogoMedia, ImageMedia1x2, ImageMedia4x1, ImageMedia201X100, ImageMedia169X100, ImageMedia153X100, and ImageMedia124X100. You must provide at least 1 LandscapeImageMedia and 1 SquareImageMedia. A total of up to 20 images and a total of up to 5 logos can be saved. If the parent campaign associates to a store and you specify Images, you must also specify Headlines, LongHeadlines, and Descriptions. Add: Optional if the parent campaign associates to a store, required if its parent campaign does not associate to a store. Update: Optional. If no value is set for the update, this setting is not changed. If you include images during update, any previously set images will be replaced. If the parent campaign associates to a store and you set this element to an empty list, the previous setting will be deleted.
A brief, punchy reason for customers to click your ad right now. This is displayed on your call to action button. Add: Required. If not provided and parent campaign associates to a store, it will default to LearnMore. Update: Optional. If no value is set for the update, this setting is not changed.
The landing page URL. The domain portion of the URL in combination with the path 1 and path 2 strings cannot exceed 67 characters. The following validation rules apply to Final URLs and Final Mobile URLs. - The length of the URL is limited to 2,048 characters. The HTTP or HTTPS protocol string does count towards the 2,048 character limit. - You may specify up to 10 items for both FinalUrls and FinalMobileUrls; however, only the first item in each list is used for delivery. The service allows up to 10 for potential forward compatibility. - Usage of '{' and '}' is only allowed to delineate tags, for example {lpurl}. - Final URLs must each be a well-formed URL starting with either http:// or https://. - If you specify FinalMobileUrls, you must also specify FinalUrls. For retail campaigns, the final url must match the domain from the store associated with the campaign. Add: Required. If not provided and parent campaign associates to a store, the store URL will be used as the final URL. Update: Optional
The mobile landing page URL. The following validation rules apply to Final URLs and Final Mobile URLs. - The length of the URL is limited to 2,048 characters. The HTTP or HTTPS protocol string does count towards the 2,048 character limit. - You may specifiy up to 10 items for both FinalUrls and FinalMobileUrls; however, only the first item in each list is used for delivery. The service allows up to 10 for potential forward compatibility. - Usage of '{' and '}' is only allowed to delineate tags, for example {lpurl}. - Final URLs must each be a well-formed URL starting with either http:// or https://. - If you specify FinalMobileUrls, you must also specify FinalUrls. Add: Optional Update: Optional
The tracking template to use as a default for all URLs in your asset group. The following validation rules apply to tracking templates. For more details about supported templates and parameters, see the Microsoft Advertising help article What tracking or URL parameters can I use? - Tracking templates defined for lower level entities e.g. ads override those set for higher level entities e.g. campaign. For more information, see Entity Limits. - The length of the tracking template is limited to 2,048 characters. The HTTP or HTTPS protocol string does count towards the 2,048 character limit. - The tracking template must be a well-formed URL beginning with one of the following: http://, https://, {lpurl}, or {unescapedlpurl}. - Microsoft Advertising does not validate whether custom parameters exist. If you use custom parameters in your tracking template and they do not exist, then the landing page URL will include the key and value placeholders of your custom parameters without substitution. For example, if your tracking template is https://tracker.example.com/?season={_season}&promocode={_promocode}&u={lpurl} and neither {_season} or {_promocode} are defined at the campaign, asset group, criterion, keyword, or ad level, then the landing page URL will be the same. Add: Optional Update: Optional. If no value is set for the update, this setting is not changed. If you set this element to an empty string (""), the previous setting will be deleted.
The editorial review status of the asset group, which indicates whether the asset group is pending review, has been approved, or has been disapproved. Add: Read-only Update: Read-only
The system generated asset group ID. Add: Read-only Update: Read-only
Array of asset group IDs to update for the specified campaign. A maximum of 100 asset groups can be specified in a single call.
An array of BatchError objects that contain details for any request items that weren't successful.
Array of audience groups. The maximum size of the list is 100 items per service request. You can add a maximum of 10,000 audience groups per account.
The name of the audience signal, the name must be unique among all audience groups within the account. The name can contain a maximum of 256 characters. Add: Required Update: Optional
The description of the audience. Use a description to help you remember what audience you are using. Add: Optional Update: Optional. If no value is set for the update, this setting is not changed.
Positive dimensions that specifying the audience composition. It should have at least one dimension. Add: Required, at least one dimension is needed. Update: Optional. For each dimension type (age, gender, audience): - If not present in the array, it's not changed. - If it's present in the array, take Age dimension type as an example: - If AgeRanges is set to null or empty, it'll remove existing values for this dimension type. - If AgeRanges has data, it simply replaces existing values. Note: You can't remove all dimension types. An error will be returned and no changes will be made.
The number of asset groups that associate with this audience group. Add: Read-only Update: Read-only
The system-generated ID. Add: Read-only Update: Required
The type of audience dimensions, the following dimension types are supported as of now: Age, Gender, Audience. Add: For more information about audience types, see the Remarks. Update: For more information about audience types, see the Remarks.
The type of the audience. Add: Read-only Update: Read-only
Array of audience group ids to be added. The maximum size of the list is 100 items per service request.
The list of audiences to add. The maximum size of the list is 100. You cannot add CustomAudience, InMarketAudience, or SimilarRemarketingList objects.
Scope defines what accounts can use this audience. If scope is set to Account, the audience can only be associated with campaigns and ad groups in one account i.e., via the ParentId. If scope is set to Customer, the audience can be associated with campaigns and ad groups in all of the customer's accounts.
When you create an audience, you can specify how far back in time Microsoft Advertising should look for actions that match your audience definition. The minimum duration is 1 day and the maximum duration allowed is 180 days.
The total number of people who are active members of this audience in the Search network. This gives you an idea of how many search users you can target. Please see more details in documentation for the objects that inherit this element e.g., RemarketingList.
The total number of people who are active members of this audience in the Audience network. This gives you an idea of how many Audience network users you can target. Please see more details in documentation for the objects that inherit this element e.g., RemarketingList.
The list of campaign types that support this audience. Supported values are Audience, DynamicSearchAds, Search, and Shopping. New campaign types might be added in the future, so you should not take any dependency on a fixed set of values.
Determines the list of customers and accounts that share the audience. Details include audience association counts. This element is only supported with a RemarketingList. Audiences of other types cannot be shared in the customer hierarchy.
The Microsoft Advertising identifier of the audience.
The name of the audience. The name can contain a maximum of 128 characters.
The description of the audience. Use a description to help you remember what audience you are targeting. The description can contain a maximum of 1,024 characters.
The type of the audience. For more information about audience types, see the Remarks.
The Microsoft Advertising identifier of the account or customer. If the Scope is set to Account, this is the account ID, and otherwise it is the customer ID.
The customer who owns the share. Add: Read-only Update: Read-only
Determines the list of customers and accounts that share the audience or UET tag. Details include audience association counts. When the audience or UET tag has not yet been shared, this element will be nil or empty. Once an audience or UET tag is shared, a CustomerAccountShare object is returned for each customer that can use the share, including one list item for the owner. Add: Required Update: Optional. Once you create this CustomerShare object, the existing CustomerAccountShare list will be removed or replaced. To remove all existing customer account shares create this CustomerShare object and set the CustomerAccountShares element to nil. To replace or append to the list of customer account shares, create this CustomerShare object and assign to the CustomerAccountShares element a new list of CustomerAccountShare objects, including any previous customer account shares that you want to retain. To retain all of the existing customer account shares, set the element that uses this CustomerShare object to nil. For example set the CustomerShare element of a RemarketingList to nil if you do not want to update any of the customer account shares.
The identifier of a customer that can use the shared audience or UET tag. If this element is not set, then the audience is only shared with a subset of advertiser accounts under this customer. Please see AccountId for details about sharing audiences with advertiser accounts. Add: Optional. You must set the AccountId or CustomerId, but you cannot set both. Update: Optional. If no value is set for the update, this setting is not changed.
The identifier of an advertiser account that can use the shared audience. This element is not applicable for UET tags since you cannot restrict UET tags to a subset of advertiser accounts. You can only create and share UET tags at the CustomerId level. If this element is not set, then all accounts under the CustomerId can use the shared audience or UET tag. One CustomerAccountShare object per advertiser account must be present in the CustomerShare for an audience that is shared with a subset of advertiser accounts, whether or not the advertiser accounts are under the same customer. Add: Optional. You must set the AccountId or CustomerId, but you cannot set both. Update: Optional. You must set the AccountId or CustomerId, but you cannot set both. If no value is set for the update, this setting is not changed.
Provides details about whether and how the shared audience or UET tag is being used. Each list item contains the association count for the corresponding usage type. Add: Read-only Update: Read-only
Indicates how the customer account share is used e.g., via audience association. The possible values include RemarketingListAssociateToAdGroup, RemarketingListAssociateToCampaign, and UETTagAssociateToRemarketingList. New values be added in the future, so you should not take any dependency on a fixed set of strings. - RemarketingListAssociateToAdGroup - The remarketing list is associated with or excluded by one or more ad groups. - RemarketingListAssociateToCampaign - The remarketing list is associated with or excluded by one or more campaigns. - UETTagAssociateToConversionGoal - The UET tag is used by one or more conversion goals. - UETTagAssociateToProductAudience - The UET tag is used by one or more product audiences. - UETTagAssociateToRemarketingList - The UET tag is used by one or more remarketing lists. Add: Read-only Update: Read-only
The association count for the corresponding usage type. Add: Read-only Update: Read-only
The type of the remarketing rule. For more information about remarketing rule types, see the Remarks. Add: Read-only Update: Read-only
The list of rule items. The maximum number of rule items in a rule item group is 100. The rule items must all be of the same concrete type derived from the RuleItem base class. Currently only a list of StringRuleItem objects are supported. The list of StringRuleItem objects apply to same visited page, and the rule conditions are joined using the logical AND operator. In other words to add a visitor to the remarketing list, one page must meet all of the conditions in this rule item list. To create a list of rules for another page, you must add a separate RuleItemGroup. Add: Required Update: Optional. If you want to keep any of the previous rule items, then you must explicitly set them again during update.
The type of rule item. For more information, see Remarks.
The list of audience identifiers to combine in a logical set. You can combine custom audiences, customer lists, product audiences, similar audiences, and remarketing lists. You cannot include other combined lists or in-market audiences in a combined list. For details, please see the remarks section below. Each combination rule set can contain up to 100 audience IDs.
Determines whether to include or exclude any or all of the AudienceIds.
A list of unique system identifiers corresponding to the audiences that were added. The list of identifiers corresponds directly to the list of audiences in the request. Items of the list may be returned as null. For each list index where an audience was not added, the corresponding element will be null.
An array of BidStrategy objects to add to the account's portfolio bid strategy library. You can include a maximum of 100 bid strategies in a single call. Each account can have up to 11,000 portfolio bid strategies. The account is determined by the required CustomerAccountId header element.
The unique Microsoft Advertising identifier of the bid strategy. Add: Read-only Update: Required
The name of the bid strategy. The name must be unique among all bid strategies within the account. The name can contain a maximum of 255 characters. The service performs a case-insensitive comparison when it compares the name to existing bid strategy names. Add: Required Update: Optional
The type of ad campaign that can be included the portfolio bid strategy. The supported campaign types are "Search" and "Shopping" (except smart shopping campaigns). Once you choose a campaign type, the portfolio can only include campaigns of that type. Add: Optional. The default campaign type is Search. Update: Read-only
The portfolio bid strategy type and settings. If the AssociatedCampaignType is "Search", the supported bid strategies are MaxClicksBiddingScheme, MaxConversionsBiddingScheme TargetCpaBiddingScheme, TargetImpressionShareBiddingScheme, and TargetRoasBiddingScheme. If the AssociatedCampaignType is "Shopping", the supported bid strategies are MaxClicksBiddingScheme and TargetRoasBiddingScheme. Once you choose a bid strategy type it cannot be updated. Add: Required Update: Optional. You can update properties of a bidding scheme, but you cannot change the type.
The number of Campaign objects that currently share this bid strategy. Add: Read-only Update: Read-only
A nullable field that indicates whether the bid strategy is created at the customer level or the account level. If no value is provided, the default scope is Account.
The currency for the cross-account poortfolio. It must match the account currency provided. If null, it defaults to the account's currency. This field can't be updated.
Specifies the reporting timezone for the campaign. If no value is provided, it defaults to the account's timezone. This field can be updated.
A list of unique system identifiers corresponding to the bid strategies that were added. The list of identifiers corresponds directly to the list of bid strategies in the request. Items of the list may be returned as null. For each list index where a bid strategy was not added, the corresponding element will be null.
A list of BrandKits to be created for the specified account.
The term exclusions to use with your brand kit.
The messaging restrictions to use with your brand kit.
Where to crop along the x-axis in pixels.
Where to crop along the y-axis in pixels.
An array of Budget objects to add to the account's shared budget library. You can add a maximum of 100 budgets in a single call. Each account can have up to 11,000 shared budgets. The account is determined by the required CustomerAccountId header element.
The name of the budget. The name must be unique among all budgets within the account. The name can contain a maximum of 255 characters. The service performs a case-insensitive comparison when it compares the name to existing budget names. Add: Required Update: Optional
The amount to spend daily across all campaigns that share the budget. Add: Required Update: Optional
The budget type determines the pace at which the budget is spent throughout the day. The only valid budget type that you can set is DailyBudgetStandard. Add: Required Update: Optional
The number of Campaign objects that currently share this budget. Add: Read-only Update: Read-only
The unique Microsoft Advertising identifier of the budget. Add: Read-only Update: Required
A list of unique system identifiers corresponding to the budgets that were added. The list of identifiers corresponds directly to the list of budgets in the request. Items of the list may be returned as null. For each list index where a budget was not added, the corresponding element will be null.
An array of the base object of a campaign conversion goal.
The Microsoft Advertising assigned identifier of a campaign.
The Microsoft Advertising assigned identifier of a conversion goal.
The type of criterion to add, for example Webpage. You can specify only one criterion type value per call. To add, delete, or update target criterions i.e., age, day and time, device, gender, location, location intent, and radius criterions, you must specify the CriterionType value as Targets. You can add, delete, and update multiple target criterion types in the same operation. To retrieve these target criterions via GetCampaignCriterionsByIds you must request the specific type individually i.e., Age, DayTime, Device, Gender, Location, LocationIntent, and Radius. To add, delete, or update audience criterions i.e., custom audiences, in-market audiences, and remarketing lists, you must specify the CriterionType value as Audience. You can add, delete, and update multiple target criterion types in the same operation. To retrieve these audience criterions via GetCampaignCriterionsByIds you must request the specific type individually i.e., CustomAudience, InMarketAudience, ProductAudience, and RemarketingList.
A list of criterions that help determine whether ads in each campaign get served. You can include up to 100 campaign criterions per request.
The identifier of the campaign to apply the criterion to.
The criterion to apply to the campaign. The criterion helps determine whether ads in the campaign are served. For a list of available criterion types, see CampaignCriterionType.
A status value that determines whether to apply the criterion to the campaign.
The unique Microsoft Advertising identifier for the campaign criterion.
The type of campaign criterion. For more information, see Remarks.
The identifier of the account to add the campaigns to.
The list of campaigns to add to the specified account. You can add 100 campaigns per service request.
The unique Microsoft Advertising identifier of the campaign. Add: Read-only Update: Required
The name of the campaign. The name must be unique among all active or paused campaigns within the account. The name can contain a maximum of 128 characters. The service performs a case-insensitive comparison when it compares the name to existing campaign names. Add: Required Update: Optional. If no value is set for the update, this setting is not changed.
The status of the campaign. Possible values are Active and Paused. The service will automatically pause the campaign if the budget is depleted. With experiment campaigns you cannot set the Budget, BudgetType, or Status The budget, and status of an experiment campaign are always inherited from the base campaign settings. Add: Optional. The default value is Paused. Update: Optional. If no value is set for the update, this setting is not changed.
The amount to spend daily on the campaign. You must set the daily budget amount if BudgetId is not set. Your budget is a target; your actual spend might be higher or lower. Variations are caused by a number of factors, such as different traffic volumes in different days of the week, or automatic detection and refunding of fraud clicks that can give money back to a campaign within a few hours of the click. Microsoft Advertising anticipates and automatically compensates for the fluctuations, and usually keeps overspend to less than 100% above your daily limit. Also note that Microsoft Advertising does not require your campaign budget to be higher than the ad group and keyword bids. In other words ad group and keyword bids are validated independently of the campaign budget. In the context of shared budgets, the budget amount is a read-only property that is always returned regardless of whether or not the campaign uses a shared budget. When a campaign is associated to a shared budget the amount returned is that of the shared budget. To determine whether the campaign uses a shared budget, check the value of the BudgetId element as described above. With experiment campaigns you cannot set the Budget, BudgetType, or Status. The budget, and status of an experiment campaign are always inherited from the base campaign settings. Note: This field is currently used to set the lifetime budget amount when the budget type is set to LifetimeBudgetStandard. Add: Required if the BudgetId is not set. Read-only if the campaign uses a shared budget. Update: Optional if the BudgetId is not set. If no value is set for the update, this setting is not changed. Not allowed if the campaign uses a shared budget. If you try to update the budget amount of a campaign that has a shared budget, the service will return the CampaignServiceCannotUpdateSharedBudget error code.
The budget type determines how the budget is spent. The possible values are DailyBudgetAccelerated, DailyBudgetStandard, and LifetimeBudgetStandard. Both DailyBudgetAccelerated and LifetimeBudgetStandard budget types are only available for Audience campaigns that use unshared campaign-level budgets. In the context of shared budgets, the budget type is a read-only property that is always returned regardless of whether or not the campaign uses a shared budget. To determine whether the campaign uses a shared budget, check the value of the BudgetId element as described above. With experiment campaigns you cannot set the Budget, BudgetType, or Status. The budget, and status of an experiment campaign are always inherited from the base campaign settings. Add: Required if the BudgetId is not set. Read-only if the campaign uses a shared budget. Update: Optional if the BudgetId is not set. If no value is set for the update, this setting is not changed. Not allowed if the campaign uses a shared budget. If you try to update the budget type of a campaign that has a shared budget, the service will return the CampaignServiceCannotUpdateSharedBudget error code.
This column is deprecated. The time zone where the campaign operates. The time zone is used for reporting and applying the start and end date of an ad group. For possible values, see Time Zones. With experiment campaigns you cannot set the Budget, BudgetType, Status, or TimeZone. The budget, status, and time zone of an experiment campaign are always inherited from the base campaign settings. Add: Required Update: Optional. If no value is set for the update, this setting is not changed. You may not update the time zone if the campaign contains or has ever contained ad groups in the Active or Paused state.
The supported settings that vary by campaign type. Note: VerifiedTrackingSetting is not currently available. You can include a maximum of one object per setting type in the list of settings e.g., one TargetSetting. If the CampaignType is set to Search and if the ExperimentId element is not set, this list can optionally include a DynamicSearchAdsSetting object. Experiment campaigns and base campaigns of experiments cannot include dynamic search ads settings. If you intend to use this campaign for experiments, do not include dynamic search ads settings. If an existing experiment is already based on this campaign, you cannot update the campaign to include dynamic search ads settings. If the CampaignType is set to Shopping, this list must include a ShoppingSetting object. If the CampaignType is set to Audience, this list may or may not include a ShoppingSetting object, depending on whether or not the Audience campaign supports product ads. If the CampaignType is set to DynamicSearchAds, this list must include a DynamicSearchAdsSetting object. If the CampaignType is set to Hotel, this list must include a HotelSetting object. If the CampaignType is set to PerformanceMax, this list must include a PerformanceMaxSetting object. If the Performance Max campaign associates to a store, it also supports a ShoppingSetting. The TargetSetting can be used with any campaign type except Performace Max, and determines whether the Audience criterions associated with this campaign use the "target and bid" option or the "bid only" target option. Within the TargetSetting you can have one TargetSettingDetail objects i.e., one per supported CriterionTypeGroup. The only criterion type value currently supported for the campaign level target setting is "Audience". The TargetSetting object is not returned by default. To get this object, include the TargetSetting value in the ReturnAdditionalFields element when you call the GetCampaignsByAccountId and GetCampaignsByIds service operations. Add: Required if the CampaignType is set to DynamicSearchAds or Shopping, and otherwise this element is optional. If this element does not include a TargetSetting object, the default bid option for all criterion type groups is effectively "bid only". Update: Optional. If no value is set for the update, this setting is not changed. The DynamicSearchAdsSetting and ShoppingSetting objects cannot be removed during update.
The campaign type determines whether the campaign is an Audience, Dynamic Search Ads, Search, Shopping campaign, Hotel Ads, or Performance Max. Add: Optional. If not specified, then default value of Search is used. Update: Not allowed.
The campaign sub type. If the sub type is not set, the campaign is created according to the campaign type. If the sub type is set to AudienceVideoAds and the campaign type is Audience, the campaign is a video audience campaign. If the sub type is set to ShoppingSmartAds, the campaign is a Microsoft Smart Shopping campaign. If the sub type is set to ShoppingSponsoredProductAd, the campaign is a Microsoft shopping campaigns for brands. Add: Optional and not applicable for most campaign types. For Microsoft smart shopping campaigns you must set the sub type to ShoppingSmartAds. For Microsoft shopping campaigns for brands you must set the sub type to ShoppingSponsoredProductAd. Update: Read-only
The percent amount by which to adjust your bid for audience ads above or below the base ad group or keyword bid. This property is available in Search campaigns if the customer is enabled for the Microsoft Audience Network. This property is not available with smart shopping campaigns. Supported values are negative one hundred (-100) through positive nine hundred (900). Setting the bid adjustment to -100 will prevent audience ads from showing for this campaign. Set this element to zero (0) if you want to use the base ad group or keyword bid instead of specifying any bid adjustment for audience ads. As a best practice you should always specify a bid adjustment value. If you set this element to null the system default bid adjustment will be used. The system default bid adjustment is currently zero (0), and is subject to change. Add: Optional Update: Optional. If no value is set for the update, this setting is not changed.
The tracking template to use as a default for all URLs in your campaign. The following validation rules apply to tracking templates. For more details about supported templates and parameters, see the Microsoft Advertising help article What tracking or URL parameters can I use? - Tracking templates defined for lower level entities e.g. ads override those set for higher level entities e.g. campaign. For more information, see Entity Limits. - The length of the tracking template is limited to 2,048 characters. The HTTP or HTTPS protocol string does count towards the 2,048 character limit. - The tracking template must be a well-formed URL beginning with one of the following: http://, https://, {lpurl}, or {unescapedlpurl}. - Microsoft Advertising does not validate whether custom parameters exist. If you use custom parameters in your tracking template and they do not exist, then the landing page URL will include the key and value placeholders of your custom parameters without substitution. For example, if your tracking template is https://tracker.example.com/?season={_season}&promocode={_promocode}&u={lpurl} and neither {_season} or {_promocode} are defined at the campaign, ad group, criterion, keyword, or ad level, then the landing page URL will be the same. Add: Optional Update: Optional. If no value is set for the update, this setting is not changed. If you set this element to an empty string (""), the previous setting will be deleted.
The bid strategy type for how you want to manage your bids. For details about supported bid strategies per campaign type, see Budget and Bid Strategies. IMPORTANT: For some bid strategy types your bid and ad rotation settings are ignored and conversion tracking (via Universal Event Tracking tag and a conversion goal) is required. For more information including supported locations, see Let Microsoft Advertising manage your bids with bid strategies. This element will be nil or empty by default if the campaign uses the MaxConversionValueBiddingScheme or TargetImpressionShareBiddingScheme bid strategy. To get the MaxConversionValueBiddingScheme or TargetImpressionShareBiddingScheme objects, include the respective MaxConversionValueBiddingScheme and TargetImpressionShareBiddingScheme values in the ReturnAdditionalFields element when you call the GetCampaignsByAccountId and GetCampaignsByIds service operations. Note: Starting August 4, 2025, the BiddingScheme will no longer support TargetCpaBiddingScheme and TargetRoasBiddingScheme. Any bid strategy set to Target CPA will be silently converted to Maximize Conversions using the Target CPA value. Any bid strategy set to Target ROAS will be silently converted to Maximize Conversion Value using the Target ROAS value. Existing campaigns that use the Target CPA and Target ROAS bid strategies will remain unaffected. Add: Optional. The default bid strategy type for Search and DynamicSearchAds campaigns is EnhancedCpcBiddingScheme. The default bid strategy type for most Shopping campaigns is EnhancedCpcBiddingScheme; however, the only supported bid strategy types for smart shopping campaigns are MaxConversionsBiddingScheme and MaxConversionValueBiddingScheme. The supported bid strategy types for Audience campaigns are EnhancedCpcBiddingScheme, ManualCpcBiddingScheme, ManualCpmBiddingScheme, and TargetCpaBiddingScheme. The supported bid strategy types for lodging campaigns are CommissionBiddingScheme, ManualCpcBiddingScheme, and PercentCpcBiddingScheme. The supported bid strategies for Performance Max campaigns are MaxConversionsBiddingScheme (with optional TCPA) and MaxConversionValueBiddingScheme (with optional TROAS). The supported bid strategies for new Video campaigns are ManualCpmBiddingScheme and ManualCpvBiddingScheme. NOTE: As of May 2024, you can no longer use the manual CPC bid strategy for audience native campaigns. You can only use manual CPC for audience display and video campaigns, and for lodging campaigns. We will automatically convert any existing manual CPC audience native campaigns to enhanced CPC. If you attempt to set manual CPC for any other campaign type, the request will be ignored without error and the bid strategy will be set to enhanced CPC. As of April 2021, you cannot set any bid strategies for ad groups or keywords. Bid strategies can only be set at the campaign level. If you attempt to set bid strategies for ad groups or keywords, the request will be ignored without error. Ad groups and keywords will inherit their campaign's bid strategy. Update: Optional. If no value is set for the update, this setting is not changed.
The unique Microsoft Advertising identifier of the Budget that this campaign shares with other campaigns in the account. If the value is not null and greater than zero, then the campaign is using a shared budget. If the value is null, then the campaign is not using a shared budget. If the campaign is using a shared budget, and you prefer that it use its own budget e.g. DailyBudget amount, set this element to '0' (zero) and set DailyBudget to a valid budget amount. Note: Shared budgets are not supported with smart shopping campaigns or Performance Max campaigns. With smart shopping campaigns, you must set the DailyBudget amount. Add: Optional Update: Optional. If no value is set for the update, this setting is not changed.
Your ad language setting determines the language you will use when you write your ads and should be the language of your customers. IMPORTANT: If languages are set at both the ad group and campaign level, the ad group level language will override the campaign level language. You can specify multiple languages individually in the list, or only include one list item set to All if you want to target all languages. The supported language strings for Search and Shopping campaigns are: Albanian, Bulgarian, Croatian, Czech, Danish, Dutch, English, Estonian, Finnish, French, German, Greek, Hungarian, Italian, Japanese, Latvian, Lithuanian, Maltese, Norwegian, Polish, Portuguese, Romanian, Slovak, Slovenian, Spanish, Swedish, and TraditionalChinese. NOTE: The following languages are not yet available for everyone: Bulgarian, Croatian, Czech, Estonian, Greek, Hungarian, Japanese, Latvian, Lithuanian, Maltese, Polish, Romanian, Slovak, Slovenian. For Audience campaigns you must include all languages i.e., set this element to All. For Dynamic Search Ads campaigns, the campaign and ad group level language settings are ignored in favor of the website domain language. You should set campaign languages to "All" and leave the ad group level language empty. Add: Required for Audience campaigns, and otherwise this element is optional. If there is no campaign language set, then the language of each ad group within the campaign will be required. Update: Optional. If no value is set for the update, this setting is not changed. Once campaign languages are set, you cannot delete all of them. The list of languages that you specify during update replaces the previous settings i.e. does not append to the existing set of languages.
The system-generated identifier of the Experiment. This element is only set for experiment campaigns i.e., campaigns that have been created for A/B testing based on another Search campaign. Base campaigns will not contain an experiment ID. Likewise, after an experiment has been Graduated to an independent campaign, this element will be empty, even though the campaign was previously an experiment campaign. With experiment campaigns you cannot set the Budget, BudgetType, or Status. The budget, and status of an experiment campaign are always inherited from the base campaign settings. If you want to change an experiment's budget, you will need to change the base campaign's budget. The change in value will then be split based on your experiment TrafficSplitPercent setting. Add: Read-only Update: Read-only
Determines whether to use the account time zone or the time zone of the search user where the ads could be delivered. Set this property to true if you want the ads to be shown in the search user's time zone, and otherwise set it to false. This element is not returned by default. To get this element, include the AdScheduleUseSearcherTimeZone value in the ReturnAdditionalFields element when you call the GetCampaignsByAccountId and GetCampaignsByIds service operations. Add: Optional. If you do not specify this element or leave it empty, the default value of false will be set and the account time zone will be used. Update: Optional. If no value is set for the update, this setting is not changed.
The system-generated identifier of the BidStrategy that this campaign shares with other campaigns in the account. If the field is empty, then the campaign is not using a portfolio bid strategy. If the field is not empty and the value is greater than zero, then the campaign is using a portfolio bid strategy. If the campaign is using a portfolio bid strategy, and you prefer that it use its own bid strategy, set this field to '0' (zero). Note: Portfolio bid strategies are not supported with smart shopping campaigns or Performance Max campaigns. Add: Optional Update: Optional. If no value is set for the update, this setting is not changed.
A nullable field that indicates whether the BidStrategyId associated with the campaign is defined at the customer level or the account level. If no value is provided, the default scope is set to Account.
A list of unique system identifiers corresponding to the deals that were added. The list of identifiers corresponds directly to the list of deals in the request. Items of the list may be returned as null. For each list index where a deal was not added, the corresponding element will be null.
The campaign is a deal campaign if true.
The date when you want your campaign to begin serving. For campaigns with budget type LifetimeBudgetStandard, StartDate is mandatory. The start date can be updated as long as the campaign has not started serving. Note: Currently, this will only be honored for Audience campaigns.
The date when you want your campaign to stop serving. If the budget type is LifetimeBudgetStandard, EndDate is required and can't be more than one year after the start date. EndDate can be set or left unset for campaigns with a daily budget. To remove the existing end date and effectively configure the campaign with no end date, set EndDate to January 1, 2050, or a later date. When retrieving the campaign, this element will be null. This indicates that no predefined end date exists, and EndDate won't explicitly be set to January 1, 2050. Note: Currently, this will only be honored for Audience campaigns.
Determines whether the dates should be managed at the campaign level or the ad group level. If set to true, campaign dates will be considered during serving. For the Lifetime Budget type, this field is required and must be set to true. For Daily Budget types, it can be set to either true or false, depending on whether you prefer to use campaign dates or ad group dates.
Indicates whether a campaign is political. Microsoft doesn't currently support political campaigns. If IsPolitical is set to true, attempts to add or update the campaign will fail with the error: PoliticalCampaignsAreNotSupported. Additionally, if this field is empty or null in a GET call or bulk download, its value is treated as false. Add: Optional. If you do not specify this field or leave it empty, the default value of false is set. Update: Optional. If you do not specify this field or leave it empty, the default value of false is set. Delete: Read-only
A list of unique system identifiers corresponding to the campaigns that were added. The list of identifiers corresponds directly to the list of campaigns in the request. Items of the list may be returned as null. For each list index where a campaign was not added, the corresponding element will be null.
The list of conversion goals to add to the account's shared conversion goal library. You can add a maximum of 100 conversion goals per service request. The account is determined by the required CustomerAccountId header element.
The conversion goal name. The maximum length of the name is 100, and the name must be unique among all conversion goals belonging to the same customer.
Defines the possible user-determined status values of a conversion goal. These are the status values that a user can decide to set, for example a goal can be set to Paused if you no longer wish to track conversions for that goal. For status values that can be set by the system, for example whether or not the UET tag is verified, see the TrackingStatus element.
Determines if the goal applies to all accounts or only the account specified in the required CustomerAccountId header element. If you have multiple Microsoft Advertising accounts, you can track conversions across all of those accounts. If you associate a goal with one account, conversions will be tracked for that account only. Possible values are Account and Customer. Once you set scope, you can't change it. If you want to change the scope, you need to create a new conversion goal and pause the old one. Only the Customer scope is supported for the AppInstallGoal.
This determines how your conversions are recorded within your chosen conversion window. There are two choices, and if you do not set a value the default is All: - All: All conversions that happen after an ad click will be counted. This is a common choice for sales. - Unique: Only one conversion that happens after an ad click will be counted. This is a common choice for leads. For example: You track two conversions: leads and sales. You pick Unique for leads and All for sales. When one ad click turns into two leads and two sales, it's counted as three conversions: one for the unique lead, and two for all the sales. This element is not applicable for the AppInstallGoal.
Determines how much each conversion is worth to your business. When adding a conversion goal if you do not specify any revenue tracking preferences, then each ConversionGoalRevenue will be set to their respective default values. When updating a conversion goal, if the Revenue element is nil or empty then none of the nested properties will be updated. However, if this element is not nil or empty then you are effectively replacing any existing revenue properties. The VariableValue option is not available for the AppInstallGoal, DurationGoal, or PagesViewedPerVisitGoal.
The conversion window is the length of time in minutes after a click that you want to track conversions. If you set this value to 43200 minutes (30 days), then conversions that happen within 30 days after a click are tracked. Past conversions aren't affected. The minimum value supported is 1 minute, although keep in mind that a shorter conversion window will reduce the number of conversions your account records. The maximum value supported is 129600 minutes (90 days).
The unique Microsoft Advertising identifier of the UET tag that you added to your website to allow Microsoft Advertising to collect actions people take on your website. Before you take a dependency on the tag ID, please note that the UET tag can be shared with or from another customer. Shared UET tags and audiences are only available for pilot customers. For an overview of sharing audiences and UET tags in a customer hierarchy, see the Share Audiences and UET Tags technical guide. This element is not applicable for the AppInstallGoal, InStoreTransactionGoal, and OfflineConversionGoal.
Defines the possible system-determined status values of a conversion goal. These are the status values that can be set by the system, for example the system sets the status to TagUnverified if the UET tag has not yet been verified. For status values that a user can decide to set, for example setting the status to Paused if you no longer wish to track conversions for that goal, see the Status element. Only the NoRecentConversions and RecordingConversions statuses are applicable for the AppInstallGoal and OfflineConversionGoal.
Determines whether or not to exclude data otherwise related to this conversion goal from a subset of performance report columns. This element is only available for customers who are enabled for the Include in Conversions feature (GetCustomerPilotFeatures returns 574). If this element is set to true, data otherwise related to this conversion goal will be excluded from the Conversions, ConversionRate, CostPerConversion, ReturnOnAdSpend, RevenuePerConversion, and Revenue report columns. Also, if you use an automated bidding bid strategy, setting this property true will result in the goal's conversions no longer factoring into automated bidding calculations. Setting this property "true" is effectively the same as unchecking "Include in Conversions" in the Microsoft Advertising web application. Regardless of this element value, the AllConversions, AllConversionRate, AllCostPerConversion, AllReturnOnAdSpend, AllRevenuePerConversion, and AllRevenue report columns will include data for all conversion goals. By default this element is false, and data related to this conversion goal are included in all report columns. For more information, see Report Attributes and Performance Statistics and the help article Conversion goals: "Conversions" versus "All conversions".
view through conversion window in minutes
The view-through conversion window is the length of time in minutes after a click that you want to track view-through conversions. If you set this value to 43200 minutes (30 days), then view-through conversions that happen within 30 days after a click are tracked. Past conversions aren't affected. The minimum value supported is 1 minute, although keep in mind that a shorter conversion window will reduce the number of conversions your account records. The maximum value supported is 43200 minutes (30 days). The IncludeViewThroughConversions account property must also be set to true for view-through conversions to be tracked. This element is not returned by default. To get this element, include the ViewThroughConversionWindowInMinutes value in the ReturnAdditionalFields element when you call the GetConversionGoalsByIds and GetConversionGoalsByTagIds service operations. This element is not applicable for the AppInstallGoal, InStoreTransactionGoal, and OfflineConversionGoal.
The category used to segment the conversion goal. Categorize your conversion goals however makes sense for your business. Goal categories don't affect performance - they are here to help you segment your goals and their performance metrics. The supported category values vary by conversion goal type, so please refer to the corresponding reference page for detailed requirements.
Determines which attribution model, _DataDriven_, _LastTouch_ or _LastClick_, is used with a conversion goal. This element is not returned by default. To get this element, include the AttributionModelType value in the ReturnAdditionalFields element when you call the GetConversionGoalsByIds and GetConversionGoalsByTagIds service operations. This element is not applicable for the AppInstallGoal, InStoreTransactionGoal, and OfflineConversionGoal.
Determines whether enhanced conversions are enabled for a conversion goal.
Determines whether a conversion goal is a simplified conversion goal. Only the EventGoal type is supported.
The unique Microsoft Advertising identifier for the conversion goal.
The type of the conversion goal. For more information about conversion goal types, see the Remarks.
Determines how revenue is tracked. The possible types are FixedValue, NoValue (the default type), and VariableValue. If the type is FixedValue then you must specify the Value element. If the type is NoValue then you must not specify the Value element. If the type is VariableValue then you can optionally specify a default value with the Value element. Add: Optional. If not specified, the default type is NoValue. Update: Optional. If not specified, the default type is NoValue.
The revenue value or amount. If you assign values to your conversions, you'll be able to see the total value driven by your advertising across different conversions, rather than simply the number of conversions that have happened. The default value is effectively 0, and possible values range from 0 to 999,9999. Accepted values depend on the revenue type, so please see the Type element for details. For the OfflineConversionGoal, the ConversionValue element of the applied OfflineConversion data takes precedence over this currency value. Add: Optional. If not specified, the default type is effectively 0. Update: Optional. If not specified, the default type is effectively 0.
The currency type that you want the conversion goal revenue to be reported. For a list of possible string values see Microsoft Advertising Currencies. For the EventGoal, InStoreTransactionGoal, OfflineConversionGoal, and UrlGoal objects, if their Scope element is set to Customer and if the Type is FixedValue or VariableValue, this property is required. For the OfflineConversionGoal, the ConversionCurrencyCode element of the applied OfflineConversion data takes precedence over this currency code. For the other supported conversion goals if you modify your UET tag tracking code to pass back both a revenue value and a currency, then the UET tag currency value takes precedence over this currency code. For more information on modifying your UET tag tracking code for variable revenue reporting, see How to report variable revenue with UET. If the Scope element of any ConversionGoal is set to Account and you do not specify the CurrencyCode, then by default the account level billing currency will be used to report conversion goal revenue. This element is not available for the AppInstallGoal, DurationGoal, or PagesViewedPerVisitGoal. You cannot set this property for those goal types. Add: Optional unless otherwise noted above. Update: Optional unless otherwise noted above.
A list of unique system identifiers corresponding to the conversion goals that were added. The list of identifiers corresponds directly to the list of conversion goals in the request. Items of the list may be returned as null. For each list index where a conversion goal was not added, the corresponding element will be null.
The conversion value rules to be created.
The locale identifier (LCID) for the request. The default value is 1033 for EnglishUS. For more LCID values, see LCID Value Set.
The location condition associated with the conversion value rule. Each conversion value rule can have up to 2 conditions.
The audience condition associated with the conversion value rule. Each conversion value rule can have up to 2 conditions.
The device condition associated with the conversion value rule. Each conversion value rule can have up to 2 conditions.
The value of the conversion value rule. It should be greater than 0. Add: Required Update: Optional
The operation type of the conversion value rule.
The currency code for the conversion value rule.
The status of the conversion value rule.
The unique identifier of the conversion value rule. Add: Optional Update: Required
The locations included in the condition.
The locations excluded from the condition.
The intent option for included locations.
The intent option for excluded locations.
Indicates if this is the primary condition. Only 1 primary condition is allowed in a conversion value rule.
The unique identifier of the location condition item. Required.
The name of the location condition item.
The type of the location condition item. Required.
The audiences included in the condition.
The unique identifier of the audience condition item. Required.
The name of the audience condition item.
The type of the audience condition item. Required.
The device types included in the condition.
The IDs of the conversion value rules that were successfully created.
The start date. Important: The value must be in your account time zone. This differs from the time zone options when you upload offline conversions in the Microsoft Advertising web application. For information about the format of the date and time, see the dateTime entry in Primitive XML Data Types.
The end date. Important: The value must be in your account time zone. This differs from the time zone options when you upload offline conversions in the Microsoft Advertising web application. For information about the format of the date and time, see the dateTime entry in Primitive XML Data Types.
Which devices types to include for the data exclusion.
Which campaign types to include for the data exclusion.
Which campaigns to include for the data exclusion.
The list of experiments to add. You can add 100 experiments per service request. You can create up to 10 nonconcurrent experiments per base campaign, whether they are added at the same time or across multiple service requests. Each base campaign must be in the same account, and the account is determined by the required CustomerAccountId header element.
The unique Microsoft Advertising identifier of the experiment. Add: Read-only Update: Required
The name of the experiment. The name of the experiment campaign that is created from the base campaign will match the experiment name, and vice versa. If the experiment name is updated, the experiment campaign's name will automatically be updated to match, and vice versa. The name must be unique (case-insensitive) among all campaigns and experiments within the account. The name can contain a maximum of 128 characters. Add: Required Update: Optional. If no value is set for the update, this setting is not changed.
The Microsoft Advertising identifier of the campaign used as the base for the experiment campaign. You can create up to 10 nonconcurrent experiments per base campaign. In other words multiple experiments for the same base campaign cannot have overlapping time intervals. Experiments are available for Audience, Search, Shopping, and Performance Max campaigns. If the campaign uses a shared budget, then you cannot use it as the base campaign for an experiment. Add: Read-only and Required. Update: Read-only. You cannot change the base campaign of an experiment.
The Microsoft Advertising identifier of the campaign that is created as a copy of the base campaign. All base campaign settings, including ad groups, ads, ad extension associations, and target settings are copied to the new experiment campaign. After the experiment campaign is created you can update all of its settings except for the campaign Budget, BudgetType, and TimeZone. The budget and time zone of an experiment campaign are always inherited from the base campaign settings. Add: Read-only Update: Read-only
The percentage of the base campaign's budget and ad traffic that you want to allocate for this experiment. Ad traffic is split between the experiment and the base campaign based on individual searches. Relevant searches will randomly bring up either ads from your experiment or ads from your base campaign. This means that individual customers could see ads from both sources if they search multiple times. Possible values range from 1 to 99. Add: Required Update: Read-only. You cannot change the split while an experiment is running.
Defines an array of the experiment arm data object.
The date that the experiment campaign can begin serving ads. The start date cannot be updated after the experiment has begun i.e., once the start date has arrived. The start date is inclusive. For example, if you set start date to 5/5/2020, the experiment will start at 12:00 AM on 5/5/2020. The time is relative to the base campaign time zone. Add: Required Update: Optional. If no value is set for the update, this setting is not changed.
The date that the experiment will expire. If you do not specify an end date, the ads will not expire. Once the end date has passed, the end date cannot be extended. The end date is inclusive. For example, if you set the end date to 12/31/2020, the experiment will end at 11:59 PM on 12/31/2020. The time is relative to the base campaign time zone. Add: Optional. If you leave this element nil or empty the experiment will not expire until you take further action e.g., set the experiment status to Ended. Update: Optional. If no value is set for the update, this setting is not changed. To delete the current end date and effectively set no end date, set the Day, Month, and Year each to '0' (zero). When you retrieve the experiment next time, this element will not be set.
The status of the experiment. Possible status values are described in the remarks below. Add: Required. You must set the status to Active; however, the status will be set automatically by Microsoft Advertising to Creating, and the next time you retrieve the experiment its status will be either Active, Creating, CreationFailed, Paused, or Scheduled. Update: Read-only
Determines whether to show individual customers ads from the experiment and the original campaign randomly, or only from one or the other. The possible values include TrafficBased and CookieBased. TrafficBased: This is also known as the search-based option. Every time customers search, they are randomly shown either ads from your experiment or ads from your original campaign. This means that individual customers could see ads from both sources if they search multiple times. CookieBased: When individual customers search, we show ads from either your experiment or your original campaign, and use a cookie to ensure that, going forward, they will only see ads from this source. The cookie-based option has an important trade-off to consider: On one hand, you may get more accurate data, since you're ensuring that an individual customer is only responding to one source or the other. On the other hand, it may take you longer to build up statistically significant comparison data than with the search-based option. Add: Optional. The default is TrafficBased. Update: Read-only. You cannot update the experiment type.
A list of unique system identifiers corresponding to the experiments that were added. The list of identifiers corresponds directly to the list of experiments in the request. Items of the list may be returned as null. For each list index where an experiment was not added, the corresponding element will be null.
Array of HTML5 assets to add to the specified campaign.
The URL of the webpage that the user is taken to when they click the ad.
The URL of the thumbnail used for the HTML5 asset.
The date and time the HTML5 asset was created in UTC.
The date and time the HTML5 asset was modified in UTC.
A descriptive error code for any issues with the HTML5 asset.
The import jobs to create. Although this element is an array, you can include a maximum of one GoogleImportJob object per call. You can set the Google account that you want to import from via the GoogleAccountId element in the GoogleImportJob object. The Microsoft Advertising ad account that you want to import to is determined by the required CustomerAccountId header element of this AddImportJobs service operation.
The unique Microsoft Advertising identifier of the import job.
The type of the import job. For more information about import job types, see the Remarks.
The status of the import job. The possible values are Active, Pause and Deleted. Scheduled imports will have an Active status, whether the job is scheduled once or on a recurring basis in the future. Paused import jobs will have a Pause status. The status of import jobs that only run once will be set to Deleted after the import. Add: Read-only Update: Optional. If no value is set for the update, this setting is not changed.
Determines whether and how often you want to receive email notifications about the import job results.
The unique identifier of the Microsoft Advertising user who created the import job.
The login user name of the Microsoft Advertising user who created the import job.
Determines whether the import job should be run once or scheduled on a recurring basis. To run the import job now, this element should be nil or empty.
The most recent import date and time for this job. The date and time is expressed in Coordinated Universal Time (UTC).
The date and time when the import job was created. The date and time is expressed in Coordinated Universal Time (UTC).
The import options that are available via API.
The email address where import results should be sent. This element is not returned by default. To get this element, include the NotificationEmail value in the ReturnAdditionalFields element when you call the GetImportJobsByIds and GetImportResults service operations.
The scheduling frequency type. Set this element to "Scheduling" if you want to choose a specific Cron value, whether the import job should run once or on a recurring basis. Set this element to "Auto" if you want Microsoft Advertising to run imports on a varying schedule that will best optimize your campaigns. If you want the import to run now, you can either set this element to "RunNow" or do not set the Google import job Frequency element at all. Add: Required
The time zone used for the import schedule. For possible values, see Time Zones. Add: Optional. If you do not set this element, then "GreenwichMeanTimeDublinEdinburghLisbonLondon" (UTC+0) will be used by default.
Represents a simplified implementation of Cron frequency. For example, set the string to "0 16 3 *" if you want the import to run weekly, every Wednesday at 4:00 PM. For details about supported frequency values, see the Remarks. Add: Required if the Type is set to "Scheduling", and otherwise the cron value is ignored.
The type of import option. For more information, see Remarks.
new ad groups and child entities for existing campaigns
new negative keywords for existing parents
new search themes for existing asset groups
search and replace for tracking templates
search and replace for custom parameters
pause campaigns without supported locations
search and dsa mixed campaign as search campaign
pause aimad group if all audience criterion not imported
update asset automation campaign setting
import ncagoal with system generated audience
The string to find. The case-insensitive search string does not support regular expressions.
The replacement string to use in place of the search string.
Identifies the list of specific ad groups to import within the campaign. If this element is nil or empty, include all ad groups of the campaign. The ActiveAdGroupsOnly element determines whether to include paused ad groups or only import active ad groups.
Determines whether to include paused ad groups or only import active ad groups. This element is not returned by default. To get this element, include the ActiveAdGroupsOnly value in the ReturnAdditionalFields element when you call the GetImportJobsByIds and GetImportResults service operations. If this element is true and if the AdGroupIds is not set, then only active ad groups from the campaign will be imported. Paused ad groups will not be imported. If this element is false or empty, then all of the campaign's ad groups will be imported. This element is ignored if specific ad groups are selected in the AdGroupIds element.
A list of unique system identifiers corresponding to the import jobs that were added. The list of identifiers corresponds directly to the list of import jobs in the request. Items of the list may be returned as null. For each list index where an import job was not added, the corresponding element will be null.
A list of BatchError objects that contain details for any list item requests that were not successful. The list of errors do not correspond directly to the list of items in the request. The list will be empty if there were no errors.
The identifier of the ad group to add the keywords to.
The list of keywords to add to the ad group. You can add a maximum of 1,000 keywords to an ad group per service request.
Determines whether or not the service should return the bid strategy type that is inherited from the parent campaign or ad group. The default value is false, and the InheritedBidStrategyTypes element will only be returned if you set this element true.
The identifier of the asset group to add the keywords to.
The system-generated identifier of the keyword. Add: Read-only Update: Required
The maximum amount that you want to pay each time someone clicks your ad. You bid against other advertisers using the same keyword, so in general, higher bids help get your ad to display in more desirable locations on the search results page. Instead of using the default ad group level bid, you can set custom bids for each keyword. Custom bids for keywords override the ad group default bid for those specific keywords. With custom bids, you can focus your time and money on the most profitable keywords but will need to spend more time on managing the individual bids. If the keyword level bid is not set, the Ad Group CpcBid is used. For more information, see Budget and Bid Strategies. Add: Optional Update: Optional. If no value is set for the update, this setting is not changed. To delete the keyword bid and use the AdGroup default match type bid, set the Amount element of the Bid object to null.
The type of match to compare the keyword and the user's search term. Add: Required Update: Optional. If no value is set for the update, this setting is not changed.
The string to use as the substitution value in an ad if the ad's title, text, display URL, or destination URL contains the {Param1} dynamic substitution string. Although you can use {Param1} to specify an ad's destination URL, you are encouraged not to. Instead, you should set the keyword's DestinationUrl element. The string can contain a maximum of 1,022 characters. The actual limit depends on the length of the element that references the substitution string. For example, the length of a text ad's title can contain a maximum of 25 characters. When implementing dynamic text in your ad copy you should provide a default string e.g. {Param1:default} that the system will use if Param1 for a keyword is null or empty, or if including the Param1 substitution value will cause the expanded string to exceed the element's limit; otherwise the ad will not serve with this keyword. For more information, see the Microsoft Advertising help article Automatically customize your ads with dynamic text parameters. Also note that if the ad group only has one ad, and if that ad uses {Param1} but does not provide a default string e.g. {Param1:default}, then you must supply a valid Param1 value for that substitution. Otherwise this keyword cannot be added or updated. Add: Optional Update: Optional. If no value is set for the update, this setting is not changed. If you set this element to an empty string (""), the previous setting will be deleted.
The string to use as the substitution value in an ad if the title, text, display URL, or destination URL contains the {Param2} dynamic substitution string. Typically, you use the {Param2} substitution string in the title or text (ad copy description) elements of an ad. The string can contain a maximum of 70 characters. The actual limit depends on the length of the element that references the substitution string. For example, the length of a text ad's title can contain a maximum of 25 characters. When implementing dynamic text in your ad copy you should provide a default string e.g. {Param2:default} that the system will use if Param2 for a keyword is null or empty, or if including the Param2 substitution value will cause the expanded string to exceed the element's limit; otherwise the ad will not serve with this keyword. For more information, see the Microsoft Advertising help article Automatically customize your ads with dynamic text parameters. Also note that if the ad group only has one ad, and if that ad uses {Param2} but does not provide a default string e.g. {Param2:default}, then you must supply a valid Param2 value for that substitution. Otherwise this keyword cannot be added or updated. Add: Optional Update: Optional. If no value is set for the update, this setting is not changed. If you set this element to an empty string (""), the previous setting will be deleted.
The string to use as the substitution value in an ad if the title, text, display URL, or destination URL contains the {Param3} dynamic substitution string. Typically, you use the {Param3} substitution string in the title or text (ad copy description) elements of an ad. The string can contain a maximum of 70 characters. The actual limit depends on the length of the element that references the substitution string. For example, the length of a text ad's title can contain a maximum of 25 characters. When implementing dynamic text in your ad copy you should provide a default string e.g. {Param3:default} that the system will use if Param3 for a keyword is null or empty, or if including the Param3 substitution value will cause the expanded string to exceed the element's limit; otherwise the ad will not serve with this keyword. For more information, see the Microsoft Advertising help article Automatically customize your ads with dynamic text parameters. Also note that if the ad group only has one ad, and if that ad uses {Param3} but does not provide a default string e.g. {Param3:default}, then you must supply a valid Param3 value for that substitution. Otherwise this keyword cannot be added or updated. Add: Optional Update: Optional. If no value is set for the update, this setting is not changed. If you set this element to an empty string (""), the previous setting will be deleted.
The keyword text. The text can contain a maximum of 100 characters. You should specify the keyword in the locale of the Language value that you specified for the ad group to which the keyword belongs. Add: Required Update: Read-only
The keyword's status. By default, the status is set to Active. Add: Optional Update: Optional. If no value is set for the update, this setting is not changed.
The editorial review status of the keyword, which indicates whether the keyword is pending review, has been approved, or has been disapproved. Add: Read-only Update: Read-only
The URL of the webpage to take the user to when they click the ad. The keyword's destination URL is used if specified; otherwise, the ad's destination URL is used. Important: As of November 2018 the keyword destination URL cannot be added or updated. You can use Final URLs instead. For more details see Migrating your keyword destination URLs to final URLs. Add: Not allowed Update: Not allowed
The tracking template to use as a default for all FinalUrls and FinalMobileUrls. The following validation rules apply to tracking templates. For more details about supported templates and parameters, see the Microsoft Advertising help article What tracking or URL parameters can I use? - Tracking templates defined for lower level entities e.g. ads override those set for higher level entities e.g. campaign. For more information, see Entity Limits. - The length of the tracking template is limited to 2,048 characters. The HTTP or HTTPS protocol string does count towards the 2,048 character limit. - The tracking template must be a well-formed URL beginning with one of the following: http://, https://, {lpurl}, or {unescapedlpurl}. - Microsoft Advertising does not validate whether custom parameters exist. If you use custom parameters in your tracking template and they do not exist, then the landing page URL will include the key and value placeholders of your custom parameters without substitution. For example, if your tracking template is https://tracker.example.com/?season={_season}&promocode={_promocode}&u={lpurl} and neither {_season} or {_promocode} are defined at the campaign, ad group, criterion, keyword, or ad level, then the landing page URL will be the same. Add: Optional Update: Optional. If no value is set for the update, this setting is not changed. If you set this element to an empty string (""), the previous setting will be deleted.
The landing page URL. The keyword's final URL is used if specified; otherwise, the ad's final URL is used. The following validation rules apply to Final URLs and Final Mobile URLs. - The length of the URL is limited to 2,048 characters. The HTTP or HTTPS protocol string does count towards the 2,048 character limit. - You may specify up to 10 items for both FinalUrls and FinalMobileUrls; however, only the first item in each list is used for delivery. The service allows up to 10 for potential forward compatibility. - Usage of '{' and '}' is only allowed to delineate tags, for example {lpurl}. - Final URLs must each be a well-formed URL starting with either http:// or https://. - If you specify FinalMobileUrls, you must also specify FinalUrls. - You may not specify FinalMobileUrls if the device preference is set to mobile. Also note that if the TrackingUrlTemplate or UrlCustomParameters elements are set, then at least one final URL is required. For more information, see URL Tracking with Upgraded URLs. Add: Optional Update: Optional. If no value is set for the update, this setting is not changed.
The mobile landing page URL. The keyword's final mobile URL is used if specified; otherwise, the ad's final mobile URL is used. Add: Optional Update: Optional. If no value is set for the update, this setting is not changed.
The bid strategy type for how you want to manage your bids. For details about supported bid strategies per campaign type, see Budget and Bid Strategies. NOTE: As of April 2021, you cannot set any bid strategies for ad groups or keywords. If you attempt to set bid strategies for ad groups or keywords, the request will be ignored without error. Ad groups and keywords will inherit their campaign's bid strategy. Add: Optional. If you do not set this element, then InheritFromParentBiddingScheme is used by default. Update: Optional. If no value is set for the update, this setting is not changed.
A list of unique system identifiers corresponding to the keywords that were added. The list of identifiers corresponds directly to the list of keywords in the request. Items of the list may be returned as null. For each list index where a keyword was not added, the corresponding element will be null.
The value of each string represents the type of bidding scheme or bid strategy type that is inherited from the parent campaign or ad group. Each string in the list is returned in the same order and corresponds to the keywords in the request message. If a keyword does not inherit from the ad group or campaign, the corresponding item in the list will be nil. This element is not returned by default. You must set ReturnInheritedBidStrategyTypes true in the request.
The list of labels to add to the account. The maximum size of the list is 100 items per service request.
The label name. The case-sensitive label name can be between 1 to 80 characters in length, and must be unique across all labels in the account. Add: Required Update: Optional. If no value is set for the update, this setting is not changed.
The label description. The label description can be between 1 to 200 characters in length. Add: Optional Update: Optional. If no value is set for the update, this setting is not changed.
The label color as a hexadecimal code. The hexadecimal value must have the '#' prefix. For example you can use the value of #FFFFFF for a white label. The color can be viewed in the Microsoft Advertising web application. Your application can display the color or utilize the hexadecimal value to categorize a set of labels. Add: Optional. If you do not specify any color, the value will be assigned at random for each label. Update: Optional. If no value is set for the update, this setting is not changed. You can update the color code but cannot remove it.
The system-generated identifier of the label. Add: Read-only Update: Required
A list of unique system identifiers corresponding to the labels that were added. The list of identifiers corresponds directly to the list of labels in the request. Items of the list may be returned as null. For each list index where a label was not added, the corresponding element will be null.
Array of LinkedIn segments to add to the specified campaign.
The negative keywords to add to the negative keyword list, or the negative sites to add to the website exclusion list. The list can contain a maximum of 5,000 items per service call.
The negative keyword list or website exclusion list. If the SharedEntityScope is either empty or set to Account, and if the SharedList is a NegativeKeywordList or AccountNegativeKeywordList, then the ListItems must be negative keyword (NegativeKeyword) objects. If the SharedEntityScope is set to Customer, and if the SharedList is a PlacementExclusionList, then the ListItems must be negative site (NegativeSite) objects.
Indicates whether the shared entity is available at the ad account (Account) or manager account (Customer) level. This element is optional and defaults to Account scope. The ad account scope is only applicable for negative keyword lists. Set this element to Customer to add negative sites to a website exclusion list in your manager account (customer) shared library.
The type of the shared list item. For more information about shared list item types, see Remarks.
A list of long values that represents the identifiers for the list items that were added. Items of the list may be returned as null. For each list index where a list item was not added, the corresponding element will be null.
The identifier of the account that owns the asset library.
An array of Media to add to the account's asset library. You can add a maximum of 10 media in a single call.
The unique Microsoft Advertising identifier of the media. Add: Read-only
The type of media to add to the media library. The recommended sub type is "GenericImage". For media that will be used with an ImageAdExtension, the supported values are GenericImage, Image16x9, Image15x10, Image4x3, and Image12x10. For media that will be used with a ResponsiveAd, the supported values are GenericImage, Image1x1, Image191x100, and Image4x1. For more information about supported aspect ratios, see the Image Data Object Remarks. Add: Required
The media type. For more information about media types, see Remarks below. Add: Read-only
The identifiers of the media that you added to the library. You use the identifier to set the appropriate media ID field in the ImageAdExtension or ResponsiveAd object. You can get the media indentifiers for image ad extensions and responsive ads with the GetMediaMetaDataByAccountId and GetMediaMetaDataByIds operations.
An array of negative keyword with associated entity such as a campaign or ad group. The specified negative keywords will be appended to any existing negative keywords if the limit of 20,000 negative keywords per associated campaign or ad group would not be exceeded. The EntityType specified within each EntityNegativeKeyword must be set to the same value. This array can contain a maximum of 1 EntityNegativeKeyword element, which contains up to 20,000 negative keywords.
The system-generated identifier of a campaign or ad group that is associated with the negative keywords.
The type of entity such as a campaign that is associated with the negative keywords. The possible values are AdGroup and Campaign.
An array of negative keywords that are associated with the corresponding campaign or ad group.
The type of the shared list item. This value is NegativeKeyword when you retrieve a negative keyword. For more information about shared list item types, see SharedListItem Data Object Remarks. Add: Read-only
The unique Microsoft Advertising identifier of the negative keyword. Add: Read-only Delete: Required
The negative keyword text. The text can contain a maximum of 100 characters. Add: Required Delete: Optional
The type of match to compare the negative keyword and the user's search term. The supported values for a negative keyword are Exact and Phrase. Add: Required Delete: Optional
An array of BatchErrorCollection objects that contain details for any negative keyword that were not successfully added. The top level error within each BatchErrorCollection object corresponds to potential campaign or ad group errors. The nested list of BatchError objects would include any errors specific to the negative keywords that you attempted to add to the campaign or ad group. The list of errors do not correspond directly to the list of items in the request. The list can be empty if there were no errors, or can include one or more error objects corresponding to each unsuccessful list item in the request.
A list of IdCollection corresponding to the negative keywords that were added for the corresponding entity. Within an IdCollection, the list of Ids corresponds directly to the list of negative keywords in the request. Items of the list may be returned as null. For each list index where a negative keyword was not added, the corresponding element will be null.
A description for the seasonality adjustment.
The percentage of the conversion rate adjustment.
Make the seasonality adjustment to these device types.
Make the seasonality adjustment to these campaign types.
Make the seasonality adjustment to these campaigns.
The negative keyword list or website exclusion list. If the SharedEntityScope is either empty or set to Account, and if the SharedEntity is a NegativeKeywordList, then the ListItems must be negative keyword (NegativeKeyword) objects. If the SharedEntityScope is set to Customer, and if the SharedEntity is a PlacementExclusionList, then the ListItems must be negative site (NegativeSite) objects.
The negative keywords (5,000 total maximum) to include with the new negative keyword list, or negative sites (10,000 total maximum) to include with the new website exclusion list. The list can contain a maximum of 5,000 items per service call. To add more list items, call the AddListItemsToSharedList operation.
Indicates whether the shared entity is available at the ad account (Account) or manager account (Customer) level. This element is optional and defaults to Account scope. The ad account scope is only applicable for negative keyword lists. Set this element to Customer to add a website exclusion list in your manager account (customer) shared library.
The identifier for the shared entity that was added.
An array of UetTag objects to add to the customer's shared UET tag library. The customer is determined by the required CustomerId header element. You can add a maximum of 100 UET tags in a single call, although please note that you can use one UET tag with all of your conversion goals and remarketing lists. Before you create multiple UET tags, see Reasons for creating more than one UET tag. If the call is successful, the tracking script that you should add to your website is included in a corresponding UetTag within the response message.
The UET tag name. The maximum length of the name is 100, and the name must be unique among all UET tags belonging to the same customer. Add: Required Update: Optional
Text to help you identify the UET tag. We recommend that you set this to the related website page name or URL. Add: Optional Update: Optional
The tracking script that you can add to your website to allow Microsoft Advertising to collect actions people take on your website. Add: Read-only Update: Read-only
If your website doesn't support JavaScript, you can use this Non-JavaScript representation of the UET tag. If you use Non-JavaScript, you can't track custom events or variable revenue. Add: Read-only Update: Read-only
The system-determined status values of a UET tag, for example the system sets the status to Unverified if the UET tag has not yet been verified. Add: Read-only Update: Read-only
Determines the list of customers that share the UET tag. Details include UET tag to audience association counts. Shared UET tags and audiences are only available for pilot customers. For an overview of sharing audiences and UET tags in a customer hierarchy, see the Share Audiences and UET Tags technical guide. Add: Optional Update: Optional. If no value is set for the update, this setting is not changed. Set this element to null or empty to retain any existing customer account shares. To remove all customer account shares, set the CustomerAccountShares element of the CustomerShare object to null or empty. To remove a subset of customer account shares, specify the customer account shares that you want to keep in the CustomerAccountShares element of the CustomerShare object.
The industry of the website associated with your UET tag. Add: Optional Update: Optional
The unique Microsoft Advertising identifier of the UET tag. Add: Read-only Update: Required and Read-only
The list of videos to add to the account. The maximum size of the list is 100 items per service request.
The description of the video asset. Add: Supported Update: Supported
The thumbnail URL of the video asset. Add: Unsupported Update: Unsupported
The original URL of the video. Note: SourceUrl must be a direct download URL. Add: Supported and Required
The URL where the video is hosted. Note: URL is reserved for internal usage. Add: Supported Update: Supported
The video's aspect ratio. Possible values are 16:9, 9:16, 4:3, 3:4, 1:1, 5:4, and 4:5.
The duration in milliseconds of the video asset. Add: Unsupported Update: Unsupported
The status of the video asset. The status can be Draft, Active, Deleted or Failed. Add: Unsupported Update: Supported
The date and time the video was created, in Coordinated Universal Time.
The date and time the video was last modified, in Coordinated Universal Time.
Read the description for each possible error code below. AssetDataInvalid: The file downloaded from the URL is not a video. VideoDownloadError: The provided URL is not accessible. AssetDataInvalidWidth: The video frame width is less than 120 pixels. AssetDataInvalidHeight: The video frame height is less than 120 pixels. InvalidDuration: The video duration is less than 6 seconds. VideoOverweight: The video file size is greater than 2 GB. VideoTranscodingError: A general failure code that represents a transcoding issue. This is controlled by Azure Media Service. Learn more about encoding video and JobErrorCode.
A list of unique system identifiers corresponding to the videos that were added. The list of identifiers corresponds directly to the list of videos in the request. Items of the list may be returned as null. For each list index where a video was not added, the corresponding element will be null.
The identifier of an entity associated with the ad extension. Add: Required Update: Required
The type of entity associated with the ad extension. Add: Required Update: Required
The ad extension associated with a supported entity. Add: Required Update: Required
The editorial status of the ad extension. Add: Read-only Update: Read-only
An array of objects that associate an ad extension and its editorial status to an account, campaign, or ad group. Add: Required Update: Required
A code that identifies the reason for the failure. For a list of possible reason codes, see Editorial Reason Codes.
The component of the ad extension that failed editorial review.
The term that failed editorial review. This element will not be set if a combination of terms caused the failure or if the failure was based on a policy violation.
The list of publisher countries or regions whose editorial guidelines do not allow the specified term.
The identifier of the ad extension that failed editorial review.
A list of AdExtensionEditorialReason objects that identify the component of an ad extension that failed editorial review, and the reason for the failure.
The identifier of an entity associated with the ad extension.
The action to be applied for the AdGroupCriterion.
The BiddableAdGroupCriterion or NegativeAdGroupCriterion, either of which must contain a ProductPartition criterion. For the Update action, only the CriterionBid and DestinationUrl elements of the AdGroupCriterion are mutable. To update the order or structure of the product group, you cannot use the update action. You must delete ad group criterions and then add new product partitions instead.
The identifier of the ad group to which the negative site URLs belong.
A list of URLs of the websites where you do not want your ads displayed. This element can include a maximum of 2,500 URLs. Each URL must specify the domain name e.g., contoso.com which can include up to three subdomains and two subdirectories. The subdomain count includes the www prefix. For example one.two.three.contoso.com/1/2, www.two.three.contoso.com/1/2, and one.two.contoso.co.uk/1/2 are valid URLs, whereas one.two.three.contoso.co.uk/1/2 (too many subdomains) and one.two.three.contoso.com/1/2/3 (too many subdirectories) are not. Duplicate URLs in the list are not added. You can only exclude websites for syndicated search websites. The ad group's network must be set to OwnedAndOperatedAndSyndicatedSearch. For more information about network distribution, see Network. Note: You can exclude Yahoo and Microsoft sites (e.g., MSN.com) from Microsoft Audience Network (MSAN) ads, but not search ads. Negative site URLs specified at the ad group level are used instead of any negative site URLs specified at the campaign level. If you associate any website exclusion lists (Placement Exclusion List or Account Placement Exclusion List) with an ad account, the list of negative sites are used in addition to the campaign negative sites or ad group negative sites. To remove ad group negative site URLs, set this element to null.
The image field for the ad recommendation.
Defines the relationship of an asset to an ad.
The ad recommendation image suggestion metadata data object.
The type of media to add to the library. The recommended media type is "GenericImage". For media that will be used with an ImageAdExtension, the supported values are GenericImage, Image16x9, Image15x10, Image4x3, and Image12x10. For media that will be used with a ResponsiveAd, the supported values are GenericImage, Image1x1, Image191x100, and Image4x1. For more information about supported aspect ratios, see the Remarks section below. Add: Required
The media type. For more information about media types, see the Media Data Object Remarks. Add: Read-only
A base64 string that represents the image or icon to add to the library. The base64 string can contain a maximum of 102,400 characters. For information about restrictions and supported data types, see Remarks below.
The text asset properties for the ad recommendation.
The image asset properties for the ad recommendation.
The customized properties for the ad recommendation.
The status of the current job. Possible values are: Completed, InProgress, Failed.
The error code when the JobStatus is Failed.
The error message when the JobStatus is Failed.
List of ad recommendation refined media.
An array of OperationError objects that contains the details that explain why the service operation failed.
The type of the criterion. This value is Age when you retrieve an age criterion. For more information about criterion types, see the Criterion Data Object Remarks. Add: Read-only Update: Read-only
The age range of the people you want to see your ads. Add: Required Update: Not allowed. If you specify this element it must match the existing setting.
A list of age ranges. To remove existing values, set AgeRanges to null or empty. To remove a subset of age ranges, specify the age ranges that you want to keep and the existing age ranges will be replaced. Add: Required Update: Optional.
The type of setting. For more information, see Setting Data Object Remarks.
The annotation group ID. The possible values are: 17000 - Dynamic Locations17001 - Consumer Ratings17002 - Dynamic Ad Enhancements 17003 - Dynamic Callouts17004 - Dynamic Partner Data enhancements17005 - Dynamic Sitelink17006 - Dynamic Structured Snippets17007 - Longer Ad Headlines17008 - Previous Visit17009 - Seller Ratings17011 - Dynamic Multimedia Extensions17013 - Syndication Only Decorations 17014 - Business Logo
This element determines whether the preference is for the ad extension to be displayed on mobile devices or all devices. To specify a preference for mobile devices, set this element to 30001. To specify all devices, set this element to 0 (zero) or leave the element nil. By default, this element will be nil. Add: Optional Update: Optional. If no value is set for the update, this setting is not changed.
The type of the ad extension. This value is AppAdExtension when you retrieve an app ad extension. Add: Read-only Update: Read-only For more information about ad extension types, see the Ad Extension Data Object Remarks.
The application platform. Possible values include iOS, Android, and Windows. Add: Required Update: Required
The application identifier provided by the app store. If the application is new, please expect to wait 4-7 days before the ad will be eligible to deliver. Add: Required Update: Required
The text displayed in the app ad extension. The text can contain a maximum of 35 characters. Add: Required Update: Optional
The URL of the app store download webpage that users are taken to when they click the app extension link. The URL can contain dynamic text strings such as {keyword}. For a list of supported parameters, see the Available parameters section within the Microsoft Advertising help article What tracking or URL parameters can I use?. The URL can contain a maximum of 1,024 characters. If the URL does not specify a protocol, the system uses the HTTP protocol when a user clicks the ad. If the URL specifies the HTTP protocol when you add an ad, the service will remove the http:// protocol string (the HTTP protocol string does not count against the 1,024 character limit); however, the service will not remove an HTTPS protocol string (https://) from the URL. Add: Required Update: Optional
The conversion goal name. The maximum length of the name is 100, and the name must be unique among all conversion goals belonging to the same customer. Add: Required Update: Optional
Defines the possible user-determined status values of a conversion goal. These are the status values that a user can decide to set, for example a goal can be set to Paused if you no longer wish to track conversions for that goal. For status values that can be set by the system, see the TrackingStatus element. Add: Optional Update: Optional
Determines if the goal applies to all accounts or only the account specified in the required CustomerAccountId header element. If you have multiple Microsoft Advertising accounts, you can track conversions across all of those accounts. If you associate a goal with one account, conversions will be tracked for that account only. For app install goals the Account level scope is not supported. You can set this element to Customer or leave it nil. If not specified, the scope will be set to Customer by default. Add: Optional Update: Optional
Determines how much each conversion is worth to your business. When adding a conversion goal if you do not specify any revenue tracking preferences, then each ConversionGoalRevenue will be set to their respective default values. When updating a conversion goal, if the Revenue element is nil or empty then none of the nested properties will be updated. However, if this element is not nil or empty then you are effectively replacing any existing revenue properties. The VariableValue option is not available for app install conversion goals. Add: Optional Update: Optional
The conversion window is the length of time in minutes after a click that you want to track conversions. If you set this value to 43200 minutes (30 days), then conversions that happen within 30 days after a click are tracked. Past conversions aren't affected. The minimum value supported is 1 minute, although keep in mind that a shorter conversion window will reduce the number of conversions your account records. The maximum value supported is 129600 minutes (90 days). Add: Optional Update: Optional
Defines the possible system-determined status values of a conversion goal. These are the status values that can be set by the system, for example the system sets the status to RecordingConversions if we have recorded conversions within the last 7 days. Only the NoRecentConversions and RecordingConversions statuses are applicable for app install conversion goals. For status values that a user can decide to set, for example setting the status to Paused if you no longer wish to track conversions for that goal, see the Status element. Add: Read-only Update: Read-only
Determines whether or not to exclude data otherwise related to this conversion goal from a subset of performance report columns. This element is only available for customers who are enabled for the Include in Conversions feature (GetCustomerPilotFeatures returns 574). If this element is set to true, data otherwise related to this conversion goal will be excluded from the Conversions, ConversionRate, CostPerConversion, ReturnOnAdSpend, RevenuePerConversion, and Revenue report columns. Also, if you use an automated bidding bid strategy, setting this property true will result in the goal's conversions no longer factoring into automated bidding calculations. Setting this property "true" is effectively the same as unchecking "Include in Conversions" in the Microsoft Advertising web application. Regardless of this element value, the AllConversions, AllConversionRate, AllCostPerConversion, AllReturnOnAdSpend, AllRevenuePerConversion, and AllRevenue report columns will include data for all conversion goals. By default this element is false, and data related to this conversion goal are included in all report columns. For more information, see Report Attributes and Performance Statistics and the help article Conversion goals: "Conversions" versus "All conversions". Add: Optional Update: Optional
The category used to segment the conversion goal. Categorize your conversion goals however makes sense for your business. Goal categories don't affect performance - they are here to help you segment your goals and their performance metrics. The supported category values vary by conversion goal type. App install goals only support the Download category. Add: Optional. If you leave this element nil or empty, the default category will be set to Download. Update: Optional. If no value is set for the update, this setting is not changed.
The unique Microsoft Advertising identifier for the conversion goal. Add: Read-only Update: Required and Read-Only
The type of the conversion goal. This value is AppInstall when you retrieve an app install goal. For more information about conversion goal types, see the ConversionGoal Data Object Remarks. Add: Read-only Update: Read-only
The application platform. Possible values include Android, iOS, Windows and WindowsPhone. Add: Required Update: Optional
The application identifier provided by the app store. Add: Required Update: Optional
A list of unique identifiers of the ads or keywords that failed editorial review. The list can contain a maximum of 1,000 EntityIdToParentIdAssociation objects. You submit each ad or keyword identifier with their respective ad group parent identifier in a EntityIdToParentIdAssociation object. The list of EntityIdToParentIdAssociation must include either ad identifiers or keyword identifiers. The list cannot include a mix ad and keyword entity identifiers. If an entity in the list has already been approved, the entity is ignored. If an entity in the list is not appealable, the call fails. If an entity in the list has an appeal pending, this request supersedes the pending request. Note: To support AssetGroups, EntityId = AssetGroupId and ParentId = CampaignId. For asset group appeals, we limit the amount of objects to 100 instead of 1,000.
The type of entity that the entity to parent list contains. The supported entity type values are Ad, AdGroup, AssetGroup, Campaign, ImageAsset, Keyword, and TextAsset.
The justification for the appeal. The string can contain a maximum of 1,000 characters. The justification applies to all of the specified entities. A useful justification should include reasons why the ad or keyword is compliant with editorial policy for example, JustificationText = "my ads for paint guns are not firearms, they are painting tools".
The system-generated unique identifier of an entity such as ad or keyword.
The identifier of the entity's parent. An ad group is the parent of an ad or keyword.
An array of BatchError objects that contain details for any appeals that were not successfully submitted. The list of errors corresponds directly to the list of EntityIdToParentIdAssociation in the request. Items of the list may be returned as null. For each list index where an appeal was successfully submitted, the corresponding error element will be null. Ideally all appeals are submitted successfully and all elements in this list are null.
The unique Microsoft Advertising identifier for the ad. Add: Read-only Update: Required and Read-only
The type of the ad. This value is AppInstall when you retrieve an app install ad. For more information about ad types, see the Ad Data Object Remarks. Add: Read-only Update: Read-only
The status of the ad. You can set the ad status to Active or Paused. Add: Optional Update: Optional
The editorial review status of the ad, which indicates whether the ad is pending review, has been approved, or has been disapproved. Add: Read-only Update: Read-only
This element determines whether the preference is for app install ads to be displayed on mobile and tablet devices or only on mobile devices. (App install ads are not currently supported on desktop computers.) To specify a preference for mobile devices only (i.e. excluding tablets), set this element to 30001. To specify a preference for both mobile and tablet devices, set this element to 0 (zero) or leave the element nil. By default, this element will be nil. Add: Optional Update: Optional
The tracking template to use as a default for the URL specified with FinalUrls. The following validation rules apply to tracking templates. For more details about supported templates and parameters, see the Microsoft Advertising help article What tracking or URL parameters can I use? - Tracking templates defined for lower level entities e.g. ads override those set for higher level entities e.g. campaign. For more information, see Entity Limits. - The length of the tracking template is limited to 2,048 characters. The HTTP or HTTPS protocol string does count towards the 2,048 character limit. - The tracking template must be a well-formed URL beginning with one of the following: http://, https://, {lpurl}, or {unescapedlpurl}. - Microsoft Advertising does not validate whether custom parameters exist. If you use custom parameters in your tracking template and they do not exist, then the landing page URL will include the key and value placeholders of your custom parameters without substitution. For example, if your tracking template is https://tracker.example.com/?season={_season}&promocode={_promocode}&u={lpurl} and neither {_season} or {_promocode} are defined at the campaign, ad group, criterion, keyword, or ad level, then the landing page URL will be the same. Add: Optional Update: Optional. If no value is set for the update, this setting is not changed. If you set this element to an empty string (""), the previous setting will be deleted.
The URL where a search user lands and can choose to install an app. Add: Required Update: Optional
The list of key and value strings for forward compatibility to avoid otherwise breaking changes when new elements are added in the current API version. There are currently not any ForwardCompatibilityMap key and value pairs that are applicable for this object.
The application platform. Possible values include iOS and Android. Add: Required Update: Optional
The application identifier provided by the app store. If the application is new, please expect to wait 4-7 days before the ad will be eligible to deliver. Add: Required Update: Optional
The title of the ad. The title must contain at least one word. The ad's copy and title combined must total at least three words. The title cannot contain dynamic text strings such as {keyword}. The maximum input length of the title is 25 characters. Note that for ad groups that use Traditional Chinese, the title is limited to 15 characters. The title cannot contain the newline (\n) character. Add: Required Update: Optional
The ad copy. The copy must contain at least one word. The ad's copy and title combined must total at least three words. The ad copy cannot contain dynamic text strings such as {keyword}. The maximum input length of the copy is 71 characters. Note that for ad groups that use Traditional Chinese, the text is limited to 38 characters. The ad copy cannot contain the newline (\n) character. Add: Required Update: Optional
The list of key and value strings for forward compatibility to avoid otherwise breaking changes when new elements are added in the current API version. Forward compatibility changes will be noted here in future releases. There are currently no forward compatibility changes for this data object.
A list of AssetGroupListingGroupAction objects that each contain an Action element and a ListingGroup element. All of the asset group listing group actions must be for the same asset group. You can pass 5,000 AssetGroupListingGroupAction per call and apply a maximum of 20,000 listing groups to each asset group.
The action to be applied for the AssetGroupListingGroup.
The AssetGroupListingGroup to apply action to. Update is not supported for listing group, To update the order or structure of the listing group, you cannot use the update action. You must delete existing listing groups and then add new listing groups instead.
The unique Microsoft Advertising identifier of the AssetGroupListingGroup. Add: Read-only Update: Read-only
The identifier of the asset group this listing group belongs to. Add: Required Update: Not supported Delete: Required
The type of listing group, e.g., Subdivision or Unit. Add: Required Update: Not supported Delete: Optional
The identifier of the parent listing group. This element must be set to null if the listing group node represents the root node of a listing group tree. Add: Required Update: Not supported Delete: Required
A condition that helps determine whether a product from the Microsoft Merchant Center store gets served as an ad. Multiple product conditions can be specified by creating a tree of AssetGroupListingGroup objects using ApplyAssetGroupListingGroupActions. For a catalog item to be served as an ad, it must meet all conditions. Add: Required Update: Not supported Delete: Optional
Set to true If you want to exclude products specified by current. Otherwise, the products will be included. Default value is false. Add: Optional Update: Not supported Delete: Optional
The path of a listing group node. Add: Read-only Update: Read-only Delete: Read-only
A list of IDs that for the listing groups that had the action applied. The list of IDs corresponds directly to the list of listing groups in the request. If any listing group action failed, then all remaining listing group actions will fail and all elements in this list will be null.
The customer list associated with the audience.
Scope defines what accounts can use this audience. If scope is set to Account, the audience can only be associated with campaigns and ad groups in one account i.e., via the ParentId. If scope is set to Customer, the audience can be associated with campaigns and ad groups in all of the customer's accounts. Add: Required Update: Optional. You can change the scope from Account to Customer, but you cannot change the scope from Customer to Account.
When you create an audience, you can specify how far back in time Microsoft Advertising should look for actions that match your audience definition. The minimum duration is 1 day and the maximum duration allowed is 390 days. You can also set the duration to -1 for no expiration. Add: Optional. If not specified, the membership duration will be set to 30 by default. Update: Optional. If no value is set for the update, this setting is not changed.
The total number of people who are active members of this audience in the Search network. This gives you an idea of how many search users you can target. The audience needs to have at least 300 people before Microsoft Advertising will use it for optimizations. This property will be nil or empty for up to 48 hours while the audience is being built, for example if you add or update the customer list membership duration. Add: Read-only Update: Read-only
The total number of people who are active members of this audience in the Audience network. This gives you an idea of how many Audience network users you can target. The audience needs to have at least 300 people before Microsoft Advertising will use it for optimizations. Add: Read-only Update: Read-only
The list of campaign types that support this audience. Supported values are Audience, DynamicSearchAds, Search, and Shopping. New campaign types might be added in the future, so you should not take any dependency on a fixed set of values. Add: Read-only Update: Read-only
Determines the list of customers and accounts that share the audience. Details include audience association counts. Shared UET tags and audiences are only available for pilot customers. For an overview of sharing audiences and UET tags in a customer hierarchy, see the Share Audiences and UET Tags technical guide. Add: Optional Update: Optional. If no value is set for the update, this setting is not changed. Set this element to null or empty to retain any existing customer account shares. To remove all customer account shares, set the CustomerAccountShares element of the CustomerShare object to null or empty. To remove a subset of customer account shares, specify the customer account shares that you want to keep in the CustomerAccountShares element of the CustomerShare object.
The Microsoft Advertising identifier of the audience. Add: Read-only Update: Required and read-only
The name of the audience. The name can contain a maximum of 128 characters. Add: Required Update: Optional. If no value is set for the update, this setting is not changed.
The description of the audience. Use a description to help you remember what audience you are targeting. The description can contain a maximum of 1,024 characters. Add: Optional Update: Optional. If no value is set for the update, this setting is not changed.
The type of the audience. This value is CustomerList when you retrieve a customer list audience. For more information about audience types, see the Audience Data Object Remarks. Add: Read-only Update: Read-only
The Microsoft Advertising identifier of the account or customer. If the Scope is set to Account, this is the account ID, and otherwise it is the customer ID. Add: Required Update: Read-only. You cannot change the parent ID.
The list of key and value strings for forward compatibility to avoid otherwise breaking changes when new elements are added in the current API version. Forward compatibility changes will be noted here in future releases. There are currently no forward compatibility changes for the Audience object.
Defines the CustomerListUserData data object. You can specify one user data type in CustomerListItemSubtype. Use CustomerListActionType to specify the action type. Note: The maximum user data for CustomerListItems is 1000.
The Microsoft Advertising assigned identifier of an audience, for example the customer list ID.
An array of customer list items. When CustomerListItemSubType is "Email", each item must be a SHA-256 hashed email address (lowercase hexadecimal string of 64 characters). For example, the email test`@contoso`.com should be hashed as a8e34c39d390c30c3ff245256c46c7076cecb7dfcfd60f7534d1037e901fad76.
The user data type of the customer list item.
The action type when uploading user data.
Optional flag to accept Customer Match terms for this request. - true: Accept terms and process customer data - false: Reject terms and return error 8003 (CustomerListTermsAndConditionsNotAccepted) - Not set: Fallback to previous behavior in which to accept terms through the Microsoft Advertising UI Add: Optional Update: Optional
A list of up to 5,000 AdGroupCriterionAction objects that each contain an Action element and a BiddableAdGroupCriterion. All of the ad group criterion actions must be for the same ad group. For more information including validation rules, please see Create a Microsoft Shopping campaign with the Campaign Management Service.
A list of identifiers that identify the criterion that had the action applied. The list of identifiers corresponds directly to the list of criterion in the request. If any criterion action failed, then all remaining criterion actions will fail, and all elements in this list will be null.
An array of BatchError objects that contain details for any request items that were not successful. The list of errors do not correspond directly to the list of items in the request. The list can be empty if there were no errors, or can include one or more error objects corresponding to each unsuccessful list item in the request. For criterion which failed due to user error, an actionable error code will be returned. If any criterion action failed, then all remaining criterion actions will fail, and none of the elements in this list will be null. For criterion that might have otherwise succeeded, a generic error will be returned which explains that a related entity failed.
The offline conversion adjustments to apply.
The MSCLKID for the offline conversion. To ensure that auto-tagging is enabled for Microsoft click ID tracking, use the GetAccountProperties and SetAccountProperties operations. Apply: Optional Note: The MSCLKID is optional when you provide a hashed email address or phone number for enhanced conversions.
The conversion goal name. This name must match an existing conversion goal name, otherwise the offline conversion goal data will not be applied. Apply: Required
The date and time when the original offline conversion occurred. The date and time must be within the last 90 days, otherwise the operation will fail when you attempt to send Microsoft Advertising the offline conversion data. To be counted by Microsoft Advertising as an offline conversion after successful upload, the following additional requirements must be met: - The date and time of the conversion must be set later than the date and time of the recorded click. - The date and time must be within the conversion window. The ConversionWindowInMinutes property of the OfflineConversionGoal determines the maximum length of time in minutes after a click that conversions will be tracked. For example if three clicks were recorded on April 30th, if the ConversionWindowInMinutes of the OfflineConversionGoal is equal to 30 days (43200 minutes), and if you send Microsoft Advertising the following offline conversions on July 31st, then Microsoft Advertising will only count the one with MicrosoftClickId=2 as an offline conversion. - MicrosoftClickId=1; ConversionTime=2020-04-30T17:02:35.6853793Z - MicrosoftClickId=2; ConversionTime=2020-05-15T17:02:35.6853793Z - MicrosoftClickId=3; ConversionTime=2020-06-15T17:02:35.6853793Z The offline conversion data with MicrosoftClickId=1 will not be uploaded since the conversion date and time is more than 90 days ago, and the offline conversion data with MicrosoftClickId=3 will not be counted because it does not fall within the conversion window (April 30 through May 29). Important: The value must be in Coordinated Universal Time (UTC). This differs from the time zone options when you upload offline conversions in the Microsoft Advertising web application. For information about the format of the date and time, see the dateTime entry in Primitive XML Data Types. Apply: Required
The date and time when the adjustment occurred. The adjustment time cannot be earlier than the original offline conversion date and time. Important: The value must be in Coordinated Universal Time (UTC). This differs from the time zone options when you upload offline conversions in the Microsoft Advertising web application. For information about the format of the date and time, see the dateTime entry in Primitive XML Data Types. Apply: Required
Determines whether to retract or restate the offline conversion. If this value is "Restate", the offline conversion previously attributed to the specified MicrosoftClickId will be adjusted according to the new AdjustmentCurrencyCode, AdjustmentTime, and AdjustmentValue. If this value is "Retract", the offline conversion previously attributed to the specified MicrosoftClickId will be retracted or deleted. Apply: Required
The adjusted offline conversion value. Apply: Required if AdjustmentType is set to "Restate", and otherwise this field should not be set.
The currency code for the restated offline conversion. For more information, see Currencies. Apply: Required if AdjustmentType is set to "Restate", and otherwise this field is ignored. If you do not specify an adjustment currency code with the restatement, then the CurrencyCode element of the goal's ConversionGoalRevenue is used.
The hashed email address using the SHA-256 algorithm for use with enhanced conversions.
The hashed phone number according to the E.164 standard for use with enhanced conversions.
The list of offline conversions for the account. You can add a maximum of 1,000 offline conversions per service request. Each offline conversion can be split across multiple click IDs. A single click ID can, however, be associated with multiple conversion goals and also be associated with the same goal multiple times, as long as the conversion time is different. Also, the same conversion can't be applied more than once. If you send Microsoft Advertising duplicates, the first instance will be used and the others will be ignored.
The date and time when the offline conversion occurred. The date and time must be within the last 90 days, otherwise the operation will fail when you attempt to send Microsoft Advertising the offline conversion data. To be counted by Microsoft Advertising as an offline conversion after successful upload, the following additional requirements must be met: - The date and time of the conversion must be set later than the date and time of the recorded click. - The date and time must be within the conversion window. The ConversionWindowInMinutes property of the OfflineConversionGoal determines the maximum length of time in minutes after a click that conversions will be tracked. For example if three clicks were recorded on April 30th, if the ConversionWindowInMinutes of the OfflineConversionGoal is equal to 30 days (43200 minutes), and if you send Microsoft Advertising the following offline conversions on July 31st, then Microsoft Advertising will only count the one with MicrosoftClickId=2 as an offline conversion. - MicrosoftClickId=1; ConversionTime=2020-04-30T17:02:35.6853793Z - MicrosoftClickId=2; ConversionTime=2020-05-15T17:02:35.6853793Z - MicrosoftClickId=3; ConversionTime=2020-06-15T17:02:35.6853793Z The offline conversion data with MicrosoftClickId=1 will not be uploaded since the conversion date and time is more than 90 days ago, and the offline conversion data with MicrosoftClickId=3 will not be counted because it does not fall within the conversion window (April 30 through May 29). Important: The value must be in Coordinated Universal Time (UTC). This differs from the time zone options when you upload offline conversions in the Microsoft Advertising web application. For information about the format of the date and time, see the dateTime entry in Primitive XML Data Types. Apply: Required
The offline conversion value. Apply: Optional. If you do not specify an offline conversion value, then the Value element of the goal's ConversionGoalRevenue is used.
The currency code for the offline conversion. For more information, see Currencies. Apply: Optional. If you do not specify an offline conversion currency code, then the CurrencyCode element of the goal's ConversionGoalRevenue is used.
This field can only be set for conversions actions which use external attribution. It represents the fraction of the conversion that is attributed to each click. Its value must be greater than 0 and less than or equal to 1. A GoalNotEligibleForExternalAttribution error will be returned if this field is used with a non-externally attributed conversion action. Apply: Optional
This field can only be set for conversions actions which use external attribution. It specifies the attribution model name. A GoalNotEligibleForExternalAttribution error will be returned if this field is used with a non-externally attributed conversion action. Apply: Optional
The online conversion adjustments to apply.
The conversion goal name. This name must match an existing conversion goal name, otherwise the online conversion goal data will not be applied. Apply: Required
Determines whether to retract or restate the online conversion. If this value is "Restate", the offline conversion previously attributed to the specified MicrosoftClickId will be adjusted according to the new AdjustmentCurrencyCode, AdjustmentTime, and AdjustmentValue. If this value is "Retract", the offline conversion previously attributed to the specified MicrosoftClickId will be retracted or deleted. Apply: Required
The adjusted online conversion value. Apply: Required if AdjustmentType is set to "Restate", and otherwise this field should not be set.
The currency code for the restated online conversion. For more information, see Currencies. Apply: Required if AdjustmentType is set to "Restate", and otherwise this field is ignored. If you do not specify an adjustment currency code with the restatement, then the CurrencyCode element of the goal's ConversionGoalRevenue is used.
A list of up to 5,000 AdGroupCriterionAction objects that each contain an Action element and either a BiddableAdGroupCriterion or NegativeAdGroupCriterion. All of the ad group criterion actions must be for the same ad group. For more information including validation rules, please see Create a Microsoft Shopping campaign with the Campaign Management Service.
The app store where the app is distributed.
The unique identifier of the mobile app.
The component of the asset group that failed editorial review.
The identifier of the asset group that failed editorial review.
The identifier of the associated campaign.
A list of AssetGroupEditorialReason objects that identify the component of an asset group that failed editorial review, and the reason for the failure.
A value that determines whether you can appeal the issues found by the editorial review.
The type of the criterion. This value is Audience when you retrieve an audience criterion. For more information about criterion types, see the Criterion Data Object Remarks. Add: Read-only Update: Read-only
The Microsoft Advertising identifier of the Audience. Add: Required Update: Read-only. You must leave this element null or the audience must already be associated with the specified entity. To associate a different audience with the entity, you must add a new audience criterion and optionally delete any existing audience criteria.
The audience type. Add: Read-only Update: Read-only
The type of audience. Add: Read-only Update: Read-only
A list of audiences. The supported audience types are: - CombinedList - CustomAudience - InMarketAudience - ProductAudience - RemarketingList - SimilarRemarketingList - CustomerList There is a maximum of 2,000 audiences in an AudienceDimension. Add: Required Update: Optional. To remove existing values, set it to null or empty; to remove a subset of audience segments, specify the audience segments that you want to keep and it will replace the existing audience segments.
The ID of the asset group. Set: Required Delete: Required
The ID of the audience group. Set: Required Delete: Required
The type of setting. This value is BaseDomainSetting when you retrieve the setting. For more information, see Setting Data Object Remarks. Add: Read-only Update: Read-only
The fundamental part of the URL (e.g., contoso.com). Note: BaseDomain is initially set automatically, you can't set it. Add: Read only. Update: Read only.
The identifier of the ad group to apply the criterion to. Add: Required Update: Required
A status value that determines whether the criterion applies for the ad group. For most biddable ad group criterions the only supported status value is Active. For exceptions, see Webpage Usage below. Add: Read-only Update: Read-only
The criterion to apply to the ad group. The criterion helps determine whether ads in the ad group are served. For a list of available criterion types, see AdGroupCriterionType. Add: Optional Update: Optional. If no value is set for the update, this setting is not changed.
The unique Microsoft Advertising identifier for the ad group criterion. Add: Read-only Update: Required
The type of the ad group criterion. This value is BiddableAdGroupCriterion when you retrieve a biddable ad group criterion. For more information about ad group criterion types, see the AdGroupCriterion Data Object Remarks. Add: Read-only Update: Read-only
The bid to use in the auction. If the inherited Criterion is a Webpage criterion, then you must use a FixedBid. If the inherited Criterion is a ProductPartition, then you must use a FixedBid unless the Sponsored Products BidOption is set to BidBoost (for details see ProductPartition Usage below). For all other biddable ad group criterions use the BidMultiplier. If you do not use the correct object type, then your requested bid will be ignored: If the bid is required, the operation will fail; If the bid is optional, the default bid will be used. Add: Requirements vary depending on the inherited Criterion type. The bid is optional and will be set to the default of 0 if not included for AgeCriterion, DayTimeCriterion, DeviceCriterion, GenderCriterion, LocationCriterion, ProfileCriterion, RadiusCriterion, AudienceCriterion, and Webpage criterions. The bid is not applicable for LocationIntentCriterion (The service will not return any error and the bid will be ignored even if you include it). When you add a ProductPartition with the ApplyProductPartitionActions operation the bid is required unless the product partition type is Subdivision, in which case the bid is not allowed. Update: Requirements vary depending on the inherited Criterion type. The bid is required for AgeCriterion, DayTimeCriterion, DeviceCriterion, GenderCriterion, LocationCriterion, ProfileCriterion, and RadiusCriterion. The bid is not applicable for LocationIntentCriterion (The service will not return any error and the bid will be ignored even if you include it). For AudienceCriterion and Webpage criterions the bid is optional, and If no value is set for the update, this setting is not changed. When you update a ProductPartition with the ApplyProductPartitionActions operation the bid is optional, and If no value is set for the update, this setting is not changed.
The URL of the webpage that the user is taken to when they click the ad. This element is only used if the inherited Criterion is a ProductPartition criterion. For details see ProductPartition Usage below.
Tracking templates are where you can specify URL tracking parameters that are used in tandem with your final URL or landing page. We recommend that you add the tracking template at the account level and then it will be applied to all URLs for lower level entities such as campaigns, ad groups, and ads. To learn more, see the Microsoft Advertising help articles URL Tracking with Upgraded URLs. This element is only used if the inherited Criterion is either a ProductPartition or Webpage criterion. For details see ProductPartition Usage and Webpage Usage below.
The final URL suffix can include tracking parameters that will be appended to the end of your landing page URL. We recommend placing tracking parameters that your landing page requires in a final URL suffix so that your customers are always sent to your landing page. For more details and validation rules see Final URL Suffix in the technical guides. This element is only used if the inherited Criterion is either a ProductPartition or Webpage criterion. For details see ProductPartition Usage and Webpage Usage below.
Your custom collection of key and value parameters for URL tracking. This element is only used if the inherited Criterion is either a ProductPartition or Webpage criterion. For details see ProductPartition Usage and Webpage Usage below.
Defines the CriterionCashback data object.
The identifier of the campaign to apply the criterion to. Add: Required Update: Required
The criterion to apply to the campaign. The criterion helps determine whether ads in the campaign are served. For a list of available criterion types, see CampaignCriterionType. Add: Required Update: Optional. If no value is set for the update, this setting is not changed.
A status value that determines whether the criterion applies for the campaign. Currently the only supported status for biddable campaign criterions is Active. Add: Read-only Update: Read-only
The unique Microsoft Advertising identifier for the campaign criterion. Add: Read-only Update: Required
The type of the campaign criterion. This value is BiddableCampaignCriterion when you retrieve a biddable campaign criterion. For more information about campaign criterion types, see the CampaignCriterion Data Object Remarks. Add: Read-only Update: Read-only
The bid to use in the auction. If the inherited Criterion is a ProductScope criterion, then you can use a FixedBid. For all other biddable campaign criterions use the BidMultiplier. If you do not use the correct object type, then your requested bid will be ignored: If the bid is required, the operation will fail; If the bid is optional, the default bid will be used. Add: Requirements vary depending on the inherited Criterion type. The bid is optional and will be set to the default of 0 if not included for AgeCriterion, DayTimeCriterion, DeviceCriterion, GenderCriterion, LocationCriterion, ProfileCriterion, and RadiusCriterion. The bid is not applicable for LocationIntentCriterion and ProductScope (The service will not return any error and the bid will be ignored even if you include it). Update: Requirements vary depending on the inherited Criterion type. The bid is required for AgeCriterion, DayTimeCriterion, DeviceCriterion, GenderCriterion, LocationCriterion, ProfileCriterion, and RadiusCriterion. The bid is not applicable for LocationIntentCriterion and ProductScope (The service will not return any error and the bid will be ignored even if you include it).
The type of the criterion bid. This value is BidMultiplier when you retrieve a bid multiplier. For more information about criterion types, see the CriterionBid Data Object Remarks. Add: Read-only Update: Read-only
The percentage amount that you want to adjust the bid for the corresponding criterion. If the campaign uses MaxClicks, MaxConversions, TargetCpa, or TargetRoas bid strategy types, then the multiplier will inform rather than directly modify or override the automated bid. For most criterion types the valid bid multiplier range is -90 through 900. For exceptions, see DeviceCriterion Usage and LocationIntentCriterion Usage below. Although this element supports a double data type, you should use whole integer values i.e., -90 through 900, for parity with the web application. Add: Required Update: Required
The unique identifier for the Microsoft Merchant Center store.
Defines the name of the store as defined in the Microsoft Merchant Center.
Value will be true if the store is active, and otherwise the value is false.
Value will be true if the store has a catalog of items, and otherwise the value is false.
The Microsoft Merchant Center store sub type. This element is only applicable for Microsoft Merchant Center stores that support Shopping Campaigns for Brands, and will be nil for all other stores. If the subtype is set to CoOp, then you have linked from a partner's store via Shopping Campaigns for Brands. When your partner retrieves the same store via GetBMCStoresByCustomerId the subtype would be nil, since from their perspective the store is not restricted to Shopping Campaigns for Brands. If the subtype is set to GlobalStore, then it is the global store to use for all Shopping Campaigns for Brands under the current manager account.
The store's destination URL. The destination URL is the web page where people are directed to when they click your ad.
The type of the ad extension. This value is CallAdExtension when you retrieve a call ad extension. Add: Read-only Update: Read-only For more information about ad extension types, see the Ad Extension Data Object Remarks.
The clickable phone number to include in the ad. The phone number can contain a maximum of 35 characters and must be valid for the specified country or region. If the campaign includes call and location ad extensions, this phone number will override the phone number specified in the location ad extensions. Note that the phone number may be reformatted. For example, if you set phone number to 4255551212, it would be reformatted to (425) 555-1212. Add: Required Update: Required
The country code where the phone number is registered. The country code must contain a 2 character country code. The supported country code values include AR, AT, AU, BR, CA, CH, CL, CO, DE, DK, ES, FI, FR, GB, HK, ID, IE, IN, IT, MX, MY, NL, NZ, NO, PE, PH, SE, SG, TH, TW, US, VE, and VN. Add: Required Update: Required
The option to show both your phone number and website, or just your phone number, to people seeing your ads on a smartphone. You might want to show only your phone number if your business requires that you talk to each customer. Set this property to true if you want the ad extension to only show the phone number without a link to your website, and otherwise if you want the ad extension include a link to your website in addition to the phone number set it to false. Add: Optional. If you do not specify this element or leave it empty, the default value of false will be set and the ad extension will include a link to your website in addition to the phone number. Update: Optional
Determines whether call tracking is enabled for the call ad extension. Call tracking is only supported in the United States and United Kingdom. Set this property to true to enable call tracking, and otherwise set it to false. Add: Optional. If you do not specify this element or leave it empty, the default value of false will be set. Update: Optional
You can either use your own phone number or use a Microsoft Advertising forwarding phone number. A Microsoft Advertising forwarding phone number is a unique phone number that is routed to your business phone number. With a Microsoft Advertising forwarding number, you can track all calls from your ad so that you can analyze the ad's performance. This element determines whether a toll-free Microsoft Advertising forwarding phone number should be created for call tracking. This element can only be set if IsCallTrackingEnabled is also true. Prior to August 2017, clients could set this property to true if a Microsoft Advertising forwarding phone number should be created for call tracking. Since August 2017, clients can no longer create a new toll-free Microsoft Advertising forwarding phone number. If you set this value true then the operation will succeed; however, a toll-free number will not be created and when you retrieve the call ad extension this property will be set to false. If a toll-free forwarding number was provisioned prior to August 2017 then this property will be true if the number is still active when you retrieve the call ad extension. Add: Optional. If you do not specify this element or leave it empty, the default value of false will be set. Update: Optional
The type of the ad extension. This value is CalloutAdExtension when you retrieve a callout ad extension. Add: Read-only Update: Read-only For more information about ad extension types, see the Ad Extension Data Object Remarks.
Additional callout text about your business, products, or services to include in a text ad. The callout extension text must be different than the text of your ad. The length of this string must be between 1 and 25 characters. Note that for Traditional Chinese characters, the length of this string must be between 1 and 12 characters. Add: Required Update: Required
The type of setting. This value is CallToActionSetting when you retrieve the setting. For more information, see Setting Data Object Remarks. Add: Read-only Update: Read-only
Determines whether to opt out of automatic selection of call to action ad asset for the multimedia ads in the campaign. When opted in, we will use artificial intelligence during ad delivery to choose the call to action asset and ignore the ad's call to action setting. Note: Not everyone has this feature yet. If you don't, don't worry - it's coming soon! Add: Optional. The default value of false will be set if not otherwise specified. Update: Optional. If no value is set for the update, this setting is not changed.
Determines whether to opt out of call to action ad asset for the audience ads in the campaign. Add: Optional. The default value of false will be set if not otherwise specified. Update: Optional. If no value is set for the update, this setting is not changed.
The identifier of the campaign to which the negative site URLs belong.
A list of URLs of the websites where you do not want your ads displayed. This element can include a maximum of 2,500 URLs. Each URL must specify the domain name e.g., contoso.com which can include up to three subdomains and two subdirectories. The subdomain count includes the www prefix. For example one.two.three.contoso.com/1/2, www.two.three.contoso.com/1/2, and one.two.contoso.co.uk/1/2 are valid URLs, whereas one.two.three.contoso.co.uk/1/2 (too many subdomains) and one.two.three.contoso.com/1/2/3 (too many subdirectories) are not. Duplicate URLs in the list are not added. You can only exclude websites for syndicated search websites. The ad group's network must be set to OwnedAndOperatedAndSyndicatedSearch. For more information about network distribution, see Network. Negative site URLs specified at the ad group level are used instead of any negative site URLs specified at the campaign level. If you associate any website exclusion lists (Placement Exclusion List or Account Placement Exclusion List) with an ad account, the list of negative sites are used in addition to the campaign negative sites or ad group negative sites. To remove campaign negative site URLs, set this element to null.
This element is not supported for combined list audiences. Add: Not supported Update: Not supported
The total number of people who are active members of this audience in the Search network. This gives you an idea of how many search users you can target. The audience needs to have at least 300 people before Microsoft Advertising will use it for optimizations. This property will be nil or empty for up to 24 hours while the audience is being built, for example if you add or update the combined list membership duration, rule, or tag identifier. This property will be nil or empty if the UET tag associated with the combined list has a status of Unverified or Inactive, because the combined list can't receive the customer information from your website that it needs to build the list. Add: Read-only Update: Read-only
The type of the audience. This value is CombinedList when you retrieve a combined list audience. For more information about audience types, see the Audience Data Object Remarks. Add: Read-only Update: Read-only
Logical conditions used to determine who to add to your combined list. Each list can include up to 100 combination rules or sets of logical conditions, and each CombinationRule can contain up to 100 audience IDs. For details, please see the CombinationRule Remarks. Add: Required Update: Required. If you want to keep any of the previous rules, then you must explicitly set them again during update.
The company name profile identifier that you can use with ProfileCriterion.
The full https path for the company's logo image.
The company name profile status. Possible status values include Active and Inactive.
The type of the setting. This value is CoOp when you retrieve a CoOp setting. For more information about setting types, see the Setting Data Object Remarks. Add: Read-only Update: Read-only
Determines whether or not to amplify your partner's bid. A bid value ad group allows you to bid on products that your merchandising partner doesn't target. If this element is set to BidValue, the auction will use use a FixedBid for product groups that have a CriterionBid. A bid boost allows you to amplify your partner's bid. If this element is set to BidBoost, the auction will use use a BidMultiplier for product groups that have a CriterionBid. You should only use BidBoost if your partner uses BidValue. Add: If this element is not set, the default bid option is BidValue. Update: Read-only. If you attempt to change the previous bid option an error will be returned.
The default bid boost percentage that you'll see in the Microsoft Advertising web application for new product groups. This ad group level target setting is not used directly in the auction. The product group bids are used to boost your partner's bid. Add: Required if the BidOption is set to BidBoost, and otherwise you may not set this element. Update: Required if the BidOption is set to BidBoost, and otherwise you may not set this element.
The fixed bid maximum. Add: Required if the BidOption is set to BidBoost, and otherwise you may not set this element. Update: Optional if the BidOption is set to BidBoost, and otherwise you may not set this element.
The type of the bidding scheme. This value is CostPerSaleBiddingScheme when you retrieve a cost per sale bidding scheme. For more information about bidding scheme types, see the BiddingScheme Data Object Remarks. Add: Read-only Update: Read-only
The target cost per sale that you want used by Microsoft Advertising to maximize conversions.
An array of URLs of the web pages used to create recommended ad assets.
Optional description of the product or service that you want to target with the specific campaign.
Optional tone for recommended text assets
Additional fields for the latest features of create asset group recommendation.
An asset group object containing recommended text assets.
An array of images recommended to be included in the asset group.
Whether the brand is detected in the request prompt.
Optional: The ad sub type used to create a recommendation.
Optional: Description of the product or service that you want to target with the specific campaign.
Optional: Tone for recommended text assets.
Optional: The identifier of the brand kit.
Additional fields for the latest features of create responsive ad recommendation.
A responsive ad object containing recommended text assets.
An array of images recommended to be included in the responsive ad.
An array of videos recommended to be included in the responsive ad.
The job information for the video recommendation job.
The unique Microsoft Advertising identifier of the ad. Add: Read-only Update: Required and Read-Only
The type of the ad. This value is ResponsiveAd when you retrieve a responsive ad. For more information about ad types, see the Ad Data Object Remarks. Add: Read-only Update: Read-only
The tracking template to use as a default for all landing page URLs. The following validation rules apply to tracking templates. For more details about supported templates and parameters, see the Microsoft Advertising help article What tracking or URL parameters can I use? - Tracking templates defined for lower level entities e.g. ads override those set for higher level entities e.g. campaign. For more information, see Entity Limits. - The length of the tracking template is limited to 2,048 characters. The HTTP or HTTPS protocol string does count towards the 2,048 character limit. - The tracking template must be a well-formed URL beginning with one of the following: http://, https://, {lpurl}, or {unescapedlpurl}. - Microsoft Advertising does not validate whether custom parameters exist. If you use custom parameters in your tracking template and they do not exist, then the landing page URL will include the key and value placeholders of your custom parameters without substitution. For example, if your tracking template is https://tracker.example.com/?season={_season}&promocode={_promocode}&u={lpurl} and neither {_season} or {_promocode} are defined at the campaign, ad group, criterion, keyword, or ad level, then the landing page URL will be the same. Add: Optional Update: Optional. If no value is set for the update, this setting is not changed. If you set this element to an empty string (""), the previous setting will be deleted.
The landing page URL. The domain portion of the URL in combination with the path 1 and path 2 strings cannot exceed 67 characters. The following validation rules apply to Final URLs and Final Mobile URLs. - The length of the URL is limited to 2,048 characters. The HTTP or HTTPS protocol string does count towards the 2,048 character limit. - You may specify up to 10 items for both FinalUrls and FinalMobileUrls; however, only the first item in each list is used for delivery. The service allows up to 10 for potential forward compatibility. - Usage of '{' and '}' is only allowed to delineate tags, for example {lpurl}. - Final URLs must each be a well-formed URL starting with either http:// or https://. - If you specify FinalMobileUrls, you must also specify FinalUrls. - You may not specify FinalMobileUrls if the device preference is set to mobile. Also note that if this ad's TrackingUrlTemplate or UrlCustomParameters element are set, then at least one final URL is required. This URL is used only if the keyword does not specify a final URL. Add: Required Update: Optional
The mobile landing page URL. The following validation rules apply to Final URLs and Final Mobile URLs. - The length of the URL is limited to 2,048 characters. The HTTP or HTTPS protocol string does count towards the 2,048 character limit. - You may specify up to 10 items for both FinalUrls and FinalMobileUrls; however, only the first item in each list is used for delivery. The service allows up to 10 for potential forward compatibility. - Usage of '{' and '}' is only allowed to delineate tags, for example {lpurl}. - Final URLs must each be a well-formed URL starting with either http:// or https://. - If you specify FinalMobileUrls, you must also specify FinalUrls. - You may not specify FinalMobileUrls if the device preference is set to mobile. This URL is used only if the keyword does not specify a final mobile URL. Add: Optional Update: Optional. If no value is set for the update, this setting is not changed. If you set this element to an empty list, the previous setting will be deleted.
Headlines are the most prominent text that appears in your ad, so you should make the most out of the available characters. We require multiple headlines so the ad can flexibly display across a variety of publishers and placements. The length of the string is limited to 30 characters. Add: Required for video ads. Not applicable for multimedia ads and audience ads. Update: Optional. Deprecated for multimedia and audience ads. Use Headlines instead.
Headlines are the most prominent text that appears in your ad, so you should make the most out of the available characters. We require multiple headlines so the ad can flexibly display across a variety of publishers and placements. The length of the string is limited to 90 characters. Add: Optional. Ignored when LongHeadlines is provided. We will fill in LongHeadlines with LongHeadlineString if LongHeadlines is empty. Not applicable for multimedia ads. Update: Optional. If no value is set for the update, this setting is not changed.
This text will appear below or adjacent to your ad's long or short headline, depending on the ad placement. You have more character space to work with in the ad text than in the headline. So once the imagery and headline have a potential customer's attention, the ad text needs to convince them to click it. What sets your product or service apart? The text must contain at least one word. The length of the string is limited to 90 characters. The text cannot contain the newline (\n) character. Add: Required for video ads. Not applicable for multimedia ads and audience ads. Update: Optional for video ads. Use Descriptions instead for audience ads or multimedia ads (deprecated).
The name of the business. Your business's name may appear in your ad, depending on the ad placement. The length of the string is limited to 25 characters. Add: Required Update: Optional. If no value is set for the update, this setting is not changed.
A brief, punchy reason for customers to click your ad right now. This is displayed on your call to action button. Add: Not applicable for audience ads; Required for multimedia ads Update: Optional. If no value is set for the update, this setting is not changed.
The language that the call to action will be served in. The call to action will always be served in this language, regardless of the campaign's language settings. Add: Not applicable for audience ads; Required for multimedia ads Update: Optional. If no value is set for the update, this setting is not changed.
Image assets with different sizes and aspect ratios so they can flexibly display across a variety of publishers and placements. Include one or more AssetLink objects that each contain an ImageAsset with SubType and crop settings that match the desired aspect ratio. For more information see the remarks below. Add: Required Update: Optional. If no value is set for the update, this setting is not changed. If you include images during update, any previously set images will be replaced.
Video assets with different sizes and aspect ratios so they can flexibly display across a variety of publishers and placements. Include one or more AssetLink objects that each contain a VideoAsset with a SubType. Add: Required for video ads Update: Optional. If no value is set for the update, this setting is not changed. If you include videos during an update, any previously set videos will be replaced.
Headlines are the most prominent text that appears in your ad, so you should make the most out of the available characters. We require multiple headlines so the ad can flexibly display across a variety of publishers and placements. Unless you pin one of the headlines to a specific position, Bing will optimize the ad layout dynamically with the best headlines and descriptions for the user's search query. From a data model perspective the desriptions and headlines are each stored as text assets i.e., one TextAsset per AssetLink. The same asset can be used by multiple ads. For example if "Seamless Integration" is a text asset, it will have the same asset identifier across all ads in the same Microsoft Advertising account. You must set between 1-15 headlines. Each headline's Text must contain at least one word. For efficient use of resources we recommend that you use dynamic text strings such as {keyword} instead of creating new ad copy for each keyword. For more information, see the Microsoft Advertising help article Automatically customize your ads with dynamic text parameters. The maximum input length of each headline's Text is 1,000 characters including dynamic text strings, and of those 1,000 no more than 30 final characters are allowed after substitution. The ad will fail to display or default text will be used if the length exceeds 30 characters after dynamic text substitution occurs. For languages with double-width characters e.g. Traditional Chinese the maximum input length is 500 characters including dynamic text strings, and of those 500 no more than 15 final characters are allowed after substitution. The ad will fail to display or default text will be used if the length exceeds 15 characters after dynamic text substitution occurs. The double-width characters are determined by the characters you use instead of the character set of the campaign or ad group language settings. Double-width characters include Korean, Japanese and Chinese languages characters as well as Emojis. The Text cannot contain the newline (\n) character. Add: Required for multimedia ads and audience ads. Not applicable for video ads. Update: Optional. To retain all of the existing asset links, set or leave this element nil. If you set this element, any headlines that were previously linked to this ad will be replaced.
For Audience campaigns, LongHeadline is the longer of two possible responsive ad headlines.
You must set between 1-5 long headlines. Each headline's Text must contain at least one word. The Text cannot contain the newline (\n) character. If the parent campaign associates to a store and you specify LongHeadlines, you must also specify Headlines, Descriptions, and Images. Add: Optional if the parent campaign associates to a store, required if its parent campaign does not associate to a store. Will use LongHeadlineString if empty. Update: Optional. To retain all of the existing asset links, set or leave this element nil. If you set a value for this element, any headlines that were previously linked to this asset group will be replaced. If the parent campaign associates to a store and you set this element to an empty list, the previous setting will be deleted.
The descriptions that are shown below the path in your ad. To maximize impressions across all ad formats, the descriptions might not always be shown in your ad. To maximize impressions across all ad formats the descriptions might not always be shown in your ad. Unless you pin one of the descriptions to a specific position, Bing will optimize the ad layout dynamically with the best headlines and descriptions for the user's search query. From a data model perspective the desriptions and headlines are each stored as text assets i.e., one TextAsset per AssetLink. The same asset can be used by multiple ads. For example if "Seamless Integration" is a text asset, it will have the same asset identifier across all ads in the same Microsoft Advertising account. You must set between 1-5 descriptions. Each description's Text must contain at least one word. For efficient use of resources we recommend that you use dynamic text strings such as {keyword} instead of creating new ad copy for each keyword. For more information, see the Microsoft Advertising help article Automatically customize your ads with dynamic text parameters. The maximum input length of each description's Text is 1,000 characters including dynamic text strings, and of those 1,000 no more than 90 final characters are allowed after substitution. The ad will fail to display or default text will be used if the length exceeds 90 characters after dynamic text substitution occurs. For languages with double-width characters e.g. Traditional Chinese the maximum input length is 500 characters including dynamic text strings, and of those 500 no more than 45 final characters are allowed after substitution. The ad will fail to display or default text will be used if the length exceeds 45 characters after dynamic text substitution occurs. The double-width characters are determined by the characters you use instead of the character set of the campaign or ad group language settings. Double-width characters include Korean, Japanese and Chinese languages characters as well as Emojis. The Text cannot contain the newline (\n) character. Add: Required for multimedia ads and audience ads. Not applicable for video ads. Update: Optional. To retain all of the existing asset links, set or leave this element nil. If you set this element, any descriptions that were previously linked to this ad will be replaced.
The URLs for 1x1 impression tracking pixels. Each pixel will report Microsoft Audience Network impressions to your third-party ad reporting tool. You can include up to 2 impression tracking URLs for each responsive ad. Each URL must be accessible. The length of the URL is limited to 2,048 characters. The HTTP or HTTPS protocol string does count towards the 2,048 character limit. For each Microsoft Audience Network impression, Microsoft will ping the URL to enable impression tracking in your third party ad reporting tool. Advanced-level user tracking such as conversion tracking or tracking based on cookies or IP addresses is not supported. This element is not returned by default. To get this element, include the ImpressionTrackingUrls value in the ReturnAdditionalFields element when you call the GetAdsByAdGroupId, GetAdsByEditorialStatus, and GetAdsByIds service operations. Add: Optional Update: Optional. If no value is set for the update, this setting is not changed. To remove impression tracking URLs set this element to an empty string array.
VerifiedTrackingSetting relates third-party measurement settings. This allows you to track viewability, brand safety, and invalid traffic metrics via a third-party verification provider, such as Integral Ad Science. This feature is available for native, display, and online video ads using the CPM bid strategy. Note: Currently, IAS is the only supported vendor (vendorName), but other verification providers are coming soon. The example below pertains to IAS. There are 3 key-value pairs for IAS:"vendorName""advertiserEntityID" (client ID for your verification provider)"publisherEntityID" (reporting ID for your verification provider)Example (required for IAS): vendorName : "IAS"advertiserEntityID : "12345678"publisherEntityID : "12345678"
A responsive search ad object containing recommended text assets.
The type of the ad. This value is ResponsiveSearch when you retrieve a responsive search ad. For more information about ad types, see the Ad Data Object Remarks. Add: Read-only Update: Read-only
The mobile landing page URL. The following validation rules apply to Final URLs and Final Mobile URLs. - The length of the URL is limited to 2,048 characters. The HTTP or HTTPS protocol string does count towards the 2,048 character limit. - You may specify up to 10 items for both FinalUrls and FinalMobileUrls; however, only the first item in each list is used for delivery. The service allows up to 10 for potential forward compatibility. - Usage of '{' and '}' is only allowed to delineate tags, for example {lpurl}. - Final URLs must each be a well-formed URL starting with either http:// or https://. - If you specify FinalMobileUrls, you must also specify FinalUrls. - You may not specify FinalMobileUrls if the device preference is set to mobile. This URL is used only if the keyword does not specify a final mobile URL. Add: Optional Update: Optional
The list of ad titles that Bing can use to optimize the ad layout. Unless you pin one of the headlines to a specific position, Bing will optimize the ad layout dynamically with the best headlines and descriptions for the user's search query. From a data model perspective the desriptions and headlines are each stored as text assets i.e., one TextAsset per AssetLink. The same asset can be used by multiple ads. For example if "Seamless Integration" is a text asset, it will have the same asset identifier across all ads in the same Microsoft Advertising account. You must set between 3-15 headlines. Each headline's Text must contain at least one word. For efficient use of resources we recommend that you use dynamic text strings such as {keyword} instead of creating new ad copy for each keyword. For more information, see the Microsoft Advertising help article Automatically customize your ads with dynamic text parameters. The maximum input length of each headline's Text is 1,000 characters including dynamic text strings, and of those 1,000 no more than 30 final characters are allowed after substitution. The ad will fail to display or default text will be used if the length exceeds 30 characters after dynamic text substitution occurs. For languages with double-width characters e.g. Traditional Chinese the maximum input length is 500 characters including dynamic text strings, and of those 500 no more than 15 final characters are allowed after substitution. The ad will fail to display or default text will be used if the length exceeds 15 characters after dynamic text substitution occurs. The double-width characters are determined by the characters you use instead of the character set of the campaign or ad group language settings. Double-width characters include Korean, Japanese and Chinese languages characters as well as Emojis. The Text cannot contain the newline (\n) character. The text can contain IF functions. Add: Required Update: Optional. To retain all of the existing asset links, set or leave this element nil. If you set this element, any headlines that were previously linked to this ad will be replaced.
The list of descriptions that Bing can use to optimize the ad layout. To maximize impressions across all ad formats the descriptions might not always be shown in your ad. Unless you pin one of the descriptions to a specific position, Bing will optimize the ad layout dynamically with the best headlines and descriptions for the user's search query. From a data model perspective the desriptions and headlines are each stored as text assets i.e., one TextAsset per AssetLink. The same asset can be used by multiple ads. For example if "Seamless Integration" is a text asset, it will have the same asset identifier across all ads in the same Microsoft Advertising account. You must set between 2-4 descriptions. Each description's Text must contain at least one word. For efficient use of resources we recommend that you use dynamic text strings such as {keyword} instead of creating new ad copy for each keyword. For more information, see the Microsoft Advertising help article Automatically customize your ads with dynamic text parameters. The maximum input length of each description's Text is 1,000 characters including dynamic text strings, and of those 1,000 no more than 90 final characters are allowed after substitution. The ad will fail to display or default text will be used if the length exceeds 90 characters after dynamic text substitution occurs. For languages with double-width characters e.g. Traditional Chinese the maximum input length is 500 characters including dynamic text strings, and of those 500 no more than 45 final characters are allowed after substitution. The ad will fail to display or default text will be used if the length exceeds 45 characters after dynamic text substitution occurs. The double-width characters are determined by the characters you use instead of the character set of the campaign or ad group language settings. Double-width characters include Korean, Japanese and Chinese languages characters as well as Emojis. The Text cannot contain the newline (\n) character. The text can contain IF functions. Add: Required Update: Optional. To retain all of the existing asset links, set or leave this element nil. If you set this element, any descriptions that were previously linked to this ad will be replaced.
The URL that will be displayed instead of the final URL. The final URL will still be used for the landing page URL. Reserved for limited pilot usage e.g. pharmaceutical customers. The domain portion of the URL in combination with the path 1 and path 2 strings cannot exceed 67 characters. Add: Optional Update: Optional. If no value is set for the update, this setting is not changed. If you set this element to an empty string (""), the previous setting will be deleted.
The first part of the optional path that will be appended to the domain portion of your display URL. The domain portion of your display URL e.g. https://www.contoso.com will be generated from the domain of your Final URL (FinalUrls element). Then if you have specified a value for Path1 it will be appended to the display URL. If you have also specified a value for Path2, then it will also be appended to the display URL after Path1. For example if your FinalUrls contains https://www.contoso.com, Path1 is set to subdirectory1, and Path2 is set to subdirectory2, then the URL displayed will be https://www.contoso.com/subdirectory1/subdirectory2. The path can contain dynamic parameters such as {MatchType}. For a list of supported parameters, see the Microsoft Advertising help article What tracking or URL parameters can I use?. The maximum input length is 1,000 characters if you include dynamic text strings. No more than 15 final (not dynamic text) characters can be input. The ad will fail to display or the default text will be used if the length of the final URL domain and the paths combined exceed 67 characters. For languages with double-width characters e.g. Traditional Chinese the maximum input length is 1,000 characters if you include dynamic text strings. No more than 7 final (not dynamic text) characters can be input. The ad will fail to display or the default text will be used if the length of the final URL domain and the paths combined exceed 33 characters. The double-width characters are determined by the characters you use instead of the character set of the campaign or ad group language settings. Double-width characters include Korean, Japanese and Chinese languages characters as well as Emojis. The path cannot contain the forward slash (/) or newline (\n) characters. If the path includes a space, it will be replaced with an underscore (_) when the ad is shown. The path can contain IF functions. Add: Optional Update: Optional. If no value is set for the update, this setting is not changed. If you set this element to an empty string (""), the previous setting will be deleted.
The second part of the optional path that will be appended to the domain portion of your display URL. The domain portion of your display URL e.g. https://www.contoso.com will be generated from the domain of your Final URL (FinalUrls element). Then if you have specified a value for Path1 it will be appended to the display URL. If you have also specified a value for Path2, then it will also be appended to the display URL after Path1. For example if your FinalUrls contains https://www.contoso.com, Path1 is set to subdirectory1, and Path2 is set to subdirectory2, then the URL displayed will be https://www.contoso.com/subdirectory1/subdirectory2. You can only specify Path2 if Path1 is also set. The path can contain dynamic parameters such as {MatchType}. For a list of supported parameters, see the Microsoft Advertising help article What tracking or URL parameters can I use?. The maximum input length is 1,000 characters if you include dynamic text strings. No more than 15 final (not dynamic text) characters can be input. The ad will fail to display or the default text will be used if the length of the final URL domain and the paths combined exceed 67 characters. For languages with double-width characters e.g. Traditional Chinese the maximum input length is 1,000 characters if you include dynamic text strings. No more than 7 final (not dynamic text) characters can be input. The ad will fail to display or the default text will be used if the length of the final URL domain and the paths combined exceed 33 characters. The double-width characters are determined by the characters you use instead of the character set of the campaign or ad group language settings. Double-width characters include Korean, Japanese and Chinese languages characters as well as Emojis. The path cannot contain the forward slash (/) or newline (\n) characters. If the path includes a space, it will be replaced with an underscore (_) when the ad is shown. The path can contain IF functions. Add: Optional Update: Optional. If no value is set for the update, this setting is not changed. If you set this element to an empty string (""), the previous setting will be deleted.
Scope defines what accounts can use this audience. For a custom audience the only supported scope is Customer, and the audience can be associated with campaigns and ad groups in all of the customer's accounts. Add: Not supported Update: Not supported
The membership duration determines how far back in time Microsoft Advertising should look for actions that match your custom audience definition in order to add people to your list. For a custom audience the membership duration is not set in the Microsoft Advertising web application, and Microsoft Advertising defers to your custom audience provider settings. When you request the custom audience via Bing Ads API, the returned membership duration will be null. Add: Not supported Update: Not supported
The total number of people who are active members of this audience in the Search network. This gives you an idea of how many search users you can target. The audience needs to have at least 300 people before Microsoft Advertising will use it for optimizations. This property will be nil or empty for up to 24 hours while the audience is being built, for example if you have imported new custom audiences from DMP, it takes 24 hours to build the audience, and in the meantime this property will be nil or empty. Add: Not supported Update: Read-only
The total number of people who are active members of this audience in the Audience network. This gives you an idea of how many Audience network users you can target. The audience needs to have at least 300 people before Microsoft Advertising will use it for optimizations. Add: Not supported Update: Read-only
The list of campaign types that support this audience. Supported values are Audience, DynamicSearchAds, Search, and Shopping. New campaign types might be added in the future, so you should not take any dependency on a fixed set of values. Add: Not supported Update: Read-only
This element is not supported for custom audiences. Add: Not supported Update: Not supported
The Microsoft Advertising identifier of the audience. Add: Not supported Update: Required and read-only
The name of the audience. The name can contain a maximum of 128 characters. Add: Not supported Update: Optional. If no value is set for the update, this setting is not changed.
The description of the audience. Use a description to help you remember what audience you are targeting. The description can contain a maximum of 1,024 characters. Add: Not supported Update: Optional. If no value is set for the update, this setting is not changed. To remove the previous setting, set this elemment to an empty string value ("").
The type of the audience. This value is Custom when you retrieve a custom audience. For more information about audience types, see the Audience Data Object Remarks. Add: Not supported Update: Read-only
The Microsoft Advertising identifier of the customer that contains the custom audience. Add: Not supported Update: Not supported
The type of the remarketing rule. For more information about remarketing rule types, see the RemarketingRule Data Object Remarks. Add: Read-only Update: Read-only
The operator that can be applied to the value of the Category element. Add: Optional if you include one or more of the other events; You must include one or more of the following event operator pairs: (ActionOperator and Action), (CategoryOperator and Category), (LabelOperator and Label), (ValueOperator and Value). Update: Optional if you include one or more of the other events; If you do not include CategoryOperator and Category during update, any existing CategoryOperator and Category settings will be deleted.
The category of event you want to track. For example, 'video'. If this element is specified during an add or update operation, then the CategoryOperator element is also required. Add: Optional if you include one or more of the other events; You must include one or more of the following event operator pairs: (ActionOperator and Action), (CategoryOperator and Category), (LabelOperator and Label), (ValueOperator and Value). Update: Optional if you include one or more of the other events; If you do not include CategoryOperator and Category during update, any existing CategoryOperator and Category settings will be deleted.
The operator that can be applied to the value of the Action element. If this element is specified during an add or update operation, then the Action element is also required. Add: Optional if you include one or more of the other events; You must include one or more of the following event operator pairs: (ActionOperator and Action), (CategoryOperator and Category), (LabelOperator and Label), (ValueOperator and Value). Update: Optional if you include one or more of the other events; If you do not include ActionOperator and Action during update, any existing ActionOperator and Action settings will be deleted.
The type of user interaction you want to track. For example 'play' or 'pause'. If this element is specified during an add or update operation, then the ActionOperator element is also required. Add: Optional if you include one or more of the other events; You must include one or more of the following event operator pairs: (ActionOperator and Action), (CategoryOperator and Category), (LabelOperator and Label), (ValueOperator and Value). Update: Optional if you include one or more of the other events; If you do not include ActionOperator and Action during update, any existing ActionOperator and Action settings will be deleted.
The operator that can be applied to the value of the Label element. Add: Optional if you include one or more of the other events; You must include one or more of the following event operator pairs: (ActionOperator and Action), (CategoryOperator and Category), (LabelOperator and Label), (ValueOperator and Value). Update: Optional if you include one or more of the other events; If you do not include LabelOperator and Label during update, any existing LabelOperator and Label settings will be deleted.
The name of the element that caused the action. For example 'trailer' or 'behindthescenes'. If this element is specified during an add or update operation, then the LabelOperator element is also required. Add: Optional if you include one or more of the other events; You must include one or more of the following event operator pairs: (ActionOperator and Action), (CategoryOperator and Category), (LabelOperator and Label), (ValueOperator and Value). Update: Optional if you include one or more of the other events; If you do not include LabelOperator and Label during update, any existing LabelOperator and Label settings will be deleted.
The operator that can be applied to the value of the Value element. Add: Optional if you include one or more of the other events; You must include one or more of the following event operator pairs: (ActionOperator and Action), (CategoryOperator and Category), (LabelOperator and Label), (ValueOperator and Value). Update: Optional if you include one or more of the other events; If you do not include ValueOperator and Value during update, any existing ValueOperator and Value settings will be deleted.
A positive integer value associated with that event. For example the value could be the duration of time that the video played. If this element is specified during an add or update operation, then the ValueOperator element is also required. Add: Optional if you include one or more of the other events; You must include one or more of the following event operator pairs: (ActionOperator and Action), (CategoryOperator and Category), (LabelOperator and Label), (ValueOperator and Value). Update: Optional if you include one or more of the other events; If you do not include ValueOperator and Value during update, any existing ValueOperator and Value settings will be deleted
The type of the criterion. This value is CustomLinkedIn when you retrieve a custom LinkedIn criterion. For more information about criterion types, see the Criterion Data Object Remarks. Add: Read-only Update: Read-only
A list of custom segment catalogs. Add: Required Update: Optional, if no value is set for the update, this setting isn't changed.
The custom segment editorial status. Add: Read-only Update: Read-only
The expiry time of the report in UTC time.
The type of the criterion. This value is DayTime when you retrieve a day and time criterion. For more information about criterion types, see the Criterion Data Object Remarks. Add: Read-only Update: Read-only
The day of the week to target. For example, you can target the ads to run only on Friday or Saturday. Add: Required Update: Not allowed. If you specify this element it must match the existing setting.
The starting hour range to target. The possible values range from 0 to 23. Add: Required Update: Not allowed. If you specify this element it must match the existing setting.
The starting minute of the hour to target. Add: Required Update: Not allowed. If you specify this element it must match the existing setting.
The ending hour range to target. Supported values range from 0 to 24. If the ToHour is set to 24, the ToMinute must be Zero. Add: Required Update: Not allowed. If you specify this element it must match the existing setting.
The ending minute of the hour to target. Add: Required Update: Not allowed. If you specify this element it must match the existing setting.
The type of the criterion. This value is Deal when you retrieve a deal criterion. For more information about criterion types, see the Criterion Data Object Remarks.
The Microsoft Advertising identifier of the Deal.
The identifier of the account that owns the extensions.
ad extension id to entity id associations
The list of ad extensions that are associated with campaigns or ad groups before calling this operation. You can specify a maximum of 100 associations to delete or remove.
The entity type or types associated with an ad extension.
The identifiers of the extensions to delete. You can specify a maximum of 100 identifiers.
The identifier of the ad group that has the criterions you want to delete.
The type of criterion to delete, for example Webpage. You can specify only one criterion type value per call. To add, delete, or update target criterions i.e., age, company name, day and time, device, gender, industry, job function, location, location intent, placement, radius, and topic criterions, you must specify the CriterionType value as Targets. You can add, delete, and update multiple target criterion types in the same operation. To retrieve these target criterions via GetAdGroupCriterionsByIds you must request the specific type individually i.e., Age, CompanyName, DayTime, Device, Gender, Industry, JobFunction, Location, LocationIntent, Placement, Radius, and Topic. To add, delete, or update audience criterions i.e., custom audiences, in-market audiences, and remarketing lists, you must specify the CriterionType value as Audience. You can add, delete, and update multiple target criterion types in the same operation. To retrieve these audience criterions via GetAdGroupCriterionsByIds you must request the specific type individually i.e., CustomAudience, InMarketAudience, ProductAudience, and RemarketingList. You cannot delete a ProductPartition with this operation. Instead, you should use ApplyProductPartitionActions.
A list of unique identifiers that identify the criterions to delete. You can include up to 1,000 ad group criterion identifiers per request.
The campaign that contains the ad groups to delete.
A maximum of 1,000 identifiers of the ad groups to delete.
The ID of the ad group that contains the ads to delete.
The IDs of the ads to delete. You can specify a maximum of 50 IDs.
An array of BatchError objects that contain details for any request items that were not successful.
The list of Audience Group associations to be deleted. The maximum size of the list is 100 items per service request.
Array of audience group IDs to be deleted. The maximum size of the list is 100 items per service request.
The IDs of the audiences to delete. You can specify a maximum of 100 IDs. You cannot delete InMarketAudience objects.
The identifiers of bid strategies to delete from the account's portfolio bid strategy library. You can include a maximum of 100 IDs in a single call. The account is determined by the required CustomerAccountId header element.
A nullable field used to delete bid strategy IDs in the request for the specified scope. If no scope is provided, the default is Account. If a bid strategy ID in the request belongs to the Account scope but the request scope is set to Customer, the call for those bid strategy IDs will fail with a PortfolioBidStrategyIdInvalid error.
The identifiers of the BrandKits to delete.
A maximum of 100 budget identifiers to delete from the account's shared budget library. The account is determined by the required CustomerAccountId header element.
The identifier of the campaign that owns the criterions to delete.
The type of criterion to delete, for example Webpage. You can specify only one criterion type value per call. To add, delete, or update target criterions i.e., age, day and time, device, gender, location, location intent, and radius criterions, you must specify the CriterionType value as Targets. You can add, delete, and update multiple target criterion types in the same operation. To retrieve these target criterions via GetCampaignCriterionsByIds you must request the specific type individually i.e., Age, DayTime, Device, Gender, Location, LocationIntent, and Radius.
A list of unique system identifiers corresponding to the campaign criterions that you want to delete. You can include up to 100 campaign criterion identifiers per request.
The identifier of the account that contains the campaigns to delete.
A maximum of 100 campaign identifiers to delete.
The IDs of the data exclusions to delete.
A maximum of 100 experiment identifiers to delete.
Array of HTML5 asset IDs to delete from the specified campaign.
The identifiers of the import jobs to delete.
The type of import job to delete. To delete GoogleImportJob objects, set this element to "GoogleImportJob".
The identifier of the ad group that contains the keywords to delete.
A maximum of 1,000 keywords identifiers to delete.
Indicates the entity type associated with the label. The supported entity type values are Campaign, AdGroup, Ad, and Keyword.
The list of label associations to delete. Each label association includes label and entity identifiers. The maximum size of the list is 100 items per service request.
The identifier of the label. Set: Required Delete: Required
The identifier of an entity associated with the label. Supported entity types for labels are campaign, ad group, ad, and keyword. The entity type is specified in the request message of each DeleteLabelAssociations, GetLabelAssociationsByEntityIds, GetLabelAssociationsByLabelIds, and SetLabelAssociations operation. Each entity can be associated with a maximum of 50 labels. For example Campaign A can be associated with up to 50 labels. Set: Required Delete: Required
An array of BatchError objects that contain details for any associations that were not successfully retrieved. The list of errors corresponds directly to the list of associations in the request. Items of the list may be returned as null. For each list index where an association was successfully retrieved, the corresponding error element will be null. Ideally all associations are retrieved successfully and all elements in this list are null.
The identifiers of labels to delete. The maximum size of the list is 100 items per service request.
Array of LinkedIn segment IDs to delete from the specified campaign.
The list of identifiers of negative keywords to delete from the negative keyword list, or the negative sites to delete from the website exclusion list. The list can contain a maximum of 5,000 items per service call.
The negative keyword list or website exclusion list. If the SharedEntityScope is either empty or set to Account, and if the SharedList is a NegativeKeywordList, then the ListItemIds must identify negative keyword (NegativeKeyword) objects. If the SharedEntityScope is set to Customer, and if the SharedList is a PlacementExclusionList, then the ListItemIds must identify negative site (NegativeSite) objects.
Indicates whether the shared entity is available at the ad account (Account) or manager account (Customer) level. This element is optional and defaults to Account scope. The ad account scope is only applicable for negative keyword lists. Set this element to Customer to delete negative sites from a website exclusion list in your manager account (customer) shared library.
The identifier of the account that owns the media library.
A maximum of 100 media identifiers to delete from the account's media library. You cannot delete media that is associated or assigned to an ImageAdExtension or ResponsiveAd object. Otherwise this operation will return the 4024 CampaignServiceMediaIsAssociated error.
An array of BatchError objects that contain details for any media that were not successfully deleted. The list of errors corresponds directly to the list of media in the request. Items of the list may be returned as null. For each list index where media was successfully deleted, the corresponding error element will be null. Ideally all media are deleted successfully and all elements in this list are null.
An array of negative keyword with associated entity such as a campaign or ad group. The EntityType specified within each EntityNegativeKeyword must be set to the same value. This array can contain a maximum of 1 EntityNegativeKeyword element, which contains up to 20,000 negative keywords.
An array of BatchErrorCollection objects that contain details for any criterion that were not successfully deleted. The top level error within each BatchErrorCollection object corresponds to potential campaign or ad group errors. The nested list of BatchError objects would include any errors specific to the negative keywords that you attempted to delete from the campaign or ad group. The list of errors do not correspond directly to the list of items in the request. The list can be empty if there were no errors, or can include one or more error objects corresponding to each unsuccessful list item in the request.
The IDs of the seasonality adjustments to delete.
The negative keyword lists or website exclusion lists to delete. If the SharedEntityScope is either empty or set to Account, then the SharedEntities must be negative keyword list (NegativeKeywordList) objects. If the SharedEntityScope is set to Customer, then the SharedEntities must be website exclusion list (PlacementExclusionList) objects. The list can contain a maximum of 20 elements.
Indicates whether the shared entity is available at the ad account (Account) or manager account (Customer) level. This element is optional and defaults to Account scope. The ad account scope is only applicable for negative keyword lists. Set this element to Customer to delete website exclusion lists in your manager account (customer) shared library.
The list of negative keyword list to campaign associations, or website exclusion list to ad account associations. This array can contain a maximum of 10,000 elements.
Indicates whether the shared entity is available at the ad account (Account) or manager account (Customer) level. This element is optional and defaults to Account scope. The ad account scope is only applicable for negative keyword list to campaign associations. Set this element to Customer to delete website exclusion list to ad account associations in your manager account (customer) shared library.
The type of shared entity. This element must be set to "NegativeKeywordList" for negative keyword list to campaign associations in your ad account shared library. This element must be set to "PlacementExclusionList" for website exclusion list to ad account associations in your manager account (customer) shared library. This element must be set to "BrandList" for brand list-to-campaign associations.
The identifier of the campaign or ad account (according to EntityType) that is associated with the shared entity.
The type of entity. This element must be set to "Campaign" for negative keyword list to campaign associations in your ad account shared library. This element must be set to "Account" for website exclusion list to ad account associations in your manager account (customer) shared library. This element must be set to "Campaign" for brand list-to-campaign associations.
Determines the owner of a website exclusion list. This read-only element is only available for PlacementExclusionList associations. Only the users of the manager account (customer) that owns a website exclusion list can update or delete the list, add or delete list items, and associate the list with ad accounts. If your ad account is associated with a website exclusion list that you do not own, you can disassociate the list from your account, but the list and list items are read-only.
For brand list-to-campaign associations, indicates whether the associated brand list is applied as an exclusion list (true) or an inclusion list (false). This field is reserved for all other association types.
An array of BatchError objects that contain details for any associations that were not successfully deleted. The list of errors corresponds directly to the list of associations in the request. Items of the list may be returned as null. For each list index where an association was successfully deleted, the corresponding error element will be null. Ideally all associations are deleted successfully and all elements in this list are null.
The identifiers of videos to delete. The maximum size of the list is 100 items per service request.
The type of the criterion. This value is Device when you retrieve a device criterion. For more information about criterion types, see the Criterion Data Object Remarks. Add: Read-only Update: Read-only
The name of the device to target. The following are the possible device names that you can specify. - Computers - Smartphones - Tablets Three separate bids for Computers, Tablets, and Smartphones should always be specified together. If you do not add individual device criterions representing each of the three device types, the missing device criterions will be added with the default bid adjustment of zero. Add: Required. Three separate criterions for Computers, Smartphones, and Tablets should be specified together in the same add criterions request. If you do not add individual device criterions representing each of the three device types, no device criterions will be added to the campaign or ad group. Update: Not allowed. If you specify this element it must match the existing setting.
Reserved for internal use. If you specify this element the add and update operations will not fail, but the OS names will not be set. When you retrieve this object, the OSName element will be nil. Add: Not allowed. Update: Not allowed.
The type of the ad extension. This value is DisclaimerAdExtension when you retrieve a location ad extension. Add: Read-only Update: Read-only For more information about ad extension types, see the Ad Extension Data Object Remarks.
The name of the disclaimer. This is only used for reporting to help identify the extension. Max. length: 35 characters.
The title of the popup in popup layout. Max. length: 75 characters
Required text if the disclaimer is in popup layout. Max. length: 500 characters.
Required text if the disclaimer is in additionalLine layout. Max. length: 80 characters.
The layout of the disclaimer. Can either be additionalLine or popup.
The final URL suffix can include tracking parameters that will be appended to the end of your landing page URL. We recommend placing tracking parameters that your landing page requires in a final URL suffix so that your customers are always sent to your landing page. For more details and validation rules see Final URL Suffix in the technical guides. Add: Optional Update: Optional. If no value is set for the update, this setting is not changed.
The landing page URL. The following validation rules apply to Final URLs and Final Mobile URLs. - The length of the URL is limited to 2,048 characters. The HTTP or HTTPS protocol string does count towards the 2,048 character limit. - You may specify up to 10 list items for both FinalUrls and FinalMobileUrls; however, only the first item in each list is used for delivery. The service allows up to 10 list items for potential forward compatibility. - Usage of '{' and '}' is only allowed to delineate tags, for example {lpurl}. - Final URLs must each be a well-formed URL starting with either http:// or https://. - If you specify FinalMobileUrls, you must also specify FinalUrls. Add: Required Update: Optional. If no value is set for the update, this setting is not changed.
The landing page URL for mobile devices. The following validation rules apply to Final URLs and Final Mobile URLs. - The length of the URL is limited to 2,048 characters. The HTTP or HTTPS protocol string does count towards the 2,048 character limit. - You may specify up to 10 list items for both FinalUrls and FinalMobileUrls; however, only the first item in each list is used for delivery. The service allows up to 10 list items for potential forward compatibility. - Usage of '{' and '}' is only allowed to delineate tags, for example {lpurl}. - Final URLs must each be a well-formed URL starting with either http:// or https://. - If you specify FinalMobileUrls, you must also specify FinalUrls. Add: Optional Update: Optional. If no value is set for the update, this setting is not changed. If you set this element to an empty list, the previous setting will be deleted.
Your custom collection of key and value parameters for URL tracking. Microsoft Advertising will accept the first 3 CustomParameter objects that you include within the CustomParameters object, and any additional custom parameters will be ignored. Each CustomParameter includes Key and Value elements. For customers in the Custom Parameters Limit Increase Phase 3 pilot (GetCustomerPilotFeatures returns 635), Microsoft Advertising will accept the first 8 custom parameter key and value pairs that you include, and if you include more than 8 custom parameters an error will be returned. Add: Optional Update: Optional. If no value is set for the update, this setting is not changed. Set the UrlCustomParameters element to null or empty to retain any existing custom parameters. To remove all custom parameters, set the Parameters element of the CustomParameters object to null or empty. To remove a subset of custom parameters, specify the custom parameters that you want to keep in the Parameters element of the CustomParameters object.
This is a disclaimer ad when set to true. Note: This will always be a disclaimer ad once this is set to true. You can only set DiscalimerAdsEnabled during ad creation.
Defines the possible user-determined status values of a conversion goal. These are the status values that a user can decide to set, for example a goal can be set to Paused if you no longer wish to track conversions for that goal. For status values that can be set by the system, for example whether or not the UET tag is verified, see the TrackingStatus element. Add: Optional Update: Optional
Determines if the goal applies to all accounts or only the account specified in the required CustomerAccountId header element. If you have multiple Microsoft Advertising accounts, you can track conversions across all of those accounts. If you associate a goal with one account, conversions will be tracked for that account only. Possible values are Account and Customer. If not specified, the scope will be set to Customer by default. Once you set scope, you can't change it. If you want to change the scope, you need to create a new conversion goal and pause the old one. Add: Optional Update: Optional
This determines how your conversions are recorded within your chosen conversion window. There are two choices, and if you do not set a value the default is All: - All: All conversions that happen after an ad click will be counted. This is a common choice for sales. - Unique: Only one conversion that happens after an ad click will be counted. This is a common choice for leads. For example: You track two conversions: leads and sales. You pick Unique for leads and All for sales. When one ad click turns into two leads and two sales, it's counted as three conversions: one for the unique lead, and two for all the sales. Add: Optional Update: Optional
Determines how much each conversion is worth to your business. When adding a conversion goal if you do not specify any revenue tracking preferences, then each ConversionGoalRevenue will be set to their respective default values. When updating a conversion goal, if the Revenue element is nil or empty then none of the nested properties will be updated. However, if this element is not nil or empty then you are effectively replacing any existing revenue properties. The VariableValue option is not available for duration conversion goals. Add: Optional Update: Optional
The unique Microsoft Advertising identifier of the UET tag that you added to your website to allow Microsoft Advertising to collect actions people take on your website. Before you take a dependency on the tag ID, please note that the UET tag can be shared with or from another customer. Shared UET tags and audiences are only available for pilot customers. For an overview of sharing audiences and UET tags in a customer hierarchy, see the Share Audiences and UET Tags technical guide. Add: Required Update: Optional
Defines the possible system-determined status values of a conversion goal. These are the status values that can be set by the system, for example the system sets the status to TagUnverified if the UET tag has not yet been verified. For status values that a user can decide to set, for example setting the status to Paused if you no longer wish to track conversions for that goal, see the Status element. Add: Read-only Update: Read-only
The view-through conversion window is the length of time in minutes after a click that you want to track view-through conversions. If you set this value to 43200 minutes (30 days), then view-through conversions that happen within 30 days after a click are tracked. Past conversions aren't affected. The minimum value supported is 1 minute, although keep in mind that a shorter conversion window will reduce the number of conversions your account records. The maximum value supported is 43200 minutes (30 days). The IncludeViewThroughConversions account property must also be set to true for view-through conversions to be tracked. This element is not returned by default. To get this element, include the ViewThroughConversionWindowInMinutes value in the ReturnAdditionalFields element when you call the GetConversionGoalsByIds and GetConversionGoalsByTagIds service operations. Add: Optional Update: Optional
The category used to segment the conversion goal. Categorize your conversion goals however makes sense for your business. Goal categories don't affect performance - they are here to help you segment your goals and their performance metrics. The supported category values vary by conversion goal type. Duration goals only support the Other category. Add: Optional. If you leave this element nil or empty, the default category will be set to Other. Update: Optional. If no value is set for the update, this setting is not changed.
Determines which attribution model, _LastTouch_ or _LastClick_, is used with a conversion goal.
The type of the conversion goal. This value is Duration when you retrieve a duration goal. For more information about conversion goal types, see the ConversionGoal Data Object Remarks. Add: Read-only Update: Read-only
The minimum amount of time in seconds that the user must spend on your website to track as a conversion. If you don't specify a value, the default value is 0, and the possible range is 0 through 86,399 (1 second less than a full 24 hour day). Add: Optional Update: Optional
The type of the ad. This value is DynamicSearch when you retrieve an dynamic search ad. For more information about ad types, see the Ad Data Object Remarks. Add: Read-only Update: Read-only
The list of key and value strings for forward compatibility to avoid otherwise breaking changes when new elements are added in the current API version. Currently there are no supported forward compatibility map key and value pairs for dynamic search ads.
The first part of the ad description. The text must contain at least one word. The maximum input length of the copy is 90 characters. Note that for ad groups that use Traditional Chinese the maximum input length of the copy is 45 characters. The text can contain IF and countdown functions. Regardless of the total length of all unsubstituted countdown parameters, the final displayed countdown will always use 8 characters out of the total characters available. For more details see Countdown Customizers. The text cannot contain the newline (\n) character. Add: Required Update: Optional
The second part of the ad description. The text must contain at least one word. The maximum input length of the copy is 90 characters. Note that for ad groups that use Traditional Chinese the maximum input length of the copy is 45 characters. The text can contain IF and countdown functions. Regardless of the total length of all unsubstituted countdown parameters, the final displayed countdown will always use 8 characters out of the total characters available. For more details see Countdown Customizers. The text cannot contain the newline (\n) character. Add: Optional Update: Optional
The first part of the optional path that will be appended to the domain portion of your display URL. The display URL e.g. www.contoso.com will be generated from the domain of your display URL. Then if you have specified a value for Path 1 it will be appended to the display URL. If you have also specified a value for Path 2, then it will also be appended to the display URL after Path 1. For example if your domain is contoso.com, Path 1 is set to subdirectory1, and Path 2 is set to subdirectory2, then the URL displayed will be www.contoso.com/subdirectory1/subdirectory2. The maximum input length of the path is 15 characters. Note that for languages with double-width characters e.g. Traditional Chinese the maximum input length of the path is 7 characters. The path can contain IF and countdown functions. Regardless of the total length of all unsubstituted countdown parameters, the final displayed countdown will always use 8 characters out of the total characters available. For more details see Countdown Customizers. The path cannot contain the forward slash (/) or newline (\n) characters. If the path includes a space, it will be replaced with an underscore (_) when the ad is shown. Add: Optional Update: Optional
The second part of the optional path that will be appended to the domain portion of your display URL. The display URL e.g. www.contoso.com will be generated from the domain of your dynamic search ads campaign level settings. Then if you have specified a value for Path 1 it will be appended to the display URL. If you have also specified a value for Path 2, then it will also be appended to the display URL after Path 1. For example if your domain is contoso.com, Path 1 is set to subdirectory1, and Path 2 is set to subdirectory2, then the URL displayed will be www.contoso.com/subdirectory1/subdirectory2. You can only specify Path2 if Path1 is also set. The maximum input length of the path is 15 characters. Note that for languages with double-width characters e.g. Traditional Chinese the maximum input length of the path is 7 characters. The path can contain IF and countdown functions. Regardless of the total length of all unsubstituted countdown parameters, the final displayed countdown will always use 8 characters out of the total characters available. For more details see Countdown Customizers. The path cannot contain the forward slash (/) or newline (\n) characters. If the path includes a space, it will be replaced with an underscore (_) when the ad is shown. Add: Optional Update: Optional
The type of the setting. This value is DynamicSearchAds when you retrieve a dynamic search ads setting. For more information about setting types, see the Setting Data Object Remarks. Add: Read-only Update: Read-only
The language of the website pages that you want to target for dynamic search ads. Your website language determines where your ads are eligible to appear. For example, a German-language ad can appear in Germany, Austria, and Switzerland, but not in Spain. If your website contains pages in multiple languages and you want to advertise all of these pages, you should create a separate campaign for each language. The supported domain languages are Dutch, English, French, German, Italian, Spanish, and Swedish. Note, if you set the campaign Languages or ad group Language, they will be ignored. Add: Required Update: Read-only and required. You cannot update the domain or language, but you must include the current domain and language when updating other properties such as Source.
Determines whether to use Bing's index, advertiser supplied URLs, or both. By default only Bing's index is used. Add: Optional Update: Optional
The page feed identifiers for dynamic search ads. The Source determines whether or not Microsoft Advertising will use the associated page feeds. See the Page Feeds technical guide for an implementation overview. Add: Optional Update: Optional. You cannot delete page feed IDs, but you can replace the previous set with a new set.
Determines whether to automatically generate dynamic search ad text in addition to the ad text you provide. During ad delivery, we will use artificial intelligence to choose the best ad text available from these options. Add: Optional. The default value of false will be set if not otherwise specified. Update: Optional. If no value is set for the update, this setting is not changed. Note: Not everyone has this feature yet. If you don't, don't worry - it's coming soon!
An array of editorial errors that contains the details that explain why the criterion or ad extension was disapproved.
An array of operation errors that contains the details that explain why the service operation failed when the error is not related to a specific item in the batch of items.
The component of the ad or keyword that failed editorial review.
The term that failed editorial review. This element cannot be set if a combination of terms caused the failure or if the failure was based on a policy violation.
A list of countries or regions where the ad or keyword failed editorial review. Each string in the list contains a two character country or region code.
Identifies the ad or keyword that failed editorial review. Note: AdOrKeywordId is the ID of the asset.
Identifies the ad group which is the parent of the ad or keyword that failed editorial review. Note: AdGroupId is always 0 for an asset since it doesn't belong to an ad group.
An array of editorial reasons that you can use to determine the component of an ad or keyword that failed editorial review, and the reason for the failure.
A value that determines whether you can appeal the issues found by the editorial review. Note: AppealStatus is based on information in the catalog.AssetEditorialStatus table. It's a combination of Appealability and IsAppealPending.
The type of the bidding scheme. This value is EnhancedCpcBiddingScheme when you retrieve an enhanced CPC bidding scheme. For more information about bidding scheme types, see the BiddingScheme Data Object Remarks. Add: Read-only Update: Read-only
Determines how much each conversion is worth to your business. When adding a conversion goal if you do not specify any revenue tracking preferences, then each ConversionGoalRevenue will be set to their respective default values. When updating a conversion goal, if the Revenue element is nil or empty then none of the nested properties will be updated. However, if this element is not nil or empty then you are effectively replacing any existing revenue properties. Add: Optional Update: Optional
The category used to segment the conversion goal. Categorize your conversion goals however makes sense for your business. Goal categories don't affect performance - they are here to help you segment your goals and their performance metrics. The supported category values vary by conversion goal type. Event goals support the AddToCart, BeginCheckout, BookAppointment, Contact, GetDirections, Other, OutboundClick, PageView, Purchase, RequestQuote, Signup, SubmitLeadForm, and Subscribe categories. Add: Required as of June 2021. Previously if you left this element nil or empty, the default category was set to None. Update: Optional if the conversion goal already has a category set other than None. If no value is set for the update, this setting is not changed.
Determines whether this goal is a simplified conversion goal. For the EventGoal columns ActionExpression, ActionOperator, CategoryExpression, CategoryOperator, LabelExpression, LabelOperator, Value, and ValueOperator: Advertisers can't manually specify values.Microsoft Advertising automatically generates compatible values based on the associated conversion event.
The type of the conversion goal. This value is Event when you retrieve an event goal. For more information about conversion goal types, see the ConversionGoal Data Object Remarks. Add: Read-only Update: Read-only
The category of event you want to track. For example, 'video'. If this element is specified during an add or update operation, then the CategoryOperator element is also required. The string cannot exceed the maximum length of 100. Add: Optional if you include one or more of the other events; You must include one or more of the following event operator pairs: (ActionOperator and ActionExpression), (CategoryOperator and CategoryExpression), (LabelOperator and LabelExpression), (ValueOperator and Value). Update: Optional if you include one or more of the other events; If you do not include CategoryOperator and CategoryExpression during update, any existing CategoryOperator and CategoryExpression settings will be deleted.
The operator that can be applied to the value of the CategoryExpression element. Add: Optional if you include one or more of the other events; You must include one or more of the following event operator pairs: (ActionOperator and ActionExpression), (CategoryOperator and CategoryExpression), (LabelOperator and LabelExpression), (ValueOperator and Value). Update: Optional if you include one or more of the other events; If you do not include CategoryOperator and CategoryExpression during update, any existing CategoryOperator and CategoryExpression settings will be deleted.
The type of user interaction you want to track. For example 'play' or 'pause'. If this element is specified during an add or update operation, then the ActionOperator element is also required. The string cannot exceed the maximum length of 100. Add: Optional if you include one or more of the other events; You must include one or more of the following event operator pairs: (ActionOperator and ActionExpression), (CategoryOperator and CategoryExpression), (LabelOperator and LabelExpression), (ValueOperator and Value). Update: Optional if you include one or more of the other events; If you do not include ActionOperator and ActionExpression during update, any existing ActionOperator and ActionExpression settings will be deleted.
The operator that can be applied to the value of the ActionExpression element. If this element is specified during an add or update operation, then the ActionExpression element is also required. Add: Optional if you include one or more of the other events; You must include one or more of the following event operator pairs: (ActionOperator and ActionExpression), (CategoryOperator and CategoryExpression), (LabelOperator and LabelExpression), (ValueOperator and Value). Update: Optional if you include one or more of the other events; If you do not include ActionOperator and ActionExpression during update, any existing ActionOperator and ActionExpression settings will be deleted.
The name of the element that caused the action. For example 'trailer' or 'behindthescenes'. If this element is specified during an add or update operation, then the LabelOperator element is also required. The string cannot exceed the maximum length of 100. Add: Optional if you include one or more of the other events; You must include one or more of the following event operator pairs: (ActionOperator and ActionExpression), (CategoryOperator and CategoryExpression), (LabelOperator and LabelExpression), (ValueOperator and Value). Update: Optional if you include one or more of the other events; If you do not include LabelOperator and LabelExpression during update, any existing LabelOperator and LabelExpression settings will be deleted.
The operator that can be applied to the value of the LabelExpression element. Add: Optional if you include one or more of the other events; You must include one or more of the following event operator pairs: (ActionOperator and ActionExpression), (CategoryOperator and CategoryExpression), (LabelOperator and LabelExpression), (ValueOperator and Value). Update: Optional if you include one or more of the other events; If you do not include LabelOperator and LabelExpression during update, any existing LabelOperator and LabelExpression settings will be deleted.
The operator that can be applied to the value of the Value element. Add: Optional if you include one or more of the other events; You must include one or more of the following event operator pairs: (ActionOperator and ActionExpression), (CategoryOperator and CategoryExpression), (LabelOperator and LabelExpression), (ValueOperator and Value). Update: Optional if you include one or more of the other events; If you do not include ValueOperator and Value during update, any existing ValueOperator and Value settings will be deleted.
A numerical value associated with that event. For example the value could be the duration of time that the video played. If this element is specified during an add or update operation, then the ValueOperator element is also required. Add: Optional if you include one or more of the other events; You must include one or more of the following event operator pairs: (ActionOperator and ActionExpression), (CategoryOperator and CategoryExpression), (LabelOperator and LabelExpression), (ValueOperator and Value). Update: Optional if you include one or more of the other events; If you do not include ValueOperator and Value during update, any existing ValueOperator and Value settings will be deleted
The type of the ad. This value is ExpandedText when you retrieve an expanded text ad. For more information about ad types, see the Ad Data Object Remarks. Add: Read-only Update: Read-only
The Ad Format Preference is used to indicate whether or not you prefer the ad copy to be shown to users as a search or audience ad. Search ads tend to be written as a call to action, whereas audience ads should be written in more of an informational style. While you have the option to use expanded text ads as audience ads, designating an ad as Audience ads preferred format allows you to optimize its messaging for native delivery. IMPORTANT: You must define at least one expanded text ad per ad group that does not prefer audience ads, otherwise the ad copy of all expanded text ads will be eligible for both search and audience ads. Possible values are AudienceAd and All. If set to All, the ad will be eligible for both search and audience ad formats. If set to AudienceAd, the ad will only be eligible for the audience ad format. Add: Optional. If you do not set this element, by default the ad format preference will be set to All. Update: Optional. If no value is set for the update, this setting is not changed.
The first part of the ad title. The three title parts will be automatically separated by a space, vertical bar, and space (" | ") when the ad is shown. Each part of the title must contain at least one word. For efficient use of resources we recommend that you use dynamic text strings such as {keyword} instead of creating new ad copy for each keyword. For more information, see the Microsoft Advertising help article Automatically customize your ads with dynamic text parameters. The title can contain IF and countdown functions. Regardless of the total length of all unsubstituted countdown parameters, the final displayed countdown will always use 8 characters out of the total characters available. For more details see Countdown Customizers. The maximum input length is 1,000 characters if you include dynamic text strings. No more than 30 final (not dynamic text) characters can be input. The ad will fail to display or the default text will be used if the length of all three title parts exceed 90 characters after dynamic text substitution occurs. For languages with double-width characters e.g. Traditional Chinese the maximum input length is 500 characters if you include dynamic text strings. No more than 15 final (not dynamic text) characters can be input. The ad will fail to display or the default text will be used if the length of all three title parts exceed 45 characters after dynamic text substitution occurs. The double-width characters are determined by the characters you use instead of the character set of the campaign or ad group language settings. Double-width characters include Korean, Japanese and Chinese languages characters as well as Emojis. The title cannot contain the newline (\n) character. Add: Required Update: Optional
The second part of the ad title. The three title parts will be automatically separated by a space, vertical bar, and space (" | ") when the ad is shown. Each part of the title must contain at least one word. For efficient use of resources we recommend that you use dynamic text strings such as {keyword} instead of creating new ad copy for each keyword. For more information, see the Microsoft Advertising help article Automatically customize your ads with dynamic text parameters. The title can contain IF and countdown functions. Regardless of the total length of all unsubstituted countdown parameters, the final displayed countdown will always use 8 characters out of the total characters available. For more details see Countdown Customizers. The maximum input length is 1,000 characters if you include dynamic text strings. No more than 30 final (not dynamic text) characters can be input. The ad will fail to display or the default text will be used if the length of all three title parts exceed 90 characters after dynamic text substitution occurs. For languages with double-width characters e.g. Traditional Chinese the maximum input length is 500 characters if you include dynamic text strings. No more than 15 final (not dynamic text) characters can be input. The ad will fail to display or the default text will be used if the length of all three title parts exceed 45 characters after dynamic text substitution occurs. The double-width characters are determined by the characters you use instead of the character set of the campaign or ad group language settings. Double-width characters include Korean, Japanese and Chinese languages characters as well as Emojis. The title cannot contain the newline (\n) character. Add: Required Update: Optional
The first part of the ad description that can show in your ad. To maximize impressions across all ad formats the description might not always be shown in your ad. The text must contain at least one word. For efficient use of resources we recommend that you use dynamic text strings such as {keyword} instead of creating new ad copy for each keyword. For more information, see the Microsoft Advertising help article Automatically customize your ads with dynamic text parameters. The text can contain IF and countdown functions. Regardless of the total length of all unsubstituted countdown parameters, the final displayed countdown will always use 8 characters out of the total characters available. For more details see Countdown Customizers. The maximum input length is 1,000 characters if you include dynamic text strings. No more than 90 final (not dynamic text) characters can be input. The ad will fail to display or the default text will be used if the length of both text parts exceed 180 characters after dynamic text substitution occurs. For languages with double-width characters e.g. Traditional Chinese the maximum input length is 500 characters if you include dynamic text strings. No more than 45 final (not dynamic text) characters can be input. The ad will fail to display or the default text will be used if the length of both text parts exceed 90 characters after dynamic text substitution occurs. The double-width characters are determined by the characters you use instead of the character set of the campaign or ad group language settings. Double-width characters include Korean, Japanese and Chinese languages characters as well as Emojis. The text cannot contain the newline (\n) character. Add: Required Update: Optional
The first part of the optional path that will be appended to the domain portion of your display URL. The domain portion of your display URL e.g. https://www.contoso.com will be generated from the domain of your Final URL (FinalUrls element). Then if you have specified a value for Path1 it will be appended to the display URL. If you have also specified a value for Path2, then it will also be appended to the display URL after Path1. For example if your FinalUrls contains https://www.contoso.com, Path1 is set to subdirectory1, and Path2 is set to subdirectory2, then the URL displayed will be https://www.contoso.com/subdirectory1/subdirectory2. The path can contain IF and countdown functions. Regardless of the total length of all unsubstituted countdown parameters, the final displayed countdown will always use 8 characters out of the total characters available. For more details see Countdown Customizers. The path can contain dynamic parameters such as {MatchType}. For a list of supported parameters, see the Microsoft Advertising help article What tracking or URL parameters can I use?. The maximum input length is 1,000 characters if you include dynamic text strings. No more than 15 final (not dynamic text) characters can be input. The ad will fail to display or the default text will be used if the length of the final URL domain and the paths combined exceed 67 characters. For languages with double-width characters e.g. Traditional Chinese the maximum input length is 1,000 characters if you include dynamic text strings. No more than 7 final (not dynamic text) characters can be input. The ad will fail to display or the default text will be used if the length of the final URL domain and the paths combined exceed 33 characters. The double-width characters are determined by the characters you use instead of the character set of the campaign or ad group language settings. Double-width characters include Korean, Japanese and Chinese languages characters as well as Emojis. The path cannot contain the forward slash (/) or newline (\n) characters. If the path includes a space, it will be replaced with an underscore (_) when the ad is shown. Add: Optional Update: Optional. If no value is set for the update, this setting is not changed. If you set this element to an empty string (""), the previous setting will be deleted.
The second part of the optional path that will be appended to the domain portion of your display URL. The domain portion of your display URL e.g. https://www.contoso.com will be generated from the domain of your Final URL (FinalUrls element). Then if you have specified a value for Path1 it will be appended to the display URL. If you have also specified a value for Path2, then it will also be appended to the display URL after Path1. For example if your FinalUrls contains https://www.contoso.com, Path1 is set to subdirectory1, and Path2 is set to subdirectory2, then the URL displayed will be https://www.contoso.com/subdirectory1/subdirectory2. You can only specify Path2 if Path1 is also set. The path can contain IF and countdown functions. Regardless of the total length of all unsubstituted countdown parameters, the final displayed countdown will always use 8 characters out of the total characters available. For more details see Countdown Customizers. The path can contain dynamic parameters such as {MatchType}. For a list of supported parameters, see the Microsoft Advertising help article What tracking or URL parameters can I use?. The maximum input length is 1,000 characters if you include dynamic text strings. No more than 15 final (not dynamic text) characters can be input. The ad will fail to display or the default text will be used if the length of the final URL domain and the paths combined exceed 67 characters. For languages with double-width characters e.g. Traditional Chinese the maximum input length is 1,000 characters if you include dynamic text strings. No more than 7 final (not dynamic text) characters can be input. The ad will fail to display or the default text will be used if the length of the final URL domain and the paths combined exceed 33 characters. The double-width characters are determined by the characters you use instead of the character set of the campaign or ad group language settings. Double-width characters include Korean, Japanese and Chinese languages characters as well as Emojis. The path cannot contain the forward slash (/) or newline (\n) characters. If the path includes a space, it will be replaced with an underscore (_) when the ad is shown. Add: Optional Update: Optional. If no value is set for the update, this setting is not changed. If you set this element to an empty string (""), the previous setting will be deleted.
The third part of the ad title. The three title parts will be automatically separated by a space, vertical bar, and space (" | ") when the ad is shown. Each part of the title must contain at least one word. For efficient use of resources we recommend that you use dynamic text strings such as {keyword} instead of creating new ad copy for each keyword. For more information, see the Microsoft Advertising help article Automatically customize your ads with dynamic text parameters. The title can contain IF and countdown functions. Regardless of the total length of all unsubstituted countdown parameters, the final displayed countdown will always use 8 characters out of the total characters available. For more details see Countdown Customizers. The maximum input length is 1,000 characters if you include dynamic text strings. No more than 30 final (not dynamic text) characters can be input. The ad will fail to display or the default text will be used if the length of all three title parts exceed 90 characters after dynamic text substitution occurs. For languages with double-width characters e.g. Traditional Chinese the maximum input length is 500 characters if you include dynamic text strings. No more than 15 final (not dynamic text) characters can be input. The ad will fail to display or the default text will be used if the length of all three title parts exceed 45 characters after dynamic text substitution occurs. The double-width characters are determined by the characters you use instead of the character set of the campaign or ad group language settings. Double-width characters include Korean, Japanese and Chinese languages characters as well as Emojis. The title cannot contain the newline (\n) character. Add: Optional Update: Optional. If no value is set for the update, this setting is not changed. If you set this element to an empty string (""), the previous setting will be deleted.
The second part of the ad description that can show in your ad. To maximize impressions across all ad formats the description might not always be shown in your ad. The text must contain at least one word. For efficient use of resources we recommend that you use dynamic text strings such as {keyword} instead of creating new ad copy for each keyword. For more information, see the Microsoft Advertising help article Automatically customize your ads with dynamic text parameters. The text can contain IF and countdown functions. Regardless of the total length of all unsubstituted countdown parameters, the final displayed countdown will always use 8 characters out of the total characters available. For more details see Countdown Customizers. The maximum input length is 1,000 characters if you include dynamic text strings. No more than 90 final (not dynamic text) characters can be input. The ad will fail to display or the default text will be used if the length of both text parts exceed 180 characters after dynamic text substitution occurs. For languages with double-width characters e.g. Traditional Chinese the maximum input length is 500 characters if you include dynamic text strings. No more than 45 final (not dynamic text) characters can be input. The ad will fail to display or the default text will be used if the length of both text parts exceed 90 characters after dynamic text substitution occurs. The double-width characters are determined by the characters you use instead of the character set of the campaign or ad group language settings. Double-width characters include Korean, Japanese and Chinese languages characters as well as Emojis. The text cannot contain the newline (\n) character. Add: Optional Update: Optional. If no value is set for the update, this setting is not changed. If you set this element to an empty string (""), the previous setting will be deleted.
The type of the import job. This value is FileImportJob when you retrieve a File import job. For more information about import job types, see the ImportJob Data Object Remarks.
The type of the import option. This value is FileImportOption when you retrieve a File import option. For more information about import option types, see the ImportOption Data Object Remarks.
The type of the ad extension. This value is FilterLinkAdExtension when you retrieve a filter link ad extension. Add: Read-only Update: Read-only For more information about ad extension types, see the Ad Extension Data Object Remarks.
The header that is appended with a colon (:) and precedes the filter link values in the ad that is shown. Filter link headers will be shown in the language that you specify. For example, if you want header Amenities in English you must set the Language to English and the AdExtensionHeaderType to Amenities. If you want header Ausstattung (Amenities in German) you must set the Language to German and the AdExtensionHeaderType to Amenities. Add: Required Update: Required
The language you want to use for the filter link headers. Filter link headers will be shown in the language that you specify. For example, if you want header Amenities in English you must set the Language to English and the AdExtensionHeaderType to Amenities. If you want header Ausstattung (Amenities in German) you must set the Language to German and the AdExtensionHeaderType to Amenities. Add: Required Update: Required
The text values that follow after the AdExtensionHeaderType component of the ad that is shown. Each text value that you choose can have a maximum length of 25 characters. Note that for Traditional Chinese characters, each value can have a maximum length of 12 characters. Add: Required Update: Required
The type of the criterion bid. This value is FixedBid when you retrieve a fixed bid criterion. For more information about criterion types, see the CriterionBid Data Object Remarks. Add: Read-only Update: Read-only
The bid value. For details about the valid bid range for your market, see Currencies. Add: Required Update: Optional
Determines the calendar day and time ranges when the ad extension is eligible to be shown in ads. The EndDate must be within 30 days of the StartDate. Add: The schedule StartDate and EndDate are required for flyer ad extensions. Update: Optional. If you set this element null, any existing scheduling set for the ad extension will remain unchanged. If you set this to any non-null Schedule object, you are effectively replacing existing scheduling settings for the ad extension. You cannot set this element to an empty Schedule object, because that would effectively attempt to delete all scheduling. This would result in an error since StartDate and EndDate are required for flyer ad extensions.
The type of the ad extension. This value is FlyerAdExtension when you retrieve a flyer ad extension. Add: Read-only Update: Read-only For more information about ad extension types, see the Ad Extension Data Object Remarks.
The flyer name. The maximum length for this element is 150 characters. Add: Required Update: Optional. If no value is set for the update, this setting is not changed.
The unique identifier of a Microsoft Merchant Center store used for product ads. Add: Optional Update: Read-only. You cannot update the store ID after it was set.
Description that can be used by the advertiser, agency, or account manager to track, label, or manage flyer extensions. This description is not displayed with the ad or image. The maximum length for this element is 1,024 characters. Add: Optional Update: Optional. If no value is set for the update, this setting is not changed.
The identifier of the image to include in the ad. You can only set one media ID. The data type is a list of long values in case support for multiple images is added later. Each media ID corresponds to an Image of the "GenericImage" Media sub type. You can get the identifier of each Image when you add them to the image library by calling the AddMedia operation. Otherwise after the media has been added to your image library you can get the media identifiers with the GetMediaMetaDataByAccountId operation. The image should have a minimum width and height of 220px, and a maximum file size of 3.9MB. Add: Required Update: Optional. If no value is set for the update, this setting is not changed.
The URL of the media that you already added. Add: Read-only Update: Read-only
The type of the criterion. This value is Gender when you retrieve a gender criterion. For more information about criterion types, see the Criterion Data Object Remarks. Add: Read-only Update: Read-only
The gender of the people you want to see your ads. Add: Required Update: Not allowed. If you specify this element it must match the existing setting.
A list of gender types. Add: Required Update: Optional. To remove existing values, set it to null or empty. To remove a subset of gender types, specify the gender types that you want to keep and it will replace the existing gender types.
The type of the criterion. This value is Genre when you retrieve a genre criterion. For more information about criterion types, see the Criterion Data Object Remarks.
The Microsoft Advertising identifier of the Genre. View this table to see possible values for GenreId.
The identifiers of each account to request migration status.
Filters the returned migration status by migration type. Currently there are no applicable migrations in progress and this element is reserved for future use.
An array of account migration statuses. For each account identifier specified in the request, an AccountMigrationStatusesInfo object is returned.
The names of account properties that you want to get. For example, determine whether or not Microsoft Click Id auto-tagging is enabled, include the MSCLKIDAutoTaggingEnabled value in your request.
An array of account properties. For each account property name specified in the request, an AccountProperty object is returned.
The identifier of the account that contains the ad extensions to get.
A value that filters the extensions based on whether they?re associated with a specific entity type. For possible values, see AssociationType. To get all extensions including those not associated with any entity, set this element to NULL.
The types of ad extensions to get from the account. You may include multiple values as flags. How you specify multiple flags depends on the programming language that you use. For example, C# treats these values as flag values and Java treats them as an array of strings. The SOAP should include a string that contains a space-delimited list of values for example, LocationAdExtension CallAdExtension.
A list of ad extension IDs. To get the extension, call the GetAdExtensionsByIds operation.
The list of entity identifiers by which you may request the respective ad extension associations. The maximum number of EntityIds per request is 100.
Filters the returned associations by ad extension type. You may include multiple values as flags. How you specify multiple flags depends on the programming language that you use. For example, C# treats these values as flag values and Java treats them as an array of strings. The SOAP should include a string that contains a space-delimited list of values for example, LocationAdExtension CallAdExtension.
Filters the returned associations by entity type.
An array of ad extension association collections. For each entity identifier specified in the request, an AdExtensionAssociationCollection is returned.
The identifier of the account that owns the ad extensions.
A list of ad extension identifiers. You can specify a maximum of 100 identifiers.
The types of ad extensions that the list of identifiers contains. You may include multiple values as flags. How you specify multiple flags depends on the programming language that you use. For example, C# treats these values as flag values and Java treats them as an array of strings. The SOAP should include a string that contains a space-delimited list of values for example, LocationAdExtension CallAdExtension.
A list of AdExtension objects. The list corresponds directly to the list of identifiers in the request. If an ad extension ID in the request is not valid or the extension is not of the type specified, the corresponding item in this list is null.
The list of ad extensions and corresponding entity associations to get.
The collection of ad extension editorial reasons.
The identifier of the ad group that owns the criterions to get.
The list of additional properties that you want included within each returned ad group criterion. The additional field values enable you to get the latest features using the current version of Campaign Management API, and in the next version the corresponding elements will be included by default. This request element is optional.
The type of criterion to get, for example Webpage. You can specify only one type. The Targets and Audience values are not allowed for this operation.
A list of unique identifiers that identify the criterions to get. You can include up to 1,000 ad group criterion identifiers per request. If this element is null, all criterions for the specified AdGroupId will be retrieved.
The list of criterions that correspond directly to the identifiers specified in the request. If an identifier in the list is not valid, the corresponding item in the response is set to null.
The identifier of the campaign that contains the ad groups to get.
The list of additional properties that you want included within each returned ad group. The additional field values enable you to get the latest features using the current version of Campaign Management API, and in the next version the corresponding elements will be included by default. This request element is optional.
The list of ad groups within the specified campaign. If the campaign contains no ad groups, an empty array is returned.
A maximum of 1,000 identifiers of the ad groups to get.
The list of ad groups that correspond directly to the ad group identifiers that you specified in the request. Items of the list may be returned as null. For each list index where an ad group was not retrieved, the corresponding element will be null.
The list of batch errors that contain details for any request items that were not successful. The list of errors do not correspond directly to the list of items in the request. The list can be empty if there were no errors, or can include one or more error objects corresponding to each unsuccessful list item in the request.
The identifier of the ad group to retrieve the ads from.
The list of additional properties that you want included within each returned ad. The additional field values enable you to get the latest features using the current version of Campaign Management API, and in the next version the corresponding elements will be included by default. This request element is optional.
The list of ads that have been retrieved. If the ad group doesn't contain ads, this array is empty.
The editorial review status that the ads must have to be returned.
The additional field values enable you to get the latest features using the current version of Campaign Management API, and in the next version the corresponding elements will be included by default. This request element is optional.
The list of ads that have been retrieved. If the ad group doesn't contain ads that meet the criteria, this array is empty.
The identifier of the ad group that contains the ads to get.
A maximum of 20 identifiers of the requested ads. If the ad identifiers do not match the requested ad types, then the operation will return a batch error for each requested ad.
An array of Ad objects that corresponds directly to the ad identifiers that you specified in the request. Items of the list may be returned as null. For each list index where an ad was not retrieved, the corresponding element will be null.
An array of annotation opt out data objects.
Whether or not the account is opted out.
Whether or not the customer is opted out.
Whether or not the customer is opted out of everything.
A list of identifiers that identify the listing groups that had the action applied. The list of identifiers corresponds directly to the list of listing groups in the request. If any listing group action failed, then all remaining listing group actions will fail, and all elements in this list will be null.
The list of listing groups that correspond directly to the identifiers specified in the request. If an identifier in the list is not valid, the corresponding item in the response is set to null.
Array of asset groups to update for the specified campaign. A maximum of 100 asset groups can be specified in a single call.
The identifier of the account that owns the asset groups.
asset group id to campaign id associations
The list of asset groups and corresponding entity associations to get.
The collection of asset group editorial reasons.
The list of AssetGroup ids used to fetch the associations. The maximum size of the list is 100 items per service request.
The list of Audience Group associations. The maximum size of the list is 100 items per service request.
The list of AudienceGroup ids used to fetch the associations. You can include a maximum of 100 IDs in a single call.
The list of Audience Group associations to get. The maximum size of the list is 100 items per service request.
Array of audience group ids to get. The maximum size of the list is 100 items per service request. If you leave this element nil or empty, then the operation will return all audience groups in the account.
Array of audience groups. The maximum size of the list is 100 items per service request.
The type of audiences to return. You may include multiple values as flags. How you specify multiple flags depends on the programming language that you use. For example, C# treats these values as flag values and Java treats them as an array of strings. The SOAP should include a string that contains a space-delimited list of values for example, RemarketingList SimilarRemarketingList.
A maximum of 100 identifiers of the requested audiences. This request element is optional. If this element is null or empty, then you are effectively requesting all customer and account scoped audiences for the specified account. If the audience identifiers do not match the requested audience types, then the operation will return a batch error for each requested audience ID.
The list of audiences that corresponds directly to the audience identifiers that you specified in the request. Items of the list may be returned as null. For each list index where an audience was not retrieved, the corresponding element will be null.
A list of unique bid strategy identifiers that identify the bid strategies to get. You can include a maximum of 100 IDs in a single call. The bid strategy IDs must be in the same account that you specified in the required CustomerAccountId header element. If you leave this element nil or empty, then the operation will return all portfolio bid strategies in the account.
A nullable field used to retrieve bid strategy IDs in the request for the specified scope. If no scope is provided, the default is Account. If a bid strategy ID in the request belongs to the Account scope but the request scope is set to Customer, the call for those bid strategy IDs will fail with a PortfolioBidStrategyIdInvalid error.
The list of additional properties that you want included within each returned bid strategy. The additional field values enable you to get the latest features using the current version of Campaign Management API, and in the next version the corresponding elements will be included by default. This request element is optional.
An array of BidStrategy objects that corresponds directly to the bid strategy identifiers that you specified in the request. Items of the list may be returned as null. For each list index where a bid strategy was not retrieved, the corresponding element will be null.
The list of additional stores that you want included. The additional field values enable you to get the latest features using the current version of Campaign Management API, and in the next version the corresponding elements will be included by default. This request element is optional.
The list of Microsoft Merchant Center stores for the specified customer.
A list of brand kits to be retrieved for the specified account.
The identifiers of the BrandKits to retrieve.
A list of BrandKits to be retrieved for the specified account.
The list of supported sales country codes for Microsoft Shopping Campaigns. For example, supported country codes include AD (Andorra), AL (Albania), AR (Argentina), AW (Aruba), AT (Austria), AU (Australia), BS (Bahamas), BD (Bangladesh), BA (Bosnia and Herzegovina), BE (Belgium), BO (Bolivia), BG (Bulgaria), BR (Brazil), BN (Brunei), CA (Canada), KY (Cayman Islands), CH (Switzerland), CL (Chile), CO (Colombia), CR (Costa Rica), CY (Cyprus), CZ (Czech Republic), DE (Germany), DK (Denmark), DM (Dominica), DO (Dominican Republic), EC (Ecuador), SV (El Salvador), EE (Estonia), ES (Spain), FJ (Fiji), FI (Finland), FR (France), GF (French Guiana), PF (French Polynesia), GB (Great Britain), GR (Greece), GU (Guam), GT (Guatemala), GY (Guyana), HT (Haiti), HN (Honduras), HR (Croatia), HU (Hungary),ID (Indonesia), IE (Ireland), IN (India), IS (Iceland), IT (Italy), LI (Liechtenstein), LT (Lithuania), LU (Luxembourg), LV (Latvia), MV (Maldives), MC (Monaco), ME (Montenegro), MK (North Macedonia), MT (Malta), MQ (Martinique),MY (Malaysia), MX (Mexico), MN (Mongolia), MS (Montserrat), NP (Nepal), NL (Netherlands), NC (New Caledonia), NO (Norway), NZ (New Zealand), PA (Panama), PG (Papua New Guinea), PH (Philippines), PY (Paraguay), PE (Peru), PL (Poland), PT (Portugal), PR (Puerto Rico), RO (Romania), RS (Serbia), LK (Sri Lanka), SE (Sweden), SG (Singapore), SI (Slovenia), SK (Slovakia), SM (San Marino), TH (Thailand), TT (Trinidad and Tobago), TR (Turkey), US (United States), UT (Uruguay), VA (Vatican City), VE (Venezuela),VN (Vietnam), ZA (South Africa). You can pass any one of the returned values in the SalesCountryCode element of a ShoppingSetting object.
A list of unique budget identifiers that identify the budgets to get. You can specify a maximum of 100 IDs. The budget IDs must be in the same account that you specified in the required CustomerAccountId header element. If you leave this element nil or empty, then the operation will return all budgets that are available to be shared with campaigns in the account.
An array of Budget objects that corresponds directly to the budget identifiers that you specified in the request. Items of the list may be returned as null. For each list index where a budget was not retrieved, the corresponding element will be null.
The unique identifier of the campaign whose criterions you want to get.
The list of additional properties that you want included within each returned campaign criterion. The additional field values enable you to get the latest features using the current version of Campaign Management API, and in the next version the corresponding elements will be included by default. This request element is optional.
The type of criterion to get, for example Webpage. You can specify only one type. The Targets value is not allowed for this operation.
A list of unique identifiers that identify the campaign criterions to get. You can include up to 100 campaign criterion identifiers per request. If this element is null, all criterions for the specified CampaignId will be retrieved.
The list of campaign criterions that correspond directly to the identifiers specified in the request. Items of the list may be returned as null. For each list index where a criterion was not retrieved, the corresponding element will be null.
A list of unique bid strategy identifiers that identify the campaign identifiers to get. You can specify a maximum of 100 IDs bid strategy IDs, and each bid strategy could be shared by up to 10,000 campaign identifiers. For each bid strategy ID that you specify in the request, an IdCollection that contains between 1 and 10,000 campaign identifers will be returned. The bid strategy IDs must be in the same account that you specified in the required CustomerAccountId header element.
A nullable field used to retrieve campaign IDs for the bid strategy IDs in the request for the specified scope. If no scope is provided, the default is Account. If a bid strategy ID in the request belongs to the Account scope but the request scope is set to Customer, the call for those bid strategy IDs will fail with a PortfolioBidStrategyIdInvalid error.
The list of campaign id collections that corresponds directly to the bid strategy identifiers that you specified in the request. Items of the list may be returned as null. For each list index where an id collection was not retrieved, the corresponding element will be null.
A list of unique budget identifiers that identify the campaign identifiers to get. You can specify a maximum of 100 budget IDs, and each budget could be shared by up to 10,000 campaign identifiers. For each budget ID that you specify in the request, an IdCollection that contains between 1 and 10,000 campaign identifers will be returned. The budget IDs must be in the same account that you specified in the required CustomerAccountId header element.
The list of campaign id collections that corresponds directly to the budget identifiers that you specified in the request. Items of the list may be returned as null. For each list index where an id collection was not retrieved, the corresponding element will be null.
The identifier of the account that contains the campaigns to get.
The type of campaign to get, for example Search, Shopping, or DynamicSearchAds. This request element is optional. If you do not set any campaign type, the default value is Search i.e., only Search campaigns will be returned. You may include multiple values as flags. How you specify multiple flags depends on the programming language that you use. For example, C# treats these values as flag values and Java treats them as an array of strings. The SOAP should include a string that contains a space-delimited list of values for example, Search Shopping.
The list of additional properties that you want included within each returned campaign. The additional field values enable you to get the latest features using the current version of Campaign Management API, and in the next version the corresponding elements will be included by default. This request element is optional.
The list of campaigns that were retrieved. If no campaigns exist, an empty array is returned.
A maximum of 100 identifiers of the campaigns to get from the specified account. The identifiers must correspond to campaigns of the specified CampaignType or types, and otherwise the service will return error code EntityIdFilterMismatch (Code 516).
The type of campaigns to get, for example Search, Shopping, or DynamicSearchAds. This request element is optional. If you do not set any campaign type, the default value is Search i.e., only Search campaigns will be returned. You may include multiple values as flags. How you specify multiple flags depends on the programming language that you use. For example, C# treats these values as flag values and Java treats them as an array of strings. The SOAP should include a string that contains a space-delimited list of values for example, Search Shopping.
An array of Campaign objects that corresponds directly to the campaign identifiers that you specified in the request. Items of the list may be returned as null. For each list index where a campaign was not retrieved, the corresponding element will be null.
An array of BatchError objects that contain details for any campaigns that were not successfully retrieved. The list of errors corresponds directly to the list of campaigns in the request. Items of the list may be returned as null. For each list index where a campaign was successfully retrieved, the corresponding error element will be null. Ideally all campaigns are retrieved successfully and all elements in this list are null.
The type of conversion goals to return. You may include multiple values as flags. How you specify multiple flags depends on the programming language that you use. For example, C# treats these values as flag values and Java treats them as an array of strings. The SOAP should include a string that contains a space-delimited list of values for example, Url Duration.
The list of additional properties that you want included within each returned conversion goal. The additional field values enable you to get the latest features using the current version of Campaign Management API, and in the next version the corresponding elements will be included by default. This request element is optional.
A maximum of 100 identifiers of the conversion goals that you want to get. If ConversionGoalIds is null or empty, then you are effectively requesting all conversion goals of the specified types for the account.
An array of ConversionGoal objects that corresponds directly to the conversion goal identifiers that you specified in the request. Items of the array may be returned as null. For each array index where a conversion goal was not retrieved, the corresponding element will be null.
A maximum of 100 tag identifiers that are used by the returned conversion goals.
The list of conversion goals do not correspond directly to the tag identifiers specified in the request because there can be multiple conversion goals that use the same tag identifier specified in the request.
Fetch conversion value rules from this account ID.
The conversion value rules associated with the specified account ID.
The IDs of the conversion value rules to fetch.
The conversion value rules that were succesfully fetched.
A list of the data exclusions associated with the specified account.
A list of the specified data exclusions associated with the specified account.
The identifier of the account that contains the specified entities.
A list of EntityIdToParentIdAssociation objects that each contain the unique system identifier of an entity such as ad or keyword, and the identifier of its parent. An ad group is the parent of an ad or keyword. The list must include all ads or all keywords which failed editorial review. The list cannot include a mix ads and keywords. The list can contain a maximum of 1,000 identifiers.
The type of entities that the entity list contains. The supported entity type values are Ad and Keyword.
An array of EditorialReasonCollection objects that corresponds directly to the EntityIdToParentIdAssociation objects that you specified in the request. Each object identifies the reason for the failure and whether it is appealable. Items of the list may be returned as null. For each list index where an EditorialReasonCollection was not retrieved, the corresponding element will be null. If the entity had not failed editorial review, the corresponding item in this collection is NULL. In addition, the item will be NULL if the specified ad or keyword identifier is not valid.
Return additional fields with the Experiment object.
The identifiers of the experiments to get. The maximum size of the list is 5,000 items per service request. If this element is not specified, the operation will return all active experiments in the ad account. An ad account can contain at most 5,000 experiments.
The zero-based results page index. For example to request the first page of results, set this value to 0 (zero).
The page size and the number of results to return in the specified page. The maximum size is 1,000. If you do not set this element the default size is 0 (zero).
An array of Experiment objects that corresponds directly to the experiment identifiers that you specified in the request. Items of the list may be returned as null. For each list index where an experiment was not retrieved, the corresponding element will be null.
The version of the location file that you want to download. Currently the only supported version is 2.0.
The language and locale of the geographical location display names. The supported language locale values are zh-Hant (Traditional Chinese), en (English), fr (French), de (German), it (Italian), ja-JP (Japanese), pt-BR (Brazilian Portuguese), and es (Spanish).
Defines the possible compression types for the file to download. Currently the only supported compression format is GZip. This request element is optional. If no value is passed, the API will continue to return uncompressed files.
The file URL that you can use to download the geographical location data for the version, language, and locale that you requested. Before you download the file, check whether the date and time of the LastModifiedTimeUtc element is later than the date and time of your previous download. You should only download the file if necessary.
The date and time that the geographical location data for the specified version, language, and locale was last updated. As a best practice you should store this date and time, and going forward only download the file if this value is updated to a later date and time. The value is in Coordinated Universal Time (UTC). The date and time value reflects the date and time at the server, not the client. For information about the format of the date and time, see the dateTime entry in Primitive XML Data Types.
The date and time that the provided file URL will expire. If you do not download the file prior to the expiration time, then you can call the operation again to request a new file URL. You might observe that the URL is set to expire 15 minutes from the time this operation completes; however, you should not depend on a fixed duration. Future calls to this operation might result in a shorter or longer expiration time. The value is in Coordinated Universal Time (UTC). The date and time value reflects the date and time at the server, not the client. For information about the format of the date and time, see the dateTime entry in Primitive XML Data Types.
The type of import job to get entity ID mappings. To get Google Ads to Microsoft Advertising entity ID mappings for each GoogleImportJob, set this element to "GoogleImportJob".
The source entity IDs that you want mapped to Microsoft Advertising entity IDs. If ImportEntityType is set to "Campaign" and ImportType is set to "GoogleImportJob", the operation will return Google Ads to Microsoft Advertising entity ID mappings. You can specify a maximum of 100 source IDs.
The type of entity to get ID mappings. For example, set this element to "Campaign" to get campaign ID mappings.
The resulting list of key and value pairs. Each key represents a source ID that you requested mappings for. The referenced key is the mapped Microsoft Advertising entity ID. If you requested a mapping with an invalid source ID, it will still be returned as the key but the referenced value will be set to 0 (zero).
The identifiers of the import jobs to get. You can specify a maximum of 100 import job IDs. If this element is not specified, the operation will return up to 500 import jobs in the ad account.
The type of import job to get. To get GoogleImportJob objects, set this element to "GoogleImportJob".
The import jobs that matched the request criteria.
The type of import job to get results. To get GoogleImportJob results, set this element to "GoogleImportJob".
Determines the index and size of import results per page. This request element is optional. If this element is not specified, the defaut page Index is 0 and the default Size is 1,000.
The identifiers of the import jobs to get results. You can specify a maximum of 100 identifiers. If this element is not specified, the operation will return results for all import jobs in the ad account within the last 90 days.
Contains the status, run time, and statistical results for each import that has run. Multiple results can be returned for the same import job e.g., results for a scheduled GoogleImportJob that has run more than once.
The unique Microsoft Advertising identifier of the import result.
The date and time the import job was run.
The settings in effect at the time the import job was run. If the ImportType of the GetImportResults operation was set to "GoogleImportJob", this element will include a GoogleImportJob object.
The statistical import results for each supported entity type. For more information, see the ImportEntityStatistics Remarks.
The URL where you can download the error logs. This element will be null or empty if there were no errors.
The type of entity eligible for import. For more information, see the remarks below.
The count of items added during import of the entity type.
The count of items changed or updated during import of the entity type.
The count of errors during import of the entity type.
The count of items deleted during import of the entity type.
The total count of additions, changes, deletions, and errors during import of the entity type.
The list of additional properties that you want included within each returned keyword. The additional field values enable you to get the latest features using the current version of Campaign Management API, and in the next version the corresponding elements will be included by default. This request element is optional.
The identifier of the ad group that keywords are returned for.
An array of Keyword objects that represents the retrieved keywords. If no keywords exist, an empty array is returned.
The review status of the keywords to retrieve.
The identifier of the ad group that contains the keywords to retrieve.
An array of Keyword objects that contains information about the keywords that were retrieved.
The identifier of the ad group whose keywords you want to get.
A maximum of 1,000 identifiers of the keywords to get.
An array of Keyword objects that corresponds directly to the keyword identifiers that you specified in the request. Items of the list may be returned as null. For each list index where a keyword was not retrieved, the corresponding element will be null.
Filters the returned associations by entity type. The supported entity type values are Campaign, AdGroup, Ad, and Keyword.
The list of entity identifiers used to request label associations. The maximum size of the list is 100 items per service request.
An array of label associations. For each entity identifier specified in the request, zero or more LabelAssociation objects are returned. Whereas the order of the returned LabelAssociation objects is guaranteed in the order of the requested entity identifiers, please note that multiple LabelAssociation objects can be returned for the same entity identifier.
The list of label identifiers used to request label associations. You must include exactly one label identifier in the list.
Determines the index and size of label association results per page. Up to 1,000 label associations will be returned per page, so you might need to request multiple pages to get all of the label associations. If this element is not specified, the defaut page Index is 0 and the default Size is 1,000.
An array of label associations. For each label identifier specified in the request, zero or more LabelAssociation objects are returned. Whereas the order of the returned LabelAssociation objects is guaranteed in the order of the requested label identifiers, please note that multiple LabelAssociation objects can be returned for the same label identifier. The entity identifiers are in ascending order for a given label's associations. It is possible to receive duplicate associations across multiple pages, so you should check for duplicate results.
The identifiers of the labels to get. The maximum size of the list is 1,000 items per service request. If this element is not specified, the operation will return all active labels in the account (1,000 results per page).
Determines the index and size of label results per page. This request element is optional. If this element is not specified, the defaut page Index is 0 and the default Size is 1,000.
An array of Label objects that corresponds directly to the label identifiers that you specified in the request. Items of the list may be returned as null. For each list index where a label was not retrieved, the corresponding element will be null.
The negative keyword list or website exclusion list. If the SharedEntityScope is either empty or set to Account, and if the SharedList is a NegativeKeywordList, then the returned list items will be negative keyword (NegativeKeyword) objects. If the SharedEntityScope is set to Customer, and if the SharedList is a PlacementExclusionList, then the returned list items will be negative site (NegativeSite) objects. You must include the Id of the SharedList when you make the service request.
Indicates whether the shared entity is available at the ad account (Account) or manager account (Customer) level. This element is optional and defaults to Account scope. The ad account scope is only applicable for negative keyword lists. Set this element to Customer to get the negative sites for a website exclusion list in your manager account (customer) shared library.
The list of negative keywords or negative sites. If no list items exist in the shared list, an empty array is returned.
The identifiers of the media to get corresponding entity associations. You can specify a maximum of 100 media identifiers in a single call.
Filters the results to only return media associations with the specified type of media enabled entity. The only supported media filter for this operation is ImageAdExtension.
An array of MediaAssociation objects that corresponds directly to the media identifiers that you specified in the request. Items of the list may be returned as null. For each list index where media associations were not retrieved, the corresponding element will be null.
Determines the type of media to get. Currently only ImageAdExtension is supported.
The system identifier of the media enabled entity, for example the identifier of an ImageAdExtension.
Determines the type of media enabled entity to get meta data. Supported values are ImageAdExtension and ResponsiveAd. You may include multiple values as flags. How you specify multiple flags depends on the programming language that you use. For example, C# treats these values as flag values and Java treats them as an array of strings. The SOAP should include a string that contains a space-delimited list of values for example, ImageAdExtension ResponsiveAd.
Determines the index and size of media meta data results per page. By default if this element is not specified, the defaut page Index is 0 and the default Size is 1,000.
The specified media meta data from the library. The meta data includes download URLs for one or more media representations.
The system identifier of the media meta data.
The name of the media subclass. For an ImageMediaRepresentation, the MediaType is Image.
The type of media in the library. For an ImageMediaRepresentation, the only possible value is ImageMediaRepresentation.
A list of ImageMediaRepresentation that each include download URLs for one or more media representations. The number of representations depends on the type of media. For image ad extensions the service will return exactly three ImageMediaRepresentation objects with varying height and width properties. For responsive ads the service will return exactly one ImageMediaRepresentation object. For more information see MediaEnabledEntityFilter.
The identifiers of the media to get. You can specify a maximum of 100 media identifiers in a single call.
An array of MediaMetaData objects that corresponds directly to the media identifiers that you specified in the request. Items of the list may be returned as null. For each list index where media meta data was not retrieved, the corresponding element will be null. The meta data includes download URLs for one or more media representations.
The type of entity corresponding to the specified EntityIds element. Possible values include AdGroup and Campaign.
An array of entity identifiers to return the associated negative keywords. The specified entities must all exist within the same parent entity, for example the ad group identifiers must all exist within the same campaign. This array can contain a maximum of 1 element.
The identifier of the parent entity corresponding to the specified EntityIds element. If the entity type is AdGroup, this element should be set to the campaign identifier that contains all of the specified ad groups. If the entity type is Campaign, the service uses the CustomerAccountId header element and this element is ignored.
An array of EntityNegativeKeyword objects that corresponds directly to the entity identifiers that you specified in the request. Items of the list may be returned as null. For each list index where negative keywords for an entity were not retrieved, the corresponding element will be null.
The identifier of the campaign that contains the ad groups.
An array of identifiers of the ad groups that contain the negative site URLs that you want to get. The call fails if the sum of all negative site URLs defined in the specified list of ad groups exceeds 30,000 URLs. To ensure that the call succeeds, consider limiting the number of ad groups to 15.
An array of AdGroupNegativeSites that corresponds directly to the ad group identifiers that you specified in the request. Items of the list may be returned as null. For each list index where an AdGroupNegativeSites was not retrieved, the corresponding element will be null.
The identifier of the account that contains the campaigns.
An array of identifiers of the campaigns that contain the negative site URLs that you want to get. The call fails if the sum of all negative site URLs defined in the specified list of campaigns exceeds 30,000 URLs. To ensure that the call succeeds, consider limiting the number of campaigns to 15.
An array of CampaignNegativeSites that corresponds directly to the campaign identifiers that you specified in the request. Items of the list may be returned as null. For each list index where an CampaignNegativeSites was not retrieved, the corresponding element will be null.
The start date of the report range in Coordinated Universal Time (UTC). The date range is up to 7 days.
The end date of the report range in Coordinated Universal Time (UTC). The date range is up to 7 days.
An array of conversion goal IDs used to filter the report. You can specify up to 20 goal IDs.
A bitwise combination of upload channel flags. If null, the report includes data from all channels.
An array containing daily conversion performance summaries, grouped by individual Goal ID.
An array of error objects for specific Goal IDs that failed to retrieve data. Returns successful data for some goals while reporting failures for others.
The unique identifier for the conversion goal.
The user-defined name of the conversion goal.
The total number of successful conversions attributed during the requested period.
The total number of conversions that couldn't be attributed to a click or valid goal.
The ratio of successful conversions to total uploads (Success / Total), represented with up to 6 decimal places.
A collection of aggregated error reasons explaining why conversions were unattributed.
A breakdown of performance metrics for each individual day within the requested range.
The number of times this specific error occurred.
The specific date the conversions were processed.
Successful conversions for this specific date.
Unattributed or failed conversions for this specific date.
The success rate for this specific date, up to 6 decimal places.
Error alerts specific to this date's uploads.
Determines whether you want industry or job function profile data. The CompanyName profile type is not supported for this service operation. You can use the SearchCompanies operation to search for profile data by company name.
The language and locale of the profile display names. The supported language locale values are zh-Hant (Traditional Chinese), en (English), fr (French), de (German), it (Italian), pt-BR (Brazilian Portuguese), and es (Spanish). Please note if LinkedIn does not provide the localized profile name, then it will default to the universal name (usually defined in English).
The file URL that you can use to download the profile data for the profile type, language, and locale that you requested. Before you download the file, check whether the date and time of the LastModifiedTimeUtc element is later than the date and time of your previous download. You should only download the file if necessary.
The date and time that the profile data for the profile type, language, and locale was last updated. As a best practice you should store this date and time, and going forward only download the file if this value is updated to a later date and time. The value is in Coordinated Universal Time (UTC). The date and time value reflects the date and time at the server, not the client. For information about the format of the date and time, see the dateTime entry in Primitive XML Data Types.
A responsive ad format for audience ads and multimedia ads.
A list of ad recommendation image suggestion.
A list of ad recommendation video suggestions.
The ad recommendation job info data object.
A list of the seasaonality adjustments associated with the specified account.
A list of the specified seasonality adjustments.
The type of shared entity to get from the ad account shared library. Set this element to NegativeKeywordList to get negative keyword lists (NegativeKeywordList) in your ad account shared library.
The negative keyword lists from the shared library.
The type of shared entity to get from the ad account or manager account (customer) library. Set this element to NegativeKeywordList to get negative keyword lists (NegativeKeywordList) in your ad account shared library. Set this element to PlacementExclusionList to get website exclusion lists (PlacementExclusionList) in your manager account (customer) shared library.
Indicates whether the shared entity is available at the ad account (Account) or manager account (Customer) level. This element is optional and defaults to Account scope. The ad account scope is only applicable for negative keyword lists. Set this element to Customer to get website exclusion lists in your manager account (customer) shared library.
The negative keyword lists or website exclusion lists.
The list of either campaign or ad account identifiers. This array can contain a maximum of 100 elements.
The type of entity corresponding to the specified EntityIds element. Set this element to "Campaign" to get negative keyword list to campaign associations, or brand exclusion or inclusion list to campaign associations in your ad account shared library. Set this element to "Account" to get website exclusion list to ad account associations in your manager account (customer) shared library.
The type of shared entity to get associations. Set this element to "NegativeKeywordList" to get negative keyword list to campaign associations in your ad account shared library. Set this element to "PlacementExclusionList" to get website exclusion list to ad account associations in your manager account (customer) shared library.
Indicates whether the shared entity is available at the ad account (Account) or manager account (Customer) level. This element is optional and defaults to Account scope. The ad account scope is only applicable for negative keyword list to campaign associations. Set this element to Customer to get website exclusion list to ad account associations in your manager account (customer) shared library.
An array of SharedEntityAssociation objects that corresponds directly to the entity identifiers that you specified in the request. Items of the list may be returned as null. For each list index where an association was not retrieved, the corresponding element will be null.
The type of entity corresponding to the specified SharedEntityIds element. Set this element to "Campaign" to get negative keyword list to campaign associations in your ad account shared library. Set this element to "Account" to get website exclusion list to ad account associations in your manager account (customer) shared library.
The list of either negative keyword list or website exclusion list identifiers. This array can contain a maximum of one element.
An array of SharedEntityAssociation objects that corresponds directly to the shared entity identifiers that you specified in the request. Items of the list may be returned as null. For each list index where an association was not retrieved, the corresponding element will be null.
The unique identifier of the UET tag used to retrieve or generate an authentication key.
The authentication key associated with the specified UET tag. If no key exists, one is generated and returned. Subsequent requests return the same key.
An array of BatchError objects containing error details.
The list of additional properties that you want included within each returned UetTag object.
A maximum of 100 identifiers of the UET tags that you want to get. If TagIds is null or empty, then you are effectively requesting all UET tags that are available for the customer.
An array of UetTag objects that corresponds directly to the UET tag identifiers that you specified in the request. Items of the array may be returned as null. For each array index where a UET tag was not retrieved, the corresponding element will be null.
The identifiers of the videos to get. The maximum size of the list is 1,000 items per service request. If this element is not specified, the operation will return all active videos in the account (1,000 results per page).
Determines the index and size of video results per page. This request element is optional. If this element is not specified, the defaut page Index is 0 and the default Size is 1,000.
An array of Video objects that corresponds directly to the video identifiers that you specified in the request. Items of the list may be returned as null. For each list index where a video was not retrieved, the corresponding element will be null.
The name of the import job. The name can be between 1 to 255 characters in length. Add: Required Update: Read-only
The unique Microsoft Advertising identifier of the import job. Add: Read-only Update: Read-only
The type of the import job. This value is GoogleImportJob when you retrieve a Google import job. For more information about import job types, see the ImportJob Data Object Remarks. Add: Read-only Update: Read-only
Determines whether and how often you want to receive email notifications about the import job results. The supported values are "None" (No emails), "Changes" (Only if there are changes or errors), "Errors" (Only if there are errors), and "EveryTime" (Every time this import runs). Add: Optional. If not set, the service sets this element to "None" by default. Update: Optional. If no value is set for the update, this setting is not changed.
The unique identifier of the Microsoft Advertising user who created the import job. Add: Read-only Update: Read-only
The login user name of the Microsoft Advertising user who created the import job. Add: Read-only Update: Read-only
Determines whether the import job should be run once or scheduled on a recurring basis. To run the import job now, this element must be nil or empty. Add: Optional Update: Optional. If no value is set for the update, this setting is not changed.
The most recent import date and time for this job. The date and time is expressed in Coordinated Universal Time (UTC). Add: Read-only Update: Read-only
The date and time when the import job was created. The date and time is expressed in Coordinated Universal Time (UTC). Add: Read-only Update: Read-only
The Google import options that are available via API. To customize Google import options, you can include a GoogleImportOption object. Otherwise to use the default Google import options, you can leave this element nil or empty. For more information about default options, see GoogleImportOption. Add: Optional Update: Optional. If no value is set for the update, this setting is not changed.
The email address where import results should be sent. This element is not returned by default. To get this element, include the NotificationEmail value in the ReturnAdditionalFields element when you call the GetImportJobsByIds and GetImportResults service operations. Add: Optional Update: Optional. If no value is set for the update, this setting is not changed.
Authorizes a Google Ads user to import accounts to Microsoft Advertising. This element is not returned when you get the GoogleImportJob. See the Get an Import Credential ID guide for more details. Add: Required Update: Read-only
The Google Ads account to import. Add: Required Update: Read-only
The list of campaigns and their ad groups to import from Google Ads. The identifiers are saved but not validated when you create an import job. If you include invalid campaign or ad group IDs, or if they become invalid e.g., the entities are deleted later from Google Ads, the invalid entities will be skipped during import. Add: Optional. If this element is not set, then all of the campaigns and ad groups in the Google Ads account are eligible for import. The set of imported entities also depends on your import options. Update: Optional. If no value is set for the update, this setting is not changed.
The Google account i.e., the Google user credentials with access to the Google Ads account. Add: Read-only Update: Read-only
The type of the import option. This value is GoogleImportOption when you retrieve a Google import option. For more information about import option types, see the ImportOption Data Object Remarks.
The prerequisite option for importing new entities and settings into Microsoft Advertising. If this element is set false, the following options are ignored: NewActiveAdsForExistingAdGroups, NewActiveCampaignsAndChildEntities, NewAdCustomizerFeeds, NewAdGroupsAndChildEntitiesForExistingCampaigns, NewAdSchedules, NewAppAdExtensions, NewAudienceTargets, NewCallAdExtensions, NewCalloutAdExtensions, NewDemographicTargets, NewDeviceTargets, NewKeywordsForExistingAdGroups, NewKeywordUrls, NewLabels, NewLocationAdExtensions, NewLocationTargets, NewNegativeKeywordLists, NewNegativeKeywordsForExistingParents, NewNegativeSites, NewPageFeeds, NewPausedAdsForExistingAdGroups, NewPausedCampaignsAndChildEntities, NewPriceAdExtensions, NewProductFilters, NewReviewAdExtensions, NewSitelinkAdExtensions, NewStructuredSnippetAdExtensions, NewUrlOptions. This option is enabled by default, or effectively set to true. Set this element false to turn off this option. This option is available in the Microsoft Advertising UI via Import from Google Ads > Choose import options > What to import > Items not previously imported into Microsoft Advertising.
Import paused campaigns along with your active campaigns. The NewActiveCampaignsAndChildEntities option must also be enabled, otherwise this option is effectively ignored. This option is turned off by default, or effectively set to false. Set this element true to enable this option. This option is available in the Microsoft Advertising UI via Import from Google Ads > Choose import options > Other options > Campaign options > Include paused campaigns when importing new items.
Import active campaigns that have not previously been imported. The import will include all ad groups, active ads, and keywords that the new campaigns contain. To also import paused campaigns, ensure that the NewPausedCampaignsAndChildEntities option is enabled. To also import paused ads, ensure that the NewPausedAdsForExistingAdGroups option is enabled. This option is enabled by default, or effectively set to true. Set this element false to turn off this option. This option is available in the Microsoft Advertising UI via Import from Google Ads > Choose import options > What to import > Items not previously imported into Microsoft Advertising > Import items > Campaigns.
Import new ad groups within existing campaigns. The import will include all active ads and keywords that the new ad groups contain. To also import paused ads, ensure that the NewPausedAdsForExistingAdGroups option is enabled. This option is enabled by default, or effectively set to true. Set this element false to turn off this option. This option is available in the Microsoft Advertising UI via Import from Google Ads > Choose import options > What to import > Items not previously imported into Microsoft Advertising > Import items > Ad groups for existing campaigns.
Import new active ads within existing ad groups. To also import paused ads, ensure that the NewPausedAdsForExistingAdGroups option is enabled. This option is enabled by default, or effectively set to true. Set this element false to turn off this option. This option is available in the Microsoft Advertising UI via Import from Google Ads > Choose import options > What to import > Items not previously imported into Microsoft Advertising > Import items > Ads for existing ad groups.
Import new keywords within existing ad groups. This option is enabled by default, or effectively set to true. Set this element false to turn off this option. This option is available in the Microsoft Advertising UI via Import from Google Ads > Choose import options > What to import > Items not previously imported into Microsoft Advertising > Import items > Keywords for existing ad groups.
Import new negative keywords for existing campaigns or existing ad groups. This option is enabled by default, or effectively set to true. Set this element false to turn off this option. This option is available in the Microsoft Advertising UI via Import from Google Ads > Choose import options > What to import > Items not previously imported into Microsoft Advertising > Import items > Negative keywords for existing campaigns and ad groups.
Import negative keyword lists that have not previously been imported. This option is enabled by default, or effectively set to true. Set this element false to turn off this option. This option is available in the Microsoft Advertising UI via Import from Google Ads > Choose import options > What to import > Items not previously imported into Microsoft Advertising > Import items > Negative keyword lists.
Import account negative keywords that have not previously been imported. This option is enabled by default, or effectively set to true. Set this element false to turn off this option. This option is available in the Microsoft Advertising UI via Import from Google Ads > Choose import options > What to import > Items not previously imported into Microsoft Advertising > Import items > Account negative keywords.
This option will pause newly imported campaigns allowing you to review your campaigns before you get your campaigns up and running. This option is turned off by default, or effectively set to false. Set this element true to enable this option. This option is available in the Microsoft Advertising UI via Import from Google Ads > Choose import options > Other options > Campaign options > Pause newly imported campaigns.
Import new keyword landing page URLs. This option is enabled by default, or effectively set to true. Set this element false to turn off this option. This option is available in the Microsoft Advertising UI via Import from Google Ads > Choose import options > What to import > Items not previously imported into Microsoft Advertising > Import items > Keyword landing page URLs.
Import tracking templates, custom parameters, and final URL suffix URL options with entities that have not previously been imported. This option is enabled by default, or effectively set to true. Set this element false to turn off this option. This option is available in the Microsoft Advertising UI via Import from Google Ads > Choose import options > What to import > Items not previously imported into Microsoft Advertising > Import items > Tracking templates, custom parameters, and final URL suffixes.
Import new negative sites for existing campaigns or existing ad groups. This option is enabled by default, or effectively set to true. Set this element false to turn off this option. This option is available in the Microsoft Advertising UI via Import from Google Ads > Choose import options > What to import > Items not previously imported into Microsoft Advertising > Import items > Negative sites.
Import paused ads along with your active ads. The NewActiveAdsForExistingAdGroups option must also be enabled, otherwise this option is effectively ignored. This option is turned off by default, or effectively set to false. Set this element true to enable this option. This option is available in the Microsoft Advertising UI via Import from Google Ads > Choose import options > Other options > Ad options > Include paused ads when importing new ads.
Import labels that have not previously been imported. Label associations are only imported if you also import the corresponding new entities. This option is enabled by default, or effectively set to true. Set this element false to turn off this option. This option is available in the Microsoft Advertising UI via Import from Google Ads > Choose import options > What to import > Items not previously imported into Microsoft Advertising > Import items > Labels.
Import new product filters from your shopping campaigns. This option is enabled by default, or effectively set to true. Set this element false to turn off this option. This option is available in the Microsoft Advertising UI via Import from Google Ads > Choose import options > What to import > Items not previously imported into Microsoft Advertising > Import items > Product filters.
Import location targets that have not previously been imported. This option is enabled by default, or effectively set to true. Set this element false to turn off this option. This option is available in the Microsoft Advertising UI via Import from Google Ads > Choose import options > What to import > Items not previously imported into Microsoft Advertising > Targeting > Location targets.
Import ad schedules that have not previously been imported. This option is enabled by default, or effectively set to true. Set this element false to turn off this option. This option is available in the Microsoft Advertising UI via Import from Google Ads > Choose import options > What to import > Items not previously imported into Microsoft Advertising > Targeting > Ad schedules.
Import device targets that have not previously been imported. This option is enabled by default, or effectively set to true. Set this element false to turn off this option. This option is available in the Microsoft Advertising UI via Import from Google Ads > Choose import options > What to import > Items not previously imported into Microsoft Advertising > Targeting > Device targets.
Import demographic targets that have not previously been imported. This option is enabled by default, or effectively set to true. Set this element false to turn off this option. This option is available in the Microsoft Advertising UI via Import from Google Ads > Choose import options > What to import > Items not previously imported into Microsoft Advertising > Targeting > Demographic targets.
Import campaign and ad group targets and exclusions for in-market audiences. Targets and exclusions for remarketing lists and combined lists can be imported if a valid UET tag identifier is set via the AssociatedUetTagId element. As support is added for import of additional audience types in the future, the corresponding lists, targets, and exclusions will also be imported if this option is enabled. This option is enabled by default, or effectively set to true. Set this element false to turn off this option. This option is available in the Microsoft Advertising UI via Import from Google Ads > Choose import options > What to import > Items not previously imported into Microsoft Advertising > Targeting > Audience targets.
Import topic targets that haven't previously been imported. This option is enabled by default, or effectively set to true. Set this element false to turn off this option. This option is available in the Microsoft Advertising UI via Import from Google Ads > Choose import options > What to import > Items not previously imported into Microsoft Advertising > Targeting > Topic targets.
Import app extensions that have not previously been imported. This option is enabled by default, or effectively set to true. Set this element false to turn off this option. This option is available in the Microsoft Advertising UI via Import from Google Ads > Choose import options > What to import > Items not previously imported into Microsoft Advertising > Ad extensions > App Extensions.
Import call extensions that have not previously been imported. This option is enabled by default, or effectively set to true. Set this element false to turn off this option. This option is available in the Microsoft Advertising UI via Import from Google Ads > Choose import options > What to import > Items not previously imported into Microsoft Advertising > Ad extensions > Call Extensions.
Import callout extensions that have not previously been imported. This option is enabled by default, or effectively set to true. Set this element false to turn off this option. This option is available in the Microsoft Advertising UI via Import from Google Ads > Choose import options > What to import > Items not previously imported into Microsoft Advertising > Ad extensions > Callout Extensions.
Import price extensions that have not previously been imported. This option is enabled by default, or effectively set to true. Set this element false to turn off this option. This option is available in the Microsoft Advertising UI via Import from Google Ads > Choose import options > What to import > Items not previously imported into Microsoft Advertising > Ad extensions > Price Extensions.
Import location extensions that have not previously been imported. This option is enabled by default, or effectively set to true. Set this element false to turn off this option. This option is available in the Microsoft Advertising UI via Import from Google Ads > Choose import options > What to import > Items not previously imported into Microsoft Advertising > Ad extensions > Location Extensions.
Import review extensions that have not previously been imported. This option is enabled by default, or effectively set to true. Set this element false to turn off this option. This option is available in the Microsoft Advertising UI via Import from Google Ads > Choose import options > What to import > Items not previously imported into Microsoft Advertising > Ad extensions > Review Extensions.
Import sitelink extensions that have not previously been imported. This option is enabled by default, or effectively set to true. Set this element false to turn off this option. This option is available in the Microsoft Advertising UI via Import from Google Ads > Choose import options > What to import > Items not previously imported into Microsoft Advertising > Ad extensions > Sitelink Extensions.
Import structured snippet extensions that have not previously been imported. This option is enabled by default, or effectively set to true. Set this element false to turn off this option. This option is available in the Microsoft Advertising UI via Import from Google Ads > Choose import options > What to import > Items not previously imported into Microsoft Advertising > Ad extensions > Structured Snippet Extensions.
Import promotion extensions that have not previously been imported. This option is enabled by default, or effectively set to true. Set this element false to turn off this option. This option is available in the Microsoft Advertising UI via Import from Google Ads > Choose import options > What to import > Items not previously imported into Microsoft Advertising > Ad extensions > Promotion Extensions.
Import logo ad extensions that have not previously been imported. This option is enabled by default, or effectively set to true. Set this element false to turn off this option. This option is available in the Microsoft Advertising UI via Import from Google Ads > Choose import options > What to import > Items not previously imported into Microsoft Advertising > Ad extensions > Logo Ad Extensions.
Import page feeds that have not previously been imported. This option is enabled by default, or effectively set to true. Set this element false to turn off this option. This option is available in the Microsoft Advertising UI via Import from Google Ads > Choose import options > What to import > Items not previously imported into Microsoft Advertising > Feeds > Page feeds.
Import ad customizer feeds that have not previously been imported. This option is enabled by default, or effectively set to true. Set this element false to turn off this option. This option is available in the Microsoft Advertising UI via Import from Google Ads > Choose import options > What to import > Items not previously imported into Microsoft Advertising > Feeds > Ad customizer feeds.
Import brand suitability that has not previously been imported. This option is enabled by default, or effectively set to true. Set this element false to turn off this option. This option is available in the Microsoft Advertising UI via Import from Google Ads > Choose import options > What to import > Items not previously imported into Microsoft Advertising > Brand Suitability
Import conversion goals that have not previously been imported. This option is enabled by default, or effectively set to true. Set this element false to turn off this option. This option is available in the Microsoft Advertising UI via Import from Google Ads > Choose import options > What to import > UET tag > Conversion goals.
Import AI Max settings that haven not previously been imported. This option is enabled by default, or effectively set to true. Set this element false to turn off this option. This option is available in the Microsoft Advertising UI via Import from Google Ads > Choose import options > Targeting > AI Max settings.
The prerequisite option for importing updated entities and settings into Microsoft Advertising. The service will import updates for previously imported items to match those currently in Google Ads. If this element is set false, the following options are ignored: UpdateAdCustomizerFeeds, UpdateAdCustomizerFeeds, UpdateAdGroupNetwork, UpdateAdSchedules, UpdateAppAdExtensions, UpdateAudienceTargets, UpdateCallAdExtensions, UpdateCalloutAdExtensions, UpdateDemographicTargets, UpdateDeviceTargets, UpdateKeywordUrls, UpdateLabels, UpdateLocationAdExtensions, UpdateLocationTargets, UpdateNegativeKeywordLists, UpdateNegativeSites, UpdatePageFeeds, UpdatePriceAdExtensions, UpdateProductFilters, UpdateReviewAdExtensions, UpdateSitelinkAdExtensions, UpdateStructuredSnippetAdExtensions, UpdateUrlOptions. This option is equivalent to the "Updates to existing items" checkbox in the Microsoft Advertising UI. This option is enabled by default, or effectively set to true. Set this element false to turn off this option. This option is available in the Microsoft Advertising UI via Import from Google Ads > Choose import options > What to import > Updates to existing items.
When enabled this option fetches updates to existing campaign budgets that are now in Microsoft Advertising. This option is only honored if UpdateEntities is also enabled. This option is enabled by default, or effectively set to true. Set this element false to turn off this option. This option is available in the Microsoft Advertising UI via Import from Google Ads > Choose import options > Bids and budgets > Update existing campaign budgets.
When enabled this option allows you to update the existing keywords, auto-targets, and product ads bid types to match those currently in Google Ads. This option is only honored if UpdateEntities is also enabled. This option is enabled by default, or effectively set to true. Set this element false to turn off this option. This option is available in the Microsoft Advertising UI via Import from Google Ads > Choose import options > Bids and budgets > Update bids.
Import updates to existing negative keyword lists. This option is only honored if UpdateEntities is also enabled. This option is enabled by default, or effectively set to true. Set this element false to turn off this option. This option is available in the Microsoft Advertising UI via Import from Google Ads > Choose import options > What to import > Updates to existing items > Campaign settings > Negative keyword lists.
Import updates to existing account negative keywords. This option is only honored if UpdateEntities is also enabled. This option is enabled by default, or effectively set to true. Set this element false to turn off this option. This option is available in the Microsoft Advertising UI via Import from Google Ads > Choose import options > What to import > Updates to existing items > Campaign settings > Account negative keywords.
Import updates to negative sites for existing campaigns and ad groups. This option is only honored if UpdateEntities is also enabled. This option is enabled by default, or effectively set to true. Set this element false to turn off this option. This option is available in the Microsoft Advertising UI via Import from Google Ads > Choose import options > What to import > Updates to existing items > Campaign settings > Negative sites.
Import updates to existing keyword landing page URLs. This option is only honored if UpdateEntities is also enabled. This option is enabled by default, or effectively set to true. Set this element false to turn off this option. This option is available in the Microsoft Advertising UI via Import from Google Ads > Choose import options > What to import > Updates to existing items > Campaign settings > Keyword landing page URLs.
Import updates to the tracking templates, custom parameters, and final URL suffix of existing entities. This option is only honored if UpdateEntities is also enabled. This option is enabled by default, or effectively set to true. Set this element false to turn off this option. This option is available in the Microsoft Advertising UI via Import from Google Ads > Choose import options > What to import > Updates to existing items > Campaign settings > Tracking templates, custom parameters, and final URL suffixes.
By enabling this option Microsoft Advertising will update the names of previously imported campaigns if the name was updated in Google Ads. However, settings and items linked to those campaigns can still be updated. Existing campaigns will be updated if the original items were created by an import after March 21, 2016. Otherwise, new campaign names will be created. This option is only applicable for existing campaigns and will not affect new campaigns. This option is enabled by default, or effectively set to true. Set this element false to turn off this option. This option is available in the Microsoft Advertising UI via Import from Google Ads > Choose import options > Other options > Campaign options > Do not update existing campaign names.
Import updates to existing labels. This option is only honored if UpdateEntities is also enabled. This option is enabled by default, or effectively set to true. Set this element false to turn off this option. This option is available in the Microsoft Advertising UI via Import from Google Ads > Choose import options > What to import > Updates to existing items > Campaign settings > Labels.
When enabled this option updates product filters in shopping campaigns to match those currently in Google Ads. This option is only honored if UpdateEntities is also enabled. This option is enabled by default, or effectively set to true. Set this element false to turn off this option. This option is available in the Microsoft Advertising UI via Import from Google Ads > Choose import options > What to import > Updates to existing items > Campaign settings > Product filters.
Import updates to existing conversion goals. This option is only honored if UpdateEntities is also enabled. This option is enabled by default, or effectively set to true. Set this element false to turn off this option. This option is available in the Microsoft Advertising UI via Import from Google Ads > Choose import options > What to import > Updates to existing items > UET tag > conversion goals.
Import updates to existing location targets. This option is only honored if UpdateEntities is also enabled. This option is enabled by default, or effectively set to true. Set this element false to turn off this option. This option is available in the Microsoft Advertising UI via Import from Google Ads > Choose import options > What to import > Updates to existing items > Targeting > Location targets.
Import updates to existing ad schedules. This option is only honored if UpdateEntities is also enabled. This option is enabled by default, or effectively set to true. Set this element false to turn off this option. This option is available in the Microsoft Advertising UI via Import from Google Ads > Choose import options > What to import > Updates to existing items > Targeting > Ad schedules.
Import updates to existing device targets. This option is only honored if UpdateEntities is also enabled. This option is enabled by default, or effectively set to true. Set this element false to turn off this option. This option is available in the Microsoft Advertising UI via Import from Google Ads > Choose import options > What to import > Updates to existing items > Targeting > Device targets.
Import updates to existing demographic targets. This option is only honored if UpdateEntities is also enabled. This option is enabled by default, or effectively set to true. Set this element false to turn off this option. This option is available in the Microsoft Advertising UI via Import from Google Ads > Choose import options > What to import > Updates to existing items > Targeting > Demographic targets.
Import updates to the language of existing campaigns and ad groups. This option is only honored if UpdateEntities is also enabled. This option is enabled by default, or effectively set to true. Set this element false to turn off this option. This option is available in the Microsoft Advertising UI via Import from Google Ads > Choose import options > What to import > Updates to existing items > Campaign settings > Campaign and ad group languages.
Import updates to existing audience targets. This option is only honored if UpdateEntities is also enabled. This option is enabled by default, or effectively set to true. Set this element false to turn off this option. This option is available in the Microsoft Advertising UI via Import from Google Ads > Choose import options > What to import > Updates to existing items > Targeting > Audience targets.
Import updates to existing topic targets. This option is only honored if UpdateEntities is also enabled. This option is enabled by default, or effectively set to true. Set this element false to turn off this option. This option is available in the Microsoft Advertising UI via Import from Google Ads > Choose import options > What to import > Updates to existing items > Targeting > Topic targets.
Import updates to existing app extensions. This option is only honored if UpdateEntities is also enabled. This option is enabled by default, or effectively set to true. Set this element false to turn off this option. This option is available in the Microsoft Advertising UI via Import from Google Ads > Choose import options > What to import > Updates to existing items > Ad extensions > App Extensions.
Import updates to existing call extensions. This option is only honored if UpdateEntities is also enabled. This option is enabled by default, or effectively set to true. Set this element false to turn off this option. This option is available in the Microsoft Advertising UI via Import from Google Ads > Choose import options > What to import > Updates to existing items > Ad extensions > Call Extensions.
Import updates to existing callout extensions. This option is only honored if UpdateEntities is also enabled. This option is enabled by default, or effectively set to true. Set this element false to turn off this option. This option is available in the Microsoft Advertising UI via Import from Google Ads > Choose import options > What to import > Updates to existing items > Ad extensions > Callout Extensions.
Import updates to existing price extensions. This option is only honored if UpdateEntities is also enabled. This option is enabled by default, or effectively set to true. Set this element false to turn off this option. This option is available in the Microsoft Advertising UI via Import from Google Ads > Choose import options > What to import > Updates to existing items > Ad extensions > Price Extensions.
Import updates to existing location extensions. This option is only honored if UpdateEntities is also enabled. This option is enabled by default, or effectively set to true. Set this element false to turn off this option. This option is available in the Microsoft Advertising UI via Import from Google Ads > Choose import options > What to import > Updates to existing items > Ad extensions > Location Extensions.
Import updates to existing review extensions. This option is only honored if UpdateEntities is also enabled. This option is enabled by default, or effectively set to true. Set this element false to turn off this option. This option is available in the Microsoft Advertising UI via Import from Google Ads > Choose import options > What to import > Updates to existing items > Ad extensions > Review Extensions.
Import updates to existing sitelink extensions. This option is only honored if UpdateEntities is also enabled. This option is enabled by default, or effectively set to true. Set this element false to turn off this option. This option is available in the Microsoft Advertising UI via Import from Google Ads > Choose import options > What to import > Updates to existing items > Ad extensions > Sitelink Extensions.
Import updates to existing structured snippet extensions. This option is only honored if UpdateEntities is also enabled. This option is enabled by default, or effectively set to true. Set this element false to turn off this option. This option is available in the Microsoft Advertising UI via Import from Google Ads > Choose import options > What to import > Updates to existing items > Ad extensions > Structured Snippet Extensions.
Import updates to existing promotion extensions. This option is only honored if UpdateEntities is also enabled. This option is enabled by default, or effectively set to true. Set this element false to turn off this option. This option is available in the Microsoft Advertising UI via Import from Google Ads > Choose import options > What to import > Updates to existing items > Ad extensions > Promotion Extensions.
Import updates to existing logo ad extensions. This option is only honored if UpdateEntities is also enabled. This option is enabled by default, or effectively set to true. Set this element false to turn off this option. This option is available in the Microsoft Advertising UI via Import from Google Ads > Choose import options > What to import > Updates to existing items > Ad extensions > Logo Ad Extensions.
Import updates to the status of existing campaigns. This option is only honored if UpdateEntities is also enabled. This option is enabled by default, or effectively set to true. Set this element false to turn off this option. This option is available in the Microsoft Advertising UI via Import from Google Ads > Choose import options > What to import > Updates to existing items > Status > Campaign status.
Import updates to the status of existing ad groups. This option is only honored if UpdateEntities is also enabled. This option is enabled by default, or effectively set to true. Set this element false to turn off this option. This option is available in the Microsoft Advertising UI via Import from Google Ads > Choose import options > What to import > Updates to existing items > Status > Ad group status.
Import updates to the status of existing ads. This option is only honored if UpdateEntities is also enabled. This option is enabled by default, or effectively set to true. Set this element false to turn off this option. This option is available in the Microsoft Advertising UI via Import from Google Ads > Choose import options > What to import > Updates to existing items > Status > Ad status.
Import updates to the status of existing keywords. This option is only honored if UpdateEntities is also enabled. This option is enabled by default, or effectively set to true. Set this element false to turn off this option. This option is available in the Microsoft Advertising UI via Import from Google Ads > Choose import options > What to import > Updates to existing items > Status > Keyword status.
Import updates to the ad distribution of existing ad groups. This option is only honored if UpdateEntities is also enabled. This option is enabled by default, or effectively set to true. Set this element false to turn off this option. This option is available in the Microsoft Advertising UI via Import from Google Ads > Choose import options > What to import > Updates to existing items > Campaign settings > Ad distribution.
Import updates to existing page feeds. This option is only honored if UpdateEntities is also enabled. This option is enabled by default, or effectively set to true. Set this element false to turn off this option. This option is available in the Microsoft Advertising UI via Import from Google Ads > Choose import options > What to import > Updates to existing items > Feeds > Page feeds.
Import updates to existing ad customizer feeds. This option is only honored if UpdateEntities is also enabled. This option is enabled by default, or effectively set to true. Set this element false to turn off this option. This option is available in the Microsoft Advertising UI via Import from Google Ads > Choose import options > What to import > Updates to existing items > Feeds > Ad customizer feeds.
Import updates to brand suitablity. This option is only honored if UpdateEntities is also enabled. This option is enabled by default, or effectively set to true. Set this element false to turn off this option. This option is available in the Microsoft Advertising UI via Import from Google Ads > Choose import options > What to import > Updates to existing items > Brand Suitability.
Import updates to existing ad customizer feeds. This option is only honored if UpdateEntities is also enabled. This option is enabled by default, or effectively set to true. Set this element false to turn off this option. This option is available in the Microsoft Advertising UI via Import from Google Ads > Choose import options > What to import > Updates to existing items > Feeds > Ad customizer attributes.
Import updates to AI Max settings. This option is enabled by default, or effectively set to true. Set this element false to preserve existing Microsoft AI Max settings. This option is available in the Microsoft Advertising UI via Import from Google Ads > Choose import options > Targeting > AI Max settings.
Removed Google Ads items will be deleted along with their associated sub-items. For example if you removed a Google Ads campaign since the previous import, then the campaign and its ad groups, ads, and keywords will be removed from Microsoft Advertising when the import runs next time. Likewise, if you removed your Google Ads account level tracking template or final URL suffix since the previous import, they will be deleted from Microsoft Advertising. Ad extensions removed in Google Ads will not be deleted in Microsoft Advertising. This option is turned off by default, or effectively set to false. Set this element true to enable this option. This option is available in the Microsoft Advertising UI via Import from Google Ads > Choose import options > What to import > Delete items that have been removed from your Google Ads account.
Due to differences in Microsoft Advertising and Google Ads minimum bid requirements any bids below the our minimum amount will automatically be raised during import. This means that the amount of money you spend overall may increase for the imported campaigns. If you decide to opt out of increasing the minimum bid during import any campaigns that don't meet the minimum amount will not get imported. This option is enabled by default, or effectively set to true. Set this element false to turn off this option. This option is available in the Microsoft Advertising UI via Import from Google Ads > Choose import options > Bids and budgets > Set unknown ad group bids to the recommended value for Microsoft Advertising.
Due to differences in Microsoft Advertising and Google Ads minimum bid and budget requirements any budgets below our minimum amount will automatically be raised during import. This means that the amount of money you spend overall may increase for the imported campaigns. If you decide to opt out of increasing the minimum budget during import any campaigns that don't meet the minimum amount will not get imported. This option is enabled by default, or effectively set to true. Set this element false to turn off this option. This option is available in the Microsoft Advertising UI via Import from Google Ads > Choose import options > Bids and budgets > Increase campaign budgets to the minimum for Microsoft Advertising.
The percentage amount that you want to increase or decrease the new or existing Microsoft Advertising campaign budgets relative to your Google Ads campaign budgets. The valid bid multiplier range is -90 through 900. For example, to increase the Microsoft Advertising campaign budgets 25 percent higher than your Google Ads campaign budgets, set this element to 25. This option is available in the Microsoft Advertising UI via Import from Google Ads > Choose import options > Bids and budgets > Customize budgets for Microsoft Advertising.
The percentage amount that you want to increase or decrease the new or existing Microsoft Advertising bids relative to your Google Ads bids. The valid bid multiplier range is -90 through 900. For example, to increase the Microsoft Advertising bids 25 percent higher than your Google Ads bids, set this element to 25. This option is available in the Microsoft Advertising UI via Import from Google Ads > Choose import options > Bids and budgets > Customize bids for Microsoft Advertising.
Set this option to insert a string at the end of each final URL, mobile URL, and destination URL during import. This option is available in the Microsoft Advertising UI via Import from Google Ads > Choose import options > Other options > Landing page URLs > Insert at the end of each final URL, mobile URL, and destination URL.
Set this option to find and replace a string within each final URL, mobile URL, and destination URL during import. When you update import options via UpdateImportJobs you can remove, update, or leave in place the prior search and replace settings. For details please see the remarks below. This option is available in the Microsoft Advertising UI via Import from Google Ads > Choose import options > Other options > Landing page URLs > Find and replace text in each final URL, mobile URL, and destination URL.
Set this option to insert a string at the end of each tracking template during import. This option is available in the Microsoft Advertising UI via Import from Google Ads > Choose import options > Other options > Tracking templates > Insert at the end of each tracking template.
Set this option to find and replace a string within each tracking template during import. When you update import options via UpdateImportJobs you can remove, update, or leave in place the prior search and replace settings. For details please see the remarks below. This option is available in the Microsoft Advertising UI via Import from Google Ads > Choose import options > Other options > Tracking templates > Find and replace text in each tracking template.
Set this option to insert a string at the end of each campaign name during import. This option is available in the Microsoft Advertising UI via Import from Google Ads > Choose import options > Other options > Campaign options > Insert at the end of each campaign name.
Set this option to find and replace a string within each campaign name during import. When you update import options via UpdateImportJobs you can remove, update, or leave in place the prior search and replace settings. For details please see the remarks below. This option is available in the Microsoft Advertising UI via Import from Google Ads > Choose import options > Other options > Campaign options > Find and replace text in each campaign name.
Set this option to find and replace a string within each custom parameter during import. When you update import options via UpdateImportJobs you can remove, update, or leave in place the prior search and replace settings. For details please see the remarks below. This option is available in the Microsoft Advertising UI via Import from Google Ads > Choose import options > Other options > Tracking templates > Find and replace text in each custom parameter.
When enabled this option will pause imported campaigns in case all of their location targets are unsupported by Microsoft Advertising. If a campaign contains both supported and unsupported location targets the campaign will not be paused and will continue to serve for supported location targets. This option is turned off by default, or effectively set to false. Set this element true to enable this option. This option is available in the Microsoft Advertising UI via Import from Google Ads > Choose import options > Other options > Targeting > Pause campaigns when all imported location targets are unsupported.
Google Ads location targets that are unsupported by Microsoft Advertising are expanded in scope and mapped to parent location targets that are supported. This option is enabled by default, or effectively set to true. Set this element false to turn off this option. If you set this element false the unsupported location targets are not imported. This option is available in the Microsoft Advertising UI via Import from Google Ads > Choose import options > Other options > Targeting > Do not expand unsupported location targets.
Note: AssociatedStoreId is deprecated. The identifier of the Microsoft Merchant Center store that you want to associate with imported product ads and product filters. If this option is null or empty, your product ads and product filters will not be imported. To learn more see the Product Ads technical guide and the Create product ads in a shopping campaign help article. This option is available in the Microsoft Advertising UI via Import from Google Ads > Choose import options > Other options > Microsoft Merchant Center > Associate Microsoft Merchant Center Store with imported shopping campaigns and ad extensions.
By enabling this option Microsoft Advertising will increase all product group bids to the minimum bid amount. Your campaigns will still be imported if you don't enable this option but any products groups that have a bid below the Microsoft Advertising minimum will not serve. This option is enabled by default, or effectively set to true. Set this element false to turn off this option. This option is available in the Microsoft Advertising UI via Import from Google Ads > Choose import options > Bids and Budgets > Increase product group bids to the minimum for Microsoft Advertising.
If you enable this option, the service will only fetch search ads from mixed campaigns and import them as search campaigns. Otherwise the service will only fetch dynamic search ads from mixed campaigns and import them as dynamic search campaigns. Mixed campaigns contain both dynamic search ads and other ad types (e.g. Expanded Text Ads). Mixed campaigns are available wherever Dynamic search ads are supported i.e., Australia (AU), Austria (AT), Belgium (BE), Canada (CA), France (FR), Germany (DE), Ireland (IE), Italy (IT), Netherlands (NL), New Zealand (NZ), Spain (ES), Sweden (SE), Switzerland (CH), United Kingdom (UK), and United States (US). In those countries/regions this option is ignored and will no longer be visible in the Microsoft Advertising UI. Then whether this option is set to true or false both search and DSA ad groups will be imported. This option is turned off by default, or effectively set to false. Set this element true to enable this option. This option is available in the Microsoft Advertising UI via Import from Google Ads > Choose import options > What to import > Import search and DSA mixed campaigns as search campaigns.
Import the account level tracking template and final URL suffix. This option is enabled by default, or effectively set to true. Set this element false to turn off this option. This option is available in the Microsoft Advertising UI via Import from Google Ads > Choose import options > What to import > Account-level URL options.
If the currency in your Google Ads account does not match the currency in your Microsoft Advertising ad account, the imported bids and budgets will be converted to their equivalent currency in Microsoft Advertising. This option is turned off by default, or effectively set to false. Set this element true to enable this option. This option is available in the Microsoft Advertising UI via Import from Google Ads > Choose import options > What to import > Choose your Google Ads account. You will only see the UI option to convert or ignore if the currency varies between your Google Ads account and Microsoft Advertising ad account.
Update the existing campaign, ad group, and keyword bid strategies to match those currently in Google Ads. This option is only honored if UpdateEntities is also enabled. This option is enabled by default, or effectively set to true. Set this element false to turn off this option. This option is available in the Microsoft Advertising UI via Import from Google Ads > Choose import options > Bids and budgets > Update bid strategies.
The identifier of the Universal Event Tracking tag (UetTag) that you want to associate with imported remarketing lists. This option is only available for customers in the Remarketing Google Import feature pilot program (GetCustomerPilotFeatures returns 750). To import audience lists, targets, and exclusions you must also enable the NewAudienceTargets option. If this option is null or empty, your remarketing lists, targets, and exclusions will not be imported. This element is not required for in-market audience targets and exclusions, since they do not depend on a UET tag. This option is available in the Microsoft Advertising UI via Import from Google Ads > Choose import options > What to import > UET tag > Asse the following UET tag with any remarketing list, audience, or converociatsion goal that has not previously imported into Microsoft Advertising.
When enabled, we will not import negative bid modifiers for desktop targets except modifiers set to -100%. This option is turned off by default, or effectively set to false. Set this element true to enable this option. This option is available in the Microsoft Advertising UI via Import from Google Ads > Choose import options > Bids and budgets > Do not import negative bid modifier for desktop (except -100%).
Import updates to existing ad landing page URLs. This option is only honored if UpdateEntities is also enabled. This option is enabled by default, or effectively set to true. Set this element false to turn off this option. This option is available in the Microsoft Advertising UI via Import from Google Ads > Choose import options > What to import > Updates to existing items > Campaign settings > Ad landing page URLs.
Import updates to existing Sitelink Extension URLs. This option is only honored if UpdateEntities is also enabled. This option is enabled by default, or effectively set to true. Set this element false to turn off this option. This option is available in the Microsoft Advertising UI via Import from Google Ads > Choose import options > What to import > Updates to existing items > Ad extensions > Sitelink Extension URLs.
The type of the ad. This value is Hotel when you retrieve a hotel ad. For more information about ad types, see the Ad Data Object Remarks. Add: Read-only Update: Read-only
The list of key and value strings for forward compatibility to avoid otherwise breaking changes when new elements are added in the current API version. There are currently not any ForwardCompatibilityMap key and value pairs that are applicable for hotel ads.
The type of the criterion. This value is HotelAdvanceBookingWindow when you retrieve a hotel advance booking window criterion. For more information about criterion types, see the Criterion Data Object Remarks. Add: Read-only Update: Read-only
Minimum number of days prior to the hotel stay.
Maxmimum of days prior to the hotel stay. Note: This can't be more than 330.
The type of the criterion. This value is HotelCheckInDate when you retrieve a hotel check in date criterion. For more information about criterion types, see the Criterion Data Object Remarks. Add: Read-only Update: Read-only
The type of the criterion. This value is HotelCheckInDay when you retrieve a hotel check in day criterion. For more information about criterion types, see the Criterion Data Object Remarks. Add: Read-only Update: Read-only
The type of the criterion. This value is HotelDateSelectionType when you retrieve a hotel date selection type criterion. For more information about criterion types, see the Criterion Data Object Remarks. Add: Read-only Update: Read-only
The type of the criterion. This value is HotelGroup when you retrieve a hotel group criterion. For more information about criterion types, see the Criterion Data Object Remarks. Add: Read-only Update: Read-only
The type of the criterion. This value is HotelLengthOfStay when you retrieve a hotel length of stay criterion. For more information about criterion types, see the Criterion Data Object Remarks. Add: Read-only Update: Read-only
Minimum of days prior to the hotel stay.
Maxmimum of nights prior to the hotel stay. Note: This can't be more than 30.
The type of ad. Can either by HPA or PPA.
The type of the ad extension. This value is ImageAdExtension when you retrieve an image ad extension. Add: Read-only Update: Read-only For more information about ad extension types, see the Ad Extension Data Object Remarks.
Alternative description of the image media for usability. If the image could not be displayed, the alternative text is used instead. The maximum length for this element is 35 characters. Add: Required Update: Required
Description that can be used by the advertiser, agency, or account manager to track, label, or manage image media. This description is not displayed with the ad or image. The maximum length for this element is 100 characters. Add: Optional Update: Optional. If you set this element null, the previous setting will be deleted.
The URL of the webpage to take the user to when they click the image. The URL can contain dynamic text strings such as {keyword}. For more information, see What tracking or URL parameters can I use?. The URL can contain a maximum of 1,024 characters. If the URL does not specify a protocol, the system uses the HTTP protocol when a user clicks the ad. If the URL specifies the HTTP protocol when you add an ad, the service will remove the http:// protocol string (the HTTP protocol string does not count against the 1,024 character limit); however, the service will not remove an HTTPS protocol string (https://) from the URL. If the URL is not specified for the image ad extension, the URL of the ad is used. Add: Optional Update: Optional. If you set this element null, the previous setting will be deleted.
The identifiers of the images to include in the ad. You may not specify media identifiers for more than one image of the same aspect ratio. In other words each of the referenced images must have different aspect ratios. You can specify up to four (4) image media identifiers. While the minimum required is one image media ID, in order to qualify for all ad placements you must provide four image media identifiers, where each ID corresponds to an Image of one of the four supported Media types (aspect ratios). The supported aspect ratios for audience ads are 16:9, 1.5:1, 4:3, and 1.2:1. For more information see the Image data object reference documentation. You can get the identifier of each Image when you add them to the image library by calling the AddMedia operation. Otherwise after the media has been added to your image library you can get the media identifiers with the GetMediaMetaDataByAccountId operation. Add: Required Update: Required
The tracking template to use as a default for all FinalUrls and FinalMobileUrls. The following validation rules apply to tracking templates. For more details about supported templates and parameters, see the Microsoft Advertising help article What tracking or URL parameters can I use? - Tracking templates defined for lower level entities e.g. ads override those set for higher level entities e.g. campaign. For more information, see Entity Limits. - The length of the tracking template is limited to 2,048 characters. The HTTP or HTTPS protocol string does count towards the 2,048 character limit. - The tracking template must be a well-formed URL beginning with one of the following: http://, https://, {lpurl}, or {unescapedlpurl}. - Microsoft Advertising does not validate whether custom parameters exist. If you use custom parameters in your tracking template and they do not exist, then the landing page URL will include the key and value placeholders of your custom parameters without substitution. For example, if your tracking template is https://tracker.example.com/?season={_season}&promocode={_promocode}&u={lpurl} and neither {_season} or {_promocode} are defined at the campaign, ad group, criterion, keyword, or ad level, then the landing page URL will be the same. Add: Optional Update: Optional. If no value is set for the update, the prior setting is removed.
The final URL suffix can include tracking parameters that will be appended to the end of your landing page URL. We recommend placing tracking parameters that your landing page requires in a final URL suffix so that your customers are always sent to your landing page. For more details and validation rules see Final URL Suffix in the technical guides. Add: Optional Update: Optional. If no value is set for the update, the prior setting is removed.
Your custom collection of key and value parameters for URL tracking. Microsoft Advertising will accept the first 3 CustomParameter objects that you include within the CustomParameters object, and any additional custom parameters will be ignored. Each CustomParameter includes Key and Value elements. For customers in the Custom Parameters Limit Increase Phase 3 pilot (GetCustomerPilotFeatures returns 635), Microsoft Advertising will accept the first 8 custom parameter key and value pairs that you include, and if you include more than 8 custom parameters an error will be returned. Add: Optional Update: Optional. If no value is set for the update, the prior setting is removed.
The landing page URL. The following validation rules apply to Final URLs and Final Mobile URLs. - The length of the URL is limited to 2,048 characters. The HTTP or HTTPS protocol string does count towards the 2,048 character limit. - You may specify up to 10 list items for both FinalUrls and FinalMobileUrls; however, only the first item in each list is used for delivery. The service allows up to 10 list items for potential forward compatibility. - Usage of '{' and '}' is only allowed to delineate tags, for example {lpurl}. - Final URLs must each be a well-formed URL starting with either http:// or https://. - If you specify FinalMobileUrls, you must also specify FinalUrls. - You may not specify FinalMobileUrls if the DevicePreference is set to 30001 (mobile). Add: Optional Update: Optional. If no value is set for the update, the prior setting is removed.
The landing page URL for mobile devices. The following validation rules apply to Final URLs and Final Mobile URLs. - The length of the URL is limited to 2,048 characters. The HTTP or HTTPS protocol string does count towards the 2,048 character limit. - You may specify up to 10 list items for both FinalUrls and FinalMobileUrls; however, only the first item in each list is used for delivery. The service allows up to 10 list items for potential forward compatibility. - Usage of '{' and '}' is only allowed to delineate tags, for example {lpurl}. - Final URLs must each be a well-formed URL starting with either http:// or https://. - If you specify FinalMobileUrls, you must also specify FinalUrls. - You may not specify FinalMobileUrls if the DevicePreference is set to 30001 (mobile). Add: Optional Update: Optional. If no value is set for the update, the prior setting is removed.
Image assets with different sizes and aspect ratios so they can flexibly display across a variety of publishers and placements. Include one or more AssetLink objects that each contain an ImageAsset with SubType and crop settings that match the desired aspect ratio. Add: Required Update: Optional. If no value is set for the update, this setting is not changed. If you include images during update, any previously set images will be replaced.
The display text of your image extension. The maximum length for this element is 35 characters. Add: Required when Layouts contains SearchMultiple, else Optional. Update: Required when Layouts contains SearchMultiple, else Optional. If you set this element null, the previous setting will be deleted.
The list of eligible image layouts. Supported values are SearchSingle and SearchMultiple. New layouts might be added in the future, so you should not take any dependency on a fixed set of values. Add: Required Update: Optional. If no value is set for the update, this setting is not changed. If you include layouts during update, any previously set layouts will be replaced.
The name of the media representation. For ImageAdExtension media representations, the possible values are Preview, Thumbnail, and Original. For ResponsiveAd media representations, the only possible value is Original.
The type of the media representation. This value is ImageMediaRepresentation when you retrieve an image media representation.
The height of the image in pixels. For more information, see Remarks below.
The width of the image in pixels. For more information, see Remarks below.
The entity type of an impression-based remarketing list.
The campaign identifier to associate with the impression-based remarketing list.
The ad group identifier to associate with the impression-based remarketing list. Note: The AdGroupId is null for an impression-based remarketing list with users who have viewed an ad under campaign.
A list of unique system identifiers corresponding to the campaigns associated with the impression-based remarketing list. The list of identifiers corresponds directly to the list of campaigns in the request. Items of the list may be returned as null. For each list index where a campaign was not added, the corresponding element will be null.
A list of unique system identifiers corresponding to the ad groups associated with the impression-based remarketing list. The list of identifiers corresponds directly to the list of ad groups in the request. Items of the list may be returned as null. For each list index where an ad group was not added, the corresponding element will be null.
The type of the bidding scheme. This value is InheritFromParentBiddingScheme when you retrieve an "inherit from parent" bidding scheme. For more information about bidding scheme types, see the BiddingScheme Data Object Remarks. Add: Read-only Update: Read-only
The type of bidding scheme (a.k.a. bid strategy type) that is inherited from the parent campaign or ad group. This value is equal to the Type element of the parent campaign or ad group's BiddingScheme object. Possible values include EnhancedCpc, ManualCpc, MaxClicks, MaxConversions, MaxConversionValue, TargetCpa, TargetImpressionShare, and TargetRoas. New bid strategy types might be added in the future, so you should not take any dependency on a fixed set of values.
Scope defines what accounts can use this audience. For an in-market audience the only supported scope is Customer, and the audience can be associated with campaigns and ad groups in all of the customer's accounts. Add: Not supported Update: Not supported
When you create an audience, you can specify how far back in time Microsoft Advertising should look for actions that match your audience definition. The minimum duration is 1 day and the maximum duration allowed is 180 days. Add: Not supported Update: Not supported
The total number of people who are active members of this audience in the Search network. This gives you an idea of how many search users you can target. Add: Not supported Update: Not supported
The total number of people who are active members of this audience in the Audience network. This gives you an idea of how many Audience network users you can target. Add: Not supported Update: Not supported
The list of campaign types that support this audience. Supported values are Audience, DynamicSearchAds, Search, and Shopping. New campaign types might be added in the future, so you should not take any dependency on a fixed set of values. Add: Not supported Update: Not supported
This element is not supported for in-market audiences. Add: Not supported Update: Not supported
The Microsoft Advertising identifier of the audience. Add: Not supported Update: Not supported
The name of the audience. The name can contain a maximum of 128 characters. Add: Not supported Update: Not supported
The description of the audience. Use a description to help you remember what audience you are targeting. The description can contain a maximum of 1,024 characters. Add: Not supported Update: Not supported
The type of the audience. This value is InMarket when you retrieve an in-market audience. For more information about audience types, see the Audience Data Object Remarks. Add: Not supported Update: Not supported
The Microsoft Advertising identifier of the customer that contains the in-market audience. Add: Not supported Update: Not supported
Determines if the goal applies to all accounts or only the account specified in the required CustomerAccountId header element. For in-store transaction goals the Account level scope is not supported. You can set this element to Customer or leave it nil. If not specified, the scope will be set to Customer by default. Add: Optional Update: Optional
Determines how much each conversion is worth to your business. When adding a conversion goal if you do not specify any revenue tracking preferences, then each ConversionGoalRevenue will be set to their respective default values. When updating a conversion goal, if the Revenue element is nil or empty then none of the nested properties will be updated. However, if this element is not nil or empty then you are effectively replacing any existing revenue properties. You must specify the ConversionGoalRevenue CurrencyCode when adding or updating an in-store transaction goal. Add: Optional Update: Optional
Not applicable for in-store transaction goals.
The category used to segment the conversion goal. Categorize your conversion goals however makes sense for your business. Goal categories don't affect performance - they are here to help you segment your goals and their performance metrics. The supported category values vary by conversion goal type. In-store transaction goals only support the Purchase category. Add: Optional. If you leave this element nil or empty, the default category will be set to Purchase. Update: Optional. If no value is set for the update, this setting is not changed.
The type of the conversion goal. This value is InStoreTransaction when you retrieve an in-store transaction goal. For more information about conversion goal types, see the ConversionGoal Data Object Remarks. Add: Read-only Update: Read-only
The type of the ad extension. This value is LocationAdExtension when you retrieve a location ad extension. Add: Read-only Update: Read-only For more information about ad extension types, see the Ad Extension Data Object Remarks.
The business address. The supported country code values include AR, AT, AU, BR, CA, CH, CL, CO, DE, DK, ES, FI, FR, GB, HK, ID, IE, IN, IT, MX, MY, NL, NZ, NO, PE, PH, SE, SG, TH, TW, US, VE, and VN. Add: Required Update: Required
The latitude and longitude coordinates of the specified Address element. The coordinates are used to mark the business location on Bing Maps when the user clicks the address on the ad. If the specified coordinates are not within the range of valid values, the service determines the coordinates based on the address. If you specify the known coordinates, the service does not confirm whether the specified coordinates match the specified business address. If you do not provide the coordinates, the AddAdExtensions operation uses the business address to determine the coordinates. When adding more than 10 location ad extensions, the service resolves coordinates offline, and otherwise resolves coordinates up front during execution of the service operation. The location will not be used in an ad until the coordinates are determined, which can take from seconds to minutes depending on the number of location ad extensions being added and the current demand. To determine whether the coordinates have been resolved, call the GetAdExtensionsByIds operation and access the GeoCodeStatus element. For a list of possible status values see BusinessGeoCodeStatus. Add: Optional Update: Optional
A status value that indicates whether the business latitude and longitude coordinates have been determined. If you provide the coordinates, the status will be set to Complete; otherwise, the status will indicate the progress of determining the coordinates of the specified business address. Add: Not allowed Update: Not allowed
The name of the business. The name can contain a maximum of 80 characters. Add: Required Update: Required
The business phone number to include in the ad. The phone number is clickable on hi-fi mobile devices. The phone number can contain a maximum of 35 characters and must be valid for the specified country or region. If the campaign also includes a call extension, the phone number in the call extension, will override this phone number. Add: Optional Update: Optional. If you set this element null, the previous setting will be deleted.
The type of the criterion. This value is Location when you retrieve a location criterion. For more information about criterion types, see the Criterion Data Object Remarks. Add: Read-only Update: Read-only
The unique Microsoft Advertising identifier for the location where you want to show your ads. For possible values, see the Location Id field of the geographical locations file. You can call the GetGeoLocationsFileUrl operation to download the file. IMPORTANT: Please check the Status field in the geographical locations file before adding or updating a location criterion. If the status is PendingDeprecation, the location criterion is no longer used for targeting or exclusions. Deprecated location criteria can still be retrieved, but you cannot add or update deprecated location criteria. Add: Required Update: Not allowed. If you specify this element it must match the existing setting.
The location type. Possible values include, but are not limited to City, Country, MetroArea, Neighborhood, PostalCode, and State. New location sub types can be added anytime. Rarely will the location type change for a given location ID. Add: Read-only Update: Read-only
The location display name. Add: Read-only Update: Read-only
Reserved for internal use. Add: Read-only Update: Read-only
The type of the criterion. This value is LocationIntent when you retrieve a location intent criterion. For more information about criterion types, see the Criterion Data Object Remarks. Add: Read-only Update: Read-only
Determines whether a person must be physically located in the targeted location in order for the ad to display. The following values are supported. The default value is PeopleInOrSearchingForOrViewingPages. - Use PeopleInOrSearchingForOrViewingPages if you want to show ads to people in, searching for, or viewing pages about your targeted location. - Use PeopleIn if you want to show ads to people in your targeted location. Add: Optional. If no value is specified the default value is PeopleInOrSearchingForOrViewingPages. Update: Optional. If no value is set for the update, this setting is not changed.
The business name. Maximum length is 25 characters. Add: Required Update: Required
The asset ID for the business logo. The business logo must have a 1:1 aspect ratio. The minimum image size is 128px by 128px. The maximum image size is 5120 KB. Add: Required Update: Required
The URL of the business logo. This is used internally. Add: Not allowed Update: Not allowed
The domain name. Note: Use the domain name, not a URL. For example, use "contoso.com", not "https://contoso.com". The maximum length is 50 characters. Add: Optional Update: Optional
The type of the bidding scheme This value is ManualCpaBiddingScheme when you retrieve a manual CPA bidding scheme. For more information about bidding scheme types, see the BiddingScheme Data Object Remarks. Add: Read-only Update: Read-only
The type of the bidding scheme This value is ManualCpcBiddingScheme when you retrieve a manual CPC bidding scheme. For more information about bidding scheme types, see the BiddingScheme Data Object Remarks. Add: Read-only Update: Read-only
The type of the bidding scheme. This value is ManualCpmBiddingScheme when you retrieve a manual CPM bidding scheme. For more information about bidding scheme types, see the BiddingScheme Data Object Remarks. Add: Read-only Update: Read-only
The type of the bidding scheme. This value is ManualCpvBiddingScheme when you retrieve a manual CPV bidding scheme. For more information about bidding scheme types, see the BiddingScheme Data Object Remarks. Add: Read-only Update: Read-only
The type of the bidding scheme. This value is MaxClicksBiddingScheme when you retrieve a maximum clicks bidding scheme. For more information about bidding scheme types, see the BiddingScheme Data Object Remarks. Add: Read-only Update: Read-only
The maximum cost per click that you want to spend. Add: Optional Update: Optional
The type of the bidding scheme. This value is MaxConversionsBiddingScheme when you retrieve a maximum conversions bidding scheme. For more information about bidding scheme types, see the BiddingScheme Data Object Remarks. Add: Read-only Update: Read-only
The maximum cost per click that you want to spend. Note: MaxCpc shouldn't be set for Smart Shopping or Performance Max campaigns as it doesn't apply. Add: Optional Update: Optional
The target cost per action that you want to spend. Note: TargetCpa is used by Audience, Search, Smart Shopping, and Performance Max campaigns. Add: Optional Update: Optional
The type of the bidding scheme. This value is MaxConversionValueBiddingScheme when you retrieve a maximum conversion value bidding scheme. For more information about bidding scheme types, see the BiddingScheme Data Object Remarks. Add: Read-only Update: Read-only
The target return on ad spend. Note: TargetRoas is used by Search, Shopping, Smart Shopping and Performance Max campaigns.
The MaxRoasBiddingScheme object is not in use and will be removed from a future version of the API.
A status value that determines whether the criterion applies for the ad group. Currently the only supported status for negative ad group criterions is Active. Add: Read-only Update: Read-only
The type of the ad group criterion. This value is NegativeAdGroupCriterion when you retrieve a negative ad group criterion. For more information about ad group criterion types, see the AdGroupCriterion Data Object Remarks. Add: Read-only Update: Read-only
The criterion to apply to the campaign. The criterion helps determine whether ads in the campaign are served. For a list of available criterion types, see CampaignCriterionType. Add: Optional Update: Optional. If no value is set for the update, this setting is not changed.
A status value that determines whether the criterion applies for the campaign. Currently the only supported status for negative campaign criterions is Active. Add: Read-only Update: Read-only
The type of the campaign criterion. This value is NegativeCampaignCriterion when you retrieve a negative campaign criterion. For more information about campaign criterion types, see the CampaignCriterion Data Object Remarks. Add: Read-only Update: Read-only
The type of the shared list item. This value is NegativeSite when you retrieve a negative site. For more information about shared list item types, see SharedListItem Data Object Remarks. Add: Read-only Delete: Read-only
The unique Microsoft Advertising identifier of the negative site. Add: Read-only Delete: Required
The URL of the website where you do not want your ads displayed. Each URL must specify the domain name e.g., contoso.com which can include up to three subdomains and two subdirectories. The subdomain count includes the www prefix. For example one.two.three.contoso.com/1/2, www.two.three.contoso.com/1/2, and one.two.contoso.co.uk/1/2 are valid URLs, whereas one.two.three.contoso.co.uk/1/2 (too many subdomains) and one.two.three.contoso.com/1/2/3 (too many subdirectories) are not. Duplicate URLs in a website exclusion list (Placement Exclusion List or Account Placement Exclusion List) are not allowed. You can only exclude websites for syndicated search websites. The ad group's network must be set to OwnedAndOperatedAndSyndicatedSearch. For more information about network distribution, see Network. If you associate any ebsite exclusion lists (Placement Exclusion List or Account Placement Exclusion List) with an ad account, the list of negative sites are used in addition to the campaign negative sites or ad group negative sites. Negative site URLs specified at the ad group level are used instead of any negative site URLs specified at the campaign level. Add: Required Delete: Optional
The identifier for the new customer acquisition goal.
Enable new customer acqisition bid only mode.
The target amount you want to pay for a new customer's purchase of your product or service.
The type of rule item. For more information, see RuleItem Data Object Remarks.
The rule operand or key on the left hand side of the operator. Supported values are Url and ReferrerUrl. For example to define a rule where the page Url must contain page.html, set the Operand to Url, Operator to Contains, and Value to page.html. Add: Required Update: Required
The rule value on the right hand side of the operator. Add: Required Update: Required
Determines if the goal applies to all accounts or only the account specified in the required CustomerAccountId header element. If you have multiple Microsoft Advertising accounts, you can track conversions across all of those accounts. If you associate a goal with one account, conversions will be tracked for that account only. Possible values are Account and Customer. Once you set scope, you can't change it. If you want to change the scope, you need to create a new conversion goal and pause the old one. Add: Optional. If not specified, the scope will be set to Account by default. Update: Read-only. You cannot update the offline conversion goal scope.
This determines how your conversions are recorded within your chosen conversion window. There are two choices, and if you do not set a value the default is All: - All: All conversions with different offline conversion times that happen after an ad click will be counted. This is a common choice for sales. - Unique: Only the first conversion that happens after an ad click will be counted. This is a common choice for leads. For example: You track two conversions: leads and sales. You pick Unique for leads and All for sales. When one ad click turns into two leads and two sales, it's counted as three conversions: one for the unique lead, and two for all the sales. Duplicate offline conversions with the same MicrosoftClickId and ConversionTime will be ignored. In other words only the first offline conversion for a given MicrosoftClickId and ConversionTime will be counted. Add: Optional Update: Optional
Determines how much each conversion is worth to your business. When adding a conversion goal if you do not specify any revenue tracking preferences, then each ConversionGoalRevenue will be set to their respective default values. When updating a conversion goal, if the Revenue element is nil or empty then none of the nested properties will be updated. However, if this element is not nil or empty then you are effectively replacing any existing revenue properties. If the revenue type is FixedValue or VariableValue, then the ConversionCurrencyCode and ConversionValue elements of the applied OfflineConversion data takes precedence over the ConversionGoalRevenue currency code and value. Add: Optional Update: Optional
The conversion window is the length of time in minutes after a click that you want to track conversions. If you set this value to 43200 minutes (30 days), then conversions that happen within 30 days after a click are tracked. Past conversions aren't affected. The default value is 43200. The minimum value supported is 1 minute, although keep in mind that a shorter conversion window will reduce the number of conversions your account records. The maximum value supported is 129600 minutes (90 days). Add: Optional Update: Optional
Not applicable for offline conversion goals.
The category used to segment the conversion goal. Categorize your conversion goals however makes sense for your business. Goal categories don't affect performance - they are here to help you segment your goals and their performance metrics. The supported category values vary by conversion goal type. Offline conversion goals support the AddToCart, BeginCheckout, BookAppointment, Contact, GetDirections, Other, OutboundClick, PageView, Purchase, RequestQuote, Signup, SubmitLeadForm, and Subscribe categories. Add: Required as of June 2021. Previously if you left this element nil or empty, the default category was set to None. Update: Optional if the conversion goal already has a category set other than None. If no value is set for the update, this setting is not changed.
The type of the conversion goal. This value is OfflineConversion when you retrieve an offline conversion goal. For more information about conversion goal types, see the ConversionGoal Data Object Remarks. Add: Read-only Update: Read-only
This determines if your offline conversion goal uses your own attribution model and allows you to import fractional credit for each MSCLKID. This element is not returned by default. To get this element, include the IsExternallyAttributed value in the ReturnAdditionalFields element when you call the GetConversionGoalsByIds and GetConversionGoalsByTagIds service operations. Note: You can only set IsExternallyAttributed via the Campaign Management API. Add: Optional Update: Optional
Determines how much each conversion is worth to your business. When adding a conversion goal if you do not specify any revenue tracking preferences, then each ConversionGoalRevenue will be set to their respective default values. When updating a conversion goal, if the Revenue element is nil or empty then none of the nested properties will be updated. However, if this element is not nil or empty then you are effectively replacing any existing revenue properties. The VariableValue option is not available for pages viewed per visit conversion goals. Add: Optional Update: Optional
The category used to segment the conversion goal. Categorize your conversion goals however makes sense for your business. Goal categories don't affect performance - they are here to help you segment your goals and their performance metrics. The supported category values vary by conversion goal type. Pages viewed per visit goals only support the Other category. Add: Optional. If you leave this element nil or empty, the default category will be set to Other. Update: Optional. If no value is set for the update, this setting is not changed.
The type of the conversion goal. This value is PagesViewedPerVisit when you retrieve a pages viewed per visit goal. For more information about conversion goal types, see the ConversionGoal Data Object Remarks. Add: Read-only Update: Read-only
The minimum number of pages the user must visit, in order to count as a conversion. Add: Required Update: Optional
The list of rule item groups that you want applied to the remarketing list. The maximum number of rule item groups in this element is 100. The maximum number of rule items per rule item group is 100. Add: Required Update: Required. If you want to keep any of the previous rule item groups, then you must explicitly set them again during update.
Determines whether the rule item groups are evaluated based on conjunctive normal form (CNF) or disjunctive normal form (DNF). This element is not returned by default. To get this element, include the NormalForm value in the ReturnAdditionalFields element when you call the GetAudiencesByIds service operation. Add: Optional. The default value is "Disjunctive". Update: Optional
The list of rule item groups that you want applied as exclusions to the remarketing list. The maximum number of rule item groups in this element is 100. The maximum number of rule items per rule item group is 100. Exclusions take precedence over inclusions. In other words if the user visited any excluded page within the RemarketingList membership duration e.g. previous 30 days, then they cannot be added to the list even if other page views satisfy conditions in the included rule item groups. If the excluded page views occurred prior to the membership duration lookback, and if the user's page views satisfy conditions in the included rule item groups within the membership duration, then they can be added to the remarketing list. Add: Required Update: Required. If you want to keep any of the previous rule item groups, then you must explicitly set them again during update.
The list of rule item groups related to pages the audience visited. The maximum number of rule item groups in this element is 100. The maximum number of rule items per rule item group is 100. Add: Required Update: Required. If you want to keep any of the previous rule item groups, then you must explicitly set them again during update.
The list of rule item groups related to other pages the audience visited. The maximum number of rule item groups in this element is 100. The maximum number of rule items per rule item group is 100. Add: Required Update: Required. If you want to keep any of the previous rule item groups, then you must explicitly set them again during update.
The maximum effective bid limit, in absolute form, at the campaign level. The actual CPC bid amount, in percent form, must be set at the ad group level and can optionally be set at the hotel group level again. For example, for a maximum percent CPC bid of $10.60, the MaxPercentCpc value should be 10.60. Campaigns with PercentCpc and ManualCPC bidding scheme can participate in a shared budget. MaxPercentCpc must be greater than 0.
If false, then the entire domain will be targeted. If true (opted out), then only the final URLs in the asset groups and feed will be targeted. Add: Optional. The default value is false. Update: Optional
The page feed identifiers for performance max ads. See the Page Feeds technical guide for an implementation overview. Add: Optional Update: Optional. You cannot delete page feed IDs, but you can replace the previous set with a new set.
If false, then text assets will be dynamically generated. If true (opted out), then text assets will not be dynamically generated. Add: Optional. The default value is false. Update: Optional
If false, then image assets will be dynamically generated. If true (opted out), then image assets will not be dynamically generated. Add: Optional. The default value is false. Update: Optional
If true, then bidding will be opted out of cost per sale.
The type of the criterion. This value is Placement when you retrieve a placement criterion. For more information about criterion types, see the Criterion Data Object Remarks. Add: Read-only Update: Read-only
The ID of the placement. Possible values include 12: Microsoft Edge New Tab Page, 13: Productivity, 14: Gaming, 15: MSN.
The type of the ad extension. This value is PriceAdExtension when you retrieve a price ad extension. Add: Read-only Update: Read-only For more information about ad extension types, see the Ad Extension Data Object Remarks.
The type of the price ad extension. Possible values include: Brands, Events, Locations, Neighborhoods, ProductCategories, ProductTiers, ServiceCategories, Services, ServiceTiers, and Unknown. Add: Required Update: Required
The tracking template to use as a default for all landing page URLs. The following validation rules apply to tracking templates. For more details about supported templates and parameters, see the Microsoft Advertising help article What tracking or URL parameters can I use? - Tracking templates defined for lower level entities e.g. ads override those set for higher level entities e.g. campaign. For more information, see Entity Limits. - The length of the tracking template is limited to 2,048 characters. The HTTP or HTTPS protocol string does count towards the 2,048 character limit. - The tracking template must be a well-formed URL beginning with one of the following: http://, https://, {lpurl}, or {unescapedlpurl}. - Microsoft Advertising does not validate whether custom parameters exist. If you use custom parameters in your tracking template and they do not exist, then the landing page URL will include the key and value placeholders of your custom parameters without substitution. For example, if your tracking template is https://tracker.example.com/?season={_season}&promocode={_promocode}&u={lpurl} and neither {_season} or {_promocode} are defined at the campaign, ad group, criterion, keyword, or ad level, then the landing page URL will be the same. Add: Optional Update: Optional. If you set this element null, the previous setting will be deleted.
Your custom collection of key and value parameters for URL tracking. Microsoft Advertising will accept the first 3 CustomParameter objects that you include within the CustomParameters object, and any additional custom parameters will be ignored. Each CustomParameter includes Key and Value elements. For customers in the Custom Parameters Limit Increase Phase 3 pilot (GetCustomerPilotFeatures returns 635), Microsoft Advertising will accept the first 8 custom parameter key and value pairs that you include, and if you include more than 8 custom parameters an error will be returned. Add: Optional Update: Optional. If you set this element null, the previous setting will be deleted.
The language for the ad copy of your price ad extension. For possible values, see Ad Languages. Add: Required Update: Required
The price table rows. You must have between 3 and 8 price table rows. The order you create them in is the expected order in the ad but the order is not guaranteed. Add: Required Update: Required
The type of the ad. This value is Product when you retrieve a product ad. For more information about ad types, see the Ad Data Object Remarks. Add: Read-only Update: Read-only
The list of key and value strings for forward compatibility to avoid otherwise breaking changes when new elements are added in the current API version. There are currently not any ForwardCompatibilityMap key and value pairs that are applicable for product ads.
This property is reserved for internal use and will be removed from a future version of the API. You can use Merchant Promotions if you want tags to appear at the bottom of your product ad as "special offer" links, helping to increase customer engagement. Add: Optional Update: Optional
When you create an audience, you can specify how far back in time Microsoft Advertising should look for actions that match your audience definition. The minimum duration is 1 day and the maximum duration allowed is 180 days. Add: Optional. If not specified, the membership duration will be set to 30 by default. Update: Optional. If no value is set for the update, this setting is not changed.
The total number of people who are active members of this audience in the Search network. This gives you an idea of how many search users you can target. The audience needs to have at least 300 people before Microsoft Advertising will use it for optimizations. This property will be nil or empty for up to 24 hours while the audience is being built, for example if you add or update the membership duration or tag identifier. Add: Read-only Update: Read-only
This element is not supported for product audiences. You can use a shared TagId with product audiences, but a product audience itself cannot be shared. Add: Not supported Update: Not supported
The type of the audience. This value is ProductAudience when you retrieve a product audience. For more information about audience types, see the Audience Data Object Remarks. Add: Read-only Update: Read-only
Determines whether to remarket your products to general visitors, product searchers, product viewers, shopping cart abandoners, or past buyers. Add: Required Update: Optional. If no value is set for the update, this setting is not changed.
The Microsoft Advertising identifier of the Universal Event Tracking (UET) tag that is used with the remarketing list. Before you take a dependency on the tag ID, please note that the UET tag can be shared with or from another customer. Shared UET tags and audiences are only available for pilot customers. For an overview of sharing audiences and UET tags in a customer hierarchy, see the Share Audiences and UET Tags technical guide. Add: Required Update: Optional. If no value is set for the update, this setting is not changed.
The type of the criterion. This value is ProductPartition when you retrieve a product partition criterion. For more information about criterion types, see the Criterion Data Object Remarks. Add: Read-only Update: Read-only
The identifier of the parent BiddableAdGroupCriterion or NegativeAdGroupCriterion. This element must be set to null if the product partition represents the root node of a product partition tree. Add: Required Update: Update is not supported for this object Delete: Required
A condition that helps determine whether a product from the Microsoft Merchant Center store gets served as an ad. Multiple product conditions can be specified by creating a tree of ProductPartition objects using ApplyProductPartitionActions. For a catalog item to be served as an ad, it must meet all conditions. To get a list of all conditions for an ad group, call GetAdGroupCriterionsByIds with the AdGroupCriterionIds element set to null and the CriterionType element set to ProductPartition. Add: Required Update: Update is not supported for this object
The type of product partition, for example Subdivision or Unit. Add: Required Update: Update is not supported for this object
The type of the criterion. This value is ProductScope when you retrieve a product scope criterion. For more information about criterion types, see the Criterion Data Object Remarks. Add: Read-only Update: Read-only
A list of up to 7 product conditions that helps determine whether a product from the Microsoft Merchant Center store gets served as an ad. Product conditions might not be returned in the order that you submitted them. The available Attribute and Operand values vary depending on the campaign type. For supported attribute and operand values, see ProductCondition Remarks. Conditions might not be returned in the order that you submitted them. Add: Required Update: Required
The type of the criterion. This value is Profile when you retrieve a profile criterion. For more information about criterion types, see the Criterion Data Object Remarks. Add: Read-only Update: Read-only
The identifier of the company name, industry, or job function profile that you want to target. For details about how to get profile identifiers, see Profile Data. Add: Required Update: Required
Determines whether the profile criterion corresponds to a company name, industry, or job function. Add: Required Update: Required
The type of the ad extension. This value is PromotionAdExtension when you retrieve a promotion ad extension. Add: Read-only Update: Read-only For more information about ad extension types, see the Ad Extension Data Object Remarks.
The promotion target or item. For example, you might run a promotion for "shoes" at either $20 or 20% discount. To run a promotion for "Up to $20 off shoes", set the PromotionItem to "shoes", set the DiscountModifier to UpTo, set CurrencyCode to "USD", and set MoneyAmountOff to 20. The string can contain a maximum of 20 characters. Add: Required Update: Optional. If no value is set for the update, this setting is not changed.
The promotion discount modifier. For example, let's say the discount modifier is set to UpTo. Then, if the unmodified promotion discount would be "$20 off shoes", the modified promotion is "Up to $20 off shoes." Add: Optional. If you do not specify this element or leave it empty, the default value of None will be set. Update: Optional. If no value is set for the update, this setting is not changed.
The percent off promotion value. For example, 10.0 represents a 10% discount. Add: Required. You must set either MoneyAmountOff or PercentOff, but you cannot set both. Update: Optional. You can set either MoneyAmountOff or PercentOff, but you cannot set both. If you set this property, then the CurrencyCode setting is no longer applicable and will be deleted if it was previously set.
The money off promotion value. For example, to promote "$20 off shoes - On orders over $100", set the PromotionItem to "shoes", set CurrencyCode to "USD", set MoneyAmountOff to 20, and set OrdersOverAmount to 100. Add: Required. You must set either MoneyAmountOff or PercentOff, but you cannot set both. Update: Optional. You can set either MoneyAmountOff or PercentOff, but you cannot set both.
The promotion code appended to the promotion target. For example, to promote "$20 off shoes - Promocode SAVE20", set the PromotionItem to "shoes", set CurrencyCode to "USD", set MoneyAmountOff to 20, and set PromotionCode to "SAVE20". The string can contain a maximum of 15 characters. Add: Optional. You cannot set both OrdersOverAmount and PromotionCode. Update: Optional. You cannot set both OrdersOverAmount and PromotionCode. If no value is set for the update, this setting is not changed. If you set this element to an empty string (""), the previous setting will be deleted. If you set this property, then the CurrencyCode setting is no longer applicable and will be deleted if it was previously set.
The orders over amount value appended to the promotion target. For example, to promote "$20 off shoes - On orders over $100", set the PromotionItem to "shoes", set CurrencyCode to "USD", set MoneyAmountOff to 20, and set OrdersOverAmount to 100. Add: Optional. You cannot set both OrdersOverAmount and PromotionCode. Update: Optional. You cannot set both OrdersOverAmount and PromotionCode. If no value is set for the update, this setting is not changed. If you set this element to '0' (zero), the previous setting will be deleted.
The start date helps to inform the promotion date or dates that will be displayed in the ad. For example if the PromotionStartDate and PromotionEndDate dates are both set to February 14th, the text "Valid Feb 14" could be included in the displayed promotion. The PromotionStartDate date must be earlier than, or equal to, the PromotionEndDate date. This property does not override the inherent delivery range for a promotion. Both the promotion PromotionOccasion and Scheduling determine when the promotion is eligible to be shown in ads. If the end date has already passed for the current year, then each start and end date must be set for dates during the following year. Add: Optional Update: Optional. If no value is set for the update, this setting is not changed. To delete the current end date and effectively set no end date, set the Day, Month, and Year each to '0' (zero). When you retrieve the promotion ad extension next time, this element will not be set.
The end date helps to inform the promotion date or dates that will be displayed in the ad. For example if the PromotionStartDate and PromotionEndDate dates are both set to February 14th, the text "Valid Feb 14" could be included in the displayed promotion. The PromotionStartDate date must be earlier than, or equal to, the PromotionEndDate date. This property does not override the inherent delivery range for a promotion. Both the promotion PromotionOccasion and Scheduling determine when the promotion is eligible to be shown in ads. If the end date has already passed for the current year, then each start and end date must be set for dates during the following year. Add: Optional Update: Optional. If no value is set for the update, this setting is not changed. To delete the current end date and effectively set no end date, set the Day, Month, and Year each to '0' (zero). When you retrieve the promotion ad extension next time, this element will not be set.
The promotion occasion. Both the PromotionOccasion and Scheduling elements determine when the promotion is eligible to be shown in ads. The PromotionOccasion determines the time period or seasonality e.g., WomensDay from February 15 through March 31 each year. The promotion will only run within the dates corresponding to the occasion that you set. See PromotionOccasion for details about the defined date range for each occasion. The Scheduling can limit the promotion to a shorter timeframe within the occasion's date range e.g., limit the promotion to run from February 20 through March 8. The Scheduling can also be used to run the same promotion multiple years e.g., run the WomensDay promotion every year from February 15 through March 31. Add: Optional. If you do not specify this element or leave it empty, the default value of None will be set. Update: Optional. If no value is set for the update, this setting is not changed. If you set this element, then PromotionStartDate and PromotionEndDate must also be set to retain or update the previous settings.
The language that the ad extension will be served in. The extension will always be served in this language, regardless of the campaign or ad group's language settings. The supported language strings are: Danish, Dutch, English, Finnish, French, German, Italian, Norwegian, Portuguese, Spanish, Swedish, and TraditionalChinese. Add: Required Update: Optional. If no value is set for the update, this setting is not changed.
The currency code for the promotion price or discount. This field is only applicable if you set MoneyAmountOff or OrdersOverAmount. The supported currency codes are ARS, AUD, BRL, CAD, CHF, CLP, CNY, COP, DKK, EUR, GBP, HKD, INR, MXN, NZD, PEN, PHP, PLN, SEK, SGD, USD, TWD, and VEF. Add: Required if MoneyAmountOff or OrdersOverAmount are set. Update: Optional. If no value is set for the update, this setting is not changed. If you set either PercentOff or PromotionCode, this setting is no longer applicable and will be deleted.
The type of the criterion. This value is Radius when you retrieve a radius criterion. For more information about criterion types, see the Criterion Data Object Remarks. Add: Read-only Update: Read-only
The name of the geographical location being targeted. The name can contain a maximum of 50 characters. Add: Optional Update: Read-only
The radius that specifies the area surrounding the geographical location to target. If the RadiusUnit is set to Miles, then positive integer values from 1 to 500 are accepted. If the RadiusUnit is set to Kilometers, then positive integer values from 1 to 800 are accepted. The data type is double and may be supported in a future release. Currently the service only accepts and returns integer values. Add: Required Update: Not allowed. If you specify this element it must match the existing setting.
The unit of measurement for the specified radius, for example kilometers or miles. Add: Required Update: Not allowed. If you specify this element it must match the existing setting.
The latitude, in degrees, of the target location. The latitude must be greater than or equal to -85.0 and less than or equal to +85.0. Add: Required Update: Not allowed. If you specify this element it must match the existing setting.
The longitude, in degrees, of the target location. The longitude must be greater than or equal to -180.0 and less than or equal to +180.0. Add: Required Update: Not allowed. If you specify this element it must match the existing setting.
The total number of people who are active members of this audience in the Search network. This gives you an idea of how many search users you can target. The audience needs to have at least 300 people before Microsoft Advertising will use it for optimizations. This property will be nil or empty for up to 24 hours while the audience is being built, for example if you add or update the remarketing list membership duration, rule, or tag identifier. This property will be nil or empty if the UET tag associated with the remarketing list has a status of Unverified or Inactive, because the remarketing list can't receive the customer information from your website that it needs to build the list. Add: Read-only Update: Read-only
The type of the audience. This value is RemarketingList when you retrieve a remarketing list audience. For more information about audience types, see the Audience Data Object Remarks. Add: Read-only Update: Read-only
A rule includes conditions used to determine who to add to your remarketing list. You can choose one of the four types of rules to target different audiences: CustomEventsRule, PageVisitorsRule, PageVisitorsWhoDidNotVisitAnotherPageRule, and PageVisitorsWhoVisitedAnotherPageRule. Add: Required Update: Optional. If no value is set for the update, this setting is not changed. If you want to keep any of the previous rule items, then you must explicitly set them again during update. You can choose to change the type of rule during update.
The type of the setting. This value is ResponsiveSearchAds when you retrieve a dynamic search ads setting. For more information about setting types, see the Setting Data Object Remarks. Add: Read-only Update: Read-only
Not everyone has this feature yet. If you don't, don't worry - it's coming soon! Determines whether to automatically generate responsive search ad assets in addition to the ad text you provide. During ad delivery, we will use artificial intelligence to choose the best assets available from these options. Add: Optional. The default value of true will be set if not otherwise specified. Update: Optional. If no value is set for the update, this setting is not changed.
The type of the ad extension. This value is ReviewAdExtension when you retrieve a review ad extension. Add: Read-only Update: Read-only For more information about ad extension types, see the Ad Extension Data Object Remarks.
Determines whether the review text is an exact quote or paraphrased. If not specified, the default value of false indicates that the review text is paraphrased from the source. If set to true, the review text will be surrounded automatically with quotation marks when displayed with the ad. Add: Optional Update: Optional. If you set this element null, the previous setting will be deleted.
The text that is either a paraphrase or an exact quote from the review source. The combined length of the Source and Text strings must not exceed 67 characters. Note that for Traditional Chinese characters, the combined length of the Source and Text Source and Text strings is limited to 33 characters. Do not surround the text with quotation marks. If IsExact is set to True, the review text will be surrounded automatically with quotation marks when displayed with the ad. Add: Required Update: Required
The review source name. The combined length of the Source and Text strings must not exceed 67 characters. Note that for Traditional Chinese characters, the combined length of the Source and Text Source and Text strings is limited to 33 characters. Add: Required Update: Required
The review source Url. The Url must begin with either the http:// or https:// prefix. The length of this string is limited to 2,048 characters. Add: Required Update: Required
The company name filter string. You can search using partial or full company name. The minimum length of the string is 3. The service searches across all language-locales for the string. The company name will be returned in the requested LanguageLocale if available.
The list of companies that match the requested company name filter.
The list of account properties that you want to set. For example, you can enable Microsoft Click Id auto-tagging for tracking offline conversions. Partial success is not supported i.e., if any account property cannot be set, then none of the account properties will be set.
The list of ad extensions with associated account, campaign, or ad group. You can only associate ad extensions with one type of entity per service call. Specify the entity type with the AssociationType element. Call and Location ad extensions cannot be associated with an ad group. Call ad extensions cannot be associated with an account. You may set a maximum of 100 associations per service call.
The type of all entities specified in the AdExtensionIdToEntityIdAssociations list.
The list of Audience Group associations to set. The maximum size of the list is 100 items per service request. Only 1 audience group can be associated to each asset group. Note: You will overwrite an existing association if you set a new one. AudienceGroupAssetGroupAssociation will update with the new audience group.
The list of label associations to set. Each label association includes label and entity identifiers. The maximum size of the list is 100 items per service request. Each entity can be associated with a maximum of 50 labels. For example Campaign A can be associated with up to 50 labels.
An array of AdGroupNegativeSites objects that identify the ad groups to update with the specified negative site URLs. The array can contain a maximum of 5,000 objects. The total number of URLs that you can specify per request for all ad groups combined is 30,000. For example, if you specify 2,500 URLs per ad group, the maximum number of AdGroupNegativeSites objects that you should pass is 12.
An array of CampaignNegativeSites objects that identify the campaigns to update with the specified negative site URLs. The array can contain a maximum of 5,000 objects. The total number of URLs that you can specify per request for all ad campaigns combined is 30,000. For example, if you specify 2,500 URLs per campaign, the maximum number of CampaignNegativeSites objects that you should pass is 12.
Indicates whether the shared entity is available at the ad account (Account) or manager account (Customer) level. This element is optional and defaults to Account scope. The ad account scope is only applicable for negative keyword list to campaign associations. Set this element to Customer to set website exclusion list to ad account associations in your manager account (customer) shared library.
The type of the setting. This value is Shopping when you retrieve a shopping setting. For more information about setting types, see the Setting Data Object Remarks. Add: Read-only Update: Read-only
Helps determine which Microsoft Shopping campaign serves ads, in the event that two or more campaigns use the product catalog feed from the same Microsoft Merchant Center store. A higher priority value denotes a higher priority. The supported values for most shopping campaigns are 0, 1, and 2. For smart shopping campaigns (campaign SubType set to ShoppingSmartAds), you must set the priority to 3. For Performance Max campaigns, you must set the priority to 4. In the Microsoft Advertising web application, the default priority selected is "Low" which is the equivalent of '0'. Add: Required Update: Optional
The country code for the Microsoft Merchant Center store. The Microsoft Merchant Center store catalog will be filtered to only include products for the specified country. To get the list of supported country codes use the GetBSCCountries operation. For example, supported country codes include "AU" (Australia), "AT" (Austria), "BE" (Belgium), "CA" (Canada), "CH" (Switzerland), "DE" (Germany), "ES" (Spain), "FR" (France), "GB" (United Kingdom), "IN" (India), "IT" (Italy), "NL" (Netherlands), "SE" (Sweden), and "US" (United States). Add: Optional Update: Read-only
The unique identifier for the Microsoft Merchant Center store that contains a product catalog feed that you want to use for the campaign. Once you choose a store for a campaign, you can't change it. If at some point you want to use a different store, you would need to create a new shopping campaign with a new shopping setting. With Shopping Campaigns for Brands a single campaign can target all your retailer partners, and there's no need to create individual campaigns for each retailer. We recommend that you set this to the ID of your manager account's global store (store SubType set to GlobalStore). By initially targeting all linked stores via the campaign shopping setting, you can then add up to 10 campaign negative StoreCriterion to exclude specific retailers as needed. To get the store ID, call the GetBMCStoresByCustomerId operation. The Id element of each BMCStore represents a store ID. Add: Required Update: Read-only
Determines whether local inventory ads are enabled for the Microsoft Merchant Center store. Not everyone has this feature yet. If you don't, don't worry. It's coming soon. Set this property to true if you want to enable local inventory ads, and otherwise set it to false. Add: Optional. If you do not specify this element or leave it empty, the default value of false will be set and local inventory ads will not be enabled. Update: Optional. If no value is set for the update, this setting is not changed.
Determines whether shoppable ads are enabled for the Microsoft Merchant Center store. Not everyone has this feature yet. If you don't, don't worry. It's coming soon. Set this property to true if you want to enable shoppable ads, and otherwise set it to false. Add: Optional. If you do not specify this element or leave it empty, the default value of false will be set and shoppable ads will not be enabled. Update: Optional. If no value is set for the update, this setting is not changed.
Lets you advertise all products with the same feed label in a Shopping or Performance Max campaign. There can only be one feed label per campaign. FeedLabel and SalesCountryCode are mutually exclusive You can set only one of these properties.Each feed label can have a maximum of 20 characters.You can't use FeedLabel with Shopping CoOp campaigns. Add: Optional. Update: Optional. If no value is set for the update, this setting is not changed.
Scope defines what accounts can use this audience. The scope of a similar audience is automatically set to the scope of the source remarketing list. If scope is set to Account, the audience can only be associated with campaigns and ad groups in one account i.e., via the ParentId. If scope is set to Customer, the audience can be associated with campaigns and ad groups in all of the customer's accounts. Add: Not supported Update: Not supported
This element is not applicable for similar audiences. Add: Not supported Update: Not supported
The total number of people who are active members of this audience in the Search network. This gives you an idea of how many search users you can target. The audience needs to have at least 300 people before Microsoft Advertising will use it for optimizations. The search size of a similar audience can differ from the search size of the source remarketing list. This property will be nil or empty for up to 24 hours while the source remarketing list is being built, for example if you add or update the remarketing list membership duration, rule, or tag identifier of the source remarketing list. This property will be nil or empty if the UET tag associated with the source remarketing list has a status of Unverified or Inactive, because the remarketing list can't receive the customer information from your website that it needs to build the list. Add: Not supported Update: Not supported
The total number of people who are active members of this audience in the Audience network. This gives you an idea of how many Audience network users you can target. The audience needs to have at least 300 people before Microsoft Advertising will use it for optimizations. The audience network size of a similar audience can differ from the audience network size of the source remarketing list. Add: Not supported Update: Not supported
This element is not supported for similar remarketing lists. Add: Not supported Update: Not supported
The Microsoft Advertising identifier of the similar audience. Add: Not supported Update: Not supported
The name of the similar audience is set by Microsoft Advertising. The name can contain a maximum of 128 characters. Add: Not supported Update: Not supported
The type of the audience. This value is SimilarRemarketingList when you retrieve a similar audience for remarketing lists. For more information about audience types, see the Audience Data Object Remarks. Add: Not supported Update: Not supported
The Microsoft Advertising identifier of the account or customer. If the Scope is set to Account, this is the account ID, and otherwise it is the customer ID. Add: Not supported Update: Not supported
The list of key and value strings for forward compatibility to avoid otherwise breaking changes when new elements are added in the current API version. Forward compatibility changes will be noted here in future releases. There are currently no forward compatibility changes for the Audience object. Add: Not supported Update: Not supported
The Microsoft Advertising identifier of the remarketing list that Microsoft Advertising used to generate this similar audience. Add: Not supported Update: Not supported
The type of the site. This value is NegativeKeywordList when you retrieve an Negative Keyword List. This value is AccountPlacementInclusionList when you retrieve a AccountPlacementInclusionList.
The unique Microsoft Advertising identifier of the site. Add: Read-only Update: Required
This element determines whether the preference is for the ad extension to be displayed on mobile devices or all devices. To specify a preference for mobile devices, set this element to 30001. To specify all devices, set this element to 0 (zero) or leave the element nil. By default, this element will be nil. Add: Optional Update: Optional. If no value is set for the update, the prior setting is removed.
The type of the ad extension. This value is SitelinkAdExtension when you retrieve a sitelink ad extension. Add: Read-only Update: Read-only For more information about ad extension types, see the Ad Extension Data Object Remarks.
The site-link text displayed in the ad. If you specify Description1 or Description2 then the display text can contain a maximum of 25 characters; otherwise, the display text can contain a maximum of 35 characters. If any Traditional Chinese characters are included, the limits are 11 characters given Description1 or Description2, and 15 characters otherwise. Each Traditional Chinese character countes as two characters and each English character will count only as one character. Add: Required Update: Required
The URL of the webpage that users are taken to when they click the site link. Important: If you are currently using Destination URLs, you must replace them with Final URLs. For more information, see URL Tracking with Upgraded URLs. The URL can contain dynamic parameters such as {MatchType}. For a list of supported parameters, see the Microsoft Advertising help article What tracking or URL parameters can I use?. The URL can contain a maximum of 1,024 characters. If the URL does not specify a protocol, the system uses the HTTP protocol when a user clicks the ad. If the URL specifies the HTTP protocol when you add an ad, the service will remove the http:// protocol string (the HTTP protocol string does not count against the 1,024 character limit); however, the service will not remove an HTTPS protocol string (https://) from the URL. Add: Not allowed. The destination URL is deprecated, and instead you must set the FinalUrls element. Update: Optional. The destination URL is deprecated, and instead you must set the FinalUrls element. You can either leave this element empty or set it to an empty string.
The site link description line 1. The maximum input length is 35 characters. If any Traditional Chinese characters are included, the limit is 15 characters. Each Traditional Chinese character countes as two characters and each English character will count only as one character. If you specify Description1 then Description2 is required. Add: Optional Update: Optional. If no value is set for the update, the prior setting is removed.
The site link description line 2. The maximum input length is 35 characters. If any Traditional Chinese characters are included, the limit is 15 characters. Each Traditional Chinese character countes as two characters and each English character will count only as one character. If you specify Description2 then Description1 is required. Add: Optional Update: Optional. If no value is set for the update, this setting is not changed. If you set this element to an empty string (""), the previous setting will be deleted.
The landing page URL. The following validation rules apply to Final URLs and Final Mobile URLs. - The length of the URL is limited to 2,048 characters. The HTTP or HTTPS protocol string does count towards the 2,048 character limit. - You may specify up to 10 list items for both FinalUrls and FinalMobileUrls; however, only the first item in each list is used for delivery. The service allows up to 10 list items for potential forward compatibility. - Usage of '{' and '}' is only allowed to delineate tags, for example {lpurl}. - Final URLs must each be a well-formed URL starting with either http:// or https://. - If you specify FinalMobileUrls, you must also specify FinalUrls. - You may not specify FinalMobileUrls if the DevicePreference is set to 30001 (mobile). Add: Required Update: Required
The type of the criterion. This value is Store when you retrieve a store criterion. For more information about criterion types, see the Criterion Data Object Remarks. Add: Read-only Update: Read-only
The system-generated identifier of the Microsoft Merchant Center store to exclude. You cannot exclude the global store (store SubType set to GlobalStore).
The type of the ad extension. This value is StructuredSnippetAdExtension when you retrieve a structured snippet ad extension. Add: Read-only Update: Read-only For more information about ad extension types, see the Ad Extension Data Object Remarks.
The header that is appended with a colon (:) and precedes the snippet values. Structured Snippet headers must be specified in the same language that you intend it to be shown. For example, if you want header Amenities in English you must specify the header as Amenities. If you want header Ausstattung in German you must specify the header as Ausstattung (Amenities in German). For a list of supported headers per language, please see Ad Extension Header Languages. Add: Required Update: Required
The snippet values that follow after the Header component of the ad that is shown. Each text value that you choose can have a maximum length of 25 characters. Note that for Traditional Chinese characters, each value can have a maximum length of 12 characters. Add: Required Update: Required
The type of the bidding scheme. This value is TargetCpaBiddingScheme when you retrieve a target CPA bidding scheme. For more information about bidding scheme types, see the BiddingScheme Data Object Remarks. Add: Read-only Update: Read-only
The target cost per acquisition (CPA) that you want used by Microsoft Advertising to maximize conversions. Add: Required Update: Optional
The type of the bidding scheme. This value is TargetImpressionShareBiddingScheme when you retrieve a target impression share bidding scheme. For more information about bidding scheme types, see the BiddingScheme Data Object Remarks. Add: Read-only Update: Read-only
The target impression share for the ad position where you want your ads to appear. Add: Required Update: Optional
This is where on search results pages you want your ads to appear for the target impression share you set. Possible values include FirstPage, MainLine, and MainLine1. - FirstPage: In any position on the first search results page. - MainLine: In the first set of ads that appear on the first search results page. - MainLine1: The very first ad that appears on the first search results page. Add: Required Update: Optional
This is the maximum amount that you're willing to pay for a click on your ad. Add: Optional Update: Optional
The type of the bidding scheme. This value is TargetRoasBiddingScheme when you retrieve a target ROAS bidding scheme. For more information about bidding scheme types, see the BiddingScheme Data Object Remarks. Add: Read-only Update: Read-only
The maximum cost per click that you want to spend. Add: Optional Update: Optional. The MaxCpc setting is cleared if the update value is empty.
The target return on ad spend (ROAS) that you want used by Microsoft Advertising to maximize conversions. The supported target ROAS values range from 0.01 (1 percent) to 1,000.00 (100,000 percent). Add: Required Update: Optional
The type of the setting. This value is Target when you retrieve a target setting. For more information about setting types, see the Setting Data Object Remarks. Add: Read-only Update: Read-only
Determines whether the Age, Audience, CompanyName, Gender, Industry, and JobFunction criterion type groups use the "target and bid" option or the "bid only" target option. If the Campaign Type is set to Audience, the supported values for the CriterionTypeGroup element of each TargetSettingDetail item are Age, Audience, CompanyName, Gender, Industry, and JobFunction. Otherwise the only value currently supported for other campaign types e.g., Search is Audience. Each criterion type group name is specified in a separate TargetSettingDetail object. When you retrieve this TargetSetting object, a TargetSettingDetail object will only be returned for each of the types that are setup to use the "target and bid" option. Include a TargetSettingDetail in this list for each specific criterion type group that you want to use the "target and bid" option. In this case we will only deliver ads to people who meet at least one of your criteria, while letting you make bid adjustments for specific criteria. The TargetSettingDetail applies to all criteria of the specified type e.g., all LocationCriterion that were added to the ad group. Exclude the TargetSettingDetail for a specific criterion type group name from this list if you want the "bid only" option. In this case we will deliver ads to everyone who meets your other targeting criteria, while letting you make bid adjustments for specific criteria. An entity such as a remarketing list can be associated with multiple ad groups, and each ad group's target settings (e.g., the Audience criterion group name for remarketing lists) are applied independently for delivery. For example the same remarketing list can be associated with Ad Group A and Ad Group B. The TargetSettingDetail for each ad group are set independently, and therefore the same remarketing list might be associated via the "target and bid" option for Ad Group A while associated via the "bid only" option for Ad Group B. Add: Optional. For each criterion type group name that is excluded from this list, the default setting is effectively "bid only". Update: Optional. Once you create this TargetSetting object, the existing list of TargetSettingDetail will be removed or replaced. To remove all existing TargetSettingDetail create this TargetSetting object and set the Details element to nil. To replace or append to the list of TargetSettingDetail, create this TargetSetting object and assign to the Details element a new list of TargetSettingDetail objects, including any previous TargetSettingDetail items that you want to retain. To retain all of the existing TargetSettingDetail, set the element that uses this TargetSetting object to nil. For example set the Settings element of an AdGroup to nil if you do not want to update any of the TargetSettingDetail.
The criterion type group that you want to set either the "target and bid" option or the "bid only" target option. If the Campaign Type is set to Audience, the supported values are Age, Audience, CompanyName, Gender, Industry, and JobFunction. Otherwise the only value currently supported for other campaign types e.g., Search is Audience. For more details see the Remarks below. Add: Required Update: Required
Determines whether you want to use the "target and bid" option or the "bid only" target option for the criterion type group. A value of True corresponds to the "target and bid" option, and in this case we will only deliver ads to people who meet at least one of your criteria, while letting you make bid adjustments for specific criteria. A value of False corresponds to the "bid only" option, and in this case we will deliver ads to everyone who meets your other targeting criteria, while letting you make bid adjustments for specific criteria. Add: Required Update: Required
The unique Microsoft Advertising identifier for the ad. Add: Not supported Update: Required and Read-only
The type of the ad. This value is Text when you retrieve a text ad. For more information about ad types, see the Ad Data Object Remarks. Add: Not supported Update: Not supported
The status of the ad. You can set the ad status to Active or Paused. Add: Not supported Update: Optional
The editorial review status of the ad, which indicates whether the ad is pending review, has been approved, or has been disapproved. Add: Not supported Update: Not supported
This element determines whether the preference is for text ads to be displayed on mobile devices or all devices. To specify a preference for mobile devices, set this element to 30001. To specify all devices, set this element to 0 (zero) or leave the element nil. By default, this element will be nil. You must define at least one text ad per ad group that is not mobile preferred, otherwise the ad will be eligible for all devices. Add: Not supported Update: Not supported
The Ad Format Preference is used to indicate whether or not you prefer the ad copy to be shown to users as a search or audience ad. Search ads tend to be written as a call to action, whereas audience ads should be written in more of an informational style. While you have the option to use search text ads as audience ads, designating an ad as Audience ads preferred format allows you to optimize its messaging for native delivery. IMPORTANT: You must define at least one text ad per ad group that does not prefer audience ads, otherwise the ad copy of all text ads will be eligible for both search and audience ads. Possible values are AudienceAd and All. If set to All, the ad will be eligible for both search and audience ad formats. If set to AudienceAd, the ad will only be eligible for the audience ad format. Add: Not supported Update: Not supported
The tracking template to use as a default for all landing page URLs. The following validation rules apply to tracking templates. For more details about supported templates and parameters, see the Microsoft Advertising help article What tracking or URL parameters can I use? - Tracking templates defined for lower level entities e.g. ads override those set for higher level entities e.g. campaign. For more information, see Entity Limits. - The length of the tracking template is limited to 2,048 characters. The HTTP or HTTPS protocol string does count towards the 2,048 character limit. - The tracking template must be a well-formed URL beginning with one of the following: http://, https://, {lpurl}, or {unescapedlpurl}. - Microsoft Advertising does not validate whether custom parameters exist. If you use custom parameters in your tracking template and they do not exist, then the landing page URL will include the key and value placeholders of your custom parameters without substitution. For example, if your tracking template is https://tracker.example.com/?season={_season}&promocode={_promocode}&u={lpurl} and neither {_season} or {_promocode} are defined at the campaign, ad group, criterion, keyword, or ad level, then the landing page URL will be the same. Add: Not supported Update: Not supported
The landing page URL. This URL is used only if the keyword does not specify a final URL. The following validation rules apply to Final URLs and Final Mobile URLs. - The length of the URL is limited to 2,048 characters. The HTTP or HTTPS protocol string does count towards the 2,048 character limit. - You may specify up to 10 items for both FinalUrls and FinalMobileUrls; however, only the first item in each list is used for delivery. The service allows up to 10 for potential forward compatibility. - Usage of '{' and '}' is only allowed to delineate tags, for example {lpurl}. - Final URLs must each be a well-formed URL starting with either http:// or https://. - If you specify FinalMobileUrls, you must also specify FinalUrls. - You may not specify FinalMobileUrls if the device preference is set to mobile. Also note that if this ad's TrackingUrlTemplate or UrlCustomParameters element are set, then at least one final URL is required. Add: Not supported Update: Not supported
The mobile landing page URL. This URL is used only if the keyword does not specify a final mobile URL. The following validation rules apply to Final URLs and Final Mobile URLs. - The length of the URL is limited to 2,048 characters. The HTTP or HTTPS protocol string does count towards the 2,048 character limit. - You may specify up to 10 items for both FinalUrls and FinalMobileUrls; however, only the first item in each list is used for delivery. The service allows up to 10 for potential forward compatibility. - Usage of '{' and '}' is only allowed to delineate tags, for example {lpurl}. - Final URLs must each be a well-formed URL starting with either http:// or https://. - If you specify FinalMobileUrls, you must also specify FinalUrls. - You may not specify FinalMobileUrls if the device preference is set to mobile. Also note that for TextAd objects you may not specify FinalMobileUrls if the DevicePreference is set to 30001 (mobile). Add: Not supported Update: Not supported
The URL of the webpage to take the user to when they click the ad. The URL can contain dynamic parameters such as {MatchType}. For a list of supported parameters, see the Microsoft Advertising help article What tracking or URL parameters can I use?. The URL can contain a maximum of 1,024 characters. If the URL does not specify a protocol, the system uses the HTTP protocol when a user clicks the ad. If the URL specifies the HTTP protocol when you add an ad, the service will remove the http:// protocol string (the HTTP protocol string does not count against the 1,024 character limit); however, the service will not remove an HTTPS protocol string (https://) from the URL. Important: If you are currently using Destination URLs, you must replace them with Final URLs. For more information, see URL Tracking with Upgraded URLs. This URL is used only if the keyword does not specify a destination URL. Add: Not supported Update: Not supported
The title of the ad. The title must contain at least one word. The ad's copy and title combined must total at least three words. The title can contain dynamic text strings such as {keyword}. For more information, see the Microsoft Advertising help article Automatically customize your ads with dynamic text parameters. The maximum input length of the title is 80 characters, and can contain dynamic text strings. The ad will fail to display or default text will be used if the length exceeds 25 characters after dynamic text substitution occurs. Note that for ad groups that use Traditional Chinese, the title is limited to 15 characters after substitution. The title cannot contain the newline (\n) character. Add: Not supported Update: Not supported
The ad copy. The copy must contain at least one word. The ad's copy and title combined must total at least three words. The text can contain dynamic text strings such as {keyword}. For more information, see the Microsoft Advertising help article Automatically customize your ads with dynamic text parameters. The maximum input length of the copy is 300 characters, and can contain dynamic text strings. The ad will fail to display or default text will be used if the length exceeds 71 characters after dynamic text substitution occurs. Note that for ad groups that use Traditional Chinese, the text is limited to 38 characters after substitution. The text cannot contain the newline (\n) character. Add: Not supported Update: Not supported
The URL to display in the ad. The subdirectory of the display URL can contain dynamic text strings such as {keyword}; however, the URL hostname cannot contain dynamic text. For more information, see the Microsoft Advertising help article Automatically customize your ads with dynamic text parameters. The maximum input length of the URL is 200 characters, and can contain dynamic text strings. The ad will fail to display or default text will be used if the length exceeds 35 characters after dynamic text substitution occurs. Add: Not supported Update: Not supported
The unique Microsoft Advertising identifier for the asset in a Microsoft Advertising account. The same asset can be used by multiple ads. For example if Seemless Integration is a text asset, it will have the same asset identifier across all ads in the same Microsoft Advertising account. After you link a text asset to an ad and then retrieve the ad e.g., via GetAdsByIds, the response will include the asset identifier e.g., ""id:""123, whether the asset is new or already existed in the account's asset library. Add: Read-only. Even if the asset already exists and you specify an invalid identifier, this value will be ignored. Update: Read-only. Even if the asset already exists and you specify an invalid identifier, this value will be ignored.
The type of the asset. This value is TextAsset when you retrieve a text asset. For more information about asset types, see the Asset Data Object Remarks. Add: Read-only Update: Read-only
The meaning and business rules for the text asset vary depending on where it is used. For example, see responsive search ad Descriptions and Headlines. Add: Required Update: Required
The type of the criterion. This value is Topic when you retrieve a topic criterion. For more information about criterion types, see the Criterion Data Object Remarks. Add: Read-only Update: Read-only
The ID of the topic. Possible values include: 1: Games2: Shopping3: Business & Industrial4: Sports5: Home & Garden6: News7: Travel & Transportation8: Finance9: Health10: Jobs & Education11: Arts & Entertainment12: Autos & Vehicles13: Computers & Electronics14: Real Estate15: Hobbies & Leisure16: Beauty & Fitness17: Internet & Telecom18: Books & Literature19: Law & Government20: Food & Drink21: People & Society22: Online Communities23: Science24: Pets & Animals25: Reference26: World Localities
The identifier of the account which contains the extensions.
The list of ad extensions of any type, to update within the account. You may specify a maximum of 100 extensions per call.
An array of BatchErrorCollection objects that contain details for any ad extensions that were not successfully updated. The top level error within each BatchErrorCollection object corresponds to potential ad extension errors. The nested list of BatchError objects would include any errors specific to the list items within an ad extension (if applicable). The list of errors do not correspond directly to the list of items in the request. The list can be empty if there were no errors, or can include one or more error objects corresponding to each unsuccessful list item in the request.
The type of criterion to update, for example Webpage. You can specify only one criterion type value per call. To add, delete, or update target criterions i.e., age, company name, day and time, device, gender, industry, job function, location, location intent, and radius criterions, you must specify the CriterionType value as Targets. You can add, delete, and update multiple target criterion types in the same operation. To retrieve these target criterions via GetAdGroupCriterionsByIds you must request the specific type individually i.e., Age, CompanyName, DayTime, Device, Gender, Industry, JobFunction, Location, LocationIntent, and Radius. To add, delete, or update audience criterions i.e., custom audiences, in-market audiences, and remarketing lists, you must specify the CriterionType value as Audience. You can add, delete, and update multiple target criterion types in the same operation. To retrieve these audience criterions via GetAdGroupCriterionsByIds you must request the specific type individually i.e., CustomAudience, InMarketAudience, ProductAudience, and RemarketingList. You cannot update a ProductPartition with this operation. Instead, you should use ApplyProductPartitionActions.
The list of criterions to update. You can include up to 1,000 ad group criterions per request. Within each AdGroupCriterion object, you must specify the criterion's ID and the ID of the ad group that it belongs to.
An array of BatchErrorCollection objects that contain details for any criterion that were not successfully updated. The top level error within each BatchErrorCollection object corresponds to potential criterion errors. The nested list of BatchError objects would include any errors specific to the list of items a criterion can have. The list of errors do not correspond directly to the list of items in the request. The list can be empty if there were no errors, or can include one or more error objects corresponding to each unsuccessful list item in the request.
The identifier of the campaign that owns the ad groups to update.
An array that can contain a maximum of 1,000 AdGroup objects to update.
Determines whether or not the service should use the AudienceAdsBidAdjustment element of each specified AdGroup during update. If set to True, the AudienceAdsBidAdjustment will be used, and otherwise it will be ignored and your existing native bid adjustment setting will be retained during update. The default value is False if this element is not set.
The ID of the ad group that contains the ads to update.
A list of ads to update. You may update a maximum of 50 ads. The Id element must specify the ID of the ad to update. Specify only those elements that you want to update. The call will fail if you specify a non-null value for a read-only element such as Id.
Array of audience groups to update. The maximum size of the list is 100 items per service request.
A list of audiences to update. The maximum size of the array is 100. You can only update RemarketingList and CustomAudience objects. You cannot update InMarketAudience objects.
An array of BidStrategy objects to update in the account's portfolio bid strategy library. You can include a maximum of 100 bid strategies in a single call. The account is determined by the required CustomerAccountId header element.
An array of Budget objects to update in the account's shared budget library. You can update a maximum of 100 budgets in a single call. The account is determined by the required CustomerAccountId header element.
The type of criterion to update, for example Webpage. You can specify only one criterion type value per call. To add, delete, or update target criterions i.e., age, day and time, device, gender, location, location intent, and radius criterions, you must specify the CriterionType value as Targets. You can add, delete, and update multiple target criterion types in the same operation. To retrieve these target criterions via GetCampaignCriterionsByIds you must request the specific type individually i.e., Age, DayTime, Device, Gender, Location, LocationIntent, and Radius.
The list of campaign criterions to update. You can include up to 100 campaign criterions per request. Within each CampaignCriterion object, you must specify the criterion's ID and the ID of the campaign that it belongs to.
An array of BatchErrorCollection objects that contain details for any criterion that were not successfully updated. The top level error within each BatchErrorCollection object corresponds to potential criterion errors. The nested list of BatchError objects would include any errors specific to the list of items a criterion can have, for example a list of product conditions. The list of errors do not correspond directly to the list of items in the request. The list can be empty if there were no errors, or can include one or more error objects corresponding to each unsuccessful list item in the request.
The identifier of the account that contains the campaign to update.
An array that can contain a maximum of 100 Campaign objects to update.
An array of ConversionGoal objects to update within the account's shared conversion goal library. You can update a maximum of 100 conversion goals in a single call. The account is determined by the required CustomerAccountId header element.
Update the status of the conversion value rules with these IDs.
The new status to be applied to the specified conversion value rules.
An array of Experiment objects to update within the account. You can update a maximum of 100 experiments in a single call. The account is determined by the required CustomerAccountId header element.
The import jobs to update. Although this element is an array, you can include a maximum of one GoogleImportJob object per call.
A list of unique system identifiers corresponding to the replacement import jobs. The list of replacement identifiers corresponds directly to the list of replaced import jobs in the request. Items of the list may be returned as null. For each list index where an import job was not updated, the corresponding element will be null.
The identifier of the ad group whose keywords will be updated.
An array of Keyword objects that contains the updated keyword information. The Id element of each of these objects identifies the keyword to update. This array can contain a maximum of 1,000 elements.
The list of labels that you want to update. The maximum size of the list is 100 items per service request.
An array of the LinkedIn segments to update.
n array BatchError that contains details for any request items that were not successful. The list of errors does not correspond directly to the list of items in the request. The list can be empty if there were no errors, or it can include one or more error objects corresponding to each unsuccessful list item in the request.
The negative keyword lists or website exclusion lists to update. If the SharedEntityScope is either empty or set to Account, then the SharedEntities must be negative keyword list (NegativeKeywordList) objects. If the SharedEntityScope is set to Customer, then the SharedEntities must be website exclusion list (PlacementExclusionList) objects. The list can contain a maximum of 20 items per service call.
Indicates whether the shared entity is available at the ad account (Account) or manager account (Customer) level. This element is optional and defaults to Account scope. The ad account scope is only applicable for negative keyword lists. Set this element to Customer to update website exclusion lists in your manager account (customer) shared library.
An array of UetTag objects to update within the customer's shared UET tag library. You can update a maximum of 100 UET tags in a single call.
The list of videos that you want to update. The maximum size of the list is 100 items per service request.
The category used to segment the conversion goal. Categorize your conversion goals however makes sense for your business. Goal categories don't affect performance - they are here to help you segment your goals and their performance metrics. The supported category values vary by conversion goal type. Url goals support the AddToCart, BeginCheckout, BookAppointment, Contact, GetDirections, Other, OutboundClick, PageView, Purchase, RequestQuote, Signup, SubmitLeadForm, and Subscribe categories. Add: Required as of June 2021. Previously if you left this element nil or empty, the default category was set to None. Update: Optional if the conversion goal already has a category set other than None. If no value is set for the update, this setting is not changed.
The type of the conversion goal. This value is Url when you retrieve a Url goal. For more information about conversion goal types, see the ConversionGoal Data Object Remarks. Add: Read-only Update: Read-only
The operator that can be applied to the value of the Url element. Add: Optional; If not specified, the default operator is Equals. Update: Optional; If not specified during update, the previous setting is retained.
The expression used to determine the page or pages the user has to visit in order to count as a conversion. Add: Required Update: Optional
The display mode for vanity pharma URLs for a campaign. Note: VanityPharmaDisplayUrlMode is available for limited pilot usage (e.g., pharmaceutical customers). Add: Optional. If you do not specify this field or leave it empty, the default value of ManufacturerWebsiteUrl will be set. Update: Optional. If no value is set for the update, this setting is not changed. Delete: Read-only.
The text that shows in the display URL of a text ad when WebsiteDescription is the selected display mode for vanity pharma URLs for the campaign. Note: VanityPharmaWebsiteDescription is available for limited pilot usage (e.g., pharmaceutical customers). Add: Optional. If you do not specify this field or leave it empty, the default value of Unspecified is set. Update: Optional. If no value is set for the update, this setting is not changed. If no value is set but the value for VanityPharmaDisplayURLMode is set to ManufacturerWebsiteUrl, the value of Unspecified is set. If no value is set but the value for VanityPharmaDisplayURLMode is set to WebsiteDescription, the campaign service will return the TBD error code. If a value other than Unspecified is set but the value for VanityPharmaDisplayURLMode is set to ManufacturerWebsiteUrl, the campaign service will return the TBD error code. Delete: Read-only
The unique Microsoft Advertising identifier for the asset in a Microsoft Advertising account. The same image asset identifier can be used multiple times in the same ad for different aspect ratios, and can also be used by multiple ads in the same Microsoft Advertising account. Add: Read-only. Even if the asset already exists and you specify an invalid identifier, this value will be ignored. Update: Read-only. Even if the asset already exists and you specify an invalid identifier, this value will be ignored.
The type of the asset. This value is VideoAsset when you retrieve a video asset. For more information about asset types, see the Asset Data Object Remarks. Add: Read-only Update: Read-only
Represents the aspect ratio for this Video asset. The possible subtype values include VideoMedia16X9, VideoMedia5X4, VideoMedia1X1, VideoMedia4X5, VideoMedia9X16 Add: Required Update: Read-only. You cannot update the subtype while updating VideoAsset.
The type of the criterion. This value is Webpage when you retrieve a webpage criterion. For more information about criterion types, see the Criterion Data Object Remarks. Add: Read-only Update: Read-only
The webpage parameter that contains a list of webpage conditions or criteria. Add: Required Update: Optional. You can update the criterion name, but cannot update the webpage conditions. To update the conditions you must delete the criterion and add a new criterion.
An insertion order to add to the account.
The identifier of the account to which the insertion order applies. You cannot update the account identifier after you create the insertion order. Add: Required Update: Read-only
Reserved for internal use. Add: Required for some accounts; Optional for some accounts. Update: Read-only
A description of the insertion order. The description is limited to 100 characters. Add: Optional Update: Optional
The date that the insertion order expires. The end date must be later than the start date. The date is stored in Coordinated Universal Time (UTC). Only the month, day, and year of the specified string are used. If you specify the hour, minutes, and seconds of a date they will be ignored. For information about the format of the date and time, see the dateTime entry in Primitive XML Data Types. Note: If the insertion order has no end date, EndDate is empty. Adding or updating unlimited insertion orders isn't supported. EndDate operates in read-only mode. Add: Required Update: Optional. If you attempt to update the StartDate or EndDate of an insertion order that is part of a recurring series the API will return an error.
A system-generated identifier that identifies the insertion order. Add: Read-only Update: Read-only and Required
An identifier of the last user to update the insertion order. Add: Read-only Update: Read-only
The date and time that the insertion order was last updated. The date is stored in Coordinated Universal Time (UTC). For information about the format of the date and time, see the dateTime entry in Primitive XML Data Types. Add: Read-only Update: Read-only
A percentage of the budget that has been spent. Specify the percentage as a value from 0 to 100. Notification is sent when the threshold is reached. For example, if you set the threshold to 70, the Billing service sends notification when you have spent 70 percent of the budget. If you do not want to receive notification, set to NULL. Reserved for internal use. Add: Optional Update: Optional
Reserved for internal use only. Add: Optional Update: Optional
The budget for this insertion order. The budget is a hard limit. When the account reaches this limit and there is not another insertion order available, the account's lifecycle status value is set to Pause. This element is empty if the insertion order has unlimited budget. The budget is the maximum amount of money you want to spend for an insertion order. For insertion orders with unlimited budget, your budget is bounded by your credit limit. In that case each campaign's daily budget determines the maximum spend. Note: Adding or updating unlimited insertion orders isn't supported. SpendCapAmount operates in read-only mode. Add: Required Update: Optional
The date that the insertion order can begin accruing charges. The start date must be later than the current date. The date is stored in Coordinated Universal Time (UTC). Only the month, day, and year of the specified string are used. If you specify the hour, minutes, and seconds of a date they will be ignored. For information about the format of the date and time, see the dateTime entry in Primitive XML Data Types. Add: Required Update: Optional. You can only update the start date via this element if the Status is PendingUserReview. If the start date has already passed, then you cannot change it. If you attempt to update the StartDate or EndDate of an insertion order that is part of a recurring series the API will return an error.
The friendly name that can be used to reference this insertion order. The name can contain a maximum of 100 characters. The name does not need to be unique compared to other insertion orders for the customer. Add: Optional Update: Optional
The status of the insertion order. Add: Read-only. Insertion orders that you create are immediately set to Active, NotStarted, or Declined. Update: Required to approve or decline an insertion order that is not yet approved, or cancel an insertion order that has already be approved. You can only approve or decline via this element if the current status is set to PendingUserReview. You can only cancel via this element if the current status is set to Active, Exhausted, or NotStarted. Once the insertion order status is Active, Exhausted, Expired, or NotStarted, then you can either make new changes or approve or decline the current pending changes via the PendingChanges element. When you call UpdateInsertionOrder you can either set this Status element or modify other elements of this object, but you cannot change the status in parallel with other property updates. If you update the Status of an insertion order that is part of a recurring series, the status update will be applied to all insertion orders in the series.
A purchase order value that can be used to reference this insertion order in monthly invoices. This value will be printed as the purchase order in the monthly invoices. The purchase order can contain a maximum of 50 characters. Add: Optional Update: Optional
Can be used to manage changes for an approved insertion order with status set to either Active, Exhausted, Expired, or NotStarted. Add: Read-only Update: Optional
The system-generated account number that is used to identify the account in the Microsoft Advertising web application. The account number has the form xxxxxxxx, where xxxxxxxx is a series of any eight alphanumeric characters. Add: Read-only Update: Read-only
The running balance of the insertion order. The running balance value is initially the same as the SpendCapAmount, and then decreases each time an ad in the account is served. This element is empty if the insertion order has unlimited budget. Add: Read-only Update: Read-only
The remaining balance of the insertion order. The remaining balance is initially 0 (zero), and then increases towards the SpendCapAmount each time an ad in the account is served. This element is empty if the insertion order has unlimited budget. Add: Read-only Update: Read-only
The percent of budget remaining for the insertion order. This value is calculated as BudgetRemaining / SpendCapAmount. This element is empty if the insertion order has unlimited budget. Add: Read-only Update: Read-only
The percent of budget spent for the insertion order. This value is calculated as BudgetSpent / SpendCapAmount. This element is empty if the insertion order has unlimited budget. Add: Read-only Update: Read-only
The name of the recurring insertion order series. The name can contain a maximum of 100 characters. Even if the insertion order is later removed from the recurring series, this element will continue to reflect the name of the series it was created in. Add: Read-only Update: Read-only
Determines whether the insertion order is in a recurring series. If the value is True, the insertion order is part of a recurring series. If you attempt to update the StartDate or EndDate of an insertion order that is part of a recurring series the API will return an error. If you update the Status of an insertion order that is part of a recurring series, the status update will be applied to all insertion orders in the series. Add: Read-only Update: Read-only
Determines how an order recurs in the series. The possible values are Monthly, BiMonthly, Quarterly, and Yearly. Add: Read-only Update: Read-only
Determines whether the insertion order has unlimited budget. If the value is True, the insertion order will have unlimited budget and the SpendCapAmount of this insertion order will be ignored. Add: Optional Update: Optional
Determines whether the insertion order has no end date. If the value is True, the insertion order will have no end date and the EndDate of this insertion order will be ignored. Add: Optional Update: Optional
A description of the insertion order. The description is limited to 100 characters. Add: Read-only Update: Optional
The date that the insertion order expires. The end date must be later than the start date. The date is stored in Coordinated Universal Time (UTC). Only the month, day, and year of the specified string are used. If you specify the hour, minutes, and seconds of a date they will be ignored. For information about the format of the date and time, see the dateTime entry in Primitive XML Data Types. This element is empty if the insertion order has no end date. Add: Read-only Update: Optional
An identifier of the last user to request a change to the insertion order. Add: Read-only Update: Read-only
The date and time that the insertion order change request was submitted. The date is stored in Coordinated Universal Time (UTC). For information about the format of the date and time, see the dateTime entry in Primitive XML Data Types. Add: Read-only Update: Read-only
A percentage of the budget that has been spent. Specify the percentage as a value from 0 to 100. Notification is sent when the threshold is reached. For example, if you set the threshold to 70, the Billing service sends notification when you have spent 70 percent of the budget. If you do not want to receive notification, set to NULL. Reserved for internal use. Add: Read-only Update: Optional
Internal use only. Add: Read-only Update: Optional
The budget for this insertion order. The budget is a hard limit. When the account reaches this limit and there is not another insertion order available, the account's lifecycle status value is set to Pause. This element is empty if the insertion order has unlimited budget. Add: Read-only Update: Optional
The date that the insertion order can begin accruing charges. The start date must be later than the current date. The date is stored in Coordinated Universal Time (UTC). Only the month, day, and year of the specified string are used. If you specify the hour, minutes, and seconds of a date they will be ignored. For information about the format of the date and time, see the dateTime entry in Primitive XML Data Types. Add: Read-only Update: Optional. You can only update the start date via this element if the Status element of the InsertionOrder is NotStarted. If the start date has already passed, then you cannot change it.
The friendly name that can be used to reference this insertion order. The name can contain a maximum of 100 characters. The name does not need to be unique compared to other insertion orders for the customer. Add: Read-only Update: Optional
A purchase order value that can be used to reference this insertion order in monthly invoices. This value will be printed as the purchase order in the monthly invoices. The purchase order can contain a maximum of 50 characters. Add: Read-only Update: Optional
Can be used to accept or decline the insertion order pending changes. When you call UpdateInsertionOrder you can either set this ChangeStatus element or modify other elements of this object, but you cannot change the status in parallel with other property updates.
A long value that represents the identifier for the insertion order that was added.
Identifies the server time in UTC when the insertion order was added.
An array of BatchError objects that identifies the items in the batch of items in the request message that caused the operation to fail. Each object contains the details that explain why the item caused the failure.
An array of OperationError objects that contains the reasons that explain why the service operation failed when the error is not related to a specific item in the batch of items.
The identifier of the account for which the billing document was generated.
The currency of the billing document. For possible values, see Currencies.
The identifier of the customer for which the billing document was generated.
A list of account identifiers to check for eligibility.
A list of account id and coupon code pairs.
The date a claim was made for an account.
An array of OperationError objects that correspond to any email addresses where the coupon code could not be sent to. The list can be empty if there were no errors.
The code that can be used to redeem the coupon.
The class name that the coupon was minted from.
The coupon's type. Supported types include: Acquisition: Acquisition coupon is used to acquire new customers. Only new customers can redeem this coupon. Retention: Retention coupons can be used by both new and existing customers.
The value amount of the coupon. The CurrencyCode element determines the currency.
The coupon can't be consumed until the account's spend reaches this threshold from the time coupon was redeemed. The CurrencyCode element determines the currency.
The currency of the coupon amount and spend threshold. For possible values, see Currencies.
The percent off coupon value. This is only applicable for a percentage coupon. For example, 10.0 represents a 10% discount.
Active days since coupon has been redeemed. After these days, the coupon can't be consumed.
The coupon expiration date. After this date, the coupon can't be consumed.
The coupon cannot be redeemed before the start date.
The last date that the coupon can be redeemed.
The email address the coupon has been emailed by the DispatchCoupons operation.
The date the coupon was emailed by the DispatchCoupons operation.
Has the coupon been redeemed. Value will be true if the coupon has been redeemed, and otherwise the value is false.
Contains redemption and consuming details. Returned only when the account where the coupon was redeemed bills to the coupon's owner customer.
The AccountId, AccountNumber, and ClaimDate of the claim.
The identifier of the account to which the coupon was redeemed.
The remaining amount of the coupon in account currency.
The currency of the coupon balance and spend threshold.
The date that coupon was redeemed to the account.
The date that the coupon is ready to be consumed.
The identifier of the account related to the claim.
The account number of the account related to the claim.
The value of the upfront spending coupon.
The length of time in which the coupon may be used.
The amount that must be spent before the coupon is applied.
The balance after the coupon is applied.
Email addresses to which the coupons are dispatched. Email address count should not exceed 1000.
The identifier of the customer that the coupon class belongs to.
The name of coupon class whose available coupons are dispatched.
An array of BatchError objects that correspond to any email addresses where the coupon code could not be sent to. The list can be empty if there were no errors.
The class name of the distributed coupons.
An array of OperationError objects that correspond to any email addresses where the coupon could not be distributed. The list can be empty if there were no errors.
The identifier of the account that contains the spend information to get. The account must use the invoice payment method; credit card accounts are not supported. If the account identifier belongs to an aggregator, the operation sums the account balances for all the accounts of all the customers that the aggregator manages. If the aggregator has ten customers and each customer has ten accounts, the operation returns the sum of the monthly spend of all 100 accounts. To get the monthly spend of a single account of a customer that the aggregator manages, set the AccountId element to the specified account identifier. To get the monthly spend of all the accounts of a customer that the aggregator manages, call this operation for each account, and then sum the monthly spend amounts.
The month and year for which you want to get the monthly spend information (the operation ignores the day and time values). The service uses the month and year components corresponding to the specified dateTime. For example 2020-05-15T00:00:00 and 2020-05 are both valid and will return the same results. If you specify the current month, the operation returns the month-to-date spend amount. For example, if the current date is May 15, 2020 and you set MonthYear to May 2020, the operation returns the spend amount for May 1 to May 15, inclusively. You cannot specify a future month and year. If you specify a prior month for which there is no data, the call returns 0 (zero). The spend amount can span multiple insertion orders (IOs). If the credits are greater than the actual spend, the returned monthly spend amount is a negative value.
The amount spent by the account in the specified period. The account must be Yahoo!-managed. If the account is not Yahoo!-managed, the return value is 0.
A list of identifiers of the accounts whose billing document information you want to get.
The start date to use for specifying the billing documents to get. The start date cannot be later than the end date. You must specify the date in Coordinated Universal Time (UTC).
The end date to use for specifying the billing documents to get. To specify today's date as the end date, set EndDate to NULL. The end date cannot be earlier than the start date. You must specify the date in Coordinated Universal Time (UTC).
Include the invoice number with the request.
The list of billing document information objects that were retrieved.
Identifies the list of billing documents that you want to get. Each BillingDocumentInfo object in the list must contain the CustomerId and DocumentId. The other properties are ignored. You can include up to 25 items in the list.
The format to use to generate the billing document. For example, you can generate the billing document in PDF or XML format.
The list of billing documents that were retrieved.
Determines the field to order the results. For example order the results by Id.
Determines whether the results are ascending or descending.
The page size and the number of results to return in the specified page. The maximum size is 100. If you do not set this element the default size is 0 (zero).
The name of the element for the object you are searching. For possible values, see the SearchInsertionOrders operation.
Defines the relationship between the field and the value.
The string to search in the specified field. The length of this string must be four or greater, unless the field is set to MarketCountry or MarketLanguage.
The identifier of the account to which the coupon is redeemed.
The date and time that the coupon was redeemed.
Determines the request conditions. This operation's response will include coupons that match all of the specified predicates. You may specify up to 4 predicates, and one of the predicate fields must be CustomerId. For a list of supported Field and Operator elements of a Predicate object for this service operation, see Predicate Remarks.
Determines the order of results by the specified property of a coupon. You should only specify one OrderBy element in the array. Additional elements are not supported and will be ignored by the service. For this service operation, the following values are supported in the Field element of a OrderBy object. CouponClassName - The order is determined by the CouponClassName element of the returned Coupon. CouponStartDate - The order is determined by the CouponStartDate element of the returned Coupon.
Determines the index and size of results per page.
If set to "CouponClaimInfo", return CouponClaimInfo in the response.
A list of coupons that meet the specified criteria.
Determines the request conditions. This operation's response will include accounts that match all of the specified predicates. You may specify up to 6 predicates, and one of the predicate fields must be AccountId. You may use the StartDate and EndDate predicate fields twice each to specify start and end date ranges, and otherwise may only use each predicate field once. For a list of supported Field and Operator elements of a Predicate object for this service operation, see Predicate Remarks.
Determines the order of results by the specified property of an account. You should only specify one OrderBy element in the array. Additional elements are not supported and will be ignored by the service. For this service operation, the following values are supported in the Field element of a OrderBy object. Id - The order is determined by the Id element of the returned InsertionOrder. Name - The order is determined by the Name element of the returned InsertionOrder.
The list of additional properties that you want included within each returned insertion order. The additional field values enable you to get the latest features using the current version of Customer Billing API. Note: Corresponding elements will be included by default in a future update. This request element is optional.
A list of insertion orders that meet the specified criteria.
An insertion order to update within the account.
Identifies the server time in UTC when the insertion order was last modified.
The system-generated identifier of the account.
A flag value that indicates who paused the account. The following are the possible values: 1 - The user paused the account. 2 - The billing service paused the account. 4 - The user and billing service paused the account.
The system-generated identifier of the customer that manages or owns the account. If this account is the result of an account match using the FindAccountsOrCustomersInfo, the customer identifier is that of the customer that owns the account. However, if the account is the result of a customer match, the customer identifier is that of the aggregator that manages the account, if the account is managed by an aggregator; otherwise, the identifier is that of the customer that owns the account.
The name of the customer that manages or owns the account.
The system-generated account number that is used to identify the account in the Microsoft Advertising web application. The account number has the form xxxxxxxx, where xxxxxxxx is a series of any eight alphanumeric characters.
The account mode distinguishes between smart and expert accounts. The possible values include, but are not limited to: Expert - Expert Mode is the full-feature Microsoft Advertising experience. It gives you more control over campaign management, lets you add more content to your ads, and provides much more in the way of performance reporting and tracking. Smart - Microsoft Advertising will use Microsoft AI to create ads and manage your advertising campaign for you. UnifiedSmart - The account supports advertising across Bing, Google, and Facebook. You can also manage your social network presence on Facebook, Instagram, and LinkedIn. Note: As of April 25, 2023, UnifiedSmart no longer supports Twitter. Most Bing Ads API operations are only supported with Expert accounts. Accounts with any account mode are returned when you request account information e.g., FindAccountsOrCustomersInfo, GetAccount, GetAccountsInfo, GetUser, and SearchAccounts. Add: Read-only for most accounts. Customers in the closed Unified smart campaigns pilot can set the account mode to "UnifiedSmart". Update: Read-only
The container name of the tax certificate.
The status of the tax certificate: Valid, Invalid, or Pending.
The account that you want to add to the existing customer. You must set the ParentCustomerId in the advertiser account object.
The identifier of the customer that is billed for the charges that the account generates. This is either the aggregator that manages this account on behalf of the owner or the identifier of the customer that owns the account. The service sets the identifier based on the owner of the payment instrument identified in the PaymentMethodId element. Add: Read-only Update: Read-only
The ISO code for the currency that is used to settle the account. The service uses the currency information for billing purposes. Add: Required Update: Read-only
The financial status of the account. For example, the status can indicate whether the account is in good standing or is past due. Add: Read-only Update: Read-only
The system-generated identifier of the account. This is the identifier that you set the AccountId element and CustomerAccountId SOAP header to in many of the campaign requests. Add: Read-only Update: Required
The language used to render the billing documents that you receive from Microsoft Advertising (if you use an invoice as your payment method). This setting is only for billing documents for this account, and doesn't apply to other Microsoft Advertising accounts you might have. If you leave this empty when signing up a customer, the operation uses the language value from the Lcid element of the primary user. If the Lcid is set to a value such as FrenchCanada, then the account language is set to French. Add: Read-only for AddAccount; Required for SignupCustomer if the UserInvitation is set, and otherwise this element is Optional. Update: Optional. If no value is set for the update, this setting is not changed.
The identifier of the last user to update the account's information. Add: Read-only Update: Read-only
The date and time that the account was last updated. The value is in Coordinated Universal Time (UTC). The date and time value reflects the date and time at the server, not the client. For information about the format of the date and time, see the dateTime entry in Primitive XML Data Types. Add: Read-only Update: Read-only
The name of the account. The string can contain between 3 and 100 characters and must be unique among all account names within the customer. Add: Required Update: Required
The identifier of the customer that owns the account. In the campaign requests that require a customer identifier, this is the identifier that you set the CustomerId SOAP header to. Add: Required for AddAccount; Required for SignupCustomer if the UserInvitation is not set, and otherwise this element is ignored. Update: Read-only
The identifier of the payment instrument to use to settle the account. Add: Optional for AddAccount; Read-only for SignupCustomer if the UserInvitation is not set. When you call SignupCustomer set this element to NULL. The service picks up the payment method identifier associated with the aggregator customer's invoice automatically. For SignupCustomer if the UserInvitation is set, and if the new client account is being linked to an agency via LinkedAgencies, and if the agency should be billed, set this element to the agency's payment instrument ID. Otherwise you should leave this element null. Update: Optional. If no value is set for the update, this setting is not changed.
The type of payment instrument to use to settle the account. You do not have to set this value because the type is determined by the payment instrument corresponding to the PaymentMethodId element. When you call the GetAccount and SearchAccounts to get the account data, PaymentMethodType is set to NULL, and you cannot determine the payment method that the account uses. Reserved for internal use. Add: Read-only Update: Read-only
The identifier of the account manager who is primarily responsible for managing this account. Only Super Admin and Standard users can be set as the primary contact for an account. Add: For AddAccount if the new client account is being linked to an agency via LinkedAgencies, then you can assign one of the agency users as primary user for the new account. When you call SignupCustomer as an aggregator without including the UserInvitation, you should leave this element empty and the primary user will be set to the aggregator user identifier. When you call SignupCustomer and the UserInvitation is included, you can leave this element empty and the primary user will be set to the identifier of the new client user who accepts the invitation. When you call SignupCustomer and if the UserInvitation is set, and if the new client account is being linked to an agency via LinkedAgencies, then you can assign one of the agency users as primary user for the new account. Update: Optional. If no value is set for the update, this setting is not changed.
The status of the account. You cannot set the status of the account. Add: Read-only Update: Read-only
The time-stamp value that the system uses internally to reconcile updates when you call the UpdateAccount and DeleteAccount operations. Add: Read-only Update: Required
The default time-zone value to use for campaigns in this account. If you do not specify a value when the account is added, the time zone will be set to PacificTimeUSCanadaTijuana by default. This time-zone value is used by the Microsoft Advertising web application to display the account time zone preference, and does not provide a default time-zone value for campaigns that are created by using the Bulk or Campaign Management API. Add: Optional Update: Optional. If no value is set for the update, this setting is not changed.
A flag value that indicates who paused the account. The following are the possible values: 1 - The user paused the account. 2 - The billing service paused the account. 4 - The user and billing service paused the account. Add: Read-only Update: Read-only
The list of agencies linked to this account. Currently only one agency customer is supported when you add the account. When you retrieve the account all linked agency customer info will be included. Add: Optional for AddAccount; Optional for SignupCustomer if the agency customer is in the Create Accounts on Behalf of Client pilot (GetCustomerPilotFeatures returns 793). Aggregators cannot link as agencies in this context, and therefore cannot set this element. Update: Read-only
The identifier of the third party that is responsible for a sales lead. Add: Read-only Update: Read-only
For a list of valid key and value strings for this element, see AdvertiserAccount TaxInformation in the section below. Add: Optional Update: Optional. If no value is set for the update, this setting is not changed. To remove a key and value pair, set the key and then set the value to an empty string ("").
The identifier of a backup payment instrument to use to settle the account. This element is not applicable for invoiced accounts. Add: Read-only Update: Optional. If no value is set for the update, this setting is not changed.
A customer specified amount for settling against the selected payment instrument. Add: Read-only Update: Optional. If no value is set for the update, this setting is not changed.
The location where your business is legally registered. If you are an agency working as an agent for your customer, this is the location where your client is legally registered. If you are an agency working as an aggregator, this is the legally registered business address of your company. The business address is used to determine your tax requirements. Add: Required. The Address BusinessName, City, and Line1 elements are required for all countries or regions. For Brazil (BR) and India (IN), the PostalCode and StateOrProvince elements are also required. Update: Optional for accounts that are not billed by monthly invoice. Having said that, if you want to make any changes to the Address then you must set its BusinessName, City, CountryCode, Line1, and StateOrProvince elements (where applicable); Read-only for monthly invoice accounts. To update the BusinessAddress of an invoice account, contact your account manager or support.
Determines whether to append or replace the supported UTM tracking codes. Microsoft Advertising can automatically add UTM tags to your destination URL so you can use your website analytics tool, for example Google Analytics, to track how people got to your website. Auto-tags are applied for example to expanded text ads, keywords, Microsoft Shopping Campaigns, and Sitelink Extensions. For details about auto-tagging, please see the Microsoft Advertising help article How do I add UTM tags to my landing page URL?. Add: Optional. If not specified the default value is Inactive. Update: Optional. If no value is set for the update, this setting is not changed.
The identifier of the payment instrument of your client (the sold-to customer) to use to settle the account. Add: Required for AddAccount if the BillToCustomerId differs from the ParentCustomerId; Read-only and not applicable for SignupCustomer. Update: Optional. If no value is set for the update, this setting is not changed.
The account tax certificate data object.
The system-generated identifier of the customer.
The city, which can contain a maximum of 35 characters. Add: Required Update: Optional. If no value is set for the update, this setting is not changed.
The country/region code. For possible values e.g., "US", see Geographical Location Codes. Add: Required Update: Optional. If no value is set for the update, this setting is not changed.
The system-generated identifier of the address object. Add: Read-only Update: Required
The first line of the address, which can contain a maximum of 35 characters. Add: Required Update: Optional. If no value is set for the update, this setting is not changed.
The second line of the address, which can contain a maximum of 35 characters. Add: Optional Update: Optional. If no value is set for the update, this setting is not changed.
The third line of the address, which can contain a maximum of 35 characters. Add: Optional Update: Optional. If no value is set for the update, this setting is not changed.
The fourth line of the address, which can contain a maximum of 35 characters. Add: Optional Update: Optional. If no value is set for the update, this setting is not changed.
The Postal or ZIP Code, which can contain a maximum of 10 characters. Add: Required Update: Optional. If no value is set for the update, this setting is not changed.
The state or province. You must use the state or province code without country/region prefix. For example given US-WA, you should use only the WA suffix for Washington state. Add: Required for countries or regions that define sub geographies, but should be set to null for countries or regions that do not define sub geographies, such as Singapore. Update: Optional. If no value is set for the update, this setting is not changed.
The date and time that the address was last updated. The value is in Coordinated Universal Time (UTC). The date and time value reflects the date and time at the server, not the client. For information about the format of the date and time, see the dateTime entry in Primitive XML Data Types. Add: Read-only Update: Read-only
The legal business name, which can contain a maximum of 100 characters. Add: Required Update: Optional. If no value is set for the update, this setting is not changed.
A system-generated account identifier corresponding to the new account specified in the request. Use this identifier with operation requests that require an AccountId body element and a CustomerAccountId SOAP header element.
The date and time that the account was added. The date and time value reflects the date and time at the server, not the client. For information about the format of the date and time, see the dateTime entry in Primitive XML Data Types.
The list of client links to add. You should limit your request to 10 client links per call.
Determines whether the link is to a client advertiser account or a client customer. The possible values are AccountLink and CustomerLink. If this element is empty or set to AccountLink, the ClientEntityId, ClientEntityName, and ClientEntityNumber represent a client advertiser account. If this element is set to CustomerLink, the ClientEntityId, ClientEntityName, and ClientEntityNumber represent a client customer. Add: Optional. If this element is not set, the service attempts to create an advertiser account client link. Update: Read-only
The identifier of the client advertiser account or client customer to manage. The Type element determines whether the link is to a client advertiser account or a client customer. Add: Required. Either the ClientEntityId or ClientEntityNumber is required, but specifying both will cause the operation to fail. Update: Read-only and Required.
The number of the client advertiser account or client customer to manage. The Type element determines whether the link is to a client advertiser account or a client customer. Add: Required. This element is required if Type is CustomerLink. If required and missing, a ClientLinkFieldInvalid error is returned. If the customer ID doesn't match, a LinkPairMismatch error is returned. Update: Read-only and Required.
The name of the client advertiser account or client customer to manage The Type element determines whether the link is to a client advertiser account or a client customer. Add: Read-only Update: Read-only
The identifier of the customer who manages or is requesting to manage the client advertiser account. Add: Required. Either the ManagingCustomerId or ManagingCustomerNumber is required, but specifying both will cause the operation to fail. Update: Read-only and Required
The number of the customer who manages or is requesting to manage the client advertiser account. Add: Required. Either the ManagingCustomerId or ManagingCustomerNumber is required, but specifying both will cause the operation to fail. Update: Read-only and Required
The name of the customer who manages or is requesting to manage the client advertiser account. Add: Read-only Update: Read-only
Optional message from the requestor providing context and details about the client link invitation. Add: Optional Update: Optional. If no value is set for the update, this setting is not changed.
The friendly name that can be used to reference this client link. The name can contain a maximum of 40 characters. A default name will be provided if none is specified. The name does not need to be unique compared to other client links for the user. Add: Optional Update: Read-only
The email of the user who created the client link request. This value does not need to be the same as, nor is it used to modify, the email already stored in Microsoft Advertising for the current authenticated user. If not specified, the service will set this value to the email already stored in Microsoft Advertising for the current authenticated user. Add: Optional Update: Read-only
The name of the parent customer of the user who created the client link request. This value does not need to be the same as, nor is it used to modify, the customer name already stored in Microsoft Advertising. If not specified, the service will set this value to the parent customer name already stored in Microsoft Advertising for the current authenticated user. Add: Optional Update: Read-only
The phone number of the user who created the client link request. This value does not need to be the same as, nor is it used to modify, the phone number already stored in Microsoft Advertising for the current authenticated user. If not specified, the service will set this value to the phone number already stored in Microsoft Advertising for the current authenticated user. Add: Optional Update: Read-only
Determines whether the owner of the client advertiser account or the managing customer is responsible for billing payments. This element is only applicable for advertiser account client links, and not applicable for customer links. The client advertiser account must be set up for post-pay billing. Prepaid accounts are not supported for management by agencies. If set to true the client is responsible for billing. If set to false the managing customer is responsible for billing. Add: Required for advertiser account links; Not applicable for customer links. Update: Read-only
The date when the status would update. For an accepted link request the status would transition towards Active on this date, and for an unlink request the status would transition towards Inactive on this date. If not specified, this value will be set to the current date and time. Add: Optional Update: Read-only
Determines the life cycle status of the client link, for example whether the client link has been accepted or declined. When adding a client link this element cannot be specified, and the service sets the effective status to LinkPending. Add: Read-only Update: Required
Determines whether or not to send email notification of the client link invitation to the primary user of the client advertiser account. If set to true the client will not receive an email and otherwise, since the default value is false, the client will receive an email notification. Add: Optional Update: Read-only
The date and time that the client link was last updated. The value is in Coordinated Universal Time (UTC). The date and time value reflects the date and time at the server, not the client. For information about the format of the date and time, see the dateTime entry in Primitive XML Data Types. Add: Read-only Update: Read-only
The identifier of the last user to update the client link's information. Add: Read-only Update: Read-only
The list of key and value strings for forward compatibility to avoid otherwise breaking changes when new elements are added in the current API version. Forward compatibility changes will be noted here in future releases. There are currently no forward compatibility changes for the ClientLink object.
Determines whether the user's access to the accounts is restricted by customer hierarchy i.e., customer level client linking. This element is only applicable if Type is set to CustomerLink. In that case, the possible values include Administrative and Standard. Otherwise this field should be nil or empty. If this field is set to "Administrative", the user has access to the ClientEntityId through an Administrative customer link. If this field is set to "Standard", the user has access to the ClientEntityId through a Standard customer link. The ClientEntityId is part of a customer link hierarchy whereby the user can access other customers below it. For more information, see the User Roles technical guide. Add: Optional Update: Read-only
The number of the client advertiser account?s customer to manage. The Type element determines whether the link is to a client advertiser account or a client customer. Add: Required. This element is only applicable and required if Type isn't set or set to AccountLink. If required and missing, a ClientLinkFieldInvalid error is returned. If the account ID doesn't match, a LinkPairMismatch error is returned. Update: Read-only and Required.
A list of one or more reasons why the service operation failed, and no client links were added.
An array of OperationError lists that contain details for any client links that were not successfully added. Results are returned in the same order corresponding to the requested client links. The number of first dimension list elements is equal to the requested client links count. For successfully added client links, the OperationError element at the corresponding index is null.
The address of the user. Note that the address BusinessName element is ignored if you try to set it for a user's contact information. The business name is only required for an AdvertiserAccount object. Add: Required Update: Optional. If no value is set for the update, this setting is not changed.
A value that determines whether the user should be contacted by telephone. If true, the telephone number specified in the Phone1 element is used to contact the user. Add: Optional Update: Optional. If no value is set for the update, this setting is not changed.
A value that determines whether the user should be contacted by postal mail. If true, correspondence is sent to the address specified in the Address element. Add: Optional Update: Optional. If no value is set for the update, this setting is not changed.
The email address is used to send the account activation notification to the user, and can contain a maximum of 100 characters. If the user should be contacted by email, set the EmailFormat element to a valid format value. The contact info email address may differ from the email address corresponding to the authenticated Microsoft Account. For more information, see the IsMigratedToMicrosoftAccount and UserName elements of the User. Add: Required Update: Optional. If no value is set for the update, this setting is not changed.
The format of the body of an email message to use when correspondence is sent to the user (this does not apply to the activation notification email message). You must set this element if you want the user contacted via email. Add: Optional Update: Optional. If no value is set for the update, this setting is not changed.
The fax telephone number of the user. The telephone number can contain a maximum of 100 characters. Add: Optional Update: Optional. If no value is set for the update, this setting is not changed.
The home telephone number of the user. The telephone number can contain a maximum of 100 characters. Add: Optional Update: Optional. If no value is set for the update, this setting is not changed.
The system-generated identifier of the object. Add: Read-only Update: Required
The mobile telephone number of the user. The telephone number can contain a maximum of 100 characters. Add: Optional Update: Optional. If no value is set for the update, this setting is not changed.
The primary telephone number of the user. The telephone number can contain a maximum of 100 characters. Add: Required Update: Optional. If no value is set for the update, this setting is not changed.
An alternate telephone number for the user. The telephone number can contain a maximum of 100 characters. Add: Optional Update: Optional. If no value is set for the update, this setting is not changed.
The financial status of the customer. For example, the status indicates whether the customer is in good standing or one or more of the accounts are past due. Add: Read-only Update: Read-only
The system-generated customer identifier. Use this identifier with operation requests that require a CustomerId SOAP header element. Add: Read-only Update: Required
The primary business segment of the customer, for example, automotive, food, or entertainment. Add: Required Update: Required
The identifier of the last user to update the customer's information. Add: Read-only Update: Read-only
The date and time that the customer information was last updated. The value is in Coordinated Universal Time (UTC). The date and time value reflects the date and time at the server, not the client. For information about the format of the date and time, see the dateTime entry in Primitive XML Data Types. Add: Read-only Update: Read-only
The primary country where the customer operates. For a list of customer market country code values, see Product Language. Add: Required Update: Read-only
The primary language that the customer uses. Your customer market language determines the language of the Microsoft Advertising interface. For a list of customer market language code values, see Product Language. Add: Required Update: Read-only
The name of the customer. The name can contain a maximum of 90 characters. Add: Required Update: Required
For internal use only. If this element is set when calling SignupCustomer an error will be returned. If this element is set when calling UpdateCustomer the element will be ignored. Add: Read-only Update: Read-only
The status of the customer. When you create the customer, the status is set to Active. You cannot change the status. Add: Read-only Update: Read-only
A time-stamp value that the system uses internally to reconcile updates when you call the UpdateCustomer and DeleteCustomer operations. Add: Read-only Update: Required
A system-generated customer number that is used in the Microsoft Advertising web application. The customer number has the form xxxxxxxxxx, where xxxxxxxxxx is a series of any ten alphanumeric characters. Add: Read-only Update: Read-only
The customer's business address. This property is not used by Microsoft Advertising, and you must set the account business address instead. Add: Optional Update: Optional
The role that the user has when accessing advertiser accounts through the CustomerId. Possible values include the following: 16 - The user has the Advertiser Campaign Manager role. 33 - The user has the Aggregator role. 41 - The user has the Super Admin role. 100 - The user has the Viewer role. 203 - The user has the Standard User role. For more information, see the User Roles technical guide.
The identifier of the customer where the user has either signed up or has some account hierarchy relationship.
The list of accounts that the user can access in the customer. If the user has CID level of access, then AccountIDs will be not returned. For account level access, the AccountIDs will be returned in the CustomerRole object of the GetUser API.
The list of linked accounts that the user can access through the CustomerId as an agency on behalf of another customer. If this element is nil, the user does not have access to individually linked advertiser accounts through the CustomerId. The user might have access to advertiser accounts in other linked customers, so be sure to take into account all CustomerRoles returned by GetUser. Please note that accounts created as an aggregator via SignupCustomer will also be returned in this element. You can delete aggregatee accounts via DeleteAccount, but you cannot delink them via UpdateClientLinks. Call the SearchClientLinks operation to help determine which accounts can be delinked.
Determines whether the user's access to the accounts is restricted by customer hierarchy i.e., customer level client linking. The possible values include Administrative, Standard, and LinkedEntityOnly. It is also possible this field can be nil or empty. If this field is nil or empty, the user is signed up directly on the CustomerId. If this field is set to "Administrative", the user has access to the CustomerId through an Administrative customer link. If this field is set to "Standard", the user has access to the CustomerId through a Standard customer link. If this field is set to "LinkedEntityOnly", the user is signed up directly on the CustomerId but cannot access its advertiser accounts. The CustomerId is part of a customer link hierarchy whereby the user can access other customers below it. For more information, see the User Roles technical guide.
The minimum date. The date format should be specified as "yyyyMMdd". For example April 3, 2020 should be specified as "20200403".
The maximum date. The date format should be specified as "yyyyMMdd". For example December 31, 2050 should be specified as "20501231".
The identifier of the account to delete.
The time-stamp value that the operation uses to reconcile the update. You must call GetAccount to get the time-stamp value. The delete operation fails if the account object has a time-stamp value that differs from the one that you pass.
The identifier of the customer to delete.
The time-stamp value that the operation uses to reconcile the update. You must call GetCustomer to get the time-stamp value. The delete operation fails if the customer object has a time-stamp value that differs from the one that you pass.
The time-stamp value that the operation uses to reconcile the update. You must call GetUser to get the time-stamp value. The delete operation fails if the user object has a time-stamp value that differs from the one that you pass.
The key and value of a notification entity.
The criteria to use to filter the list of accounts and customers. You can specify either an account name, account number, or customer name. The filter value can contain a partial or full name or number. The operation includes the account or customer in the result if the name or number begins with the specified filter value. The operation performs a case-insensitive comparison when it compares your filter value to the name or number. For example, if you specify "t" as the filter value, the list will include accounts and customers whose names begin with "t" or "T". The operation filters first for accounts that match the filter criteria. If the number of accounts that match the filter criteria is less than the specified TopN value, the operation searches for customers whose name matches the filter criteria. Setting this element to an empty string is the same as calling the GetAccountsInfo followed by calling the GetCustomersInfo.
A nonzero positive integer that specifies the number of accounts to return in the result. You must specify a value from 1 through 5,000.
The list of additional properties that you want included within each returned account. The additional field values enable you to get the latest features using the current version of Customer Management API, and in the next version the corresponding elements will be included by default. This request element is optional.
A list of AccountInfoWithCustomerData objects of the accounts and customers that match the specified filter criteria. The objects contain information that identifies the account and customer. To get the complete details of an account in the list, access the AccountId element of the AccountInfoWithCustomerData object and use it to call GetAccount operation. To get the complete details of a customer in the list, access the CustomerId element of the AccountInfoWithCustomerData object and use it to call GetCustomer.
The identifier of the customer whose accounts you want to get. If null, the operation searches for a match among all of the accounts of the customers that the user manages and owns.
The criteria to use to filter the list of accounts. You can specify either an account name or an account number. If your filter value is of the form, Xnnnnn, where nnnnn is a series of digits, the operation filters by account number. The filter value can contain a partial or full account name or number of the accounts that you want to get. The operation includes the account in the result if the name or number of the account begins with the specified filter value. The operation performs a case-insensitive comparison when it compares your filter value to the account name or number. For example, if you specify "t" as the filter value, the list will include accounts whose names begin with "t" or "T". Setting this element to an empty string is the same as calling the GetAccountsInfo.
A list of AccountInfo objects of the accounts that match the specified filter criteria. To get the complete details of an account in the list, access the Id element of the AccountInfo object and use it to call GetAccount.
The identifier of the account used to get a list of feature pilot IDs.
A list of integers that identify the feature pilots that are enabled for the ad account. For more information about pilot participation please contact your account manager.
An account object that contains information about the account, such as payment method, account type, and parent customer.
The identifier of the customer used to get the account information. This request element is optional. If not set, the user's credentials are used to determine the customer.
Determines whether to return only the advertiser accounts that belong to the customer or to also return linked advertiser accounts under other customers. To limit the results to advertiser accounts directly under the specified customer, set this element to true, and otherwise leave it empty or set the property to false. The default value is false.
The list of information about advertiser accounts that match the request criteria. Note that there can be a delay of up to five minutes from the time that you create an account until the account information is included in the response.
The user's contact information. Update: Optional. If no value is set for the update, this setting is not changed.
The identifier of the customer for this user to access. Update: Read-only
The Microsoft Advertising identifier of the user. Update: Required
The user's job title. The title can contain a maximum of 50 characters. Update: Optional. If no value is set for the update, this setting is not changed.
The identifier of the last user to update the user's information. Update: Read-only
The date and time that that the user information was last updated. The value is in Coordinated Universal Time (UTC). The date and time value reflects the date and time at the server, not the client. For information about the format of the date and time, see the dateTime entry in Primitive XML Data Types. Update: Read-only
The locale to use when sending correspondence to the user by email or postal mail. The default is EnglishUS. Update: Optional. If no value is set for the update, this setting is not changed.
The name of the user. Update: Optional. If no value is set for the update, this setting is not changed.
This element is reserved for internal use and will be removed from a future version of the API. The GetUser operation does not return the password. Update: Read-only
This element is reserved for internal use and will be removed from a future version of the API. Update: Optional. If no value is set for the update, this setting is not changed.
The status of the user. Update: Read-only
A time-stamp value that the system uses internally to reconcile updates when you call UpdateUser or DeleteUser. Update: Required
The logon user name of the user. The email address of the Microsoft Account may differ from the Email element of the ContactInfo object. Update: Read-only
The OAuth access token that represents the credentials of the user who has permissions to Microsoft Advertising accounts. For more information see Authentication with OAuth. Update: Read-only
The first name of the user. The first name is limited to 100 characters. Add: Required Update: Optional. If no value is set for the update, this setting is not changed.
The last name of the user. The last name is limited to 100 characters. Add: Required Update: Optional. If no value is set for the update, this setting is not changed.
The middle initial of the user. The middle initial is limited to one character. Add: Optional Update: Optional. If no value is set for the update, this setting is not changed.
The identifier of the customer used to get a list of feature pilot IDs.
A list of integers that identify the feature pilots that are enabled for all accounts owned by a customer (manager account). For more information about pilot participation please contact your account manager. For example the following values correspond to customer level feature pilots. 78 - Call Tracking 268 - Dynamic Search Ads 317 - Similar Remarketing Lists 351 - Local Inventory Ads 388 - Microsoft Audience Network 567 - Azure AD Work and School Accounts 574 - Include in Conversions 579 - Customer List Audience 600 - Dynamic Search Ads Text Part 2 616 - View-through conversions 618 - Combined List Audience 626 - Multi-Image Ad Extensions 635 - Custom Parameters Limit Increase Phase 3 636 - Final Url Suffix Phase 3 637 - Cookie-Based Experiments 684 - Shopping Campaigns for Brands 704 - Target ROAS Bid Strategy Type in UK/CA/AU/DE/FR 718 - Smart Shopping Campaigns 720 - Promotion Ad Extensions 721 - Target ROAS Bid Strategy Type in US 734 - Google Import As A Service 762 - Target Impression Share Bid Strategy Type 764 - Site Property Promotion Ad for Hotels 777 - Responsive Ads for Smart Shopping Campaigns 793 - Create Accounts on Behalf of Client 802 - Flyer Ad Extensions Please note the list of pilot IDs might also include account level pilot IDs for internal use. You should ignore account level pilot IDs returned by this operation and use the GetAccountPilotFeatures operation instead.
The identifier of the customer whose information you want to get.
A Customer object that contains information about the customer.
A partial or full name of the customers that you want to get. The operation includes the customer in the result if the customer's name begins with the specified filter name. This request element is optional. If you do not want to filter by customer name, set this element to an empty string. The operation performs a case-insensitive comparison when it compares your name filter value to the customer names. For example, if you specify "t" as the filter value, the list will include customers whose names begin with "t" or "T".
A nonzero positive integer that specifies the number of customers to return in the result.
The list of information about customers that match the request criteria.
The identifier of the customer whose hierarchy you want to get.
Determines whether to return only the advertiser accounts that belong to the customer or to also return linked customers and linked advertiser accounts under other customers. To limit the results to advertiser accounts directly under the specified customer, set this element to true, and otherwise leave it empty or set the property to false. The default value is false.
The locale of the message. The default value is en. Add: Optional Update: Optional
The UserId filter. Add: Optional Update: Optional
A list of notification type filter. Add: Optional Update: Optional
A collection of Notification objects that contains information about the Notification.
The identifier of the type of Notification.
The supporting data of the Notification.
Used to estimate adoption of multi-factor authentication (MFA) by users of your application. The operation returns true if during calendar year 2021 the user passed through MFA via Microsoft Advertising online, Microsoft Advertising Editor, or Microsoft Advertising mobile. Otherwise this value is false.
The identifier of the user to get. If this element is null or not provided, the response will include details for the authenticated user specified in the request header.
A user object that contains information about the user.
The list of roles that a user has for each customer or list of accounts. At minimum one list item will be returned. If a user's credentials can access multiple customers, then one CustomerRole object per customer will be returned. You can view all of your own roles across all customers; however, you will only see the roles of other users as it pertains to customers that you can access. For example let's say you`@contoso`.com and another-user`@contoso`.com can access Customer A. The other user might also have access to Customer B and C; however when you call this operation with their user identifier, you will only see their role under Customer A. When another-user`@contoso`.com calls this operation with their own credentials, the operation would return three CustomerRole objects.
The identifier of the customer to which the users belong.
The status value that the operation uses to filter the list of users that it returns. The operation returns only those users with the specified status.
A list of UserInfo objects that identifies the list of users who meet the filter criteria. To get the user data for a user in the list, access the Id element of the UserInfo object and use it to call GetUser.
The system-generated identifier of the user.
The page size and the number of results to return in the specified page. The maximum size for SearchAccounts is 1,000. The maximum size for SearchClientLinks is 100. The maximum size for SearchCustomers is 1,024. If you include page info but do not set this element the default size is 0 (zero).
The name of the element for the object you are searching. For possible values, see the Remarks below.
Determines the conditions that all must be met to return accounts. You must include exactly one predicate. If the predicate Field is set to "AccountLifeCycleStatus", then you must specify one additional predicate with the Field set to another value such as UserId. For details about each supported predicate Field value see Predicate Remarks.
Determines the order of results by the specified property of an account. This request element is optional. You can specify up to one OrderBy element in the array. Additional elements are not supported and will be ignored by the service. If you set the Field element of the OrderBy object to "Id", "Name", or "Number", the returned Accounts will be ordered by the account identifiers, names, or numbers accordingly. This request element is optional.
A list of accounts that meet the request criteria.
Determines the conditions that must be met to return client links. You must include one or two predicates. For details about how results are determined for each supported predicate Field value see Predicate Remarks.
Determines the order of results. This request element is optional. If specified, you should only include one OrderBy element in the list. Additional elements are not supported and will be ignored by the service. For this service operation, the following values are supported in the Field element of a OrderBy object. Id - The order is determined by the ClientAccountId element of the returned ClientLink. Name - The order is determined by the Name element of the returned ClientLink. Number - The order is determined by the ManagingCustomerNumber element of the returned ClientLink.
Determines the conditions that all must be met to return customers. You must include between one and 10 predicates. To filter by the created date range, you can include two predicates with the Field value set to CreatedDate, and otherwise may only use each predicate field once. For details about each supported predicate Field value see Predicate Remarks.
Determines the minimum and maximum customer creation date range. This request element is optional.
Determines the order of results by the specified property of a customer. This request element is optional. You can specify up to one OrderBy element in the array. Additional elements are not supported and will be ignored by the service. For this service operation, the following values are supported in the Field element of a OrderBy object: Id - The order is determined by the Id element of the returned Customer. Name - The order is determined by the Name element of the returned Customer. Number - The order is determined by the Number element of the returned Customer.
A list of customers that meet the request criteria.
Determines the conditions that all must be met to return user invitations. You must include exactly one predicate. For details about each supported predicate Field value see Predicate Remarks.
A list of user invitations that meet the specified criteria.
A system-generated unique identifier for the user invitation. Send: Read-only Signup: Read-only
The first name of the user. The first name is limited to 40 characters. Send: Required Signup: Required
The last name of the user. The last name is limited to 40 characters. Send: Required Signup: Required
The email address corresponding to the user's Microsoft account. The address can contain a maximum of 100 characters. Send: Required Signup: Required
The identifier of the customer this user is invited to manage. The AccountIds element determines which customer accounts the user can manage. Send: Required Signup: Read-only
The role that the user has for each customer or list of accounts. Possible values include the following: 16 - The user has the Advertiser Campaign Manager role. 33 - The user has the Aggregator role. 41 - The user has the Super Admin role. 100 - The user has the Viewer role. 203 - The user has the Standard User role. For more information, see the User Roles technical guide. Send: Required Signup: Required. The role ID must be set to 41 or 203.
An array of identifiers of the accounts that the user can manage. To specify that the user can manage all current and future accounts of the customer to which the user belongs, set to NULL. Users with account level roles such as Advertiser Campaign Manager can be restricted to specific accounts. Users with customer level roles such as Super Admin can access all accounts within the user's customer, and their access cannot be restricted to specific accounts. When attempting to restrict customer level user roles, for example attempting to restrict a Super Admin to specific accounts, the operation will not fail and the user will be granted access for all accounts within the specified customer. Send: Optional Signup: Optional
The date and time that the user invitation will expire. The value is in Coordinated Universal Time (UTC). The duration of a user invitation is subject to change, and currently set at 30 days. You cannot set or update this value. Send: Read-only Signup: Read-only
The locale to use when sending correspondence to the user by email or postal mail. The default is EnglishUS. Send: Required Signup: Required
A system-generated identifier for the user invitation that was sent.
A Customer that specifies the details of the customer that you are adding.
An AdvertiserAccount that specifies the details of the customer's primary account. Customers in the closed Unified smart campaigns pilot must set the AccountMode element to "UnifiedSmart".
The customer identifier of the aggregator or agency that will manage the new child customer. This element is required for aggregators but ignored for agencies when the UserInvitation request element is set. Customers in the closed Unified smart campaigns pilot can link the new customer to the parent agency ID or leave this element empty.
The user invitation to send if you want to sign up a new customer on behalf of a client and optionally link to the new account as an agency. A client Super Admin user must complete sign up steps via the Microsoft Advertising UI such as accept the terms and conditions. This element is optional for agency customers in the Create Accounts on Behalf of Client pilot. Customers in the closed Unified smart campaigns pilot must set one or more of the UserId or UserInvitation element.
The identifier of an existing user who will be added as Super Admin in the new customer. This element is only available for customers in the closed Unified smart campaigns pilot. One or more of the UserId or UserInvitation element must be set.
The user to create. You can fulfill this element if you want to sign up a new customer and create a new admin user simultaneously. After the new customer is signed up, the newly created admin user must complete sign up steps via the Microsoft Advertising UI on the Microsoft Advertising activating customer page. The URL is https://ads.microsoft.com/ActivateCustomer?cid={new_customer_Id}&aid={new_account_Id} where new_customer_Id and new_account_Id are the IDs you get in the SignupCustomerResponse. The AuthenticationToken in the User element is the OAuth access token that represents the credentials of the new admin user who will be created during signup. Customers in the seamlessly set up client account and PI pilot must set one or more of the UserId or UserInvitation or User. The required fields in the User object are ContactInfo.Email, Name.FirstName, Name.LastName and AuthenticationToken.
A system-generated customer identifier corresponding to the new customer specified in the request. Use this identifier with operation requests that require a CustomerId SOAP header element.
A system-generated customer number that is used in the Microsoft Advertising web application. The customer number has the form xxxxxxxxxx, where xxxxxxxxxx is a series of any ten alphanumeric characters.
An AdvertiserAccount object that contains the updated account information. This operation overwrites the existing account data with the contents of the account object that you pass. This operation performs a full update, and not a partial update. The Account object must contain the time stamp value from the last time that the Account object was written to. To ensure that the time stamp contains the correct value, call the GetAccount operation. You can then update the account data as appropriate, and call UpdateAccount.
The date and time that the account was last updated. The value is in Coordinated Universal Time (UTC). The date and time value reflects the date and time at the server, not the client. For information about the format of the date and time, see the dateTime entry in Primitive XML Data Types.
The list of client links to update. You should limit your request to 10 client links per call.
A customer object that contains the updated customer information. This operation overwrites the existing customer data with the contents of the customer object that you pass. This operation performs a full update, and not a partial update. The Customer object must contain the time stamp value from the last time that the Customer object was written to. To ensure that the time stamp contains the correct value, call the GetCustomer operation. You can then update the customer data as appropriate, and call UpdateCustomer.
The date and time that the customer was last updated. The value is in Coordinated Universal Time (UTC). The date and time value reflects the date and time at the server, not the client. For information about the format of the date and time, see the dateTime entry in Primitive XML Data Types.
The user object that contains the updated user information. This operation overwrites the existing user data with the contents of the user object that you pass. This operation performs a full update, not a partial update. The User object must contain the time stamp value from the last time that the User object was written to. To ensure that the time stamp contains the correct value, call the GetUser operation. You can then update the user data as appropriate, and call UpdateUser.
The date and time that the user was last updated. The value is in Coordinated Universal Time (UTC). The date and time value reflects the date and time at the server, not the client. For information about the format of the date and time, see the dateTime entry in Primitive XML Data Types.
The identifier of the customer to which the user belongs.
The identifier of the user whose role you want to update.
The identifier of the role to which the values specified in the NewAccountIds or NewCustomerIds element applies to, if set. Possible values include the following: 16 - The user has the Advertiser Campaign Manager role. 33 - The user has the Aggregator role. 41 - The user has the Super Admin role. 100 - The user has the Viewer role. 203 - The user has the Standard User role. For more information, see the User Roles technical guide. Important: The list above provides examples of possible return values. Other values might be returned. Deprecated or internal roles can be included in the response.
An array of identifiers of the accounts to restrict the user to. The user will be able to manage only these accounts. If the user is currently restricted to a set of accounts, set this element to the new accounts that you want the user to also manage. For example, if the user currently manages accounts 123 and 456, and you want the user to also manage account 789, set this element to 789. For usage, see the Remarks section below.
An array of identifiers of the customers to restrict the user to. The user will be able to manage only these customers. For usage, see the Remarks section below.
The identifier of the role to which the values specified in the DeleteAccountIds or DeleteCustomerIds element applies, if set. Possible values include the following: 16 - The user has the Advertiser Campaign Manager role. 33 - The user has the Aggregator role. 41 - The user has the Super Admin role. 100 - The user has the Viewer role. 203 - The user has the Standard User role. For more information, see the User Roles technical guide. Important: The list above provides examples of possible return values. Other values might be returned. Deprecated or internal roles can be included in the response.
An array of identifiers of the accounts to remove from the list of accounts that the user can manage. For usage, see the Remarks section below.
An array of identifiers of the customers to remove from the list of customers that the user can manage. For usage, see the Remarks section below.
The date and time that the user roles were last updated. The value is in Coordinated Universal Time (UTC). The date and time value reflects the date and time at the server, not the client. For information about the format of the date and time, see the dateTime entry in Primitive XML Data Types.
The address that was submitted for validation. The submitted Address is always passed back here in the response, so this element is always set.
Determines whether or not the submitted address is valid for Microsoft Advertising accounts, and whether or not any address suggestions are available via the SuggestedAddresses response element. Possible string values are AddressValidWithoutSuggestions, AddressValidWithSuggestions, AddressInvalidWithoutSuggestions, and AddressInvalidWithSuggestions.
One or more suggested addresses if the Status is either AddressValidWithSuggestions or AddressInvalidWithSuggestions. This element will be nil if the Status is either AddressValidWithoutSuggestions or AddressInvalidWithoutSuggestions.
The report will include data for only the specified distribution medium. For example, you can use the filter to include data for only search ads. You can specify one or more distribution mediums.
The report will include data where the ad is displayed on the specified device types. For example, you may use the filter to include data for only ads displayed on smartphones. You may specify one or more device types.
The report will include data where the ad is displayed on the specified device operating systems. For example, you may use the filter to include data for only ads displayed on Windows devices.
The report will include data for only the account status. For example, you can use the filter to include data for only active accounts. You can specify one or more account statuses.
The name of the report. The name is included in the report header. If you do not specify a report name, the system generates a name in the form, ReportType-ReportDateTime. The maximum length of the report name is 200.
The format of the report data. For example, you can request the data in comma-separated values (Csv) format or tab-separated values (Tsv) format. The default value is Csv. All downloaded files are ZIP compressed.
Determines whether or not the service must ensure that all the data has been processed and is available. If set to true and if the system has not finished processing all the data based on the requested Aggregation, Scope, and Time, the service returns error code NoCompleteDataAvaliable (2004). Otherwise by default the request can succeed, there is no indication as to whether the data is complete, and the report will contain only the data that the system has finished processing at the time of the request. Please note that because today is still in progress and data is not complete, you cannot set this element to true if the Time period (whether custom or predefined date) includes today's date. For more information, see Time Zones in Reporting.
Determines whether or not the downloaded report should contain header metadata such as report name, date range, and aggregation. Set this property true if you want the report header metadata excluded from the downloaded report. The default value is false.
Determines whether or not the downloaded report should contain footer metadata such as Microsoft copyright (`@2020` Microsoft Corporation. All rights reserved.). Set this property true if you want the report footer metadata excluded from the downloaded report. The default value is false.
Determines whether or not the downloaded report should contain header descriptions for each column. The report column header matches the requested column name e.g. Impressions and Clicks. Set this property true if you want the report column headers excluded from the downloaded report. The default value is false.
Determines the format for certain fields in the downloaded report file. The data format for certain fields can be updated within the current API version without breaking existing client applications. You can get the latest data format by setting this optional request field to 2.0. If you do not set this field, the service defaults to version 1.0. For details about changes between format versions, see Report Format Version.
The entity scope of the report. Use this element to limit the report data to specific accounts.
The filter information to use to filter the report data.
The time period to use for the report. You can specify a custom date range or select a predefined date range, for example, Today or ThisWeek. For a list of the time periods that you can specify for each aggregation type, see Aggregation and Time. You can set the time zone within the ReportTime object, which helps you accurately scope data for the requested time period. If you do not choose a time zone, the Reporting service uses PacificTimeUSCanadaTijuana by default.
The type of aggregation to use to aggregate the report data. For example, you can aggregate the report data by day or week, or request a summary report. The default aggregation is Summary. It is important to note that if you do not include TimePeriod in the list of Columns, the aggregation you chose will be ignored and Summary aggregation will be used regardless.
The list of attributes and performance statistics to include in the report. The report will include the columns in the order that you specify them.
A list of up to 1,000 account identifiers to include in the report. This element is required.
A predefined date range value. Each report request type specifies the predefined time periods that you can specify for each aggregation type.
The start date of the custom date range. The start date must be earlier than or the same as the end date.
The end date of the custom date range. The end date cannot be later than today's date.
Determines the time zone that is used to establish today's date. When you submit the report request today's date can vary around the world depending on the time zone. The report time period that you choose e.g., 'Yesterday' is then relative to today's date. If you do not choose a time zone, the Reporting service uses PacificTimeUSCanadaTijuana by default. For example, a report requested without a time zone specified at 2 AM EasternTimeUSCanada on 2/2/2019 for 'Yesterday' will be interpreted as a request for 1/31/2019. A report requested at the same time for 'Yesterday' with time zone set as EasternTimeUSCanada will be interpreted as a request for 2/1/2019.
A list of up to 1,000 account identifiers to include in the report. The report scope includes a union of the AccountIds, AdGroups, and Campaigns elements. You must include at least one of these elements.
A list of up to 300 campaigns to include in the report. The report scope includes a union of the AccountIds, AdGroups, and Campaigns elements. You must include at least one of these elements.
A list of up to 300 ad groups to include in the report. The report scope includes a union of the AccountIds, AdGroups, and Campaigns elements. You must include at least one of these elements.
The identifier of the account that the campaign belongs to.
The identifier of the campaign to limit the scope to.
The identifier of the account that the ad group belongs to.
The identifier of the campaign that the ad group belongs to.
The identifier of the ad group to limit the scope to.
A list of up to 1,000 account identifiers to include in the report. The report scope includes a union of the AccountIds and Campaigns elements. You must include at least one of these elements.
list of up to 300 campaigns to include in the report. The report scope includes a union of the AccountIds and Campaigns elements. You must include at least one of these elements.
A list of up to 300 campaigns to include in the report. The report scope includes a union of the AccountIds and Campaigns elements. You must include at least one of these elements.
The report will include data for only the specified ad types. For example, the report can include data for product or expanded text ads. You can specify one or more ad types.
The report will include data for only the specified types of devices on which the ad is displayed. For example, you can use the filter to include data for only text ads displayed on smartphones. You can specify one or more device types.
The report will include data for only websites that used the specified languages. You can specify one or more languages.
The report will include data for only the ad group status. For example, you can use the filter to include data for only active ad groups. You can specify one or more ad group statuses.
The report will include data for only the ad status. For example, you can use the filter to include data for only active ads. You can specify one or more ad statuses.
The report will include data for only the keyword status. For example, you can use the filter to include data for only active keywords. You can specify one or more keyword statuses.
The entity scope of the report. Use this element to limit the report data to specific accounts, ad groups, or campaigns.
The report will include data for only the campaign status. For example, you can use the filter to include data for only active campaigns. You can specify one or more campaign statuses.
The criteria to use to filter the report data.
The report will include data for only the specified ad group status values. For example, you can use the filter to include data for only active ad groups. You can specify one or more status values.
The time period to use for the report. You can specify a custom date range or select a predefined date range, for example, Today or ThisWeek. For a list of the time periods that you can specify for each aggregation type, see Aggregation and Time.
The report will include data for only the asset group status. For example, you can use the filter to include data for only active asset groups. You can specify one or more asset group statuses.
Determines whether or not the downloaded report should contain header descriptions for each column. The report column header matches the requested column name (e.g., Impressions and Clicks). Set this property true if you want the report column headers excluded from the downloaded report. The default value is false.
The entity scope of the report. Use this element to limit the report data to specific accounts or campaigns.
The time period to use for the report. You can specify a custom date range or select a predefined date range, for example, Today or ThisWeek. For a list of the time periods that you can specify for each aggregation type, see Aggregation and Time. You can set the time zone within the ReportTime object, which helps you accurately scope data for the requested time period. If you don't choose a time zone, the Reporting service uses PacificTimeUSCanadaTijuana by default.
The entity scope of the report. Use this element to limit the report data to specific accounts, asset groups, or campaigns.
Determines whether or not the service must ensure that all the data has been processed and is available. If set to true and if the system has not finished processing all the data based on the requested Scope and Time, the service returns error code NoCompleteDataAvaliable (2004). Otherwise by default the request can succeed, there is no indication as to whether the data is complete, and the report will contain only the data that the system has finished processing at the time of the request. Please note that because today is still in progress and data is not complete, you cannot set this element to true if the Time period (whether custom or predefined date) includes today's date. For more information, see Time Zones in Reporting.
The time period to use for the report. You can specify a custom date range or select a predefined date range, for example, Today or ThisMonth. The budget summary report is always aggregated by day. You can set the time zone within the ReportTime object, which helps you accurately scope data for the requested time period. If you do not choose a time zone, the Reporting service uses PacificTimeUSCanadaTijuana by default.
The scope of the report. Use this element to limit the report to include data for specified accounts, campaigns, or ad groups. For this report you may only specify one account identifier in the AccountIds element of the AccountThroughAdGroupReportScope object.
The time period to use for the report. You can specify a custom date range or select a predefined date range, for example, Today or LastSevenDays. For a list of the time periods that you can specify for the Summary aggregation type, see Aggregation and Time. You can set the time zone within the ReportTime object, which helps you accurately scope data for the requested time period. If you do not choose a time zone, the Reporting service uses PacificTimeUSCanadaTijuana by default.
The type of aggregation to use to aggregate the report data. The default aggregation is Summary. It is important to note that if you do not include TimePeriod in the list of Columns, the aggregation you chose will be ignored and Summary aggregation will be used regardless. For this report, Aggregation must always be set to Summary.
The report will include data for only the specified campaign status values. For example, you can use the filter to include data for only active campaigns. You can specify one or more status values.
The report will include data for only the specified countries/regions where the user that clicked the ad is located. For a list of possible values, see Geographical Location Codes.
A particular supply sector, such as Travel and Tourism or Apparel. View a list of L1 verticals.
A more detailed segment of an L1 vertical. For instance, within the L1 vertical travel and tourism, L2 verticals might include Accommodations or Air travel. View a list of L2 verticals.
The most specific segment within a larger L1 vertical. For example, if the L1 vertical is travel and tourism and the L2 vertical is Accommodations, an L3 vertical might be Bed and Breakfasts or Camping and RV. View a list of L3 verticals.
Determines whether or not the service must ensure that all the data has been processed and is available. If set to true and if the system has not finished processing all the data based on the requested Scope, and Time, the service returns error code NoCompleteDataAvaliable (2004). Otherwise by default the request can succeed, there is no indication as to whether the data is complete, and the report will contain only the data that the system has finished processing at the time of the request. Please note that because today is still in progress and data is not complete, you cannot set this element to true if the Time period (whether custom or predefined date) includes today's date. For more information, see Time Zones in Reporting.
The report will include data for only the specified keywords. You can specify a maximum of 75 keywords. Each keyword can contain a maximum of 100 characters.
The report will include data for only the specified types of devices on which the ad is displayed. For example, you can use the filter to include data only for expanded text ads displayed on smartphones. You can specify one or more device types.
The list of attributes and performance statistics to include in the report. The report includes the columns in the order that you specify them.
The report will include data for campaigns that have the specified status value. You can specify one or more status values.
The report will include data for only the dynamic ad targets that have the specified status.
The report will include data for only the specified bid strategy types.
The report will include data for ads that have the specified status value. You can specify one or more status values.
The report will include data for only the specified search query strings. The list can contain a maximum of 30 strings, and each string can contain a maximum of 256 characters.
If the value of this element is set to true, search terms that had one or more ad impressions but resulted in zero clicks in the specified time duration will be excluded from the report. The default value is false, in which case the report will include zero click search term data. Regardless of the value of this filter, search terms with zero clicks in the last 30 days will always be excluded.
The feed URL will appear either as "True" or "False". If it's "True", the final URL came from a page feed associated to the campaign. If it's "False", the final URL did not come from a page feed.
The report will include data for only the specified goals. The list can contain a maximum of 300 identifiers.
The scope of the report. For example, you can limit the report to include data for a combination of accounts, ad groups, and campaigns.
The filter information to use to filter the report data. The Filter element is not supported at this time.
The report will include data for only the specified types of devices on which the ad is displayed. For example, you can use the filter to include data for only ads displayed on computers. You can specify one or more device types.
The report will include data for only the specified delivered match types. For example, you can use the filter to include data for ads that were delivered using the exact or phrase match type. You can specify one or more delivered match types. To filter on bid match types, see the BidMatchType element.
The report will include data for only the specified bid match types. For example, you can use the filter to include data for ads that were bid on using the exact or phrase match type. You can specify one or more bid match types. To filter on delivered match types, see the DeliveredMatchType element.
The report will include data for only keywords with the specified quality scores. You can filter the report based on one or more of the following relevance values: 0 - N/A (as shown in the web application) 1 - Underperforming 2 - Underperforming 3 - Underperforming 4 - Underperforming 5 - Underperforming 6 - Average performance 7 - Competitive 8 - Competitive 9 - Competitive 10 - Competitive
How well your keyword competes against other keywords targeting the same traffic. Ads that are relevant to searchers' queries or other input are more likely to have a higher click-through rate. This metric tells you if a keyword is underperforming and causing a loss in impression share, so you can make keyword changes or remove ads altogether. A score of 3 is Above Average; a score of 2 is Average; and a score of 1 is considered Below Average. If you specify a time period that spans multiple days, the score will be the same for each day in the time period, and the value is the most recent calculated score. Data for this column is typically updated 14-18 hours after the UTC day ends.
How closely related your ads is to the customer's search query or other input. It tells you how relevant your ad and landing page are to potential customers. A score of 3 is Above Average; a score of 2 is Average; and a score of 1 is considered Below Average. If you specify a time period that spans multiple days, the score will be the same for each day in the time period, and the value is the most recent calculated score. Data for this column is typically updated 14-18 hours after the UTC day ends.
An aggregate quality assessment of all landing pages on your site. The landing page experience score measures whether your landing page is likely to provide a good experience to customers who click your ad and land on your website. A score of 3 is Above Average; a score of 2 is Average; and a score of 1 is considered Below Average. If you specify a time period that spans multiple days, the score will be the same for each day in the time period, and the value is the most recent calculated score. Data for this column is typically updated 14-18 hours after the UTC day ends.
The report will include data for only the specified bid strategy type or types. For example, you can use the filter to include data only for keywords that were bid on using the enhanced bid strategy type. You can specify one or more bid strategy types.
A list of the columns to sort, and the corresponding sort order.
The top number of data rows to return in the report.
The keyword performance report column by which to sort.
Defines the ascending or descending sort order of values within the specified report column.
The time period to use for the report. You can specify a custom date range or select a predefined date range, for example, Today or ThisWeek. Note: Historical data isn't available. For a list of the time periods that you can specify for each aggregation type, see Aggregation and Time. You can set the time zone within the ReportTime object, which helps you accurately scope data for the requested time period. If you do not choose a time zone, the Reporting service uses PacificTimeUSCanadaTijuana by default.
The type of aggregation to use to aggregate the report data. For example, you can aggregate the report data by day or week, or request a summary report. The default aggregation is ClickID. It is important to note that if you do not include TimePeriod in the list of Columns, the aggregation you chose will be ignored and ClickID aggregation will be used regardless.
The report will only include data for accounts with the specified status. For example, you can use the filter to include data for only active accounts. You can specify one or more account statuses.
The report will only include data for campaigns with the specified status. For example, you can use the filter to include data for only active campaigns. You can specify one or more campaign statuses.
The report will only include data for ad groups with the specified status. For example, you can use the filter to include data for only active ad groups. You can specify one or more ad group statuses.
The report will only include data for keywords with the specified status. For example, you can use the filter to include data for only active keywords. You can specify one or more keyword statuses.
Not applicable for the negative keyword conflict report.
The identifier of the report request. The SubmitGenerateReport operation returns the identifier. The identifier is valid for a maximum of one day. If you have not successfully downloaded the file within this period, it is removed from the download site and you will need to get a new report request identifier. The string has a length up to 40 and can contain any character.
Contains the status of the report request and the download URL.
The encoded URL from where the report can be downloaded. Once returned, the URL is valid for five minutes. You should not take a dependency on the domain of the download URL as it is subject to change. The report that you download is compressed by using zip compression. You must first unzip the report before you can use its contents. Use the download URL only if the Status element is set to Success. Even when the Status is set to Success, this element can be nil if no data is available for the submitted report parameters.
Not applicable for the product negative keyword conflict report.
The report will include data for only the campaign type. For example, you can use the filter to include data for only Shopping campaigns. You can specify one or more campaign types.
The report will include data for only the specified distribution medium. For example, you may use the filter to include data for only search ads. You may specify one or more distribution mediums.
Includes rows in the report where the delivered match type matches one of the specified match types. You can include multiple match type values as flags. Supported values include Exact, Phrase, Broad, and AIOptimized. This element is optional. If not specified, all delivered match types are included.
Includes rows in the report where the search term matches one of the specified search query strings. You can specify up to 100 search query strings. Each search query string can contain a maximum of 100 characters. This element is optional. If not specified, the report is not filtered on search term.
Includes rows in the report where the ad type matches one of the specified ad types. You can include multiple ad type values as flags. This element is optional. If not specified, all ad types are included.
Includes rows in the report where the language matches one of the specified languages. You can include multiple language values as flags. This element is optional. If not specified, all languages are included.
The report will include data for only the specified type of entity. For example, you can use the filter to include data only for changes to ad groups or campaigns. You may specify only one type of entity.
The report will include data for only the specified type of change. For example, you can use the filter to include data only for updates or deletions. You may specify only one type of change.
The entity scope of the report. Use this element to limit the report data to specific accounts, ad groups, or campaigns. For this report you may only specify one account identifier in the AccountIds element of the AccountThroughAdGroupReportScope object.
The time period to use for the report. You can specify a custom date range or select one of the following predefined date ranges: LastSevenDays LastMonth LastThreeMonths You can set the time zone within the ReportTime object, which helps you accurately scope data for the requested time period. If you do not choose a time zone, the Reporting service uses PacificTimeUSCanadaTijuana by default.
The report will only include data for campaigns with the specified search category.
The report will only include data for campaigns with the specified search queries.
The report will include data for only the specified delivered match types (as opposed to the bid match type). For example, you can use the filter to include data for ads that were delivered using the exact or phrase match type. You can specify one or more delivered match types.
The name of the report. The name will be used as the name of the download file. This element is optional.
The format of the report file. For example you can specify to have the report data written to a file that uses comma-separated values (CSV). This element is optional and defaults to Csv.
Determines whether the operation returns data for only fully processed time periods. This element is optional and defaults to false.
Determines whether or not the report includes header information such as the report name and date range. This element is optional and defaults to false.
Determines whether or not the report includes footer information such as copyright. This element is optional and defaults to false.
Determines whether or not the report includes header descriptions for each column of data. This element is optional and defaults to false.
The format version of the report file. This element is optional.
The entities and their scope to include in the report. Use this element to limit the report data to specific accounts and campaigns. This element is required.
The filter information to use to filter the report data. This element is optional.
The time frame to use to aggregate the report data. You can specify a custom date range or select a predefined date range, for example, Today or ThisWeek. This element is required.
The type of aggregation to use to aggregate the report data. For example, you can aggregate the report data by day or week. Supported values are Hourly, Daily, Weekly, Monthly, Yearly, DayOfWeek, and HourOfDay*. This element is required.
The list of attributes and performance statistics to include in the report. The report will include the columns in the order that you specify them. You must specify Final URL and at least one performance statistics column, e.g., Impressions. This element is required.
The report request. The request must be an object that derives from ReportRequest. For a list of report request types, see Report Types.
The identifier of the report request. Use this identifier when calling the PollGenerateReport to determine the status of the report request. The identifier is valid for a maximum of one day. If you have not successfully downloaded the file within this period, it is removed from the download site and you will need to get a new report request identifier. The string has a length up to 40 and can contain any character.
Determines whether or not the downloaded report should contain header metadata such as report name and date range. Set this property true if you want the report header metadata excluded from the downloaded report. The default value is false.
SELECT $this ?key WHERE { $this <https://relay.inferal.com/ontology/microsoftads/record/Microsoftads.CampaignManagementAuditPointResult/details/entry> ?left, ?right . FILTER(?left != ?right) ?left <https://relay.inferal.com/ontology/microsoftads/record/Microsoftads.CampaignManagementAuditPointResult/details/key> ?key . ?right <https://relay.inferal.com/ontology/microsoftads/record/Microsoftads.CampaignManagementAuditPointResult/details/key> ?key . }