Bulk File Schema

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

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

File Schema

You can choose to download either a tab or comma delimited set of records (rows) and fields (columns). The first column header is named Type. The rest of the column names map to properties within or associated with the corresponding record type.

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. Likewise, unless otherwise noted in the reference documentation you should not depend on a fixed set of values returned in each field.

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. Currently the only supported format version is 6.0.

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

To specify the version using bulk upload, set the Name field of the Format Version record to 6.0.

Record Types

Records available for upload and download using Format Version 6.0 are detailed in the table below.

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.

Record Type Supported Campaign Types
Account All
Account Action Ad Extension DynamicSearchAds
Search
Account App Ad Extension DynamicSearchAds
Search
Account Callout Ad Extension DynamicSearchAds
Search
Account Image Ad Extension DynamicSearchAds
Search
Account Location Ad Extension DynamicSearchAds
Search
Account Price Ad Extension DynamicSearchAds
Search
Account Sitelink Ad Extension DynamicSearchAds
Search
Account Structured Snippet Ad Extension DynamicSearchAds
Search
Action Ad Extension DynamicSearchAds
Search
Ad Group All
Ad Group Age Criterion All
Ad Group Action Ad Extension DynamicSearchAds
Search
Ad Group App Ad Extension DynamicSearchAds
Search
Ad Group Callout Ad Extension DynamicSearchAds
Search
Ad Group Company Name Criterion All
Ad Group Custom Audience Association All
Ad Group DayTime Criterion All
Ad Group DeviceOS Criterion All
Ad Group Dynamic Search Ad Target DynamicSearchAds
Ad Group Gender Criterion All
Ad Group Image Ad Extension DynamicSearchAds
Search
Ad Group Industry Criterion All
Ad Group In Market Audience Association All
Ad Group Job Function Criterion All
Ad Group Label All
Ad Group Location Criterion All
Ad Group Location Intent Criterion All
Ad Group Negative Age Criterion Audience
Ad Group Negative Company Name Criterion Audience
Ad Group Negative Custom Audience Association All
Ad Group Negative Gender Criterion Audience
Ad Group Negative Dynamic Search Ad Target DynamicSearchAds
Ad Group Negative Industry Criterion Audience
Ad Group Negative In Market Audience Association All
Ad Group Negative Job Function Criterion Audience
Ad Group Negative Keyword All
Ad Group Negative Location Criterion All
Ad Group Negative Product Audience Association All
Ad Group Negative Remarketing List Association All
Ad Group Negative Similar Remarketing List Association All
Ad Group Negative Site All
Ad Group Price Ad Extension DynamicSearchAds
Search
Ad Group Product Audience Association All
Ad Group Product Partition Shopping
Ad Group Radius Criterion All
Ad Group Remarketing List Association All
Ad Group Review Ad Extension DynamicSearchAds
Search
Ad Group Similar Remarketing List Association All
Ad Group Sitelink Ad Extension DynamicSearchAds
Search
Ad Group Structured Snippet Ad Extension DynamicSearchAds
Search
App Ad Extension DynamicSearchAds
Search
App Install Ad Search
App Install Ad Label Search
Budget All
Call Ad Extension DynamicSearchAds
Search
Callout Ad Extension DynamicSearchAds
Search
Campaign All
Campaign Age Criterion All
Campaign Action Ad Extension DynamicSearchAds
Search
Campaign App Ad Extension DynamicSearchAds
Search
Campaign Call Ad Extension DynamicSearchAds
Search
Campaign Callout Ad Extension DynamicSearchAds
Search
Campaign Company Name Criterion DynamicSearchAds
Search
Shopping
Campaign Custom Audience Association DynamicSearchAds
Search
Shopping
Campaign DayTime Criterion All
Campaign DeviceOS Criterion All
Campaign Gender Criterion All
Campaign Industry Criterion DynamicSearchAds
Search
Shopping
Campaign In Market Audience Association DynamicSearchAds
Search
Shopping
Campaign Job Function Criterion DynamicSearchAds
Search
Shopping
Campaign Label All
Campaign Location Ad Extension DynamicSearchAds
Search
Campaign Location Criterion All
Campaign Location Intent Criterion All
Campaign Negative Custom Audience Association DynamicSearchAds
Search
Shopping
Campaign Negative Dynamic Search Ad Target DynamicSearchAds
Campaign Negative In Market Audience Association DynamicSearchAds
Search
Shopping
Campaign Negative Keyword All
Campaign Negative Keyword List Association DynamicSearchAds
Search
Shopping
Campaign Negative Location Criterion All
Campaign Negative Product Audience Association DynamicSearchAds
Search
Shopping
Campaign Negative Remarketing List Association DynamicSearchAds
Search
Shopping
Campaign Negative Similar Remarketing List Association DynamicSearchAds
Search
Shopping
Campaign Negative Site All
Campaign Price Ad Extension DynamicSearchAds
Search
Campaign Product Audience Association DynamicSearchAds
Search
Shopping
Campaign Product Scope Audience
Shopping
Campaign Radius Criterion All
Campaign Remarketing List Association DynamicSearchAds
Search
Shopping
Campaign Review Ad Extension DynamicSearchAds
Search
Campaign Similar Remarketing List Association DynamicSearchAds
Search
Shopping
Campaign Sitelink Ad Extension DynamicSearchAds
Search
Campaign Structured Snippet Ad Extension DynamicSearchAds
Search
Custom Audience

Only update is supported for upload. You cannot add or delete a custom audience using the Bing Ads API.
All
Dynamic Search Ad DynamicSearchAds
Dynamic Search Ad Label DynamicSearchAds
Expanded Text Ad Search
Expanded Text Ad Label Search
Experiments Search
Format Version All
Image Ad Extension DynamicSearchAds
Search
In Market Audience

Bulk upload is not supported. You cannot add, update, or delete an in-market audience using the Bing Ads API.
All
Keyword Search
Keyword Label Search
Keyword Best Position Bid Search
Keyword First Page Bid Search
Keyword Main Line Bid Search
Label All
Location Ad Extension DynamicSearchAds
Search
Negative Keyword List All
Offline Conversion

Bulk upload only supports adding new offline conversion data. Bulk download, bulk upload update, and bulk upload delete operations are not supported.
All
Price Ad Extension DynamicSearchAds
Search
Product Ad Shopping
Product Ad Label Shopping
Product Audience All
Remarketing List All
Responsive Ad Audience
Responsive Ad Label Audience
Responsive Search Ad Search
Responsive Search Ad Label Search
Review Ad Extension DynamicSearchAds
Search
Shared Negative Keyword All
Similar Remarketing List All
Sitelink Ad Extension DynamicSearchAds
Search
Structured Snippet Ad Extension DynamicSearchAds
Search
Text Ad Search
Text Ad Label Search

Type Hierarchy

The download file will always include a record for the Format Version and Account record types. For upload, the Format Version is required and must precede all other record types in the bulk file.

  • If a parent entity is created in the same file, it should precede any dependent child records in the bulk file. For example as shown in the 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. 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 Microsoft Advertising identifiers, then you should use Reference Keys.

    Record Type Hierarchy

  • It is not required to include the record for a parent entity that already has been assigned a valid Microsoft Advertising identifier.

  • 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.

  • 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.

  • Partial updates are supported for bulk records including negative keywords, negative sites, and target criterions. For example you can update the bid of a single location criterion, and you do not need to download and upload the entire set of target criterions for the campaign or ad group.

  • When updating a record, the Id field for the updated record is required. The Parent Id or Reference Keys 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.

  • If you are replacing one set of records with another set then you must specify the deleted records prior to the new set. For example to replace all existing Campaign Negative Keyword for a given campaign, first include a Campaign Negative Keyword with Status set to Deleted and Parent Id set to the campaign ID. If you do not specify any Id i.e., do not attempt to delete a specific camapaign negative keyword, this will effectively delete all Campaign Negative Keyword for that campaign. Below the "delete all" record, you can include one or more new Campaign Negative Keyword records with all of the required properties for the upload add operation.

  • If you are replacing an existing record with a new record that has the same unique properties, then you must specify the deleted record prior to the new record. For example to replace an existing Ad Group Dynamic Search Ad Target for a given ad group, first include an Ad Group Dynamic Search Ad Target with Status set to Deleted, Id set to the existing dynamic ad target (webpage criterion) ID, and Parent Id set to the ad group ID. Below the deleted record, you can include a new Ad Group Dynamic Search Ad Target record (presumably with new webpage conditions).

    Note

    In most cases you can update the existing record instead of submitting separate delete and add records, for example you can update the Bid Adjustment field of an existing Campaign Gender Criterion.

  • When deleting a record the Id field is required. A reference to the parent entity, whether the value is a Microsoft Advertising assigned system identifier or a Reference Keys for the parent record, is also required. For example when deleting an ad group, either the Parent Id field of the Ad Group record should match the Id field in the Campaign record or the Campaign field of the Ad Group record should match the Campaign field in the Campaign record. If both are provided then the Parent Id field of the Ad Group record (Reference Keys) is ignored.

  • With a few exceptions the result file will only include the columns that you uploaded. For example if you upload a new Ad Group Negative Keyword without the Id column header, then the result file will not include the assigned identifier for the new negative keyword. The bulk file should contain the Id column; however, you should leave the Id empty for each new Ad Group Negative Keyword. The exceptions to this rule are campaigns, ad groups, ads, and keywords in which case the result file will contain all columns regardless of the uploaded columns.

Update with delete_value

To remove an existing setting, you should not write an empty string ("") to the Bulk file because such strings are ignored by the Bulk service. Use the reserved "delete_value" string to delete or reset the value of an optional field.

  • If you use the reserved "delete_value" string in an optional field, the previous setting will be deleted. For example if you set the Custom Parameter field of the Ad Group record to "delete_value", all previous custom parameters will be deleted from the ad group. Likewise if you set the Tracking Template field of the Ad Group record to "delete_value", the previous tracking template will be deleted from the ad group.
  • The Bing Ads SDKs for .NET, Java, and Python automatically write "delete_value" where applicable. For more details see Bulk Service Manager - Update with delete_value.

If you use "delete_value" in required fields, please note the following.

  • If you use the reserved "delete_value" string in place of a required primitive value, it will be ignored. Although the field was not updated, the "delete_value" string will be passed through via the upload results file. For example if you set the Ad Group field (ad group name) of the Ad Group record to "delete_value", the ad group's name would not be updated.
  • If you use the reserved "delete_value" string in place of a required value set, the field will be updated to the default value, and the results file will reflect that change. For example if you set the Network Distribution field of the Ad Group record to "delete_value", then the ad group's network distribution would be set to OwnedAndOperatedAndSyndicatedSearch and the upload results file would reflect the same.

Reference Keys

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

Note

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

Negative Reference Key

When referring to a preceding record in the bulk file that does not yet have an assigned Microsoft Advertising identifier, you can 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.

The first example shows how to create an Ad Group for a new Campaign. Set the Parent Id field in the Ad Group record to the negative reference key of the Campaign (-111). If you will add additional records in the same file that should have the Ad Group as their parent (e.g. Keyword or Ad Group Callout Ad Extension), then you should also set the Id field in the Ad Group to a negative value e.g. -1111 which can be referenced from the child records.

Type Id Parent Id
Campaign -111
Ad Group -1111 -111

The second example shows how to create a Campaign Callout Ad Extension for a new Campaign and a new Callout Ad Extension. The example also shows how to create an Ad Group Callout Ad Extension for a new Ad Group and another new Callout Ad Extension.

Type Id Parent Id
Callout Ad Extension -11
Callout Ad Extension -12
Campaign -111
Ad Group -1111 -111
Campaign Callout Ad Extension -11 -111
Ad Group Callout Ad Extension -12 -1111

Logical Reference Key

When referring to a new Campaign or Ad Group record you can use the campaign and ad group name instead of setting the Parent Id field to a Negative Reference Key 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 following example.

Type Campaign Ad Group
Campaign Women's Shoes
Ad Group Women's Shoes Women's Red Shoe Sale

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 Microsoft Advertising system makes no modifications to your client identifiers and passes them through to the results file for the corresponding 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 type represents a product ad error. The Error and Error Number columns will contain details about the error.

Note

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

Errors related to new features such as Final URLs will include additional details about where the error occurred in the Field Path column. Each field path name corresponds to an element of one of the Campaign Management Service data objects. For example if the Tracking Template field of a Campaign record does not begin with http:// or https://, {lpurl}, or {unescapedlpurl}, the value of this Field Path value is TrackingTemplate. The TrackingUrlTemplate is an element of the Campaign data object available with the Campaign Management Service.

Type Tracking Template Error Error Number Field Path
Campaign Error tracker.example.com/?season={_season}&promocode={_promocode}&u={lpurl} InvalidUrlScheme 4600 TrackingTemplate
Campaign Error tracker.example.com/?season={_season}&promocode={_promocode}&u={lpurl} CampaignServiceInvalidUrl 2611 TrackingTemplate

Important

The Field Path value is subject to change, so you should not take a dependency on the current string format. The Field Path is not supported for all errors. It is supported for Mobile Final Url, Final Url, Tracking Template, and Custom Parameter fields of the respective Campaign, Ad Group, Expanded Text Ad, Product Ad, Ad Group Product Partition, Keyword, and Sitelink Ad Extension records. It is also supported for errors related to all fields of the Callout Ad Extension and Review Ad Extension records.

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.