This guide will be removed on April 29, 2022. Please use our new, easier-to-use Toast technical documentation site. All updated content is on the new site.

Guest search

After a search configuration request, the Toast POS device displays the guest search criteria. An employee can search for a guest on the Toast POS device using a guest's information, such as name, room number, or reservation number.

Search workflow

  1. An employee enters the guest's identifying information in the input fields on the Toast POS device and searches for the guest.

  2. The Toast POS device sends a TENDER_SEARCH request to the PMS provider. The request is a TenderTransaction object that contains a searchTransactionInformation object which contains a searchTerms object. This searchTerms object contains the search criteria, in the form of a key-value pair:

    • The key corresponds to the input field where the restaurant employee enters the guest's identifying information.

    • The value corresponds to the string that the employee types on the Toast POS device. The value can be partial such as only first name or last name or partial name.

  3. The PMS provider returns the results of the search request in a searchResponse object that contains a searchResults property. The searchResults property contains an array of AccountInfo objects. Each entry in the array corresponds to a guest and has:

    • An identifier for the guest (tenderIdentifier).Each tenderIdentifier should be unique for each guest returned in the TENDER_SEARCH response.

      Important

      tenderIdentifier is generated by the integration partner and should never be generated using a guest's sensitive information, such as credit card details.

    • The search results returned as key-value pairs with the guest information such as name and room number.

      Guest search results are displayed on the Toast POS device.

The following example shows a search for a guest whose name contains john. The PMS provider responds with two results for john adams and tommy john and their information.

Search request body

{
	discountsTransactionInformation: null,
	paymentsTransactionInformation: null,
	redeemTransactionInformation: null,
	gratuityTransactionInformation: null,
	reverseTransactionInformation: null,
	searchTransactionInformation: {
	swipeData: null,
	scanData: null,
	searchTerms: [
	{ key: 'Room Number', value: '' },
	{ key: 'Name', value: 'john' },
	{ key: 'Reservation Number', value: '' },
	{ key: 'Company Name', value: '' }
	]
	}
	}

Successful search response

{
	searchResponse: {
	searchResults: [
	{
	tenderIdentifier: '2',
	properties: [
	{ key: 'Room Number', value: '406' },
	{ key: 'Name', value: 'john adams' },
	{ key: 'Reservation Number', value: '7492936' },
	{ key: 'Company Name', value: 'Apple, Inc.' },
	{ key: 'Guest Status', value: 'Active' },
	{ key: 'Charge Limit', value: '$120.00' }
	],
	additionalProperties: [ { key: 'storedValue', value: 60 } ]
},
{
	tenderIdentifier: '4',
	properties: [
	{ key: 'Room Number', value: '1234' },
	{ key: 'Name', value: 'tommy john' },
	{ key: 'Reservation Number', value: '12531953' },
	{ key: 'Company Name', value: 'Toast, Inc.' },
	{ key: 'Guest Status', value: 'Active' },
	{ key: 'Charge Limit', value: '$200.00' }
],
	additionalProperties: [ { key: 'storedValue', value: 400000 } ]
},
{
	tenderIdentifier: '5',
properties: [
	{ key: 'Room Number', value: '555' },
	{ key: 'Name', value: 'jimmy john' },
	{ key: 'Reservation Number', value: undefined },
	{ key: 'Company Name', value: 'Microsoft' },
	{ key: 'Guest Status', value: undefined },
	{ key: 'Charge Limit', value: '$2450.00' }
],
	additionalProperties: [ { key: 'storedValue', value: 980.73 } ]
}
]
},
	transactionStatus: 'ACCEPT'
}