Using this API

Use the Hotel SOAP API to Search, Check Policies and Book hotels with over 100 different suppliers all over the world.

The Hotel SOAP API has the following methods to be consumed, in this order:

• • SearchAvailability: used to define what kind of room or rooms you want, which Checkin date, number of nights and how you want to see your results.

  • GetCancellationPolicies: used to check which are the Cancellation Policies for the chosen room.

  • DoBooking: used to confirm a booking, send passenger's and payment informations. Read more about the possible status here.

  • CancelBooking: used to cancel a booking.

Below you will find further information about the rules, possibilities, points of attention and most important properties for each method. For a list of all of our properties, please check each method's reference page.

Hotel SOAP API endpoint

Each Operator will have its own instance of the Cangooroo Booking Engine and, with that, each will have its own endpoint. Unless specified otherwise, your Operator's endpoint will curently be:

• • https://ws-[OPERATOR].cangooroo.net/ws/2013/hotel_l.asmx

Please note the words in BOLD on the example above since those will vary depending on the Operator you're integrating against.

Search Availability

This is where everything begins. The Search Availability Request is where you will pass your Credentials, define what kind of rooms and the quantity of rooms you want, the Checkin date, number of nights and how you want us to return you your result.

To see all properties contained in the Search Availability Request and Response, please refer to this reference page.

Search Availability Request

Our SearchAvailability Request is pretty simple and below you will find the most common usage of this method as well as some examples for the most Frequently Asked Questions we have.

Credentials

The credentials tag is fairly simple and only has the UserName and the Password as shown below:

The UserName tag is where you're supposed to put in the UserName given you by the Operator. While the Password is where you're supposed to insert the Password given you by the Operator.

Criteria

The Criteria section is where you define what are you looking for and below you will find the explanation for all the sections and most important properties.

Rooms and SearchRoom

The <Rooms> tag is a list that expect 1 or many <SearchRoom> tags, which means that for every different type of room you should send a different <SearchRoom> tag.

For example, to search for one room for one adult, you should do this:

The composition above will look for one room ( <Quantity>1</Quantity> ) that accepts one adult ( <QtyAdults>1</QtyAdults> ).

Now, to search for two rooms ( <Quantity>2</Quantity> ) that will accept one adult each ( <QtyAdults>1</QtyAdults> ), this is what you should do:

If you want to search for two rooms that will accept different amounts of adults like one adult in one room, two adults in the other, you should do this:

Note from the example above that the <Quantity> tag defines how many rooms you're looking for with the quantity of adults defined by the <QtyAdults> tag.

And lastly, to look for a room with children, you must specify the ages of the children within the <AgeOfTheChildrens> tag. For example, to look for one room for two adults and two children you should send:

Is important to understand the difference between the <Quantity> tag and the number of rooms you're searching for. What determines the number of rooms you're looking for in total is the number of <SearchRoom> tags that you provide us with, while the <Quantity> tag is always considered with the <QtyAdults> tag to decide the quantity of rooms for that quantity of adults.

CityId

The <CityId> tag is where you should send us the Destination Id of the City, Point of Interest or Neighborhood you want Cangooroo's API to search. You can learn more about how to obtain our Destinations Ids by reading about our Commons API.

CheckInDate and NumberOfNights

The <CheckInDate> tag defines the checkin date of the booking you want to do while the <NumberOfNights> defines how long the stay will be. For example, if you want to confirm a booking for 25 of december of 2025 that will last for 6 nights, you must send us:

It is also very important to remember to never send us any Timezone information. You should build your Request regardless of the Timezone from where you are and to where your passenger will go.

AccomodationSearchType and ReturnRoomOnRequest

The <AccomodationSearchType> tag is an mandatory ENUM with the possible values (Hotel or Home). Cangooroo's Hotel SOAP API allows you to look for both of them but most Operators will only have Hotel Suppliers.

To find out if you will have to search for Homes as well, please get in touch with your Operator.

The <ReturnRoomOnRequest> tag is a boolean and determines if (TRUE) you will work with room rates that aren't guaranteed by the supplier or (FALSE) if you only want rates that are 100% guaranteed.

Both of these tags will depend largely of your Operator's business strategy and although is important to know what each of them means, the correct way to work with them will depend on the Operator's strategy.

As an example, to search for a Hotel with guaranteed rates you should send us:

Mandatory and Optional properties

The list above explained all the mandatory properties in our Search Availability Request. To see all the optionals properties as well and understand what each of them does, please refer to our reference page.

Search Availability Response

Our SearchAvailability Response will hold all the results given your Criteria, separated by Hotels ( <HotelResult_f> ) and Rooms in each Hotel ( <RoomResult_g> ). Below you will find the most important sections and properties and to see all the properties and what each of them mean, please see our reference page.

Token and information about the number of results

The <Token> tag is extremely important, as explained in our Services page. You will need this Token in order to confirm your booking and this information should be carried with each following Requests you make.

A Token will always be unique and the combination of Token + Credentials + expiration time guarantees that we will never have matching results stored within our servers.

Tags such as <NumberOfTotalResults>, <NumberOfResultsAfterFilter> and <NumberOfResultsOnThisResp> will give you information about the whole number of results we found, how many of them were shown to you after any filter you used - if any - and lastly the quantity of results in this single Response.

When your search gives you larger sets of results, those can affect your application's performance and in those occasions, you will have to work with filters and pagination of our results. For more information on how to do this, please see our reference page.

Hotels and Rooms

The SearchAvailability Response will always be a composition of multiple Hotels with multiple Rooms each, thus creating a list within a list. That is important to keep in mind since you will probably have to iterate through each of them to go over all the results we returned.

Inside those lists, the <HotelId> tag and the <RoomId> tag must be mentioned since they behave very differently. While the <HotelId> is an integer value and will hardly change, the <RoomId> is a string value and will change constantly since it is the encrpyted result of multiple information. Therefore, never assume the Room Id format or size nor map it because it is a dynamic value.

Other properties in the SearchAvailability Response

We return a lot of information for each result. The decision of which of them you will use and how will depend largely on your Operator's strategy and your integration purpose. To see a full list of all the properties, please check our reference page.

Get Cancellation Policies

The Get Cancellation Policies is the method you should call after receiving the SearchAvailability Response and after you've selected the room, or rooms, you wish to book. This is a mandatory step for our booking process, which means that you will must make this call before attempting to confirm your booking.

It's important to be aware that many Suppliers work with cached information to decrease their response time when replying to availability requests, that is why some values might change from the Search Availability Response to the Get Cancellation Policies Response such as price, rate information and other properties. That is why is important that you compare, verify and update your information and properly notify your user in case of any changes.

To see all properties contained in the Get Cancellation Policies Request, please refer to our reference page.

Get Cancellation Policies Request

The GetCancellationPolicies Request is pretty direct and simple and below you will find the most Frequently Asked Questions we have about it.

Credentials

The credentials tag is the same as required on the SearchAvailability Request with a UserName and a Password as shown below:

The UserName tag is where you're supposed to put in the UserName given you by the Operator. While the Password is where you're supposed to insert the Password given you by the Operator.

Token

As stated before, the Token you received on the SearchAvailability Response is extremely important because it is this information that binds the booking process together. To learn more about the Token, you can check our Services page.

You must pass the Token on the <Token> tag as shown below, since the combination of your Token + Credentials + expiration time will guarantee that you will have access to the rooms returned to you on the SearchAvailability Response.

Hotel Id and Room Ids

Pretty straightforward, the <HotelId> tag is where you must pass the Id of the desired hotel for the room or rooms you've chosen from the SearchAvailability Response before. Is important to note that you can only call the GetCancellationPolicies method for one Hotel Id at a time, meaning that you can't have more than one Hotel Id on the same Request.

The <RoomIds> tag is a String list, meaning that you can request the cancellation policies for more than one Room at a time, provided that they're all rooms in the same Hotel. However, you should only request the exact quantity of rooms that you searched for, which means that if you're trying to book 2 rooms, you should pass 2 and only 2 room id; if you're trying to book 1 room, you should pass 1 room id.

Despite the <RoomIds> list being opened to accept multiple room ids, is extremely important that you request only the correct quantity of rooms on each GetCancellationPolicies Request given that requesting a different number might trigger unexpected behavior and errors.

In order to request the Cancellation Policies for other rooms from your Search Availability Result, you must do so in a new Get Cancellation Policies request. Essentially you can make many different GetCancellationPolicies requests, but all of them must have the exact quantity of rooms you searched for.

Get Cancellation Policies Response

Example: 1 adult, 1 room

Rules:

• You can't send pax with same names in the method doBooking!

• In getCancellationPolicies method:

  • since a lot of suppliers works with cache in search availability method to decrease response time, sometimes the price, cancellation policies and other properties may change values between searchAvailability and getCancellationPolicies. Because of that you have always to update all the values with getCancellationPolicies response.

  • in getCancellationPoliciesReponse you will see a tag called "HotelInfo". This tag returns the hotel name, hotel address direct from the supplier. It's mandatory to show this new informations to your client.

<HotelInfo>

<CityId>1003944</CityId>

<HotelName>Hampton Inn Miami Airport East</HotelName>

<Address>3449 Northwest 42 Avenue</Address>

<HotelCategory xsi:nil="true"/>

<HotelId>1299244</HotelId>

<LastUpdate xsi:nil="true"/>

</HotelInfo>

Certification process

Please refer to the following file to review the tests done in the certification process.

• Certification process (Portuguese).