Adding guests durring the booking step

Overview

When booking rooms using the LiteAPI, the required guests object lets you specify the individuals associated with each booking. This includes not just the names of the guests, but also contact information like email. The occupancyNumber field plays a key role in linking guests to specific rooms, but it can cause confusion if mistakenly assumed to represent the number of people in each room.

In this guide we'll clarify how to properly use the guests object and occupancyNumber to ensure that your API calls are successful. In short, guests are linked to each room / occupancy and must have exactly one guest attached.

Key Concepts

• guests Array: This is an array of guest objects where each object represents a guest related to the booking. This is required for production bookings.
• occupancyNumber Field: This field helps associate a guest with a specific room. It should correspond to the number of rooms being booked and is indexed starting from 1. The occupancyNumber is not the number of people in the room, but rather the identifier for the room itself.
• Relationship between occupancyNumber and rooms booked: If the guests array is used, each room must have one primary contact listed under guests. This means that the occupancyNumber is associated one-to-one with each room during the booking process. Occupancy is actually referring to the original occupancies array passed during the rate request step.

Understanding the guests and occupancyNumber

Correct Usage of guests

• Each room booked requires one primary contact, which will usually be the credit card holder for the booking.
• When booking multiple rooms, a primary contact must be provided for each room. For example, if you are booking two rooms, you will need to include one guest for each room.

occupancyNumber and its Role

• The occupancyNumber field does not represent the number of people in the room. Instead, it indicates the room number (starting from 1). For example:
  • occupancyNumber: 1 corresponds to the first room.
  • occupancyNumber: 2 corresponds to the second room.
• Each occupancyNumber must be unique, and all required fields within guests must be filled out (remarks are not required).

Common Misunderstanding

People often assume that occupancyNumber refers to the number of guests in a room. This is incorrect. Instead, occupancyNumber identifies the room itself, and one guest’s contact information must be provided per room.

Example

Consider the following example where two rooms are being booked:

• Room 1 has 2 adults. (Sunny Mars, and Mary Mars)
• Room 2 has 1 adults and 1 child. (Alice Kazam and her child Lizzy Kazam)

The API call could look like this:

{
  "holder": {
    "firstName": "Steve",
    "lastName": "Doe",
    "email": "[email protected]"
  },
  "payment": {
    "method": "WALLET"
  },
  "guests": [
    {
      "occupancyNumber": 1,
      "remarks": "quiet room please",
      "firstName": "Sunny",
      "lastName": "Mars",
      "email": "[email protected]"
    },
    {
      "occupancyNumber": 2,
      "remarks": "quiet room please",
      "firstName": "Alice",
      "lastName": "Kazam",
      "email": "[email protected]"
    }
  ],
  "prebookId": "fnz0v9WwR"
}

Here:
"occupancyNumber": 1 refers to the first room where one adult in that room has their information listed.
"occupancyNumber": 2 refers to the second room where the adult in that room has their information listed.

Error Handling

If you encounter the error message:

{
  "error": {
    "code": 4002,
    "description": "invalid occupancy number",
    "message": "required request field is missing or wrong input"
  }
}

This typically indicates one of the following issues:

1. Incorrect occupancyNumber Index: The occupancyNumber should start from 1, not 0 or any other value. Make sure that your occupancyNumber starts from 1 and increases sequentially for each room booked.
2. Missing Required Fields: If the guests object is provided, ensure that all required fields, such as firstName, lastName, and email, are filled out for each guest.
3. Incorrect Number of guests: Ensure that you are not mistakenly entering guests for each person in the room. Instead, provide one primary contact for each room.

Summary

• guests should contain one object per room, with each object representing the primary contact for that room.
• occupancyNumber starts from 1 and should increase sequentially for each room.
• All guests required fields must be filled out.

If you follow these guidelines, your bookings should go through without errors. For more details, refer to the API reference or reach out to our support team.