Hotel
Using this API
Use the Hotel Rest API to Search, Check Policies and Book hotels with over 100 different suppliers all over the world.
The Hotel Rest API has the following methods to be consumed, in this order:
Search: 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.
GetPaymentPolicies: 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.
GetServiceDetails: Serves to view the details of your booking.
The API works with Json in its requests and responses, so text parameters can be identified by placing double quotation marks ("example"), Boolean numbers and parameters can be sent normally.
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.
*Note that in the answers, some fields (usually the observation fields and more information) have HTML tags to make organizing the text easier.
Hotel API endpoint
Each method will have its own instance of the Cangooroo Booking Engine and, with that, each one will have its own endpoint. Unless otherwise specified, the endpoints of the Hotel services will be:
{{URL}}/ws/Rest/Hotel.svc/Search
{{URL}}/ws/Rest/Hotel.svc/GetCancellationPolicies
{{URL}}/ws/Rest/Hotel.svc/Booking
{{URL}}/ws/Rest/Hotel.svc/Cancel
{{URL}}/ws/Rest/Hotel.svc/GetServiceDetails
*Note the BOLD words in the example above, since they vary depending on the method you will be using.
Search
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.
Request
The Search Request is pretty simple, below you will find the most common usage of this method as well as some examples for the most Frequently Asked Questions we have.
{
"Credential": {
"Username": "Your_Username",
"Password": "Your_Password"
},
"Criteria":{
"DestinationId": 1003937,
"NumNights": 1,
"ReturnHotelStaticData": false,
"ReturnOnRequestRooms": false,
"CheckinDate": "2019-04-19",
"MainPaxCountryCodeNationality": "BR",
"SearchRooms": [{
"NumAdults": 1,
"Quantity": 1
}],
"Filters": {
"MinPrice": 100.00,
"MaxPrice": 1000.00,
"CheapestRoomOnly": true,
"SelectedHotelsIds": [489479, 449267]
}
}
}
Credential
The credentials tag is fairly simple and only has the UserName and the Password as shown below:
"Credential": {
"Username": "Your_Username",
"Password": "Your_Password"
},
The UserName space 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 you are looking for and you will find the explanation for all the sections and most important properties.
DestinationId
Is the ID of the destination city, where the user wishes to reserve the room.
"DestinationId": 1003937,
NumNights
The NumberOfNights field defines how long the user wants to spend.
"NumNights": 5,
ReturnHotelStaticData
This property is responsible for returning hotel data such as latitude, longitude, hotel category, thumbnail used, hotel name and hotel id.
"ReturnHotelStaticData": false,
ReturnOnRequestRooms
Some providers already leave rooms reserved in some hotels to always have 1 room to book at that hotel, this field will show if the passenger wants to see these rooms in their search.
"ReturnOnRequestRooms": false,
CheckinDate
The CheckInDate field sets the check-in date for the desired reservation, note that the date format should be yyyy-mm-dd.
"CheckinDate": "2026-12-25",
MainPaxCountryCodeNationality
It is the code that informs the nationality of the main passenger.
"MainPaxCountryCodeNationality": "BR",
SearchRooms
The SearchRooms field is an object that can receive from 2 to 3 different parameters.
The first one is the NumAdults that would receive the number of adults looking to stay.
"NumAdults": 1,
The second field to be completed is the children's ages, this is an optional field if the user wishes to travel with one or more children, he or she must state their ages, otherwise this field does not have to be completed and your request may be excluded.
"ChildAges": [7],
The third field is the number of rooms that the user wishes to reserve.
"Quantity": 1
Here are two separate examples of SearchRooms.
The first example below is a survey done for 1 child and 1 adult:
"SearchRooms": [{
"NumAdults": 1,
"ChildAges": [7],
"Quantity": 1
}]
The second example is a similar survey, however for only 1 adult
"SearchRooms": [{
"NumAdults": 1,
"Quantity": 1
}]
* Remember that a hotel search can only be done if the children are accompanied by at least 1 adult(MainPax), if a survey is made with 0 adults, no hotel will be returned.
Filters
These are filters that can be used in the search, returning hotels based on user preferences, this is an optional field, so it is up to the user to fill it out or not.
"Filters": {
"MinPrice": 100.00,
"MaxPrice": 1000.00,
"CheapestRoomOnly": true,
"SelectedHotelsIds": [489479, 449267]
}
The properties below are related to the price range that will be returned to the user, so you can set a minimum price and a maximum price for your reservation.
"MinPrice": 100.00,
"MaxPrice": 1000.00,
The following property will receive a Boolean value, and if the value is true, will return only the cheapest room of each Hotel.
"CheapestRoomOnly": true,
A list of hotel Ids you want to search.
"SelectedHotelsIds": [489479, 449267]
Response
Our Search Response will hold all your criteria, separated by Hotels and Rooms in each Hotel. Below you will find the most important sections and properties.
Token
The Token field 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.
Fields such as TotalHotelResults and TotalTime will give you information about the whole number of results we found and how many time has passed since the request
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 Search 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 fields and the RoomId field 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 Search 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.
GetCancellationPolicies
The GetCancellationPolicies is the method you should call after receiving the Search 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 GetCancellationPolicies Request and Response, please refer to this reference page.
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 Search Request with a UserName and a Password as shown below:
"Credential": {
"Username": "Your_Username",
"Password": "Your_Password"
},
The UserName field 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 field 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.
"Token": "99f97a37-5b71-468e-995b-56db85081a12",
Hotel Id and Room Ids
Pretty straightforward, the HotelId field 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 fieldis 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.
"HotelId": 622455,
"RoomIds": ["3160005"]
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 GetCancellationPolicies request. Essentially you can make many different GetCancellationPolicies requests, but all of them must have the exact quantity of rooms you searched for.
Response
As a response, the updated cancellation policies will be returned with the supplier information, deadline for cancellation of the reservation with the updated values.
Booking
The DoBooking method is used to confirm the reservation of the Hotel and room that were chosen in Search and dealt with in the GetCancellationPolices, this is another simple but very important step, as it will inform the main passenger and the escorts (if they have one).
To see all properties contained in Booking Request and response, please refer to our reference page.
Request
The DoBooking request is already a bit more complex, in addition to informing the IDs of the hotel and the chosen rooms, passengers will need be inform who of them will be the main passenger(geralmente o primeiro passageiro é considerado o principal).
{
"Credential": {
"Username": "Your_Username",
"Password": "Your_Password"
},
"Token": "7c1088f2-6a0b-4a1a-9548-66768adee375",
"HotelId": 426484,
"Rooms": [{
"RoomId": "3160002",
"Paxs": [{
"Name": "Caique",
"Surname": "Nobook",
"Age": 30,
"MainPax": true,
"isChild": false
}]
}]
}
Credentials
The credentials tag is the same as required on the Search Request with a UserName and a Password as shown below:
{
"Credential": {
"Username": "Your_Username",
"Password": "Your_Password"
},
Token
The token that was generated in the survey and handled in the GetCancellationPolicies will be used for the last time to close the room reservation.
"Token": "7c1088f2-6a0b-4a1a-9548-66768adee375",
Hotel Id and Room
Here the user must inform the id of the hotel and the ids of the rooms to be reserved; In the Paxs field, the user must enter the information of the passengers that will be in the rooms, remembering that the first passenger (adult) will be considered the MainPax, as can be seen in the example below.
"Token": "7c1088f2-6a0b-4a1a-9548-66768adee375",
"HotelId": 426484,
"Rooms": [{
"RoomId": "3160002",
Paxs
Here you will be informed of the passengers that will be staying at the hotel, where the name, surname and age will be passed, it is worth noting that the MainPax field shows if the passenger informed is the main one (Usually the first passenger to be informed is the main one).
"Paxs": [{
"Name": "Caique",
"Surname": "Nobook",
"Age": 30,
"MainPax": true,
"isChild": false
}]
Payment
This field refers to the payment data of the user, if the user chooses to make the payment, or if the agency is anticipated and the reservation is in penalty, cangooroo will make the payment.
Payment data will also serve as a guarantee if the room is returned with the property "IsPrePayment" to true, so the provider can guarantee that he will receive it for that reservation.
"Payment": {
"IsBilled": false,
"CreditCard": {
"Holder": "Caique",
"CardNumber": "40028922",
"SecurityCode": "762",
"YearExpiration": 2024,
"MonthExpiration": "04",
"Installments": 3,
"CardOperator": "Test"
},
"ContractingParty": {
"DistrictName": "São Paulo",
"ZipCode": "04552-000",
"CityName": "São Paulo",
"AddressComplement": "Complemento",
"CPF": "123.456.789-10",
"Address": "Rua do rocio",
"PersonName": "Caique NoBook",
"AddressNumber": "199",
"PhoneNumber": "940028922",
"PhoneNumberDDD": "11",
"PhoneNumberDDI": "55",
"StateCode": "SP",
"Email": "test.test@t4w.com.br",
"ReceiveCreditCardReceipt": false,
"CountryCode": "SP"
},
"PaymentConditionId": Value will be provided by Operator,
"RetainCommission": false
}
Response
Here, the user can see the result of his request, together with the other information of his reservation, such as the name of the hotel, rates and observations, it is worth paying attention in the fields ServiceId (code of your reservation) and Status your reservation as they show whether your reservation for that room was made successfully or not.
Cancel
This method is very simple, where the client will inform, in addition to the credentials of the client, the ServiceId of his reservation made in the previous method.
To see all properties contained in Cancel Request and response, please refer to our reference page.
{
"Credential": {
"Username": "cangooroov3",
"Password": "cangooroo@123"
},
"ServiceId": 31504
}
Request
Credential
The credentials tag is the same as required on the SearchAvailability, cancellationPolicies and DoBooking Request with a UserName and a Password as shown below:
{
"Credential": {
"Username": "Your_Username",
"Password": "Your_Password"
},
ServiceId
After you enter the credentials of the user, the ServiceId of a reservation that was made with the credentials informed must be passed.
"ServiceId": 31504
Response
Here you can see the canceled service details, along with the confirmation of your cancellation in the Status field.
GetServicesDetails
this is a very simple method as it is used to return the details of your reservation based on the ServiceId informed.
To see all properties contained in GetServicesDetails Request and response, please refer to our reference page.
Request
This method is similar to the previous one, being necessary to inform only the credentials of the user and the ServiceId.
Credential
The credentials tag is the same as required on the SearchAvailability, cancellationPolicies and DoBooking Request with a UserName and a Password as shown below:
{
"Credential": {
"Username": "Your_Username",
"Password": "Your_Password"
},
ServiceId
After you enter the credentials of the user, the ServiceId of a reservation that was made with the credentials informed must be passed.
"ServiceId": 31504
Response
in the response the customer will be able to see the details of his reservation, such as the status of his reservation, the payment status, cancellation policies and hotel data.