Export (0) Print
Expand All

The bulk schema defines the contents of the file for download or upload with the Bing Ads Bulk service. For both download and upload, the Bulk service supports the file types and corresponding schemas in the DownloadFileType value set.

For more information about using the Bulk service to manage your campaigns, see Downloading and Uploading Campaigns. For more information about understanding the data file contents, see the sections below.

File Schema

Depending on the file type chosen, the file is either a tab or comma delimited set of records, and may be described as a table with records (rows) and fields (columns). As shown in the image below, the first field is named Type. The rest of the field names map to elements within or associated with the corresponding record type.

Bulk File in Excel


System_CLiX_important Important

New record types (rows) and fields (columns) may be added anytime, and you should not depend on record or field order in the bulk download or bulk upload results file. Similarly during upload you may submit the fields in any order. The upload record order is important when creating new entities, as described below within Type Hierarchy.

Format Versions

The bulk format version is separate from the Bing Ads API version. Format version enables a flexible upgrade path to adopt the latest supported features without breaking your application. As a best practice you should always upgrade to the latest format version.

To specify the file format version using bulk download, set FormatVersion to 3.0 in either the DownloadCampaignsByAccountIds or DownloadCampaignsByCampaignIds request.

To specify the version using bulk upload, set the Name field of the Format Version record. If not specified the default format version is 1.0, which is deprecated. You should upgrade to the latest version (3.0) as soon as feasible.

System_CLiX_important Important

Before you upgrade to the latest format version, you should read Bulk File Deprecated Record Types. If you currently use any of the deprecated records, you should read about and understand the differences between the deprecated version and the latest version of the Bulk File Record Types.

Record Types

The download file will always include a record for the Format Version and Account record Type, which are read-only. When you specify the following BulkDownloadEntity values, the download file can include records for each Type shown below.

System_CLiX_important Important

New record types (rows) and fields (columns) may be added anytime, and you should not depend on record or field order in the bulk download or bulk upload results file.

System_CLiX_note Note

For information about deprecated record versions see Bulk File Deprecated Record Types.

BulkDownloadEntity Value

Record Type

AdGroupAppAdExtensions

Ad Group App Ad Extension

AdGroupImageAdExtensions

Ad Group Image Ad Extension

AdGroupNegativeKeywords

Ad Group Negative Keyword

AdGroupNegativeSites

Ad Group Negative Site

AdGroupProductTargets

Ad Group Product Target

AdGroups

Ad Group

AdGroupSiteLinksAdExtensions

Ad Group Sitelink Ad Extension

AdGroupTargets

Ad Group Age Target

Ad Group DayTime Target

Ad Group DeviceOS Target

Ad Group Gender Target

Ad Group Location Target

Ad Group Negative Location Target

Ad Group Radius Target

Ads

Mobile Ad

Product Ad

Text Ad

AppAdExtensions

App Ad Extension

CallAdExtensions

Call Ad Extension

CampaignAppAdExtensions

Campaign App Ad Extension

CampaignCallAdExtensions

Campaign Call Ad Extension

CampaignImageAdExtensions

Campaign Image Ad Extension

CampaignLocationAdExtensions

Campaign Location Ad Extension

CampaignNegativeKeywordListAssociations

Campaign Negative Keyword List Association

CampaignNegativeKeywords

Campaign Negative Keyword

CampaignNegativeSites

Campaign Negative Site

CampaignProductAdExtensions

Campaign Product Ad Extension

Campaigns

Campaign

CampaignSiteLinksAdExtensions

Campaign Sitelink Ad Extension

CampaignTargets

Campaign Age Target

Campaign DayTime Target

Campaign DeviceOS Target

Campaign Gender Target

Campaign Location Target

Campaign Negative Location Target

Campaign Radius Target

ImageAdExtensions

Image Ad Extension

Keywords

Keyword

System_CLiX_note Note

If the requested download DataScope includes BidSuggestionsData, the download will include the following record types for each corresponding keyword.

LocationAdExtensions

Location Ad Extension

NegativeKeywordLists

Negative Keyword List

ProductAdExtensions

Product Ad Extension

SharedNegativeKeywords

Shared Negative Keyword

SiteLinksAdExtensions

Sitelink Ad Extension

Type Hierarchy

The Format Version and Account records precede all other record types in the bulk file. New record uploads should appear in descending order where any parent or association dependencies are listed above the child or dependent record. For example as shown in the dependency diagram below, when associating a site link ad extension with a campaign, the Campaign Sitelink Ad Extension record must be included in the file after both the Campaign and Sitelink Ad Extension records.

System_CLiX_note Note

If a parent entity is created in the same file, it should precede any dependent child records in the bulk file. It is not required to include the record for a parent entity that already has a valid Bing Ads identifier.

Record Type Hierarchy


In the example described above, the Id and Parent Id fields of the Campaign Sitelink Ad Extension record should be set to the identifier of the Sitelink Ad Extension and Campaign records respectively. If the Sitelink Ad Extension and Campaign records are also new and do not yet have assigned Bing Ads identifiers, then you should use reference keys as described in the next section.

For details about parent identifiers for each record type, see Bulk File Record Types.

Reference Keys

When referring to preceding record in the bulk file that does not yet have an assigned Bing Ads identifier, you may use either a logical reference key or negative reference key depending on the record type.

Logical Reference Key

When referring to a new Campaign or Ad Group record use the campaign and ad group name instead of setting the Parent Id field within the child record. For example to add a new ad group to a new campaign, and add a new keyword to the new ad group, set the Campaign and Ad Group fields in the child records as shown in the figure below.

System_CLiX_note Note

If the parent entity is created in the same file, it should precede any dependent child records in the bulk file.

Logical Reference Key


Negative Reference Key

When referring to a new ad extension record set the extension's Id field to a negative number of your choice. This custom Id is known as a negative reference key. Then you may use the negative reference key within the Id field of a dependent record. For example to add a new site link ad extension and a new campaign, and then associate the new site link ad extension with the new campaign, use the campaign name in the Campaign field as the logical key for associating the entity and set the Id field in the Campaign Sitelink Ad Extension record to the negative reference key of the Sitelink Ad Extension as shown in the figure below.

Negative Reference Key


You may follow the same process and include the Ad Group field as the ad group logical key to create a AdGroup Sitelink Ad Extension association record.

Client Identifiers

Client identifiers may be used to associate input records in the bulk upload file with output records in the results file. For example when adding new records you may set the Client Id field to a string value of your choosing. The Bing Ads system makes no modifications to your client identifiers and passes them through to the results file for the corresponding record.

Managing Bulk Records

Partial success is supported when adding, updating, and deleting bulk file records. For example if you try to add three campaigns and only two are correctly specified in the file, then two will be added. The results file will include details for both successful Campaign records, one attempted Campaign record, and one Campaign Error record.

Adding Records

If the new campaign identifier is not yet known, for example when adding a campaign, ad group, text ad, and keyword in the same file, specify the Campaign name as the logical reference key for any child records. It is not necessary to specify an existing parent in the upload.

Updating Records

When updating a record, the Id field for the updated record is required. The Parent Id or reference key to the parent record is also required.

When updating the campaign or ad group name, it is optional to specify the new name for the child records if the correct Parent Id is provided. In the example upload file below, the campaign name will be updated from Campaign A to Campaign A'1. It is not necessary to update the campaign name in the Ad Group, Text Ad, and Keyword records.

Updating Bulk Records


Use the literal string delete_value to delete or empty the existing value of an optional field. If you use delete_value in required fields, please note the following.

  • If during update you try to delete a required string value, delete_value will be ignored and the results file will show delete_value as the value for that field. For example if you set the Budget field of the Campaign record to delete_value, then the Budget field would be set to delete_value in the results file. In this example the campaign's budget would not be updated.

  • If during update you try to delete a required value set the results file will return the default value. For example if you set the Network Distribution field of the Ad Group record to delete_value, then the Network Distribution field would be set to OwnedAndOperatedAndSyndicatedSearch in the results file. In this example the ad group's network distribution would be set to OwnedAndOperatedAndSyndicatedSearch.

Incremental Updates

Incremental updates are supported for negative keywords, negative sites, and targets. For example to add or delete an individual negative keyword, you do not need to download the entire set of associated negative keywords, make updates, and upload the new list. To delete all negative keywords associated with the campaign or ad group, include a record with Status set to Deleted and the Keyword field empty. Then optionally you may add new negative keyword records to replace the deleted set.

Deleting Records

When deleting a record the Id element is required. The Parent Id or reference key to the parent record is also required. For example when deleting an ad group the Parent Id should be set to the campaign identifier or the Campaign field should be set to the campaign name. If both are provided then the reference key is ignored.

Targets

Target associations span multiple records even for a single target and associated entity. For example the Campaign Age Target, Campaign DayTime Target, Campaign Gender Target, Campaign DeviceOS Target, Campaign Location Target, and Campaign Negative Location Target shown below all share the same target identifier in the Id field. Also multiple records may be required to represent an individual target type, for example there are two records for Campaign Gender Target representing Male and Female target bids.

System_CLiX_note Note

There are no records which represent a non-associated target object, and thus target identifiers may not be shared between multiple campaigns or ad groups.

Bulk Target Records


The Target All field is only applicable for day and hour targets, and is equivalent of setting the TargetAllDays and TargetAllHours elements of the respective HourTarget and DayTarget campaign management objects. In bulk download the value of Target All for a target type will always be identical. For bulk upload you should always set Target All to a consistent value for all records of a day or hour target. To update the Target All value, a single record may be uploaded for each day or hour target and as a best practice you should only upload the minimum required records.

In the example above, there isn't a record for Sunday however the value of Target All is true for other records, which indicates that Sunday is included implicitly with the base keyword or ad group level bid. Also note that all hour ranges are targeted and yet the value for Target All is false in this example. Since the Target All field is deprecated it is a best practice to set all Target All values to false, and explicitly include records for each day or hour that you want to target.

The Physical Intent field is only applicable for location targets, and is the equivalent of setting the HasPhysicalIntent element of the LocationTarget campaign management object. In the example above, Physical Intent is set to true for each location target. In bulk download the value of Physical Intent for a given location target will always be identical.

For bulk upload you should always set Physical Intent to a consistent value for all records of a location target. To update the Physical Intent value a single record may be uploaded for each location target, and as a best practice you should only upload the minimum required records.

To delete an entire target type, include a single record with only the Type, Status, Id, and Parent Id fields and set the status to Deleted. Whenever you update or delete a target association record, a new target identifier is created and associated with the campaign or ad group. The previous target identifier remains in your customer level target library. The following example demonstrates how to delete all of the target types shown above.

Delete Bulk Target Records


Ad Extensions

When referring to a new ad extension record set the extension's Id field to a negative number of your choice. This custom Id is known as a negative reference key. Then you may use the negative reference key within the Id field of a dependent record. For example to add a new site link ad extension and a new campaign, and then associate the new site link ad extension with the new campaign, use the campaign name in the Campaign field as the logical reference key for associating the entity and set the Id field in the Campaign Sitelink Ad Extension record to the negative reference key of the Sitelink Ad Extension as shown in the figure below.

Negative Reference Key


You may follow the same process and include the Ad Group field as the ad group logical key to create a AdGroup Sitelink Ad Extension association record.

Errors

The bulk download file or the bulk upload results file may contain records where the corresponding Type field includes the Error suffix. For example a product ad error record would have Product Ad Error as the Type field. The Error and Error Number columns will contain details about the error. If the issue is related to an editorial error, then the Editorial Location, Editorial Term, Editorial Reason Code, and Publisher Countries columns may also contain more information about the error.

For example if you attempt to set the Promotion for Product Ad to www.bing.com, the file returned will include the following columns with corresponding values for the record.

Type

Promotion

Editorial Location

Editorial Term

Editorial Reason Code

Error

Error Number

Product Ad Error

www.bing.com

AdDescription

bing

17

CampaignServiceEditorialValidationError

1042

System_CLiX_note Note

The upload results file may include multiple error records corresponding to the same uploaded record.

For more information, see Bing Ads Operation Error Codes and Bing Ads Editorial Failure Reason Codes.

Community Additions

ADD
Show:
© 2014 Microsoft