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, etc.

Resource Overview


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.


  • 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

  • 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’, or ‘RiNo’.
    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’ or ‘Denver’.
    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 18 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


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&

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.

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.


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


To get information about the current status of a reservation

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

Example Response

    "guid": "30d57d688e42410c8714ab83e0e7f343",
    "guest_guid": "83b6062bf77d447b821839f494f5a7df",
    "first_name": "Jenny",
    "last_name": "Tutone",
    "phone": "(555) 867-5309",
    "email": "",
    "location": "Northwest",
    "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,
    "rate_text": "based on our individual prime rate of $11 per guest per hour"

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.
confirmed Reserved The reservation is confirmed and on the calendar.
penciled_in Reserved The reservation is merely penciled-in on the calendar and may be subject to change.
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.
out_of_luck Closed The reservation was on the wait-list, but we were unable to serve them.
abandoned Closed For various other reasons, the reservation was removed.

GET /api/version/reservations/hdyhaus.format

Get available HDYHAU values. HDYHAU is “How did you hear about us?”. These enumerated values are supported in the ‘hdyhau’ field of a reservation request.




To get all available HDYHAUs

GET /api/v1/reservations/hdyhaus

Example Response

    "hdyhaus": [

GET /api/version/reservations/occasions.format

Get available occasion values.
These enumerated values are supported in the ‘occasion’ field of a reservation request.




To get all available occasions

GET /api/v1/reservations/occasions

Example Response

    "occasions": [

Powered by Lyrical Systems