Get started with the Hotel API

Do you have your Bing Ads credentials?

To use the Hotel API, you must have a Bing Ads account and a Microsoft account. To get a Bing Ads account, go to If you're not signed in to your Microsoft account, you'll be redirected to sign in to your Microsoft account or sign up for a Microsoft account. After signing in, you'll have the option to Sign up for a new Bing Ads account. Select the sign-up option and continue with the sign-up process.

Unlike the other Bing Ads APIs, the Hotel API does not use a developer token. The API ignores it if you include it.

Authenticating your credentials

The Hotel API uses the OAuth authentication scheme. For details about authenticating Microsoft account credentials using OAuth, see Authentication with OAuth.

You can use the Bing Ads SDK for .NET, Java, or Python to authenticate Microsoft account credentials. For details about using the SDK to get the access token, see C# | Java | Python. (You should only use the SDK to get the access token if you're using the SDK for Bing Ads campaigns, too. Otherwise, it may not be worth the overhead of installing the SDK.)

If you choose not to use the Bing Ads SDK to get the tokens, see OAuth C# Example for an example OAuth implementation.


If you use the API from a service, you must write a simple app to get the refresh token for a user that has permissions to access the hotel data. You will call the app you write once just to get the refresh token. After getting the refresh token, store it in secure storage that's accessible by your service.

Follow the steps outlined in Authentication with OAuth for getting the client ID for your app and for implementing the code grant flow. For an example of a simple console app that you use to get the tokens, see OAuth C# Example.

After getting the initial refresh token, the following shows the basic calling sequence that you'll make to get the access token that you set the Authorization header to.

  • Get the refresh token from secured storage
  • Send an HTTP POST request to
    • The following shows the body of the POST (the parameters are separated for readability):
  • Get the access token, refresh token, and access token expiration from the response
  • Set a timer that expires just before the access token expires
  • Set the Authorization header to the access token
  • Store the new refresh token in secured storage
  • When the expiration timer expires, repeat the process

You should only get a new access token just before the current token expires. Do not get a new access token for each call.

If you receive an invalid_grant error, your refresh token is no longer valid. You will need to run your app again to provide consent and get a new refresh token.

Authenticating your credentials in sandbox

For the sandbox environment, the following are the endpoints you must use to get Microsoft accounts and your application's client ID. Wherever you see endpoints mentioned in Authentication with OAuth, substitute them with the following SI endpoints.

  •—Endpoint for Bing Ads sandbox
  •—Endpoint for getting a sandbox Microsoft account
  •—Endpoint for sandbox email used when getting a sandbox Microsoft account
  •—Endpoint for getting a sandbox client ID
  •—Endpoint for OAuth requests

Getting sandbox credentials

Get a sandbox account if you don't already have one

You use the sandbox environment to test your application before putting it in production. Use the following steps to get a sandbox account.

  1. Open a browser and navigate to
  2. Click Sign up for Bing Ads or Sign up now
  3. Fill out the Create Account form
  4. For Import/Create Campaign, click Skip campaign creation
  5. For Go Live, click Skip payment information

Send an invite so you can create an MSA (read step 5 carefully)

The above steps create a Bing Ads legacy account. To use Hotel Ads API, you need a sandbox Microsoft account (MSA). To get an MSA that you can use in sandbox, you need to invite a user to work on your account. The following steps show how to invite a user to work on your account.

  1. In Bing Ads, click your user name (upper right corner)
  2. Click Accounts & Billing
  3. Click Users
  4. Click Invite user
  5. Enter the email address of the user to invite. The email address must use (for example,


You may send invites to email accounts only. You may not send invites to any other domain, even if the account is linked to an email account. If you try to send an invite to another domain (for example,, the BingAds UI will show the invite as pending indefinitely (the invite is never sent).

  1. Click Send

Create an MSA to use with Hotel Ads API (read steps 3 and 5 carefully)

Bing Ads sends an email invite to the user. If the invite doesn’t show up in the inbox, check the Junk Email folder. It may take a couple of minutes to receive the invite. The following steps show how to accept the invitation.

  1. Open the email from Bing Ads with subject line, Invitation to Bing Ads
  2. Click the embedded link
  3. Select Create a new email address to create an MSA. You must create a new MSA; you may not use an existing MSA.
  4. Click Next
  5. Enter an MSA email address. The email server must be (for example,


Sandbox supports MSAs created using an email account only. You may not use an email account. Also, you may not use an email account from another email service (for example, even if the account is linked to an or email account.

  1. Finish the work flow by specifying the rest of your user information
  2. Exit Bing Ads after completing the MSA process.

After Bing creates the account, you may use the MSA with the Hotel Ads API to create hotel ad campaigns.


The MSA signup process returns you to the SI Bing Ads user interface ( After completing the MSA process, sign out of the SI interface. To access your Hotel Ads Campaigns using the Bing Ads user interface in sandbox, go to and sign in using your new MSA email address.

Where do you use your credentials?

After getting the user's OAuth access token, set the Authorization header to it.

var headers = new WebHeaderCollection();
headers.Add(HttpRequestHeader.Authorization, "Bearer " + tokens.AccessToken);

For information about the Authorization header and other headers that the request and response may contain, see Headers.


The Hotel API uses the standard Authorization header. If you use the Bing Ads SDK to get the OAuth tokens, you'll use the SDK to get the tokens and then set the Authorization header.

Do you have your hotel feed set up?

Before using the Hotel API, you should have your hotel feeds set up. For details, see: