Room.Works API


Room Mapping API has a Production environment with the below Endpoint:



  • Room Mapping API is currently a Read-only type of service where the end-user cannot post or update anything onto our servers.
  • Room Mapping API currently does not have nor require any staging API.


Each endpoint within Room Mapping API requires an API key which is generated and issued to each client by our API team. The authentication gateway validates the API Key and processes the request as per the request if the user is successfully authenticated.


Securing API Key

Your API Key carries many privileges, so be sure to keep them secure! Do not share the key in publicly accessible areas such as GitHub, client-side code, and so forth.

The most popular choice, perhaps due to its usage by AWS API Gateway is X-API-KEY which is a custom header convention for passing your API key. Here is a sample API key and how it fits within the request.

GET / HTTP/1.1
X-API-KEY: 7671ae5e-9f4e-4a71-8242-c7691a9275a5


Mapping API

Room Mapping API is the primary endpoint within the Room Mapping API. The response data entirely depends on how accurate the parameters are passed during the request. To send API requests, the developer needs to :

  • Identify the hotel: This is done by either sending to the API the Gimmonix Hotel ID or sending us a specific supplier Hotel ID, such as the Expedia Rapid ID,'s ID or Hotelbeds' ID for example.
    You can send more than one Hotel ID. To the list of supported suppliers keys.
  • Supplier rates in Array: Developer is required to pass the array of rates as received by the different suppliers within the Rate Object as provided in the Room Mapping API body parameters. The mandatory fields for room delivery and rates are room/rate name and room id (for a supplier that supports room id).


API limitation :

Room Mapping API allows a maximum of 200 room names to be passed in a single request.

Mapping API examples (Postman) - Click here.

Updated Hotels API

Updated Hotels API allows to get all ids of hotels with changed data since the requested date.

Each request returns the provided count of rows.

Updated Hotels API examples (Postman) - Click here.

API Type & Codes

Request Type

Room Mapping API HTTPS request support is limited to a subset of RFC 2616 for the Production APIs and will follow the same approach once Staging API is available.



Never access the response body without confirming over the HTTP Response Code within the Header first.

Request TypeSupportedDescription
'POST'YesPrimary endpoint under Room Mapping API uses POST to retrieve relevant hotel rooms detail.

Response Code

Room Mapping uses conventional HTTP response codes to indicate the success or failure of an API request. In general:

  • Codes in the 200 OK range indicate success.
  • Codes in the 400 Bad Request,401 Unauthorized, 403 Forbidden indicate an error that failed given the information provided.
  • Codes in the 500 Internal Server Error range indicate an error within our servers however these are rare.


Graceful Exception Handling

Our libraries raise exceptions for many reasons, such as parameters issues, authentication errors, and network unavailability. We recommend writing code that gracefully handles all possible API exceptions.

Additional HTTP Response Codes

Other standard HTTP errors may be generated by our stack and not directly from our API. Here are the categories of possible Standard HTTP response codes.

1xxCommunication transfer protocol-level information.Informational
2xxThis indicates that the client's request was accepted successfully.Success
3xxIndicates that the client must take some additional action to complete their request.Redirection
4xxThis category of error status codes points to the clients.Client Error
5xxThis category of error is related to server exceptions due to internal incapability to perform the request. The user is advised to contact the Room Mapping API Support team.Server Code

Error Response Body - Any response code within the 4xx or 5xx range will have a static response object alongside a relevant error message to aid the developer. Here is what the response body looks like in case of any error.