Zeus (Zumata Hotel API) (3.75.0)

Download OpenAPI specification:Download

Zumata's API is a new approach in B2B travel APIs. In a few simple steps, you can be getting real-time travel pricing, availability and booking worldwide via simple API calls.

The purpose of this site is to provide documentation and technical guidance to users of Zumata’s API products.

Usage of the Zumata API requires consent to be bound by the terms of the Zumata API Agreement.

Important Notes

Read this section carefully and follow the recommendations specified in here.

Session

Zumata API is designed to be stateless and sessionless in its beginning. However, we have realized that this has caused us more issues as more clients start to integrate our solution.

It is therefore strongly recommended that client includes the session ID that they have received in the previous call to the subsequent calls of the related.

By doing so, you will greatly help Zumata in assisting you should there be any issues for your integration. If you are trying to do a different search/booking, you should have a different session ID.

Example

  1. You start with a multiple properties search without any session ID being passed in the HTTP header. However, you received a session ID in the response.
  2. In the next polling call, include the session ID in the HTTP header with key X-Session.
  3. In the booking policy call, include the session ID received in step 1 in the same header.
  4. In the booking call, include the session ID received in step 1 in the same header.
  5. In the booking status polling call, include the session ID received in step 1 in the same header.
  6. In the cancellation call, include the session ID received in step 1 in the same header.

Event

Similar to the situation explained above, each response from our server contains a session ID and an event ID. It has no function aside from identifying the particular request / response pair.

When reporting issues regarding the API to ZUMATA, kindly include session ID and event IDs in your communications where possible to help us debug problems you may have faced.

Search Polling

Search is architected as a polling endpoint; that means that you can continue to call the endpoint, and at any point in time the results from it are viable for display and booking.

And, over time, polls should contain more data than previous ones. This allows you to poll from your front end browser application through to your server and from there on to the endpoint, with each call returning progressively more data.

This will allow users to see hotel packages as soon as they are available rather than waiting for an arbitrary cut-off time or full search completion.

It is also possible to use the alternative method of simply waiting until either:

  1. an arbitrary time has passed (max_time) or
  2. search is complete. In your code, you start the search with an initial call at the 0-seconds elapsed mark, then call once every 2-3 seconds until your max_time has been exceeded or we have returned a search completed response. Once this has happened you could return the results to your webpage or application.

Note: You should use source_market where possible to reduce possibly nationality issues with your bookings.

Supplier Pending Status

A booking with bkg-ip may transition into bkg-cf, bkg-af or bkg-ps within 90 seconds. A booking with bkg-ps then transition into bkg-cf or bkg-af within a few minutes to a few hours (depending on supplier).

Therefore, client should not treat bkg-ps as a failed booking as this state indicates that the supplier is still working on confirming the booking.

Upon receiving bkg-ps, client should continue polling the booking status at this interval:

  1. Polling every 1 minutes for the next 5 minutes.
  2. Polling every 5 minutes after that for the next 6 hours.

If booking that went into bkg-ps didn’t change into bkg-cf or bkg-af within the 6 hours timeframe, client may contact our customer support for assistance.

Missing/Invalid Fields

You may have used some fields in the request and received some fields in the response which are not documented in here. Such fields are most likely have been deprecated.

You may also notices that some fields are marked as required but you have been omitting them in your requests so far. Those fields are marked as required as they are recommended not be to omitted. However, the API couldn't enforce them as required as it would break existing client integration. New client are requested to follow those required fields.

Test environment

As majority of the suppliers have rather unstable test environment, we have designed a controlled test environment to help you during the integration period.

These are the things to take note of:

  • Only these hotels are available: kLxE, BlKz, 8Ycj, PLPo, K5Rm, 09uu, dnhy, XNVf, 9CPH, NBUd, 7uLH, fst1, fst2, fst4
  • These hotels has special behaviors:
    • PLPo: Booking will always takes more than 60 seconds to complete.
    • dnhy: Booking will first goes into pending supplier status before being confirmed.
    • 9CPH: Booking policy will always returned with higher price.
    • 7uLH: Booking will always take more than 60 seconds to complete and will respond with an empty result until it completes.
    • fst1: Always return result on second polling of /hotel_list and /hotel_rooms
    • fst2: Takes 2+ seconds to return result of /hotel_list and /hotel_rooms. Use it to simulate slow result.
    • fst4: Takes 4+ seconds to return result of /hotel_list and /hotel_rooms. Use it to simulate very slow result.

Note: The expected response time when sending fst1,fst2,fst4 in one request to /hotel_list is more than 5 seconds. This is because fst4 takes 4+ seconds to respond. You must continue to poll, in order to get the result.

Tips: We suggest sending only fst1 or fst2 to have a better development experince, and use fst4 to simulate a very slow result.

Changelog

v3.75.0

  • Supplier description is being returned in responses as supplier_description.

Authentication

X-Api-Key

In order to access the API, you will need an API key.

Note: The API key is case sensitive.

Security scheme type: API Key
header parameter name: X-Api-Key

Multiple Properties Search

Search multiple properties in a single call.

Hotel List

Retrieves the list of hotels with rate from a selected package (lowest price), based on a list of hotel IDs.

Authorizations:
query Parameters
hotel_id_list
required
Array of string <string> (HotelIDList)

A comma separated Hotel IDs to be searched for with the other given parameters. Only 200 hotel IDs may be sent in a given request.

check_in_date
required
string <date> (CheckInDate)
Example: "2018-11-01"

The check-in date for the property stay. The value of this can range from today’s date to 1 year in the future. The check-in-date is considered to be as at the destination of the respective hotels.

check_out_date
required
string <date> (CheckOutDate)
Example: "2018-11-02"

The check-out date for the property stay. The value of this can range from tomorrow’s date to 1 year in the future. The check-in-date is considered to be as at the destination of the respective hotels. It is expected that this date occurs after the check-in date.

room_count
required
integer <int32> (RoomCount) [ 1 .. 9 ]
Example: 1

The total number of rooms required for the stay.

adult_count
required
integer <int32> (AdultCount) [ 1 .. 36 ]
Example: 2

The total number of adult guests who will be staying in the property.

children
Array of integer <int32> (Children)

A comma separated list of children ages.

currency
required
string <ISO 4217> (Currency) \w{3}
Example: "USD"

Result prices will be returned in this currency.

source_market
required
string <ISO 3166> (Country) \w{2}
Example: "US"

For sourcing availability within certain markets, a source market option may be usable for more accurate pricing and reduction in booking errors. If you do not include an accurate source market, you may be liable for a booking for the incorrect market.

header Parameters
X-Session
string <string> (Session) \w{32}
Example: "bf1882b665bf480caec3f99ad32b77a7"

Session ID is used to group related operations together.

Responses

200

Search result.

get /hotel_list

Live server

https://api-v3.zumata.com/hotel_list

Test server

https://test-api-v3.zumata.com/hotel_list

Response samples

application/json
Copy
Expand all Collapse all
{
  • "session_id": "f7be405b631e41c19c9f02229cc98866",
  • "event_id": "f951dba1cae6e6b59596f6829d788cf6",
  • "status": "in-progress",
  • "search":
    {
    },
  • "hotels": [ ]
}

Single Property Search

Search single property in a single call.

Hotel Rooms

Searches a list of available packages for a given hotel ID and specified parameters.

Authorizations:
query Parameters
hotel_id
required
string <string> (HotelID) \w{4}

Unique ID of the property returned. Every property has a unique ID.

check_in_date
required
string <date> (CheckInDate)
Example: "2018-11-01"

The check-in date for the property stay. The value of this can range from today’s date to 1 year in the future. The check-in-date is considered to be as at the destination of the respective hotels.

check_out_date
required
string <date> (CheckOutDate)
Example: "2018-11-02"

The check-out date for the property stay. The value of this can range from tomorrow’s date to 1 year in the future. The check-in-date is considered to be as at the destination of the respective hotels. It is expected that this date occurs after the check-in date.

room_count
required
integer <int32> (RoomCount) [ 1 .. 9 ]
Example: 1

The total number of rooms required for the stay.

adult_count
required
integer <int32> (AdultCount) [ 1 .. 36 ]
Example: 2

The total number of adult guests who will be staying in the property.

children
Array of integer <int32> (Children)

A comma separated list of children ages.

currency
required
string <ISO 4217> (Currency) \w{3}
Example: "USD"

Result prices will be returned in this currency.

source_market
required
string <ISO 3166> (Country) \w{2}
Example: "US"

For sourcing availability within certain markets, a source market option may be usable for more accurate pricing and reduction in booking errors. If you do not include an accurate source market, you may be liable for a booking for the incorrect market.

header Parameters
X-Session
string <string> (Session) \w{32}
Example: "bf1882b665bf480caec3f99ad32b77a7"

Session ID is used to group related operations together.

Responses

200

Search result.

get /hotel_rooms

Live server

https://api-v3.zumata.com/hotel_rooms

Test server

https://test-api-v3.zumata.com/hotel_rooms

Response samples

application/json
Copy
Expand all Collapse all
{
  • "session_id": "f7be405b631e41c19c9f02229cc98866",
  • "event_id": "c2edec21e55841ffbfb8be2ee4c0bf80",
  • "status": "in-progress",
  • "search":
    {
    },
  • "hotels": [ ]
}

Booking Policy

Get the cancellation policy and the latest final price.

Generate new booking policy

Before a booking call is made against a package (returned via search), a booking policy call must be made.

Retrieving a booking policy returns additional information regarding the booking to be made and includes details like cancellation policy and hotel policies.

In the case of some suppliers this call is equivalent to an availability check, because of this it is important not to let long periods (>20 minutes) lapse between retrieval of this policy and the booking itself as this will often reduce the likelihood of a package being successfully booked.

When making the pre-book request several packages from various suppliers may be able to fulfill this request.

Accordingly, in the event of booking failure seen in our internal system, we will proceed to book from the next supplier available, until the booking request is fulfilled or no further options are available.

After submitting the booking policy, the details can be retrieved or can be used to carry out a pre-booking.

Note

  1. Include any source_market parameter settings from your search here as well.
Authorizations:
header Parameters
X-Session
string <string> (Session) \w{32}
Example: "bf1882b665bf480caec3f99ad32b77a7"

Session ID is used to group related operations together.

Request Body schema: application/json
search
required
object

The search object that was returned in the search.

package
required
object

The package object that was returned in the search.

config
object (BookingPolicyConfig)

Responses

200

Booking policy result.

404

Booking policy error.

post /booking_policy

Live server

https://api-v3.zumata.com/booking_policy

Test server

https://test-api-v3.zumata.com/booking_policy

Request samples

application/json
Copy
Expand all Collapse all
{
  • "search":
    {
    },
  • "package":
    {
    }
}

Response samples

application/json
Copy
Expand all Collapse all
{
  • "session_id": "f7be405b631e41c19c9f02229cc98866",
  • "event_id": "055f5bb761e2cec9bfcc2775a160765e",
  • "booking_policy_id": "b96f7d21-9b34-cddc-f0e9-471527040137",
  • "cancellation_policy":
    {
    },
  • "package":
    {
    }
}

Retrieve generated booking policy

Retrieve the generated booking policy using booking policy ID.

Authorizations:
path Parameters
booking_policy_id
any
Example: "2afce314-086d-42d4-ed34-6041919931d5"

The unique booking policy ID.

header Parameters
X-Session
string <string> (Session) \w{32}
Example: "bf1882b665bf480caec3f99ad32b77a7"

Session ID is used to group related operations together.

Responses

200

Booking policy result.

get /booking_policy/{booking_policy_id}

Live server

https://api-v3.zumata.com/booking_policy/{booking_policy_id}

Test server

https://test-api-v3.zumata.com/booking_policy/{booking_policy_id}

Response samples

application/json
Copy
Expand all Collapse all
{
  • "session_id": "f7be405b631e41c19c9f02229cc98866",
  • "event_id": "aebb5a2b7897260f20e1c6bc71bc859d",
  • "booking_policy_id": "b96f7d21-9b34-cddc-f0e9-471527040137",
  • "cancellation_policy":
    {
    },
  • "package":
    {
    },
  • "request":
    {
    }
}

Booking

Booking using the booking policy returned.

Prebook

Pre-books a package after a booking-policy request has been made.

Note

  1. No actual booking has been done after this call. A record is being created in our system.
Authorizations:
header Parameters
X-Session
string <string> (Session) \w{32}
Example: "bf1882b665bf480caec3f99ad32b77a7"

Session ID is used to group related operations together.

Request Body schema: application/json
booking_policy_id
required
string <uuid> (BookingPolicyID)

The unique booking policy ID.

client_reference
required
string <string> (ClientReferenceID)

Custom ID set by the client which can be retrieved during regular booking status calls.

room_lead_guests
required
Array of object (RoomLeadGuest)

Number of this should match the room_count in the search.

contact_person
required
object

Person to be contacted for the booking.

Responses

200

Pre-book result.

post /pre_book

Live server

https://api-v3.zumata.com/pre_book

Test server

https://test-api-v3.zumata.com/pre_book

Request samples

application/json
Copy
Expand all Collapse all
{
  • "booking_policy_id": "b96f7d21-9b34-cddc-f0e9-471527040137",
  • "client_reference": "7682197",
  • "room_lead_guests":
    [
    ],
  • "contact_person":
    {
    }
}

Response samples

application/json
Copy
Expand all Collapse all
{
  • "session_id": "f7be405b631e41c19c9f02229cc98866",
  • "event_id": "e40d36cbae12767d1d6d58b65feb693e",
  • "booking_id": "3874fb46-7bfc-4a25-b167-967178f0556b",
  • "client_reference": "7682197",
  • "status": "bkg-ns",
  • "status_payment": "pay-ns",
  • "requested_at": "2018-05-23T01:55:24Z",
  • "package":
    {
    },
  • "guest":
    {
    },
  • "pricing":
    {
    },
  • "cancellation_policy":
    {
    },
  • "booking_details":
    {
    },
  • "contact_person":
    {
    },
  • "room_lead_guests":
    [
    ],
  • "source_market": "US"
}

Book

Trigger the actual booking.

Authorizations:
path Parameters
booking_id
any
Example: "31403b0f-6e62-49fb-5fe4-db34cfd42feb"

The booking ID returned from the pre-book response.

header Parameters
X-Session
string <string> (Session) \w{32}
Example: "bf1882b665bf480caec3f99ad32b77a7"

Session ID is used to group related operations together.

Responses

200

Booking result.

post /book/{booking_id}

Live server

https://api-v3.zumata.com/book/{booking_id}

Test server

https://test-api-v3.zumata.com/book/{booking_id}

Response samples

application/json
Copy
Expand all Collapse all
{
  • "session_id": "f7be405b631e41c19c9f02229cc98866",
  • "event_id": "da6f358c60c8892aa486d1e78be34c05",
  • "booking_id": "3874fb46-7bfc-4a25-b167-967178f0556b",
  • "client_reference": "7682197",
  • "status": "bkg-ip",
  • "status_payment": "acc-rs",
  • "requested_at": "2018-05-23T01:55:24Z",
  • "package":
    {
    },
  • "guest":
    {
    },
  • "pricing":
    {
    },
  • "cancellation_policy":
    {
    },
  • "booking_details":
    {
    },
  • "contact_person":
    {
    },
  • "room_lead_guests":
    [
    ],
  • "source_market": "US"
}

Get booking status

Retrieves the status and information of a booking request.

Authorizations:
path Parameters
booking_id
any
Example: "31403b0f-6e62-49fb-5fe4-db34cfd42feb"

The booking ID returned from the pre-book response.

header Parameters
X-Session
string <string> (Session) \w{32}
Example: "bf1882b665bf480caec3f99ad32b77a7"

Session ID is used to group related operations together.

Responses

200

Booking result.

get /book/{booking_id}/status

Live server

https://api-v3.zumata.com/book/{booking_id}/status

Test server

https://test-api-v3.zumata.com/book/{booking_id}/status

Response samples

application/json
Copy
Expand all Collapse all
{
  • "session_id": "f7be405b631e41c19c9f02229cc98866",
  • "event_id": "10ba2c821fcfa5f86e2b7bcba8641f9e",
  • "booking_id": "3874fb46-7bfc-4a25-b167-967178f0556b",
  • "client_reference": "7682197",
  • "status": "bkg-cf",
  • "status_payment": "acc-cp",
  • "requested_at": "2018-05-23T01:55:24Z",
  • "confirmed_at": "2018-05-23T02:03:02Z",
  • "package":
    {
    },
  • "guest":
    {
    },
  • "pricing":
    {
    },
  • "cancellation_policy":
    {
    },
  • "booking_details":
    {
    },
  • "contact_person":
    {
    },
  • "room_lead_guests":
    [
    ],
  • "source_market": "US"
}

Cancellation

Cancel the confirmed booking.

Cancel booking

Cancels a booking. Please note that you cannot cancel a booking in anything other than a bkg-cf (booking confirmed) status.

It is the responsibility of the client application to wait until a booking has been confirmed before attempting a cancellation as underlying supplier systems will not process a booking in an in-process state.

Failing to observe this rule will result in liability for booking charges and/or penalties incurred.

Authorizations:
header Parameters
X-Session
string <string> (Session) \w{32}
Example: "bf1882b665bf480caec3f99ad32b77a7"

Session ID is used to group related operations together.

Request Body schema: application/json
booking_id
required
string <string> (BookingID)

Unique booking ID of the booking. This is used for confirming, retrieving and cancelling a booking.

Responses

200

Cancellation result.

post /cancel

Live server

https://api-v3.zumata.com/cancel

Test server

https://test-api-v3.zumata.com/cancel

Request samples

application/json
Copy
Expand all Collapse all
{
  • "booking_id": "3874fb46-7bfc-4a25-b167-967178f0556b"
}

Response samples

application/json
Copy
Expand all Collapse all
{
  • "session_id": "f7be405b631e41c19c9f02229cc98866",
  • "event_id": "f9d7424ffd6da18f353a5e39199aab84",
  • "booking_id": "3874fb46-7bfc-4a25-b167-967178f0556b",
  • "client_reference": "7682197",
  • "status": "bkg-cx",
  • "status_payment": "acc-cx",
  • "requested_at": "2018-05-23T01:55:24Z",
  • "confirmed_at": "2018-05-23T02:03:02Z",
  • "package":
    {
    },
  • "guest":
    {
    },
  • "pricing":
    {
    },
  • "cancellation_details":
    {
    },
  • "cancellation_policy":
    {
    },
  • "booking_details":
    {
    },
  • "contact_person":
    {
    },
  • "room_lead_guests":
    [
    ],
  • "bundled_booking": false,
  • "locale": "en-US",
  • "source_market": "US",
  • "penalty_percentage": 100
}