Events API

An event represents just that, and event at a given time and location. Events always have at least one booking, account, contact, location, and room. An event's booking can contain several events spanning multiple days.

Event Fields Overview

  • name (required) - the name of this event
  • event_start (required) - Start date time - mm/dd/yyyy hh:mm am|pm
  • start_time (deprecated) - same as event_start
  • event_end (required) - End date time - mm/dd/yyyy hh:mm am|pm
  • end_time - (deprecated) - same as event_end
  • event_start_utc - Start Date time in UTC iso8601
  • event_end_utc - End Date time in UTC iso8601
  • account_id (required) - Account ID for this event (see accounts API)
  • contact_id (required) - Contact ID for this event (see contacts API)
  • owned_by- the ID of the Tripleseat user who owns this event (see Users API)
  • guaranteed_guest_count - Integer
  • guest_count - Integer
  • food_and_beverage_min - Currency
  • rental_fee - Currency
  • price_per_person - Currency
  • deposit_amount - Currency
  • actual_amount - Currency
  • grand_total - Currency
  • amount_due - Currency
  • event_type - String (See sites API for values)
  • status (required) - DEFINITE, PROSPECT, TENTATIVE, CLOSED, or LOST
  • location_id (required) - The location ID for this event (see locations API)
  • location - Object containing information about the location for this event
  • room_ids (required) - Array of room id's for this event
  • rooms - Collection of objects detailing the rooms/areas for this event
  • booking_id (required) - the Booking ID for this event (see bookings API)
  • booking - Object containg information about the booking for this event 
  • descriptionText
  • managing_user_ids(Array) - ID's of managing users (see Users API) 
  • custom_fields - Nested collection of Custom Fields
  • billing_totals - Collection of Billing Totals (Taxes, Gratuity, etc.)
  • category_totals - Collection of Menu Item Category Totals (Food, Beverage, etc.)

Event Show / List Endpoints (JSON | XML schema)

GET /v1/events.(xml | json) 

Retrieves a paginated list of events (50 per page, use page parameter listed below to iterate over pages).

GET /v1/events/{id}.(xml | json) 

Retrieves an event by its ID.

DELETE /v1/events/{id}.(xml | json)

Deletes the event for the given ID. 

GET /v1/events/search.(xml | json)?{search params}

Search for events using filtering parameters (listed below). Append parameters together using & (e.g., ?query=kevin&sort_direction=desc&order=created_at).

Search Parameters and values

  • query - searches for events by name, contact, account, email, phone
  • order - created_at, updated_at, name, event_start (datetime)
  • sort_direction - desc, asc
  • contact_id - Contact ID
  • account_id - Account ID
  • status - prospect, tentative, definite, closed, or lost (Array or comma separated string)
  • event_start_date - mm/dd/yyyy (also requires end date)
  • event_end_date - mm/dd/yyyy (also requires start date)
  • event_created_start_date - mm/dd/yyyy (also requires end date)
  • event_created_end_date - mm/dd/yyyy (also requires start date)
  • event_updated_start_date - mm/dd/yyyy (also requires end date)
  • event_updated_end_date - mm/dd/yyyy (also requires start date)
  • room_ids - comma separated list of room ID's to match on
  • location_ids - comma separated list of location ID's to match on 
  • page (1..9999999)

Event Create/Update Endpoints (JSON | XML schema)

POST /v1/events.(xml | json)?event={event parameters}

Creates an event using the passed in event information parameters. Parameters are expected to follow the format listed in the JSON/XML schema above.

PUT /v1/events/id.(xml | json)?event={event parameters}

Works just like the create method except you need to pass in the ID of the event to update.

Create / Update Parameter Information

Most fields in the JSON/XML schema should self-explanatory, but the following are fields merit special mentioning.

  • location_id - see how to get a list of your location_id's
  • room_ids - see how to get a list of your site's room_id's
  • account_id - see the account's API for Account ID's
  • contact_id - see the contact's API for Contact ID's
  • booking_id - ID of an existing booking to assign this event to
  • booking - if a booking_id is not provided, this property can contain a nested object with the following properties:
    • name - name of the booking
    • start_date - start date for the booking - mm/dd/yyyy
    • end_date - end date for the booking - mm/dd/yyyy
    • location_id - see how to get a list of your location_id's

If no booking_id or booking object is provided, new events will automatically have a booking object created based on the event's location and start/end times.

If updating an existing event, any properties not passed in will remain unchanged.

A Note about Validation Errors for Events

Tripleseat has a number of validation rules in place to keep events from overlapping with each other, being in the past, and having proper data formatting. If an error occurs, our API will respond with the error (as a string or collection of strings) in the appropriate format.

Have more questions? Submit a request

Comments