Lyrical Systems GRM API

These are the resources available to access the Lyrical Systems GRM (Guest Relationship Management) package.

Please contact us to receive an API key to use these features.

See the overview documentation for details about response codes, error handling, organizations, sessions, and other background that will be assumed in this document.

Usage

There are two primary ways to create a reservation using the Lyrical Systems calendar:

Reservation Request

This is a simple one-shot reservation request, which adds a reservation in the new state to the calendar, to be followed up by location staff to actually confirm.

Multi-step Confirmation

This is a more involved multi-step online reservation confirmation flow.
It currently requires the additional GRM online package.

  • First the user searches for available time slots at a date and location.
  • Then after the user selects a time slot and rate, a time slot is reserved on the calendar in the reserved_online state.
  • Then the reservation is updated with additional information, including the guest identity.
  • Finally, the reservation is confirmed, which updates the reservation to the confirmed_online state, and a confirmation email is sent to the guest.

Both flows share some resources to get information about reservations.

Resource Overview

Common for both reservation flows:

Request only:

Multi-step confirmation:

Add a guest, without creating a reservation:

Common resources:

GET /api/version/reservations/info.format

Get available values for various drop-downs, including Occasions and HDYHAUs. HDYHAU is “How did you hear about us?”.
These enumerated values are supported in the ‘occasion’ and ‘hdyhau’ fields of a reservation, respectively.

Parameters

None

Examples

To get all available form info

GET /api/v1/reservations/info

Example Response

{
  "occasions": [
    {
      "value": "birthday_adult",
      "text": "Birthday - Adults"
    },
    {
      "value": "birthday_kid",
      "text": "Birthday - Kids"
    },
    {
      "value": "company",
      "text": "Company Party"
    }
  ],
  "hdyhaus": [
    {
      "value": "returning",
      "text": "Been here before"
    },
    {
      "value": "friend",
      "text": "Friend"
    }
  ]
}

GET /api/version/reservations/guid.format

Get information about a reservation by its GUID. The intended usage is for the “Reservation Status” page on our booking website.

Parameters

  • guid (required)
    This should be a 32-character GUID identifying the reservation.
    It is returned in the response of POST /api/v1/reservations/request

Examples

To get information about the current status of a reservation

GET /api/v1/reservations/30d57d688e42410c8714ab83e0e7f343?organization=00000000000000000000000000000000

Example Response

{
    "guid": "30d57d688e42410c8714ab83e0e7f343",
    "guest_guid": "83b6062bf77d447b821839f494f5a7df",
    "reservation_id": 555,
    "first_name": "Jenny",
    "last_name": "Tutone",
    "phone": "(555) 867-5309",
    "email": "jenny@columbia.net",
    "zip_code": "97205",
    "location_id": 1,
    "location": "Northwest",
    "location_full_name": "Northwest Portland",
    "region": "Portland",
    "state": "confirmed",
    "business_date": "2015-02-14",
    "start_time": "9:30pm",
    "start_time_minus_15": "9:15pm",
    "end_time": "12:00am",
    "party_size": "8+",
    "minors": false,
    "no_minors_time": "9pm",
    "rate_text": "based on our individual prime rate of $11 per guest per hour"
    "rate_title": "Pay Individually",
    "rate_description": "$11 per guest per hour",
    "rate_additional": null,
    "occasion": "just_for_fun",
    "occasion_text": "Just For Fun",
    "title": null,
    "notes": null,
    "guest_of_honor": null,
    "confirmed_at": "2015-02-10T23:55:07.140Z",
    "booking_step": 4
}

In the response, the state can be one of the following values:

State Category Description
new Requested The reservation has just been created. Our staff will respond to the guest ASAP.
contacted Reqeusted One of our staff has contacted the guest, and is awaiting a response.
needs_contact Requested Our staff needs to get back in touch with the guest before confirming.
wait_list Requested If there is available space, one of our staff will contact the guest to confirm.
     
penciled_in Reserved The reservation is merely penciled-in on the calendar and may be subject to change.
confirmed Reserved The reservation is confirmed and on the calendar.
reserved_online Reserved The time slot has been reserved using the multi-step confirmation flow.
confirmed_online Reserved The reservation has been confirmed using the multi-step confirmation flow.
     
arrived Active Some of the guests have arrived, but the party has not yet started.
in_progress Active The party is currently in progress.
running_late Active A guest has called ahead to inform us that the party will start soon.
     
completed Closed The party finished normally, and the reservation is complete.
no_show Closed The guests did not show up for the reservation.
cancelled Closed The reservation has been cancelled.
cancelled_online Closed The reservation was cancelled by the guest using the multi-step confirmation flow.
out_of_luck Closed The reservation was on the wait-list, but we were unable to serve them.
timed_out_online Closed The reservation timed out after inactivity during the multi-step confirmation flow.
abandoned Closed For various other reasons, the reservation was removed.

Resource for request flow:

POST /api/version/reservations/request.format

Create a new reservation request. This will put a reservation request on the Lyrical Systems calendar. The intended usage is for a booking form on our clients’ websites, such as the Book Your Box form for Voicebox Karaoke.

Parameters

  • api_key (required)
    This key is provided by Lyrical Systems to its clients.
    Without this key, clients are unable to create reservation requests.

  • first_name (required)

  • last_name (required)
    The name of the guest making the request

  • phone (required)
    A valid 10-digit phone number at which the guest may be contacted
    Ignores any punctuation, so a variety of formats may be accepted
    e.g. (555) 867-5309, 555-867-5309, 5558675309
    Accepts an optional extension, after an x, e.g. 555-867-5309x123

  • email (required)
    A valid email address at which the guest may be contacted

  • zip_code (optional)
    A 5-digit zip_code, with optional 4-digit extension, in which the guest resides
    e.g. 97266 or 97266-1000

  • business_date (required)
    The desired date of reservation.
    Accepts a variety of formats, but the following is recommended: 2012-02-14
    Even if the start_time is after midnight, use the date on which the location last opened its doors for business prior to the start_time.

  • location (optional)
    The desired location for the reservation. For Voicebox, it may be one of ‘Northwest’, ‘Southeast’, ‘RiNo’, ‘FortWorth’, or ‘BoDo’.
    It may also be omitted or left blank, to indicate no location preference.

  • region (optional)
    The desired region for the reservation. For Voicebox, it may be one of ‘Portland’, ‘Denver’, ‘DFW’, or ‘Boise’.
    It is only necessary to set this when there is no location provided, e.g. to specify ‘Portland’, without specifying a specific location preference.

  • start_time (required)
    The desired starting time of the reservation. It should be on a quarter-hour boundary.
    Acceptable formats include: ‘11am’, ‘11:00am’, ‘8:15pm’, ‘11pm’, ‘12am’, ‘1:45am’
    ‘8:05pm’ would not be acceptable, because it is not on a quarter-hour boundary.

  • duration (optional)
    The desired duration of the reservation in hours. Must be in intervals of a quarter-hour.
    e.g. ‘1’, ‘1.0’, ‘1.25’, ‘3’

  • party_size (optional)
    The estimated party size. Accepts a number, a bounded range, or an unbounded range.
    e.g. ‘5’, ‘5-12’, ‘14+’

  • minors (optional)
    Whether any minors under the age of 21 are expected to attend.
    One of: ‘0’, ‘1’, ‘f’, ‘t’, ‘false’, ‘true’
    Defaults to false.

  • hdyhau (optional)
    “How did you hear about us?”
    One of the values returned by a call to GET /api/v1/reservations/hdyhaus

  • occasion (optional)
    In order to best serve our guests, select the type of occasion.
    One of the values returned by a call to GET /api/v1/reservations/occasions

  • notes (optional)
    Any additional notes that the guest would like the location to be aware of.
    This may contain arbitrary text, including newlines.

  • utm_source (optional)
  • utm_medium (optional)
  • utm_term (optional)
  • utm_content (optional)
  • utm_campaign (optional)
    These optional fields indicate the corresponding Google Ad information.
    This is useful for tracking how guests discover our clients’ websites and then book reservations

Examples

To create a request, use something like the following:

POST /api/v1/reservations/request?organization=00000000000000000000000000000000&api_key=ThisIsNotARealKey&first_name=Jenny&last_name=Tutone&phone=555-867-5309&email=jenny@columbia.net&business_date=2015-02-14&location=Northwest&start_time=9:30pm&duration=2.5&party_size=8+&minors=false&hdyhau=friend&occasion=company_party&notes=I%20love%20karaoke&utm_source=google&utm_medium=cpc&utm_term=karaoke&utm_content=textlink&utm_campaign=bridal

Example Response

{
    "guid": "30d57d688e42410c8714ab83e0e7f343",
    "guest_guid": "83b6062bf77d447b821839f494f5a7df",
    "guest_new": false
}

In the response, the guid can be used to track the reservation throughout its lifetime.

The guest_guid refers to the identity of the person creating the reservation. The system tries to match to an existing guest in the GRM database, by using name, email, and phone number. If an existing guest is found, guest_new will be false. Otherwise, a new guest is created, and guest_new will be true.

Resources for multi-step confirmation flow:

GET /api/version/reservations/time_slots.format

Search for available time slots for a given date and location.

Parameters

  • api_key (required)
    This key is provided by Lyrical Systems to its clients.
    Without this key, clients are unable to create reservation requests.

  • business_date (required)
    The desired date of reservation.
    Accepts a variety of formats, but the following is recommended: 2012-02-14
    Even if the start_time is after midnight, use the date on which the location last opened its doors for business prior to the start_time.

  • location (required if multi-location)
    The desired location for the reservation. For Voicebox, it may be one of ‘Northwest’, ‘Southeast’, or ‘RiNo’.
    It may be omitted if the organization has only one location.

  • start_time (required)
    The desired starting time of the reservation. It should be on a quarter-hour boundary.
    Acceptable formats include: ‘11am’, ‘11:00am’, ‘8:15pm’, ‘11pm’, ‘12am’, ‘1:45am’
    ‘8:05pm’ would not be acceptable, because it is not on a quarter-hour boundary.

  • duration (required)
    The desired duration of the reservation in hours. Must be in intervals of a quarter-hour.
    e.g. ‘1’, ‘1.0’, ‘1.25’, ‘3’

  • party_size (required)
    The estimated party size. Accepts a postive integer.
    e.g. ‘5’

  • minors (optional)
    Whether any minors under the age of 21 are expected to attend.
    One of: ‘0’, ‘1’, ‘f’, ‘t’, ‘false’, ‘true’
    Defaults to false.

  • utm_source (optional)
  • utm_medium (optional)
  • utm_term (optional)
  • utm_content (optional)
  • utm_campaign (optional)
    These optional fields indicate the corresponding Google Ad information.
    This is useful for tracking how guests discover our clients’ websites and then book reservations

Examples

To search for available time slots for the Northwest location on Valentine’s Day around 7pm:

GET /api/v1/reservations/time_slots?organization=00000000000000000000000000000000&api_key=ThisIsNotARealKey&business_date=2020-02-14&location=Northwest&start_time=7:00pm&duration=2.5&party_size=8+&minors=false

Example Response

{
    "location": "Northwest",
    "business_date": "2020-01-14",
    "start_time": "7:00pm",
    "duration": 2.5,
    "party_size": 8,
    "minors": false,
    "messages": [
        {
            "type": "warning",
            "text": "Note that we will have some rooms closed for construction"
        }
    ],
    "sections": [
        {
            "title": "Standard Suite",
            "subtitle": "Perfect for most parties",
            "additional": null,
            "time_slots": [
                {
                    "start_time": "7:30pm",
                    "end_time": "9:30pm",
                    "duration": 2.0,
                    "room_type": "standard",
                    "rates": [
                        {
                            "type": "individual",
                            "text": "based on our individual rate of $7 per guest per hour",
                            "title": "Pay Individually",
                            "description": "$7 per guest per hour",
                            "additional": "(during prime time, charges based on 6 guest minimum)"
                        },
                        {
                            "type": "group",
                            "text": "based on our group rate of $60 per hour",
                            "title": "Pay as a Group",
                            "description": "$60 per hour",
                            "additional": "(split on up to 3 checks)"
                        }
                    ]
                },
                {
                    "start_time": "7:45pm",
                    "end_time": "10:00pm",
                    "duration": 2.25,
                    "room_type": "standard",
                    "rates": [
                        {
                            "type": "individual",
                            "text": "based on our individual rate of $7 per guest per hour",
                            "title": "Pay Individually",
                            "description": "$7 per guest per hour",
                            "additional": "(during prime time, charges based on 6 guest minimum)"
                        },
                        {
                            "type": "group",
                            "text": "based on our group rate of $60 per hour",
                            "title": "Pay as a Group",
                            "description": "$60 per hour",
                            "additional": "(split on up to 3 checks)"
                        }
                    ]
                }
            ]
        }
    ]
}

POST /api/version/reservations/reserve.format

Begin the booking process by reserving a time slot. The intended usage is for a booking form on our clients’ websites, such as the Book Your Box form for Voicebox Karaoke.

After selecting from available time slots using GET /api/version/reservations/time_slots.format, this will put a temporary reserved_online reservation on the Lyrical Systems calendar.

Parameters

  • api_key (required)
    This key is provided by Lyrical Systems to its clients.
    Without this key, clients are unable to create reservation requests.

  • business_date (required)
    The desired date of reservation.
    Accepts a variety of formats, but the following is recommended: 2012-02-14
    Even if the start_time is after midnight, use the date on which the location last opened its doors for business prior to the start_time.

  • location (required)
    The desired location for the reservation. For Voicebox, it may be one of ‘Northwest’, ‘Southeast’, or ‘RiNo’.
    It may be omitted if the organization has only one location.

  • start_time (required)
    The starting time of the reservation, as presented from an available time_slot.
    e.g. ‘11am’, ‘11:00am’, ‘8:15pm’, ‘11pm’, ‘12am’, ‘1:45am’

  • duration (required)
    The duration of the reservation in hours, as presented from an available time_slot.
    e.g. ‘1’, ‘1.0’, ‘1.25’, ‘3’

  • party_size (required)
    The estimated party size as a positive integer, same as when the search was done for available time slots.
    e.g. ‘5’

  • minors (optional)
    Whether any minors under the age of 21 are expected to attend, same as when the search was done for available time slots.
    One of: ‘0’, ‘1’, ‘f’, ‘t’, ‘false’, ‘true’
    Defaults to false.

  • room_type (required)
    One of ‘standard’, ‘lpremier’, or ‘spremier’, as presented from an available time_slot.
    e.g. ‘standard’

  • rate_type (optional)
    One of ‘individual’, ‘group’, or ‘special’, as presented from an available time_slot.
    Note that either rate_type or rate_shorthand is required.
    e.g. ‘individual’

  • rate_shorthand (optional)
    The rate shorthand, as presented from an available time_slot.
    Note that either rate_type or rate_shorthand is required.
    e.g. ‘GRP $90’

  • desired_start_time (optional)
    The desired starting time of the reservation, typically the input provided to search for available time slots.
    It should be on a quarter-hour boundary.
    Acceptable formats include: ‘11am’, ‘11:00am’, ‘8:15pm’, ‘11pm’, ‘12am’, ‘1:45am’
    ‘8:05pm’ would not be acceptable, because it is not on a quarter-hour boundary.

  • desired_duration (optional)
    The desired duration of the reservation in hours, typically the input provided to search for available time slots.
    Must be in intervals of a quarter-hour.
    e.g. ‘1’, ‘1.0’, ‘1.25’, ‘3’

  • booking_step (optional)
    A positive integer that may be used to identify which step of an online booking flow has been reached.
    Purely informational.

  • utm_source (optional)
  • utm_medium (optional)
  • utm_term (optional)
  • utm_content (optional)
  • utm_campaign (optional)
    These optional fields indicate the corresponding Google Ad information.
    This is useful for tracking how guests discover our clients’ websites and then book reservations

Examples

To reserve a time slot and begin the booking process, use something like the following:

POST /api/v1/reservations/reserve?organization=00000000000000000000000000000000&api_key=ThisIsNotARealKey&business_date=2015-02-14&location=Northwest&start_time=9:30pm&duration=2.5&party_size=8+&minors=false&room_type=standard&rate_type=individual&utm_source=google&utm_medium=cpc&utm_term=karaoke&utm_content=textlink&utm_campaign=bridal

Example Response

{
    "guid": "30d57d688e42410c8714ab83e0e7f343",
    "guest_guid": "83b6062bf77d447b821839f494f5a7df"
}

In the response, the guid can be used to track the reservation throughout its lifetime.

The guest_guid refers to the identity of the person creating the reservation, which will be available if the session is already associated to a guest. See the clear-guest route below to change this identity.

POST /api/version/reservations/guid/clear_guest.format

Reset which guest is associated to a reservation in the reserved_online state.
If, after reserving a time-slot, the user discovers that the stored guest profile information associated with their session is incorrect, this may be used to clear the guest association.

Before calling this, a new session UUID should be generated on the client, so that this and future activity by the user is not incorrectly tracked with the old session. Please provide the old_session in this case.

Parameters

  • guid (required)
    This should be a 32-character GUID identifying the reservation.
    It is returned in the response of POST /api/v1/reservations/reserve

  • api_key (required)
    This key is provided by Lyrical Systems to its clients.
    Without this key, clients are unable to create or modify reservations.

  • old_session (optional)
    Indicates which previous session UUID was in use, which caused the user to then want to clear and start fresh.

Examples

To clear the guest for a reservation, use something like the following:

POST /api/v1/reservations/30d57d688e42410c8714ab83e0e7f343/clear_guest?organization=00000000000000000000000000000000&api_key=ThisIsNotARealKey&old_session=12345678-1234-1234-1234-123456abcdef

Example Response

{
    "guid": "30d57d688e42410c8714ab83e0e7f343",
    "guest_guid": null,
    "first_name": null,
    "last_name": null,
    "phone": null,
    "email": null,
    "location": "Northwest",
    "region": "Portland",
    "state": "reserved_online",
    "business_date": "2015-02-14",
    "start_time": "9:30pm",
    "start_time_minus_15": "9:15pm",
    "end_time": "12:00am",
    "party_size": "8",
    "minors": false,
    "rate_text": "based on our individual prime rate of $11 per guest per hour"
}

PATCH /api/version/reservations/guid.format

Update a reservation in the reserved_online state.
This may be called zero or more times for the same reservation, depending on the details of the user interface flow.
Note, if any of the guest information is provided, it is all required at once, in order to correctly infer identify.

Parameters

  • guid (required)
    This should be a 32-character GUID identifying the reservation.
    It is returned in the response of POST /api/v1/reservations/reserve

  • api_key (required)
    This key is provided by Lyrical Systems to its clients.
    Without this key, clients are unable to create reservation requests.

  • first_name (required if updating guest)

  • last_name (required if updating guest)
    The name of the guest making the request

  • guest_guid (optional)
    This is returned in the response of POST /api/v1/reservations/reserve and GET /api/v1/reservations and should be passed in this call, to indicate that the guest intends to change their profile information, such as first_name or phone.
    Without providing this, if there is an existing guest and certain identifying fields in the update no longer match, a new guest record will be created instead of modifying the existing one.

  • phone (required if updating guest)
    A valid 10-digit phone number at which the guest may be contacted
    Ignores any punctuation, so a variety of formats may be accepted
    e.g. (555) 867-5309, 555-867-5309, 5558675309
    Accepts an optional extension, after an x, e.g. 555-867-5309x123

  • email (required if updating guest)
    A valid email address at which the guest may be contacted

  • zip_code (optional)
    A 5-digit zip_code, with optional 4-digit extension, in which the guest resides
    e.g. 97266 or 97266-1000

  • hdyhau (optional)
    “How did you hear about us?”
    One of the values returned by a call to GET /api/v1/reservations/hdyhaus

  • occasion (optional)
    In order to best serve our guests, select the type of occasion.
    One of the values returned by a call to GET /api/v1/reservations/occasions

  • guest_of_honor (optional)
    Many parties have a special guest, such as the birthday girl, or the person getting married

  • title (optional)
    A name for the party. Guests often enjoy giving their parties fun names.
    e.g. “Jenny’s 40th Birthday” or “Skittlefunkboomboom”

  • notes (optional)
    Any additional notes that the guest would like the location to be aware of.
    This may contain arbitrary text, including newlines.

  • booking_step (optional)
    A positive integer that may be used to identify which step of an online booking flow has been reached.
    Purely informational.

Examples

To update a reservation, use something like the following:

PATCH /api/v1/reservations/30d57d688e42410c8714ab83e0e7f343/request?organization=00000000000000000000000000000000&api_key=ThisIsNotARealKey&first_name=Jenny&last_name=Tutone&phone=555-867-5309&email=jenny@columbia.net&hdyhau=friend&occasion=company_party&title=Skittlefunkboomboom&notes=I%20love%20karaoke

Example Response

{
    "guid": "30d57d688e42410c8714ab83e0e7f343",
    "guest_guid": "83b6062bf77d447b821839f494f5a7df",
    "guest_new": false
}

The guest_guid refers to the identity of the person creating the reservation. The system tries to match to an existing guest in the GRM database, by using name, email, and phone number. If an existing guest is found, guest_new will be false. Otherwise, a new guest is created, and guest_new will be true.

POST /api/version/reservations/guid/confirm.format

Update and confirm a reservation in the reserved_online state.
This will change the reservation state to confirmed_online and send a confirmation email to the guest.

Similar to PATCH /api/v1/reservations/GUID, this may accept any additional information to update the reservation, depending on the details of the user interface flow. It may also contain no additional information, and simply confirm a reservation. Note, if any of the guest information is provided, it is all required at once, in order to correctly infer identify.

Parameters

  • guid (required)
    This should be a 32-character GUID identifying the reservation.
    It is returned in the response of POST /api/v1/reservations/reserve

  • api_key (required)
    This key is provided by Lyrical Systems to its clients.
    Without this key, clients are unable to create reservation requests.

  • first_name (required if updating guest)

  • last_name (required if updating guest)
    The name of the guest making the request

  • phone (required if updating guest)
    A valid 10-digit phone number at which the guest may be contacted
    Ignores any punctuation, so a variety of formats may be accepted
    e.g. (555) 867-5309, 555-867-5309, 5558675309
    Accepts an optional extension, after an x, e.g. 555-867-5309x123

  • email (required if updating guest)
    A valid email address at which the guest may be contacted

  • zip_code (optional)
    A 5-digit zip_code, with optional 4-digit extension, in which the guest resides
    e.g. 97266 or 97266-1000

  • hdyhau (optional)
    “How did you hear about us?”
    One of the values returned by a call to GET /api/v1/reservations/hdyhaus

  • occasion (optional)
    In order to best serve our guests, select the type of occasion.
    One of the values returned by a call to GET /api/v1/reservations/occasions

  • guest_of_honor (optional)
    Many parties have a special guest, such as the birthday girl, or the person getting married

  • title (optional)
    A name for the party. Guests often enjoy giving their parties fun names.
    e.g. “Jenny’s 40th Birthday” or “Skittlefunkboomboom”

  • notes (optional)
    Any additional notes that the guest would like the location to be aware of.
    This may contain arbitrary text, including newlines.

  • booking_step (optional)
    A positive integer that may be used to identify which step of an online booking flow has been reached.
    Purely informational.

Examples

To confirm a reservation, use something like the following:

POST /api/v1/reservations/30d57d688e42410c8714ab83e0e7f343/confirm?organization=00000000000000000000000000000000&api_key=ThisIsNotARealKey

Example Response

{
    "guid": "30d57d688e42410c8714ab83e0e7f343",
    "guest_guid": "83b6062bf77d447b821839f494f5a7df",
    "guest_new": false
}

The guest_guid refers to the identity of the person creating the reservation. The system tries to match to an existing guest in the GRM database, by using name, email, and phone number. If an existing guest is found, guest_new will be false. Otherwise, a new guest is created, and guest_new will be true.

POST /api/version/reservations/guid/cancel.format

Cancel a reservation in the reserved_online or confirmed_online state.
This will change the reservation state to cancelled_online and send a cancellation email to the guest.

Parameters

  • guid (required)
    This should be a 32-character GUID identifying the reservation.
    It is returned in the response of POST /api/v1/reservations/reserve

  • api_key (required)
    This key is provided by Lyrical Systems to its clients.
    Without this key, clients are unable to create reservation requests.

  • notes (optional)
    Any additional notes that may indicate why the guest intends to cancel the reservation.
    This may contain arbitrary text, including newlines.

Examples

To cancel a reservation, use something like the following:

POST /api/v1/reservations/30d57d688e42410c8714ab83e0e7f343/cancel?organization=00000000000000000000000000000000&api_key=ThisIsNotARealKey

Example Response

{
    "guid": "30d57d688e42410c8714ab83e0e7f343",
    "guest_guid": "83b6062bf77d447b821839f494f5a7df"
}

The guest_guid refers to the identity of the person who created the reservation.

POST /api/version/guests.format

Add a new guest to GRM, without a creating a reservation.

Parameters

  • api_key (required)
    This key is provided by Lyrical Systems to its clients.
    Without this key, clients are unable to create reservation requests.

  • first_name (required)

  • last_name (required)
    The name of the guest

  • phone (required)
    A valid 10-digit phone number at which the guest may be contacted
    Ignores any punctuation, so a variety of formats may be accepted
    e.g. (555) 867-5309, 555-867-5309, 5558675309
    Accepts an optional extension, after an x, e.g. 555-867-5309x123

  • email (required)
    A valid email address at which the guest may be contacted

  • zip_code (optional)
    A 5-digit zip_code, with optional 4-digit extension, in which the guest resides
    e.g. 97266 or 97266-1000

  • region (optional)
    The region this guest is most interested in. For Voicebox, it may be one of ‘Portland’, ‘Denver’, ‘DFW’, or ‘Boise’.

  • promo (optional)
    This optional field indicates which promotion should be triggered.
    For example, using intro can trigger an introductory offer promotion.

Examples

To add a guest, use something like the following:

POST /api/v1/guests?organization=00000000000000000000000000000000&api_key=ThisIsNotARealKey&first_name=Jenny&last_name=Tutone&phone=555-867-5309&email=jenny@columbia.net&promo=intro

Example Response

{
    "guest_guid": "83b6062bf77d447b821839f494f5a7df",
    "guest_new": true,
    "promo": "intro",
    "promo_valid": true
}

The guest_guid refers to the identity of the person creating the reservation. The system tries to match to an existing guest in the GRM database, by using name, email, and phone number. If an existing guest is found, guest_new will be false. Otherwise, a new guest is created, and guest_new will be true.

If the promo field was provided, then promo_valid will return true or false, indicating whether this new guest is eligible for the given promotion. Note that the guest will be added or updated in the GRM database even if the promo is not valid for them.

Powered by Lyrical Systems