Search Requests

Introduction

The first step in a PMS transaction is the search request. It is initiated by the POS user on the payment screen.

The Lightspeed Restaurant K-Series POS will pass a number of query parameters to the PMS, including the terms that the user searched for. An array of guests/folios matching the search terms should be returned to Lightspeed.

In general, the search function helps to find checked-in guests or folios. Guests who have not checked in cannot be found using the search function.

Parameter	Description
term	The search term entered by the end user
businessExternalReference	The PMS Provider's K-Series API Client ID (fake-client-id)
apiKey	The API key configured by the partner for the restaurant (fake-api-key)

Search terms

The Lightspeed Restaurant K-Series POS product has a full-text search, which offers various options for executing search requests.

The search request at the POS offers the option to enable manual search

If this option is activated, the search is only executed when the POS user executes the command. If the option is deactivated, a search request is triggered for each entry in the search field.

Here is an explanation of the expected response fields. If roomDescription is not available, this field can be filled with the roomId:

Parameter	Datatype	Description
roomId	String	Unique ID of the room (can be alphanumeric)
roomDescription	String	Description of the room
clientName	String	Full name of the guest
reservationId	String	Unique ID of the reservation -> The ID is part of the Charge to Room POST request
blocked	Boolean	If a guest has checked in but is blocked for room charges (e.g. if no credit card has been deposited as guarantee) If the status is “true” the User on the POS won’t be able to perform a charge to room action.

Search Types

Guest Names

The Lightspeed Restaurant K-Series POS will pass a number of query parameters to the PMS, including the guest’s name (Combination of first and last name, but it is also possible to search by first or last name only) that the user searched for.

An array of guests/folios matching the search terms should be returned to Lightspeed.

POS Action

The POS user searches for “Franz Test”

Example request

/search?businessExternalReference=fake-client-id&apiKey=fake-api-key&term=Franz%20Test

Example response

{
   "success": "true",
   "errorMessage": "",
   "reservations":[
      {
         "roomId": "1000",
         "roomDescription": "Room 1000",
         "clientName": "Franz Test",
         "reservationId": "001",
         "blocked":"false"
      }
   ]
}

Room Numbers

The Lightspeed Restaurant K-Series POS will pass a number of query parameters to the PMS, including the room number that the user searched for.

An array of guests/folios matching the search terms should be returned to Lightspeed.

POS Action

The POS user searches for “1000”

Example request

/search?businessExternalReference=fake-client-id&apiKey=fake-api-key&term=1000   

Example response

{
   "success": "true",
   "errorMessage": "",
   "reservations":[
      {
         "roomId": "1000",
         "roomDescription": "Room 1000",
         "clientName": "Franz Test",
         "reservationId": "001",
         "blocked":"false"
      }
   ]
}

Partial Guest Names

The Lightspeed Restaurant K-Series POS will pass a number of query parameters to the PMS, including the guest’s name that the user searched for.

The full text search is used to search for partial matches, e.g. "Fra" or "Te" are entered in the search mask to find the guest "Franz Test”.

An array of guests/folios matching the search terms should be returned to Lightspeed, if the search is successful.

POS Action

The POS user searches for "Fra"

Example request

/search?businessExternalReference=fake-client-id&apiKey=fake-api-key&term=Fra

Example response

{
   "success": "true",
   "errorMessage": "",
   "reservations":[
      {
         "roomId": "1000",
         "roomDescription": "Room 1000",
         "clientName": "Franz Test",
         "reservationId": "001",
         "blocked":"false"
      },
      {
         "roomId": "2000",
         "roomDescription": "Room 2000",
         "clientName": "Frank Doe",
         "reservationId": "002",
         "blocked":"false"
      }

   ]
}

Room Sharer

Room sharers are guests with different names/reservation ids who share a room.

The Lightspeed Restaurant K-Series POS will pass a number of query parameters to the PMS, including the room number that the user searched for.

An array of guests/folios matching the search terms should be returned to Lightspeed, if the search is successful.

POS Action

The POS user searches for “3000”

Example request

/search?businessExternalReference=fake-client-id&apiKey=fake-api-key&term=3000   

Example response

{
   "success": "true",
   "errorMessage": "",
   "reservations":[
      {
         "roomId": "3000",
         "roomDescription": "Room 3000",
         "clientName": "John Doe",
         "reservationId": "004",
         "blocked":"false"
      },
      {
         "roomId": "3000",
         "roomDescription": "Room 3000",
         "clientName": "Max Schneider",
         "reservationId": "005",
         "blocked":"false"
      }

   ]
}

The POS user selects the matching guest/folio from the responses.

Partial Room Numbers

The Lightspeed Restaurant K-Series POS will pass a number of query parameters to the PMS, including the room number that the user searched for.

The full text search is used to search for partial matches, e.g. "10" or "100" are entered in the search mask to find the room "1000”.

An array of guests/folios matching the search terms should be returned to Lightspeed, if the search is successful.

POS Action

The POS user searches for “10”

Example request

/search?businessExternalReference=fake-client-id&apiKey=fake-api-key&term=10   

Example response

{
   "success": "true",
   "errorMessage": "",
   "reservations":[
      {
         "roomId": "10",
         "roomDescription": "Room 10",
         "clientName": "Mike Test",
         "reservationId": "008",
         "blocked":"false"
      },
      {
         "roomId": "100",
         "roomDescription": "Room 100",
         "clientName": "Sam Test",
         "reservationId": "009",
         "blocked":"false"
      },
{
         "roomId": "1000",
         "roomDescription": "Room 1000",
         "clientName": "Franz Test",
         "reservationId": "001",
         "blocked":"false"
      }
   ]
}

The POS user selects the matching guest/folio from the responses.

Alphanumeric Room Identifiers

The Lightspeed Restaurant K-Series POS will pass a number of query parameters to the PMS, including the room alphanumeric room identifications that the user searched for.

The full text search is used to search for rooms that are composed of alphanumeric characters. A room can have the name "K101" or "Suite10".

An array of guests/folios matching the search terms should be returned to Lightspeed.

POS Action

The POS user searches for “K101”

Example request

/search?businessExternalReference=fake-client-id&apiKey=fake-api-key&term=K101

Example response

{
   "success": "true",
   "errorMessage": "",
   "reservations":[
      {
         "roomId": "K101",
         "roomDescription": "Building K 101",
         "clientName": "Mr. Rose",
         "reservationId": "011",
         "blocked":"false"
      }
   ]
}

Paymasters, Company, and Event Folios

If a company, an event or a banquet (e.g. a wedding party) is managed in the PMS, this account is often not linked to a room or a guest reservation.

The search request for such accounts follows the same rules as the search for guests or rooms.

The Lightspeed Restaurant K-Series POS will pass a number of query parameters to the PMS, including the company, event or banquet name that the user searched for.

An array of guests/folios matching the search terms should be returned to Lightspeed.

POS Action

The POS user searches for "White Wedding"

Example request

/search?businessExternalReference=fake-client-id&apiKey=fake-api-key&term=White%20Wedding

Example response

{
   "success": "true",
   "errorMessage": "",
   "reservations":[
      {
         "roomId": "9100",
         "roomDescription": "Banquet White Wedding",
         "clientName": "White Wedding",
         "reservationId": "9100",
         "blocked":"false"
      }
   ]
}

Blocked Guests

If the PMS offers the possibility to restrict room charges for a reservation, this information can be specified in the response of the search request in the field blocked.

POS Action

The POS user searches for "Norris"

Example request

/search?businessExternalReference=fake-client-id&apiKey=fake-api-key&term=Norris

Example response

{
   "success":"true",
   "errorMessage":"",
   "reservations":[
      {
         "roomId":"500",
         "roomDescription":"This reservation doesn’t allow room charges",
         "clientName":"Chuck Norris",
         "reservationId":"5000",
         "blocked":"true"
      },
      {
         "roomId":"688",
         "roomDescription":"Suite",
         "clientName":"Jane Norris",
         "reservationId":"6000",
         "blocked":"true"
      }
   ]
}

In the search field shown below, in which the responses are displayed, for both reservations the objects are "blocked": "true".

In addition, the roomDescription field in the response can be used to inform the POS user during the search that the reservation does not allow room charges.

PMS Blocked Example

If the POS user selects a blocked reservation, an error message is displayed on the POS:

PMS Blocked Error

Search Requests

Introduction​

Search terms​

Search Types​

Guest Names​

POS Action​

Example request​

Example response​

Room Numbers​

POS Action​

Example request​

Example response​

Partial Guest Names​

POS Action​

Example request​

Example response​

Room Sharer​

POS Action​

Example request​

Example response​

Partial Room Numbers​

POS Action​

Example request​

Example response​

Alphanumeric Room Identifiers​

POS Action​

Example request​

Example response​

Paymasters, Company, and Event Folios​

POS Action​

Example request​

Example response​

Blocked Guests​

POS Action​

Example request​

Example response​

Introduction

Search terms

Search Types

Guest Names

POS Action

Example request

Example response

Room Numbers

POS Action

Example request

Example response

Partial Guest Names

POS Action

Example request

Example response

Room Sharer

POS Action

Example request

Example response

Partial Room Numbers

POS Action

Example request

Example response

Alphanumeric Room Identifiers

POS Action

Example request

Example response

Paymasters, Company, and Event Folios

POS Action

Example request

Example response

Blocked Guests

POS Action

Example request

Example response