Public API
Download JSON spec

Getting Started

This page will guide you so that you can begin developing your integration with SHMS API. You can explore this API to enhance your connectivity with the SHMS system and develop new use cases and features.
In order to make your first request, you will need access to the SHMS URL and an API Key. You can request these parameters from the property. The API key is subject to rate limits that are explained in the Authentication section.

First request

You can check that your setup is working using the Get room types operation, which returns details about the room structure of the property. For example, we can try a curl -X GET "SHMS_API_SERVER"/openapi/roomTypes" -H 'x-api-key: "YOUR_API_KEY"' . If successful, the API will return 200 HTTP status code with the room structure in the message body, something like this: 
  [{
    "code": "TRI",
    "type": "NORMAL_ROOM",
    "description": "Triple Room",
    "altDescriptions": [],
    "numPax": 3,
    "numRooms": 27,
    "account": "70000000"
  },
  {
    "code": "DOB",
    "type": "NORMAL_ROOM",
    "description": "Double Room",
    "altDescriptions": [],
    "numPax": 2,
    "numRooms": 40,
    "account": "70000000"
  },
  {
    "code": "JS",
    "type": "NORMAL_ROOM",
    "description": "Junior Suite ",
    "altDescriptions": [],
    "numPax": 2,
    "numRooms": 14,
    "account": "70000000"
  },
  {
    "code": "MAST",
    "type": "HALL",
    "description": "MASTER ",
    "altDescriptions": [],
    "numPax": 0,
    "numRooms": 15,
    "account": "70000000"
  }]

API Versioning

You can include the request header Accept to choose between different versions of the API. Available values are described in each method (application/openapi-v1+json, application/openapi-v2+json, etc.). If this header is omitted, then the latest version of the API will be used and the content-type response header will indicate which version is being used.

Request parameters format

  • date: following the format YYYY-MM-DD, without including a time component. For example, October 21st, 2025 is represented as 2025-10-21
  • date-time: following the format YYYY-MM-DD hh:mm:ss, using the 24-hour clock system. For example, October 21st, 2025 at 21:00 is represented as 2025-10-21 21:00:00
  • number: used for floating-point numbers, otherwise type integer (or int64/int32) would be used
  • array of string: used for passing multiple values in a query parameter, following a comma-separated format. For example: DB,JS,BB

Data serialization

  • date: following the format YYYY-MM-DD, without including a time component. For example, October 21st, 2025 is represented as 2025-10-21
  • date-time: following the format YYYY-MM-DD hh:mm:ss, using the 24-hour clock system. For example, October 21st, 2025 at 21:00 is represented as 2025-10-21 21:00:00
  • number: used for floating-point numbers, otherwise type integer would be used

Pagination

Some operations might return a huge amount of records or need a lot of processing resources, so pagination is introduced to limit the number of records that the operation returns. In these cases, query parameters page and size are used to handle this situation and retrieve all the data in a manageable and efficient manner. The limit for the size parameter could be different from one method to another, depending on the resources consumed by the operation that is being executed.

API errors

Whenever an error is thrown by the API, the response body will have the format described in ApiError. The reason of the error will be described in the fields message , detailedDescription and validationErrors . The code field is an internal code to help accelerate troubleshooting.

Best practices

  • Use the available parameters to reduce the returned data to get only the data you need
  • Cache unchanging data or data that you use very often, to limit the number of requests done
  • Do not retry the request when you hit the rate limit. Instead, read and respect the value in the Retry-After response header. Please do not retry them automatically.
  • Pay close attention to the error message descriptions.

Typical use cases

Booking engine

A booking engine could use this API to get the availability and prices in real time:
  • Use the method Get availability filtering by dates and room types.
  • Use the method Get restrictions if the booking engine wants to control minLOS, maxLOS or release restrictions.
  • Use the method Get rate details filtering by dates and room types to get the prices of a rate. Optionally, use the method Get rate's close restrictions in order to get the close restrictions of the rate.
  • Instead of using Get rate details, use the method Get rate prices filtering by dates, room type and meal plan to get the final prices of a rate.
In addition to read operations, the API also supports write operations for managing reservations:

POS system

A POS system could use this API to get in-house stays information about their meal plans in real time:
  • Use the method Get stay by room number to locate the information for the stay.
  • Or use the method Get stays to obtain all the stays information.
  • Depending on the parameters fullCredit and mealPlan, decide if a charge to the room can be made, and post it using the Post charge operation

Reference tables

There are some enumerated values throughout the API whose meanings are explained in the following section. All the values for the enum types that are mentioned in the rest of the documentation are explained here.
This API Key will be provided by the property. It is subject to rate limiting in order to protect the system against an excessive volume of requests which could slow down the service for the rest of the users. These restrictions are also configured in the SHMS system, so the property will inform you about your rate limits (requests per day and requests per minute).
In case you hit the rate limit, an HTTP 429 error will be returned with a response header Retry-After indicating how long to wait before making the next request.