Hotel API reference

Note

This beta release of Hotel Price Ads is available to select participants only. For information about participating in the beta release program, please contact your account manager or enroll here.

The API and documentation are subject to change.

The Hotel API lets you manage your hotel ad campaigns and bidding.

Endpoints

The following is the base URI that you use to construct the endpoint.

  • Production—https://partner.api.bingads.microsoft.com/Travel/v1/

The endpoint must include the customer and account resources.

https://partner.api.sandbox.bingads.microsoft.com/Travel/V1/Customers({customerId})/Accounts({accountId})/

Set {customerId} to the customer's CustomerId and {accountId} to the customer's CustomerAccountId.

Next, append a template from the following table to add, get, and update hotel resources. For example, to get or add a hotel group, use the following endpoint:

https://partner.api.sandbox.bingads.microsoft.com/Travel/V1/Customers({customerId})/Accounts({accountId})/SubAccounts('{subAccountId}')/HotelGroups

Note

The IDs for SubAccounts, HotelGroups, Hotels, and ReportJobs are strings and must be enclosed in single quotes. For example, SubAccounts('12345')/HotelGroups. This applies to SubAccounts, HotelGroups, Hotels, and ReportJobs only; do not use single quotes for Customers and Accounts.

SubAccounts template

Verb Description
GET Gets the list of lodging campaigns (formerly hotel campaigns) defined for the specified account.

NOTE: By default, the list contains a maximum of 1,000 campaigns. To determine the total number of campaigns in the subaccount, use the $count query parameter. To specify the number of campaigns to return, use the $top query parameter. To page through all campaigns in a subaccount, use the $top and $skip query parameters.

Response body: Contains a CollectionResponse object. The value field contains the list of SubAccount objects.
POST Adds the subaccount to the specified account. You can think of subaccounts as lodging campaigns. Use subaccounts to logically organize your hotel ad campaigns. You may have a maximum of 50 active lodging campaigns per account.

Request body: Contains the SubAccount to add.

Response body: If successful, contains an AddResponse object. The value field contains the ID of the added lodging campaign.

SubAccounts('{subAccountId}') template

Verb Description
GET Gets the specified subaccount.

Response body: Contains a SubAccount object.

Template parameters:
  • {subAccountId}—Set to the ID of the subaccount to get.
PATCH Updates the subaccount.

Request body: Contains a SubAccount object that specifies only those fields to update.

Response body: None. If successful, returns HTTP status code 204.

Template parameters:
  • {subAccountId}—Set to the ID of the subaccount to update.

SubAccounts('{subAccountId}')/HotelGroups template

Verb Description
GET Gets the list of hotel groups in the specified subaccount.

NOTE: By default, the list contains a maximum of 1,000 hotel groups. To determine the total number of groups in the subaccount, use the $count query parameter. To specify the number of groups to return, use the $top query parameter. To page through all groups in a subaccount, use the $top and $skip query parameters.

Response body: Contains a CollectionResponse object. The value field contains the list of HotelGroup objects.

Template parameters:
  • {subAccountId}—Set to the ID of the subaccount that contains the hotel groups to get.
POST Adds the hotel group to the specified subaccount. Use hotel groups to create logical groupings of hotel price ads. You may create up to 1,000 active hotel groups per subaccount.

Request body: Contains the HotelGroup to add to the subaccount.

Response body: If successful, contains an AddResponse object. The value field contains the ID of the added hotel group.

Template parameters:
  • {subAccountId}—Set to the ID of the subaccount to add the hotel group to.

SubAccounts('{subAccountId}')/HotelGroups('{hotelGroupId}') template

Verb Description
GET Gets the specified hotel group.

Response body: Contains a HotelGroup object.

Template parameters:
  • {subAccountId}—Set to the ID of the subaccount that contains the hotel group.
  • {hotelGroupId}—Set to the ID of the hotel group to get.
PATCH Updates the hotel group.

Request body: Contains a HotelGroup object that specifies only those fields to update.

Response body: None. If successful, returns HTTP status code 204.

Template parameters:
  • {subAccountId}—Set to the ID of the subaccount that contains the hotel group.
  • {hotelGroupId}—Set to the ID of the hotel group to update.
DELETE Deletes the hotel group.

Request body: None.

Response body: None. If successful, returns HTTP status code 204.

Template parameters:
  • {subAccountId}—Set to the ID of the subaccount that contains the hotel group.
  • {hotelGroupId}—Set to the ID of the hotel group to delete.

SubAccounts('{subAccountId}')/Hotels template

Verb Description
GET Gets the list of hotel price ads in the specified subaccount. The list contains all hotels across all hotel groups in the subaccount.

NOTE: By default, the list contains a maximum of 1,000 hotels. To determine the total number of hotels in the subaccount, use the $count query parameter. To specify the number of hotels to return, use the $top query parameter. To page through all hotels in a subaccount, use the $top and $skip query parameters.

NOTE: Use this call to page through hotels in a UI experience only. Do not use this call to download all hotels. To download all hotels, instead use the Reporting feature.

Response body: Contains a CollectionResponse object. The value field contains the list of Hotel objects.

Template parameters:
  • {subAccountId}—Set to the ID of the subaccount that contains the hotels to get.
.

SubAccounts('{subAccountId}')/HotelGroups('{hotelGroupId}')/Hotels template

Verb Description
GET Gets the list of hotel price ads in the specified hotel group.

NOTE: By default, the list contains a maximum of 1,000 hotels. To determine the total number of hotels in the hotel group, use the $count query parameter. To specify the number of hotels to return, use the $top query parameter. To page through all hotels in a group, use the $top and $skip query parameters.

NOTE: Use this call to page through hotels in a UI experience only. Do not use this call to download all hotels. To download all hotels, instead use the Reporting feature.

Response body: Contains a CollectionResponse object. The value field contains the list of Hotel objects.

Template parameters:
  • {subAccountId}—Set to the ID of the subaccount that contains the hotel group.
  • {hotelGroupId}—Set to the ID of the hotel group that contains the hotels to get.
.

SubAccounts('{subAccountId}')/HotelGroups('{hotelGroupId}')/Hotels('{hotelId}') template

Verb Description
GET Gets the specified hotel ad.

Response body: Contains a Hotel object.

Template parameters:
  • {subAccountId}—Set to the ID of the subaccount that contains the hotel group.
  • {hotelGroupId}—Set to the ID of the hotel group that contains the hotel to get.
  • {hotelId}—Set to the hotel ad to get.
PATCH Updates the hotel ad.

Request body: Contains a Hotel object that specifies only those fields to update.

Response body: None. If successful, returns HTTP status code 204.

Template parameters:
  • {subAccountId}—Set to the ID of the subaccount that contains the hotel group.
  • {hotelGroupId}—Set to the ID of the hotel group that contains the hotel to update.
  • {hotelId}—Set to the ID of the hotel to update. You may set this parameter to the ID that Microsoft assigned to the hotel or the ID that the advertiser assigned to the hotel. If you set it to the advertiser's ID, you must set the PartnerHotelId query parameter to true.
Query parameters:
  • PartnerHotelId—Set to true if the {hotelId} resource parameter contains the ID that the advertiser assigned to the hotel. If this parameter is set to false or is missing, the ID is the one assigned by Microsoft. The default is false.

SubAccounts('{subAccountId}')/Ungrouped template

Verb Description
GET Gets the list of hotels in the Ungrouped hotel group. When you create a subaccount, the service creates the Ungrouped hotel group. All hotels from your hotel feed that are not otherwise associated with other groups are placed in this group. To associate a hotel in this group with a different hotel group, see the Associate template.

NOTE: By default, the list contains a maximum of 1,000 hotels. To determine the total number of hotels in the Ungrouped hotel group, use the $count query parameter. To specify the number of hotels to return, use the $top query parameter. To page through all hotels in the group, use the $top and $skip query parameters.

NOTE: Use this call to page through hotels in a UI experience only. Do not use this call to download all hotels. To download all hotels, instead use the Reporting feature.

Response body: Contains a CollectionResponse object. The value field contains the list of Hotel objects.

Template parameters:
  • {subAccountId}—Set to the ID of the subaccount that contains the ungrouped hotel price ads to get.

SubAccounts('{subAccountId}')/Associations template

Verb Description
GET Gets a list of hotel and hotel group associations.

NOTE: By default, the list contains a maximum of 1,000 associations. To determine the total number of associations in the subaccount, use the $count query parameter. To specify the number of associations to return, use the $top query parameter. To page through all associations in a subaccount, use the $top and $skip query parameters.

Response body: Contains a CollectionResponse object. The value field contains the list of HotelAssociation objects.

Template parameters:
  • {subAccountId}—Set to the ID of the subaccount that contains the associations to get.

SubAccounts('{subAccountId}')/Associate template

Verb Description
POST Adds a list of hotel and hotel group associations to the subaccount.

Request body: Contains an AssociationCollection object. The HotelAssociation field contains a list with a maximum of 500 HotelAssociation objects. Each object associates a hotel with a hotel group.

You may associate a hotel with one hotel group only. By default, hotels are associated with the Ungrouped hotel group. To associate a hotel with a new hotel group, use this template. When you associate a hotel with a new hotel group, the service removes the previous association.

Response body: Contains a CollectionResponse object. The value field contains a list of HotelAssociation objects. The list contains only those associations that failed validation. The list is empty if there are no errors. The association's Errors field contains the list of reasons why the association failed.

Template parameters:
  • {subAccountId}—Set to the ID of the subaccount to add the associations to.

ReportJobs template

Verb Description
POST Adds a report request to the report queue.

Request body: Contains the ReportJob object that defines the report request that you're adding to the queue.

Response body: If the report request is successfully added to the queue, the body is an AddResponse object that contains the ID of the report job. Use the ID in subsequent GET requests to get the status of the report job (see the ReportJobs('{jobId}') template).

ReportJobs('{jobId}')

Verb Description
GET Gets the status of the specified report job.

Response body: Contains a ReportJob object. Use the Status field to determine when the job finishes. When the job is complete, use the URL in the Url field to download the report.

Template parameters:
  • {jobId}—The ID of the report job to get the status of. Set to the ID of the report job that your POST request returned.

$batch template

Verb Description
POST Sends a batch request that may contain a maximum of 500 requests. Read more

Request body: Contains a string of the individual requests.

Response body: Contains a string of the corresponding responses.

Query Parameters

The following are the query parameters that the request may specify.

Parameter Description
$count An OData parameter that determines whether the response includes an @odata.count field. Typically, you include this parameter when you request a list of entities, such as a list of hotel groups. The @odata.count field contains the total number of resource entities available, not those returned in the request. For example, if you set $top to 40, but 1,000 entities exist, @odata.count is set to 1,000, not 40. To include the count, set $count to true.
$filter An OData parameter that specifies a list of expressions used to filter the data.

NOTE: You may use the $filter parameter only with the /Associations resource. For more information, see Filtering hotel associations.
$select An OData parameter that specifies a comma-delimited list of the fields to include in the response. The field names are case sensitive. For example, to include the hotel's name, partner ID, and bid fields in the response, specify the following parameter:

$select=Name,PartnerHotelId,Bid
$skip An OData parameter that specifies the number of resource entities to skip before returning entities. The $skip value must be a multiple of $top. If you specify a value that is out of range, the response contains an empty set. Use $top and $skip to page through a list of resource entities.
$top An OData parameter that specifies the number of resource entities to return. The default value is 1,000 and the maximum value that you may specify is 5,000. Use $top and $skip to page through a list of resource entities.

Headers

The following are the request and response headers.

Header Description
Authorization Request header.

Set this header to a bearer OAuth access token. For example, "Authorization: Bearer QTkxRUFBRjEzOTUyNEIx...". For information about getting a token, see Getting Started.
Content-Type Request and response header.

The type of content in the body of the request or response. For POST and PATCH, set this header to application/json.
X-MS-RequestId Response header.

The ID of the log entry that contains the details of the request. You should always capture this ID if an error occurs. If you are not able to determine and resolve the issue, include this ID along with the other information that you provide the Support team.

Note

This API supports using OAuth access tokens only for authentication (see the Authorization header). You may not use the UserName and Password headers to specify legacy credentials.

This API does not require a developer token. If you include the DeveloperToken header, the API ignores it.

Resource Objects

The following are the resource objects used by the API.

Object Description
AddResponse Defines a response object for requests that add a resource.
AdsApiError Defines an error that occurred.
AdvanceBookingWindowMultiplier Defines the amount to adjust the base bid by if the user books the specified number of days in advance.
AssociationCollection Defines a collection of hotel associations.
Budget Defines the daily budget for hotel price ads in a subaccount.
CollectionResponse Defines a response object for requests that get a list of resources.
CheckinDayOfWeekMultiplier Defines the amount to adjust the base bid by if the user checks in on one of the specified weekdays.
DateTypeMultiplier Defines the amount to adjust the base bid by if the user searched for hotels using specific dates.
DeviceMultiplier Defines the amount to adjust the base bid by if the user is using one of the specified devices to search for hotels.
FixedBid Defines a fixed bid amount.
Hotel Defines a hotel ad.
HotelAssociation Defines the association between a hotel and a hotel group.
HotelGroup Defines a logical grouping of hotel price ads.
LengthOfStayMultiplier Defines the amount to adjust the base bid by if the user stays the specified number of nights or longer.
PercentageBid Defines a bid based on the percentage of the per night total room rate.
ReportJob Defines a report job.
SiteMultiplier Defines the amount to adjust the base bid by if the user is searching for hotels on one of the specified Bing sites.
SubAccount Defines the top-level hotel price ads grouping. You can think of this logically as a lodging campaign.
UserCountryMultiplier Defines the amount to adjust the base bid by if the user accesses one of the Bing domains.

Note

The response objects include a context field. Because this field may be suppressed in the future or the model may change you should not take a dependency on it. Taking a dependency on this field may break your code in the future.

AddResponse

Defines a response object for requests that add a resource.

Name Value Type
value The ID of the resource that you added. object

AdsApiError

Defines an error that occurred.

Name Value Type
Code A symbolic code that identifies the error. For a list of codes, see Error codes. String
Message A description of the error. String
Parameter The name of the object, field, or parameter that caused the error. String

AdvanceBookingWindowMultiplier

Defines the amount to adjust the base bid by if the user books the specified number of days in advance.

Name Value Type Add Update
Factor The percentage amount to adjust the base bid by. The valid range is 0.00 through 11.00. For example, if the fixed bid is $5 and the multiplier is 5, the final bid is $25. Using the same multiplier, if the percentage bid is 5% and the total room rate is $100, the final bid is $25. Double Required Optional
MinimumNumberOfDays The minimum number of days in advance of the booking. Apply the multiplier if the booking occurs in advance the specified number of days or longer. Integer Required Optional
@odata.type The object's type. This field is set to "#Model.AdvanceBookingWindowMultiplier". String Required Required

AssociationCollection

Defines a collection of hotel associations.

Name Value Type Add Update
HotelAssociations The list of hotel and hotel group associations. The list may contain a maximum of 500 associations. HotelAssociation[] Required N/A

Bid

Defines the base class for a bid.

Do not specify this class, instead specify the FixedBid or PercentageBid class.

Name Value Type Add Update
Amount The dollar bid amount. For details about the valid bid range for your market, see the Currency Value table in the Currencies topic. The customer's account specifies the currency used. Double Required Optional

Budget

Defines the daily budget for hotel price ads in a subaccount.

Name Value Type Add Update
Amount The daily budget amount. For details about valid budgets for your market, see the Currency Value table in the Currencies topic. The customer's account specifies the currency used for the budget. Double Required Optional

CheckinDayOfWeekMultiplier

Defines the amount to adjust the base bid by if the user checks in on one of the specified weekdays.

Name Value Type Add Update
DaysOfWeek A list of weekdays. Apply the multiplier if the user is checking on one of the specified days. The following are the possible case-sensitive values.

  • Monday
  • Tuesday
  • Wednesday
  • Thursday
  • Friday
  • Saturday
  • Sunday
String[] Required Optional
Factor The percentage amount to adjust the base bid by. The valid range is 0.00 through 10.00. For example, if the fixed bid is $5 and the multiplier is 5, the final bid is $25. Using the same multiplier, if the percentage bid is 5% and the total room rate is $100, the final bid is $25. Double Required Optional
@odata.type The object's type. This field is set to "#Model.CheckinDayOfWeekMultiplier". String Required Required

CollectionResponse

Defines a response object for requests that get a list of resources.

Name Value Type
value The list of requested resources. Depending on the request, the list contains one of the following types of objects:For example, if you request a list of hotel groups, value contains a list of HotelGroup objects. object[]
@odata.count The total number resource entities available, not the number of entities in Value. The response includes this field only if you include the $count query parameter in the request.

DateTypeMultiplier

Defines the amount to adjust the base bid by if the user searched for hotels using specific dates.

Name Value Type Add Update
DateType The type of date used in the search. The following are the possible case-sensitive values.

  • Default—The user didn't search for hotels using specific dates
  • Selected—The user searched for hotels using specific dates.
String[] Required Optional
Factor The percentage amount to adjust the base bid by. The valid range is 0.00 through 10.00. For example, if the fixed bid is $5 and the multiplier is 5, the final bid is $25. Using the same multiplier, if the percentage bid is 5% and the total room rate is $100, the final bid is $25. Double Required Optional
@odata.type The object's type. This field is set to "#Model.DateTypeMultiplier". String Required Required

DeviceMultiplier

Defines the amount to adjust the base bid by if the user is using one of the specified devices to search for hotels.

Name Value Type Add Update
DeviceTypes A list of device types. Apply the multiplier if the user is using the device type to search for hotels. The following are the possible case-sensitive values.

  • Desktop
  • Mobile
  • Tablet
String[] Required Optional
Factor The percentage amount to adjust the base bid by. The valid range is 0.00 through 10.00. For example, if the fixed bid is $5 and the multiplier is 5, the final bid is $25. Using the same multiplier, if the percentage bid is 5% and the total room rate is $100, the final bid is $25. Double Required Optional
@odata.type The object's type. This field is set to "#Model.DeviceMultiplier". String Required Required

FixedBid

Defines a fixed bid amount.

Name Value Type Add Update
Amount The fixed dollar bid amount. For details about the valid bid range for your market, see the Currency Value table in the Currencies topic. The customer's account specifies the currency used.

The bid amount is the per-night bid. For example, if the bid is $3.50 and the itinerary is for a 3-night stay, the final bid is $10.50.
Double Required Optional
@odata.type The object's type. This field is set to "#Model.FixedBid". String Required Required

Hotel

Defines a hotel ad.

Name Value Type Add Update
Bid The base bid. Microsoft uses this bid in the auction unless you specify one or more multipliers (see BidMultipliers). If you don't specify a bid, the hotel inherits the bid from the hotel group or subaccount, in that order. When getting a hotel, if the hotel doesn't specify a bid, this field contains the inherited bid.

The following are the types of bids that you may specify.To pause the hotel, specify a percentage bid and set its bid amount to zero (0).

To remove the hotel's bid, set Bid to null.
object N/A Optional
BidMultipliers A list of multipliers to apply to the base bid. Microsoft applies the multipliers to the base bid and uses the adjusted bid in the auction. If the hotel does not specify a bid, the multipliers adjust the inherited bid.

If you don't specify multipliers, the hotel inherits them from the hotel group or subaccount, in that order. When getting a hotel, if the hotel doesn't specify multipliers, this field contains the inherited multipliers.

If the hotel specifies multipliers and you want to remove them, set BidMultipliers to an empty array.

The following are the types of multipliers that you may specify.
object[] N/A Optional
BidMultiplierSource The source of the bid multipliers. The following are the possible values.
  • SubAccount
  • HotelGroup
  • Hotel
For example, if the hotel and hotel group didn't specify multipliers, the hotel inherits the multipliers from the subaccount. In this case, this field is set to SubAccount.
String N/A Read-only
BidSource The source of the bid. The following are the possible values.
  • SubAccount
  • HotelGroup
  • Hotel
For example, if the hotel specifies a bid, this field is set to Hotel.
String N/A Read-only
CountryCode The two-letter ISO 3116 county code of the country where the hotel is located. The country is the same country that you specified for the hotel in your hotel feed file. String Read-only Read-only
Id A system-generated ID that uniquely identifies the hotel. String N/A Required
Name The name of the hotel. The name is the same name you specified in your hotel feed file. String N/A Read-only
PartnerHotelId The ID that you used to identify the hotel in the hotel feeds file. String N/A Read-only
Status The status of the hotel entity. The following are the possible values.
  • Active—The hotel is not deleted and may be updated.
  • Deleted—The user deleted the hotel. Users may delete hotels by using the UI only.
String N/A Read-only

HotelAssociation

Defines the association between a hotel and a hotel group.

The Update column contains N/A values because there's no HTTP update operation. To update a hotel's association, use an Add (POST) operation. See the Associate template.

Name Value Type Add Update
Errors The list of reasons why the association failed validation.

The response includes this field only if the association failed validation when you tried to add it.
AdsApiError Read-only N/A
HotelGroupId The ID of the hotel group to associate the hotel with. String Required N/A
HotelGroupName The name of the hotel group. String Read-only N/A
HotelId The ID of the hotel to associate with the specified hotel group (see HotelGroupId). You may associate the hotel with one hotel group only.

By default, all hotels are associated with a hotel group whether it's a user-defined group or the default Ungrouped hotel group. To move a hotel from one group to another, post a new association that specifies the hotel ID and new hotel group ID; the service removes the prior association.
String Required N/A
HotelName The name of the hotel. String Read-only N/A
PartnerHotelId The ID that you used to specify the hotel in the hotel feeds file. String Read-only N/A

HotelGroup

Defines a logical grouping of hotels.

Name Value Type Add Update
Bid The base bid that hotels in the group inherit if they don't specify a bid. For usage, see Bid in the Hotel object.

If you don't specify a bid, the group inherits the bid from the subaccount. When getting a hotel group, if the group doesn't specify a bid, this field contains the inherited bid.

The following are the types of bids that you may specify.To pause all hotels in the group, specify a percentage bid and set its bid amount to zero (0).

To remove the group's bid, set Bid to null.
object Optional Optional
BidMultipliers A list of multipliers that hotels in the group inherit if they don't specify multipliers. For usage, see BidMultipliers in the Hotel object.

If you don't specify multipliers, the group inherits them from the subaccount.

If the hotel group specifies multipliers and you want to remove them, set BidMultipliers to an empty array.

The following are the types of multipliers that you may specify.
object[] Optional Optional
BidMultiplierSource The source of the bid multipliers. The following are the possible values.
  • SubAccount
  • HotelGroup
For example, if the hotel group didn't specify multipliers, the hotel group inherits the multipliers from the subaccount. In this case, this field is set to SubAccount.
String Read-only Read-only
BidSource The source of the bid. The following are the possible values.
  • SubAccount
  • HotelGroup
For example, if the hotel group specifies multipliers, this field is set to HotelGroup.
String Read-only Read-only
HotelAssociationCount The number of hotels associated with the hotel group. Unsigned Integer Read-only Read-only
Id A system-generated ID that uniquely identifies the group. String Read-only Required
Name The name of the group. The name may contain a maximum of 256 characters. String Required Read-only
Status The status of the hotel group entity. The following are the possible values.
  • Active—The hotel group is not deleted and may be updated.
  • Deleted—The user deleted the hotel group. Users may delete hotel groups by using the UI only.
String Read-only Read-only

LengthOfStayMultiplier

Defines the amount to adjust the base bid by if the user stays the specified number of nights or longer.

Name Value Type Add Update
Factor The percentage amount to adjust the base bid by. The valid range is 0.00 through 10.00. For example, if the fixed bid is $5 and the multiplier is 5, the final bid is $25. Using the same multiplier, if the percentage bid is 5% and the total room rate is $100, the final bid is $25. Double Required Optional
MinimumNumberOfNights The minimum number of nights required to apply the multiplier. Apply the multiplier if the user is staying the specified number of nights or longer. Valid values are 1 through 14. Integer Required Optional
@odata.type The object's type. This field is set to "#Model.LengthOfStayMultiplier". String Required Required

Multiplier

Defines the base class for a multiplier.

Do not specify this class, instead specify one of the multiplier classes such as UserCountryMultiplier.

Name Value Type Add Update
Factor The percentage amount to adjust the base bid by. The valid range is 0.00 through 10.00. For example, if the fixed bid is $5 and the multiplier is 5, the final bid is $25. Using the same multiplier, if the percentage bid is 5% and the total room rate is $100, the final bid is $25. Double Required Optional

PercentageBid

Defines a bid based on the percentage of the per night total room rate, including taxes and other fees.

Name Value Type Add Update
Amount The percentage bid amount. The valid range is 0 through 1,000. For example, to bid 5 percent of the room's total rate, set Amount to 5.0.

The bid amount is the per-night bid. For example, if the bid is 3%, the total room rate is $99, and the itinerary is for a 3-night stay, then the final bid is $8.91.
Double Required Optional
@odata.type The object's type. This field is set to "#Model.PercentageBid". String Required Required

ReportJob

Defines a report job.

Name Value Type Add
Columns The list of columns to include in the report. The order that the report includes them is undetermined. The reporting service may also interleave other relevant columns not explicitly requested. The column names are case sensitive. For a list of column names, see Report Columns for the report type you're requesting (for example, for PerformanceReport, see Performance report columns). The columns must include at lease one dimension-type column and one metric-type column. String[] Required
Compression The type of compression to apply to the report. The following are the possible case-insensitive values.
  • ZIP
The default is no compression.
String Optional
EndDate The UTC end date of the report in the form YYYY-MM-dd. The month and day must contain two digits. For example, instead of 2018-1-4 use 2018-01-04.

The report contains data that falls within the start and end dates, inclusively. The end date must be on or later than the start date.

NOTE: When polling to get the status of the job, the service returns the date in the form YYYY-MM-ddTHH:mm:ssZ (for example, 2017-10-30T00:00:00Z).
String Required
Filter The OData filter string to apply. The maximum length of the filter string is 1,000 characters. For information about using filters, see Filtering report data.

NOTE: The report column names and enumeration values that you specify are case sensitive. For example, you must specify DeviceType instead of devicetype, and Desktop instead of desktop.
String Optional
Format The format of the contents in the report. The following are the possible case-insensitive values.
  • CSV
The default is CSV.
String Optional
HotelGroupId The ID of the hotel to limit the report to. To set this field, you must also set SubaccountId. String Optional
Id An ID that uniquely identifies the report job. String Read-only
IncludeNonPerformingHotels A Boolean value that determines whether the report includes hotels that haven't received impressions during the reporting period. To include non-performing hotels, set this field to true; otherwise, false. The default is false.

For limitations about the columns that you may specify when requesting non-performing hotels, see Including non-performing hotels in the report.
Boolean Optional
ReportType The type of entity or report to download. The following are the possible case-sensitive values. String Required
StartDate The UTC start date of the report in the form YYYY-MM-dd. The month and day must contain two digits. For example, 2018-1-4 must be 2018-01-04. The earliest date that you may specify is three years from today.

NOTE: When polling to get the status of the job, the service returns the date in the form YYYY-MM-ddTHH:mm:ssZ (for example, 2017-10-30T00:00:00Z).
String Required
Status The status of the report job. The following are the possible values.
  • Completed—The report job completed successfully. Use the URL in the Url field to download the report.
  • Failed—The job failed for some reason. In case the error is a transient error, you may want to resubmit the job. If the job fails again, capture the request ID in the X-MS-RequestId header and contact support.
  • InProgress—The service is in the process of building the report.
  • PendingExecution—The report request is queued
String Read-only
SubaccountId The ID of the subaccount to limit the report to. String Optional
Url The URL of the report to download. The service provides the URL when Status is Completed. The URL is valid for five (5) minutes from the time you get a report job with Status set to Completed. If the URL expires, send a GET request to get the status of the job again and a new URL.

SiteMultiplier

Defines the amount to adjust the base bid by if the user is searching for hotels on one of the specified Bing sites.

Name Value Type Add Update
Factor The percentage amount to adjust the base bid by. The valid range is 0.00 through 10.00. For example, if the fixed bid is $5 and the multiplier is 5, the final bid is $25. Using the same multiplier, if the percentage bid is 5% and the total room rate is $100, the final bid is $25. Double Required Optional
Sites A list of sites. Apply the multiplier if the user is using the specified site to search for hotels. The following are the possible case-sensitive values.
  • LocalUniversal—The user is searching for hotels on Bing.com.
  • MapResults—The user is searching for hotels on Bing.com/maps.
  • PropertyPromotionAd—The first results page shown in the maps search.
String[] Required Optional
@odata.type The object's type. This field is set to "#Model.SiteMultiplier". String Required Required

SubAccount

Defines the top-level hotel price ads grouping. You can think of this logically as a lodging campaign.

Name Value Type Add Update
Bid The base bid that hotels inherit if they, or the group they belong to, don't specify a bid. For usage, see Bid in the Hotel object.

The following are the types of bids that you may specify.To pause all hotels in the subaccount, specify a percentage bid and set its bid amount to zero (0).
object Required Optional
BidMultipliers A list of multipliers that hotels inherit if they, or the group they belong to, don't specify multipliers. The default is 0. For usage, see BidMultipliers in the Hotel object.

If the subaccount specifies multipliers and you want to remove them, set BidMultipliers to an empty array.

The following are the types of multipliers that you may specify.
object[] Optional Optional
DailyBudget The daily budget to spread through-out the day.

Setting the budget to 0 prevents hotels in the subaccount from serving.
Budget Required Optional
HotelAssociationCount The number of hotels associated with hotel groups in the subaccount. Unsigned Integer Read-only Read-only
Id A system-generated ID that uniquely identifies the subaccount. String Read-only Required
MaximumBid The not-to-exceed bid amount. FixedBid Optional Optional
Name The name of the subaccount. The name may contain a maximum of 128 characters. String Required Read-only
Status The status of the subaccount entity. The following are the possible values.
  • Active—The sub account is not deleted and may be updated.
  • Deleted—The user deleted the subaccount. Users may delete subaccounts by using the UI only.
String Read-only Read-only

UserCountryMultiplier

Defines the amount to adjust the base bid by if the user accesses one of the Bing domains.

Name Value Type Add Update
Countries A list of two-letter ISO 3116 country/region codes. For a list of possible country/region codes, see Allowed country/region codes.

Apply the multiplier if the user accesses the Bing domain with the specified country code. For example, if the list includes US and DE, Microsoft uses the multiplier if the user uses Bing.com with the us or de country code (for example, bing.com?cc=de).
String[] Required Optional
Factor The percentage amount to adjust the base bid by. The valid range is 0.00 through 10.00. For example, if the fixed bid is $5 and the multiplier is 5, the final bid is $25. Using the same multiplier, if the percentage bid is 5% and the total room rate is $100, the final bid is $25. Double Required Optional
@odata.type The object's type. This field is set to "#Model.UserCountryMultiplier". String Required Required

HTTP status codes

The requests may return the following HTTP status codes.

Status code Description
200 Successfully retrieved the resource.
201 Successfully added the resource.
204 Successfully updated or deleted the resource.
400 Bad request. Either a query parameter value is not valid or content in the request body is not valid.
401 Unauthorized. The user's credentials are not valid.
403 Forbidden. The download URL for the report has expired. You have seven days from the time you get the URL to download the report. If the URL expires, you must submit a new job request.
404 Not found.
429 Too many requests. The API limits the number of requests you may make per minute. The limit is not documented and is subject to change. The API returns this status code if you exceed the limit. You must wait 60 after receiving this error before resending the request.
500 Server error.

Error codes

Reporting error codes

Error code Description
CompressionTypeNotSupported The Compression field is set to a value this is not supported. For a list of supported compression algorithms, see Compression.
DuplicateValues The Columns field contains the same column name more than once.
FilterTooLong The OData filter string that you set Filter to is too long. For the allowed maximum length, see Filter.
FormatVersionNotSupported The Format field is set to a value this is not supported. For a list of supported formats, see Format.
InvalidDateRange The reporting period that you specified is not valid. For information about specifying a valid date range, see the StarteDate and EndDate fields.
InvalidReportName The ReportType field is set to a report name that is not valid. For a list of valid report names, see ReportType.
InvalidSelect One or more of the columns that you specified are not valid. Compare the column names that you used to those documented for the report you requested. Remember, the names are case sensitive.

Country or region codes

You may use the following country/region codes to set the Countries field of UserCountryMultiplier.

Country/region name Country/region code
Afghanistan AF
Albania AL
Algeria DZ
Andorra AD
Angola AO
Anguilla AI
Antarctica AQ
Antigua and Barbuda AG
Antilles (Netherlands) AN
American Samoa AS
Argentina AR
Armenia AM
Aruba AW
Australia AU
Austria AT
Azerbaijan AZ
Bahamas BS
Bahrain BH
Bangladesh BD
Barbados BB
Belarus BY
Belgium BE
Belize BZ
Bermuda BM
Benin BJ
Bhutan BT
Bolivia BO
Bosnia and Herzegovina BA
Botswana BW
Brazil BR
Brunei BN
Bulgaria BG
Burkina Faso BF
Burundi BI
Cabo Verde CV
Cambodia KH
Cameroon CM
Canada CA
Cayman Islands KY
Central African Republic CF
Chad TD
Chile CL
China CN
Christmas Island CX
Cocos Islands CC
Colombia CO
Comoros KM
Congo CG
Congo (the Democratic Republic of the) CD
Cook Islands CK
Costa Rica CR
Côte d'Ivoire CI
Croatia HR
Cyprus CY
Czech Republic CZ
Denmark DK
Djibouti DJ
Dominica DM
Dominican Republic DO
Ecuador EC
Egypt EG
El Salvador SV
Equatorial Guinea GQ
Eritrea ER
Estonia EE
Eswatini SZ
Ethiopia ET
Falkland Islands FK
Faroe Islands FO
Fiji FJ
Finland FI
France FR
French Guiana GF
French Polynesia PF
Gabon GA
Gambia GM
Georgia GE
Germany DE
Ghana GH
Gibraltar GI
Greece GR
Greenland GL
Grenada GD
Guadeloupe GP
Guam GU
Guatemala GT
Guinea GN
Guinea-Bissau GW
Guyana GY
Haiti HT
Holy See VA
Honduras HN
Hong Kong SAR HK
Hungary HU
Iceland IS
India IN
Indonesia ID
Iraq IQ
Ireland IE
Israel IL
Italy IT
Jamaica JM
Japan JP
Jordan JO
Kazakhstan KZ
Kenya KE
Kiribati KI
Korea KR
Kuwait KW
Kyrgyzstan KG
Lao People's Democratic Republic LA
Latvia LV
Lebanon LB
Lesotho LS
Liberia LR
Libya LY
Liechtenstein LI
Lithuania LT
Luxembourg LU
Macao SAR MO
Madagascar MG
Malawi MW
Malaysia MY
Maldives MV
Mali ML
Malta MT
Marshall Islands MH
Martinique MQ
Mauritania MR
Mauritius MU
Mayotte YT
Mexico MX
Micronesia FM
Moldova MD
Monaco MC
Mongolia MN
Montenegro ME
Montserrat MS
Morocco MA
Mozambique MZ
Myanmar MM
Namibia NA
Nauru NR
Nepal NP
Netherlands NL
New Caledonia NC
New Zealand NZ
Nicaragua NI
Niger NE
Nigeria NG
Niue NU
Norfolk Island NF
Norway NO
North Macedonia MK
Northern Mariana Islands MP
Oman OM
Pakistan PK
Palau PW
Palestinian Authority PS
Panama PA
Papua New Guinea PG
Paraguay PY
Peru PE
Philippines PH
Pitcairn PN
Poland PL
Portugal PT
Puerto Rico PR
Qatar QA
Réunion RE
Romania RO
Russian Federation RU
Rwanda RW
Saint Helena, Ascension and Tristan da Cunha SH
Saint Kitts and Nevis KN
Saint Lucia LC
Saint Pierre and Miquelon PM
Saint Vincent and the Grenadines VC
San Marino SM
São Tomé and Príncipe ST
Saudi Arabia SA
Senegal SN
Serbia RS
Seychelles SC
Sierra Leone SL
Singapore SG
Slovakia SK
Slovenia SI
Spain ES
Solomon Islands SB
Samoa WS
Somalia SO
South Africa ZA
Sri Lanka LK
Suriname SR
Sweden SE
Switzerland CH
Taiwan TW
Tajikistan TJ
Tanzania TZ
Thailand TH
Timor-Leste TL
Togo TG
Tokelau TK
Tonga TO
Trinidad and Tobago TT
Tunisia TN
Türkiye TR
Turkmenistan TM
Turks and Caicos Islands TC
Tuvalu TV
Uganda UG
Ukraine UA
United Arab Emirates AE
United Kingdom GB
United States US
Uruguay UY
Uzbekistan UZ
Vanuatu VU
Venezuela VE
Viet Nam VN
Virgin Islands (British) VG
Virgin Islands (U.S.) VI
Wallis and Futuna WF
Yemen YE
Zambia ZM
Zimbabwe ZW