Keyword Data Object

 

Defines a keyword.

<xs:complexType name="Keyword">
  <xs:sequence>
    <xs:element xmlns:q35="http://schemas.datacontract.org/2004/07/Microsoft.AdCenter.Advertiser.CampaignManagement.Api.DataContracts.V11" minOccurs="0" name="BiddingScheme" nillable="true" type="q35:BiddingScheme"/>
    <xs:element minOccurs="0" name="Bid" nillable="true" type="tns:Bid" />
    <xs:element minOccurs="0" name="DestinationUrl" nillable="true" type="xs:string" />
    <xs:element minOccurs="0" name="EditorialStatus" nillable="true" type="tns:KeywordEditorialStatus" />
    <xs:element xmlns:q36="http://schemas.datacontract.org/2004/07/Microsoft.AdCenter.Advertiser.CampaignManagement.Api.DataContracts.V11" minOccurs="0" name="FinalAppUrls" nillable="true" type="q36:ArrayOfAppUrl"/>
    <xs:element xmlns:q37="http://schemas.microsoft.com/2003/10/Serialization/Arrays" minOccurs="0" name="FinalMobileUrls" nillable="true" type="q37:ArrayOfstring"/>
    <xs:element xmlns:q38="http://schemas.microsoft.com/2003/10/Serialization/Arrays" minOccurs="0" name="FinalUrls" nillable="true" type="q38:ArrayOfstring"/>
    <xs:element xmlns:q39="http://schemas.datacontract.org/2004/07/System.Collections.Generic" minOccurs="0" name="ForwardCompatibilityMap" nillable="true" type="q39:ArrayOfKeyValuePairOfstringstring"/>
    <xs:element minOccurs="0" name="Id" nillable="true" type="xs:long" />
    <xs:element minOccurs="0" name="MatchType" nillable="true" type="tns:MatchType" />
    <xs:element minOccurs="0" name="Param1" nillable="true" type="xs:string" />
    <xs:element minOccurs="0" name="Param2" nillable="true" type="xs:string" />
    <xs:element minOccurs="0" name="Param3" nillable="true" type="xs:string" />
    <xs:element minOccurs="0" name="Status" nillable="true" type="tns:KeywordStatus" />
    <xs:element minOccurs="0" name="Text" nillable="true" type="xs:string" />
    <xs:element minOccurs="0" name="TrackingUrlTemplate" nillable="true" type="xs:string"/>
    <xs:element xmlns:q40="http://schemas.datacontract.org/2004/07/Microsoft.AdCenter.Advertiser.CampaignManagement.Api.DataContracts.V11" minOccurs="0" name="UrlCustomParameters" nillable="true" type="q40:CustomParameters"/>
  </xs:sequence>
</xs:complexType>

ElementDescriptionData Type
BidThe bid to use when the user’s search term and the keyword match.

To use the AdGroup default match type bid, set the Amount element of the Bid object to null.

Add: Required
Update: Optional. If no value is specified on update, this Bing Ads setting is not changed.
Bid
BiddingSchemeThe bid strategy type for how you want to manage your bids.

For keywords you can use either of the InheritFromParentBiddingScheme or ManualCpcBiddingScheme objects.

IMPORTANT: If the campaign bid strategy type is set to MaxClicks, MaxConversions, or TargetCpa, the behavior of existing features will change unless you set an individual ad group’s or keyword’s bid strategy to ManualCpc.
- You can continue to set the ad group and keyword bids; however they will not be used by Bing Ads.
- Bing Ads will periodically change your stored ad group or keyword bid settings. You can continue to set new bids, however Bing Ads may change them at any type using this bid strategy type.
- You can continue to set bid adjustments e.g. for age, gender, or location; however with one exception they will not be used by Bing Ads. Bing Ads will not honor any bid adjustments, unless you have set a bid adjustment of -100% (opt out).
- Whether you chose the DailyBudgetAccelerated or DailyBudgetStandard budget type, Bing Ads will use the DailyBudgetStandard budget type.

Also note that you must have conversion tracking (a UET tag and a conversion goal) set up for the EnhancedCpc, MaxConversions, and TargetCpa bid strategy types to work. See Universal Event Tracking for more information.

To set the MaxConversions or TargetCpa bid strategy types, the campaign must have at least 15 conversions in the last 30 days. If you try to add or update a campaign to use one of these strategy types, the requested operation will fail if there is not enough conversion history. If an active campaign uses one of these bid strategy types, and then ceases to meet the minimum conversion history requirement at any time, Bing Ads will stop auto bidding but will continue to use the DailyBudgetStandard budget type. For a new campaign we recommend that you start with EnhancedCpc and then when the campaign has enough conversion history, you can update it to use either the MaxConversions or TargetCpa bid strategy.

Tip: You can set your campaign’s bid strategy to EnhancedCpcBiddingScheme, MaxClicksBiddingScheme, MaxConversionsBiddingScheme, or TargetCpaBiddingScheme and then, at any time, set an individual ad group’s or keyword’s bid strategy to Manual CPC (ManualCpcBiddingScheme).

Note: This element is not supported for campaigns of type Shopping.

Add: Optional. If you do not set this element, then InheritFromParentBiddingScheme is used by default.
Update: Optional
BiddingScheme
DestinationUrlThe 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: If you are currently using Destination URLs, you must eventually replace them with Final URLs. For more information, see URL Tracking with Upgraded URLs.

Add: Optional
Update: Optional
string
EditorialStatusThe 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
KeywordEditorialStatus
FinalAppUrlsReserved for future use.AppUrl array
FinalMobileUrlsThe 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
string array
FinalUrlsThe 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.

    Note: 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 element are set, then at least one final URL is required.

Add: Optional
Update: Optional
string array
ForwardCompatibilityMapThe list of key and value strings for forward compatibility. This element can be used to avoid otherwise breaking changes when new elements are added in future releases.

Note: Forward compatibility changes will be noted here in future releases. There are currently no forward compatibility changes for the Keyword object.
KeyValuePairOfstringstring array
IdThe system-generated identifier of the keyword.

Add: Read-only
Update: Required
long
MatchTypeThe type of match to compare the keyword and the user's search term.

Add: Required
Update: Read-only
MatchType
Param1The 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.

Note: 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 Bing Ads 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
string
Param2The 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 Bing Ads 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
string
Param3The 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 Bing Ads 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
string
StatusThe keyword’s status. By default, the status is set to Active.

Add: Optional
Update: Optional
KeywordStatus
TextThe 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
string
TrackingUrlTemplateThe 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 Bing Ads 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 Hierarchy and 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}.

  • Bing Ads 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 for example http://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
string
UrlCustomParametersYour custom collection of key and value parameters for URL tracking.

You may include up to 3 individual CustomParameter objects within the CustomParameters object. Each CustomParameter contains a Key and Value element.

On update, 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.

Note that custom parameters for a keyword are allowed, even if the FinalUrls element is not specified.

Add: Optional
Update: Optional
CustomParameters

CampaignManagementService.svc v11

Namespace: https://bingads.microsoft.com/CampaignManagement/v11

AddKeywords
GetKeywordsByAdGroupId
GetKeywordsByEditorialStatus
GetKeywordsByIds
UpdateKeywords

Show: