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.
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.
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.
- Set the Parent Id field in the Campaign Callout Ad Extension record to the negative reference key of the Campaign (-111), and set the Id field in the Campaign Callout Ad Extension record to the negative reference key of the Callout Ad Extension (-11).
- Set the Parent Id field in the Ad Group Callout Ad Extension record to the negative reference key of the Ad Group (-1111), and set the Id field in the Ad Group Callout Ad Extension record to the negative reference key of the Callout Ad Extension (-12).
| 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.
Feedback
Coming soon: Throughout 2024 we will be phasing out GitHub Issues as the feedback mechanism for content and replacing it with a new feedback system. For more information see: https://aka.ms/ContentUserFeedback.
Submit and view feedback for